Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/mysql.rst @ 336:a5f7fc9fb611
Orthanc 1.6.0
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Wed, 18 Mar 2020 15:15:39 +0100 |
| parents | f29d75bc5c25 |
| children | 011b01ccf52d |
| 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 | |
| 14 plugins <http://www.orthanc-server.com/static.php?page=mysql>`__. | |
| 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 | |
| 50 <http://www.orthanc-server.com/browse.php?path=/plugin-mysql>`__. | |
| 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", | |
| 102 "Lock" : true // See section about Locking | |
| 103 }, | |
| 104 "Plugins" : [ | |
| 105 "/home/user/orthanc-databases/BuildMySQL/libOrthancMySQLIndex.so", | |
| 106 "/home/user/orthanc-databases/BuildMySQL/libOrthancMySQLStorage.so" | |
| 107 ] | |
| 108 } | |
| 109 | |
| 158 | 110 **Important 1:** The ``EnableIndex`` and ``EnableStorage`` options must |
| 154 | 111 be explicitly set to ``true``, otherwise Orthanc will continue to use |
| 112 its default SQLite back-end and the filesystem storage area. | |
| 113 | |
| 158 | 114 **Important 2:** To force a TCP connection on the ``localhost`` in |
| 115 UNIX (i.e. to instruct Orthanc not to use UNIX socket), the | |
| 116 ``UnixSocket`` can be set to the empty string. | |
| 117 | |
| 154 | 118 **Remark:** When using the ``Storage`` MySQL plugin, the DICOM files |
| 158 | 119 are stored as blobs in the database. This might actually consume more |
| 154 | 120 space than the DICOM file itself. |
| 121 | |
| 122 Note that a typical usage of the MySQL plugin is to enable only the | |
| 123 ``Index``, using the default filesystem storage for DICOM files. | |
| 124 | |
| 125 | |
| 126 | |
| 127 .. highlight:: text | |
| 128 | |
| 129 Orthanc must of course be **restarted** after the modification of its | |
| 130 configuration file. The log will contain an output similar to:: | |
| 131 | |
| 132 $ ./Orthanc Configuration.json | |
| 133 W0710 14:25:35.143828 main.cpp:1298] Orthanc version: 1.3.2 | |
| 134 W0710 14:25:35.146528 OrthancInitialization.cpp:120] Reading the configuration from: "./Configuration.json" | |
| 135 [...] | |
| 136 W0710 14:25:35.173652 main.cpp:671] Loading plugin(s) from: /home/jodogne/Subversion/orthanc-databases/BuildMySQL/libOrthancMySQLIndex.so | |
| 137 W0710 14:25:35.175927 PluginsManager.cpp:269] Registering plugin 'mysql-index' (version mainline) | |
| 138 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 | |
| 139 W0710 14:25:35.176323 main.cpp:671] Loading plugin(s) from: /home/jodogne/Subversion/orthanc-databases/BuildMySQL/libOrthancMySQLStorage.so | |
| 140 W0710 14:25:35.177172 PluginsManager.cpp:269] Registering plugin 'mysql-storage' (version mainline) | |
| 141 W0710 14:25:35.180684 PluginsManager.cpp:168] Your MySQL server cannot store DICOM files larger than 16MB | |
| 142 W0710 14:25:35.180714 PluginsManager.cpp:168] => Consider increasing "max_allowed_packet" in "my.cnf" if this limit is insufficient for your use | |
| 143 W0710 14:25:35.246150 main.cpp:1098] Using a custom database from plugins | |
| 144 W0710 14:25:35.246210 main.cpp:1109] Using a custom storage area from plugins | |
| 145 [...] | |
| 146 W0710 14:25:37.073633 main.cpp:683] Orthanc has started | |
| 147 | |
| 148 | |
| 149 | |
| 150 Advanced options | |
| 151 ---------------- | |
| 152 | |
| 153 Several advanced options are available as well to fine-tune the | |
| 154 configuration of the MySQL plugins. They are documented below. | |
| 155 | |
| 156 | |
| 157 Locking | |
| 158 ^^^^^^^ | |
| 159 | |
| 160 .. highlight:: json | |
| 161 | |
| 162 By default, the plugins lock the database (using `MySQL/MariaDB | |
| 163 "GET_LOCK()" | |
| 164 <https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html#function_get-lock>`__) | |
| 165 to prevent other instances of Orthanc from using the same database. If | |
| 166 you want several instances of Orthanc to share the same database, set | |
| 167 the ``Lock`` option to ``false`` in the configuration file. | |
| 168 | |
|
270
f29d75bc5c25
more info about database locking
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
231
diff
changeset
|
169 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
|
170 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
|
171 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
|
172 please check out the :ref:`documentation for PostgreSQL |
|
f29d75bc5c25
more info about database locking
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
231
diff
changeset
|
173 <postgresql-lock>`. |