Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/mysql.rst @ 499:d255e02eb89d
updated object-storage doc for 1.0.0
| author | Alain Mazy <alain@mazy.be> |
|---|---|
| date | Tue, 01 Sep 2020 18:08:45 +0200 |
| parents | 5bb6bc85f99f |
| children | 411e82bb3a9f |
| rev | line source |
|---|---|
| 154 | 1 .. _mysql: |
| 2 | |
| 3 | |
| 4 MySQL/MariaDB plugins | |
| 5 ===================== | |
| 6 | |
| 7 .. contents:: | |
| 8 | |
| 9 The Orthanc project provides two **official** plugins to replace the | |
| 10 default storage area (on the filesystem) and the default SQLite index | |
| 11 by a MySQL or a MariaDB database. | |
| 12 | |
| 13 For general information, check out the `official homepage of the | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
270
diff
changeset
|
14 plugins <https://www.orthanc-server.com/static.php?page=mysql>`__. |
| 154 | 15 |
| 230 | 16 **Warning:** According to `this thread on our discussion group |
| 231 | 17 <https://groups.google.com/d/msg/orthanc-users/yV3LSTh_TjI/Fb4ShaYMBAAJ>`__, |
| 18 the MySQL/MariaDB plugins require MySQL 8.x if running on Microsoft | |
| 19 Windows. | |
| 230 | 20 |
| 154 | 21 |
| 22 | |
| 23 Compilation | |
| 24 ----------- | |
| 25 | |
| 26 Static linking | |
| 27 ^^^^^^^^^^^^^^ | |
| 28 | |
| 29 .. highlight:: text | |
| 30 | |
| 31 The procedure to compile these plugins is similar to that for the | |
| 32 :ref:`core of Orthanc <compiling>`. The following commands should work | |
| 33 for most UNIX-like distribution (including GNU/Linux):: | |
| 34 | |
| 35 $ mkdir BuildMySQL | |
| 36 $ cd BuildMySQL | |
| 37 $ cmake ../MySQL/ -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release | |
| 38 $ make | |
| 39 | |
| 40 The compilation will produce 2 shared libraries, each containing one plugin for Orthanc: | |
| 41 | |
| 42 * ``OrthancMySQLIndex`` replaces the default SQLite index of Orthanc by MySQL. | |
| 43 * ``OrthancMySQLStorage`` makes Orthanc store the DICOM files it receives into MySQL. | |
| 44 | |
| 45 | |
| 46 Microsoft Windows | |
| 47 ^^^^^^^^^^^^^^^^^ | |
| 48 | |
| 49 Pre-compiled binaries for Microsoft Windows `are also available | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
270
diff
changeset
|
50 <https://www.orthanc-server.com/browse.php?path=/plugin-mysql>`__. |
| 154 | 51 |
| 52 | |
| 53 Dynamic linking on Ubuntu 16.04 | |
| 54 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 55 | |
| 56 .. highlight:: text | |
| 57 | |
| 58 If static linking is not desired, here are build instructions for | |
| 59 Ubuntu 16.04 (provided build dependencies for the :ref:`core of | |
| 60 Orthanc <compiling>` have already been installed):: | |
| 61 | |
| 62 $ sudo apt-get install libmysqlclient-dev | |
| 63 $ mkdir BuildMySQL | |
| 64 $ cd BuildMySQL | |
| 65 $ cmake ../MySQL/ -DCMAKE_BUILD_TYPE=Release \ | |
| 66 -DALLOW_DOWNLOADS=ON \ | |
| 67 -DUSE_SYSTEM_GOOGLE_TEST=OFF \ | |
| 68 -DUSE_SYSTEM_ORTHANC_SDK=OFF | |
| 69 $ make | |
| 70 | |
| 71 | |
| 72 Usage | |
| 73 ----- | |
| 74 | |
| 75 You of course first have to :ref:`install Orthanc <binaries>`, with a | |
| 76 version above 0.9.5. You then have to **create a database** dedicated | |
| 77 to Orthanc on some MySQL/MariaDB server. Please refer to the `MySQL | |
| 78 documentation | |
| 79 <https://dev.mysql.com/doc/refman/8.0/en/database-use.html>`__. | |
| 80 | |
| 81 .. highlight:: json | |
| 82 | |
| 83 Once Orthanc is installed and the database is created, you must add a | |
| 84 section in the :ref:`configuration file <configuration>` that | |
| 85 specifies the address of the **MySQL/MariaDB server together with your | |
| 86 credentials**. You also have to tell Orthanc in which path it can find | |
| 87 the plugins: This is done by properly modifying the ``Plugins`` | |
| 88 option. You could for instance adapt the following configuration | |
| 89 file:: | |
| 90 | |
| 91 { | |
| 92 "Name" : "MyOrthanc", | |
| 93 "MySQL" : { | |
| 94 "EnableIndex" : true, | |
| 95 "EnableStorage" : true, | |
| 158 | 96 "Host" : "localhost", // For TCP connections (notably Windows) |
| 97 "Port" : 3306, // For TCP connections (notably Windows) | |
| 154 | 98 "UnixSocket" : "/var/run/mysqld/mysqld.sock", // For UNIX on localhost |
| 99 "Database" : "orthanc", | |
| 100 "Username" : "orthanc", | |
| 101 "Password" : "orthanc", | |
| 465 | 102 "EnableSsl" : false, // force SSL connections |
| 103 "SslVerifyServerCertificates": true, // verify server certificates if EnableSsl is true | |
| 104 "SslCACertificates": "", // path to CA certificates to validate servers | |
| 154 | 105 "Lock" : true // See section about Locking |
| 106 }, | |
| 107 "Plugins" : [ | |
| 108 "/home/user/orthanc-databases/BuildMySQL/libOrthancMySQLIndex.so", | |
| 109 "/home/user/orthanc-databases/BuildMySQL/libOrthancMySQLStorage.so" | |
| 110 ] | |
| 111 } | |
| 112 | |
| 158 | 113 **Important 1:** The ``EnableIndex`` and ``EnableStorage`` options must |
| 154 | 114 be explicitly set to ``true``, otherwise Orthanc will continue to use |
| 115 its default SQLite back-end and the filesystem storage area. | |
| 116 | |
| 158 | 117 **Important 2:** To force a TCP connection on the ``localhost`` in |
| 118 UNIX (i.e. to instruct Orthanc not to use UNIX socket), the | |
| 119 ``UnixSocket`` can be set to the empty string. | |
| 120 | |
| 465 | 121 **Remark:** To force using a TLS connection, you must set ``EnableSsl`` |
| 122 to ``true``. Once ``EnableSsl`` is ``true``, the ``SslVerifyServerCertificates`` | |
| 123 enables the check of server certificates (``true`` by default). | |
| 124 The CA certificates used to verify the server certificate can be defined | |
| 125 through ``SslCACertificates``; if not defined or empty, the value of the global | |
| 126 Orthanc configuration ``HttpsCACertificates`` is used. These options have been | |
| 127 introduced in the mainline in July 2020 and have not yet been released. | |
| 128 | |
| 154 | 129 **Remark:** When using the ``Storage`` MySQL plugin, the DICOM files |
| 158 | 130 are stored as blobs in the database. This might actually consume more |
| 154 | 131 space than the DICOM file itself. |
| 132 | |
| 133 Note that a typical usage of the MySQL plugin is to enable only the | |
| 134 ``Index``, using the default filesystem storage for DICOM files. | |
| 135 | |
| 136 | |
| 137 | |
| 138 .. highlight:: text | |
| 139 | |
| 140 Orthanc must of course be **restarted** after the modification of its | |
| 141 configuration file. The log will contain an output similar to:: | |
| 142 | |
| 143 $ ./Orthanc Configuration.json | |
| 144 W0710 14:25:35.143828 main.cpp:1298] Orthanc version: 1.3.2 | |
| 145 W0710 14:25:35.146528 OrthancInitialization.cpp:120] Reading the configuration from: "./Configuration.json" | |
| 146 [...] | |
| 147 W0710 14:25:35.173652 main.cpp:671] Loading plugin(s) from: /home/jodogne/Subversion/orthanc-databases/BuildMySQL/libOrthancMySQLIndex.so | |
| 148 W0710 14:25:35.175927 PluginsManager.cpp:269] Registering plugin 'mysql-index' (version mainline) | |
| 149 W0710 14:25:35.176213 PluginsManager.cpp:168] Performance warning: The database index plugin was compiled against an old version of the Orthanc SDK, consider upgrading | |
| 150 W0710 14:25:35.176323 main.cpp:671] Loading plugin(s) from: /home/jodogne/Subversion/orthanc-databases/BuildMySQL/libOrthancMySQLStorage.so | |
| 151 W0710 14:25:35.177172 PluginsManager.cpp:269] Registering plugin 'mysql-storage' (version mainline) | |
| 152 W0710 14:25:35.180684 PluginsManager.cpp:168] Your MySQL server cannot store DICOM files larger than 16MB | |
| 153 W0710 14:25:35.180714 PluginsManager.cpp:168] => Consider increasing "max_allowed_packet" in "my.cnf" if this limit is insufficient for your use | |
| 154 W0710 14:25:35.246150 main.cpp:1098] Using a custom database from plugins | |
| 155 W0710 14:25:35.246210 main.cpp:1109] Using a custom storage area from plugins | |
| 156 [...] | |
| 157 W0710 14:25:37.073633 main.cpp:683] Orthanc has started | |
| 158 | |
| 159 | |
| 160 | |
| 161 Advanced options | |
| 162 ---------------- | |
| 163 | |
| 164 Several advanced options are available as well to fine-tune the | |
| 165 configuration of the MySQL plugins. They are documented below. | |
| 166 | |
| 167 | |
| 168 Locking | |
| 169 ^^^^^^^ | |
| 170 | |
| 171 .. highlight:: json | |
| 172 | |
| 173 By default, the plugins lock the database (using `MySQL/MariaDB | |
| 174 "GET_LOCK()" | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
270
diff
changeset
|
175 <https://dev.mysql.com/doc/refman/8.0/en/locking-functions.html>`__) |
| 154 | 176 to prevent other instances of Orthanc from using the same database. If |
| 177 you want several instances of Orthanc to share the same database, set | |
| 178 the ``Lock`` option to ``false`` in the configuration file. | |
| 179 | |
|
270
f29d75bc5c25
more info about database locking
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
231
diff
changeset
|
180 In the absence of locking, the same limitation apply to the |
|
f29d75bc5c25
more info about database locking
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
231
diff
changeset
|
181 MySQL/MariaDB plugins than to the PostgreSQL plugins (i.e. at most one |
|
f29d75bc5c25
more info about database locking
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
231
diff
changeset
|
182 instance of Orthanc writing to the database). For more information, |
|
f29d75bc5c25
more info about database locking
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
231
diff
changeset
|
183 please check out the :ref:`documentation for PostgreSQL |
|
f29d75bc5c25
more info about database locking
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
231
diff
changeset
|
184 <postgresql-lock>`. |
| 438 | 185 |
| 186 Scalability | |
| 187 ^^^^^^^^^^^ | |
| 188 | |
| 189 When configuring your MySQL plugin, ensure you've read the :ref:`scalability section | |
| 190 <scalability>` |