|
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
|
|
|
169 Obviously, one must be very cautious when sharing the same database
|
|
|
170 between instances of Orthanc. In particular, all these instances
|
|
|
171 should share the same configuration.
|
