Mercurial > hg > orthanc-book

comparison Sphinx/source/plugins/mysql.rst @ 154:365427cebb64

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mysql
author Sebastien Jodogne <s.jodogne@gmail.com>
date Tue, 10 Jul 2018 14:45:40 +0200
parents
children 86be4710bbae
comparison
equal deleted inserted replaced
153:008091376e7a 154:365427cebb64
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
16
17
18 Compilation
19 -----------
20
21 Static linking
22 ^^^^^^^^^^^^^^
23
24 .. highlight:: text
25
26 The procedure to compile these plugins is similar to that for the
27 :ref:`core of Orthanc <compiling>`. The following commands should work
28 for most UNIX-like distribution (including GNU/Linux)::
29
30 $ mkdir BuildMySQL
31 $ cd BuildMySQL
32 $ cmake ../MySQL/ -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
33 $ make
34
35 The compilation will produce 2 shared libraries, each containing one plugin for Orthanc:
36
37 * ``OrthancMySQLIndex`` replaces the default SQLite index of Orthanc by MySQL.
38 * ``OrthancMySQLStorage`` makes Orthanc store the DICOM files it receives into MySQL.
39
40
41 Microsoft Windows
42 ^^^^^^^^^^^^^^^^^
43
44 Pre-compiled binaries for Microsoft Windows `are also available
45 <http://www.orthanc-server.com/browse.php?path=/plugin-mysql>`__.
46
47
48 Dynamic linking on Ubuntu 16.04
49 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
50
51 .. highlight:: text
52
53 If static linking is not desired, here are build instructions for
54 Ubuntu 16.04 (provided build dependencies for the :ref:`core of
55 Orthanc <compiling>` have already been installed)::
56
57 $ sudo apt-get install libmysqlclient-dev
58 $ mkdir BuildMySQL
59 $ cd BuildMySQL
60 $ cmake ../MySQL/ -DCMAKE_BUILD_TYPE=Release \
61 -DALLOW_DOWNLOADS=ON \
62 -DUSE_SYSTEM_GOOGLE_TEST=OFF \
63 -DUSE_SYSTEM_ORTHANC_SDK=OFF
64 $ make
65
66
67 Usage
68 -----
69
70 You of course first have to :ref:`install Orthanc <binaries>`, with a
71 version above 0.9.5. You then have to **create a database** dedicated
72 to Orthanc on some MySQL/MariaDB server. Please refer to the `MySQL
73 documentation
74 <https://dev.mysql.com/doc/refman/8.0/en/database-use.html>`__.
75
76 .. highlight:: json
77
78 Once Orthanc is installed and the database is created, you must add a
79 section in the :ref:`configuration file <configuration>` that
80 specifies the address of the **MySQL/MariaDB server together with your
81 credentials**. You also have to tell Orthanc in which path it can find
82 the plugins: This is done by properly modifying the ``Plugins``
83 option. You could for instance adapt the following configuration
84 file::
85
86 {
87 "Name" : "MyOrthanc",
88 "MySQL" : {
89 "EnableIndex" : true,
90 "EnableStorage" : true,
91 "Host" : "localhost", // For Windows or network connections
92 "Port" : 3306, // For Windows or network connections
93 "UnixSocket" : "/var/run/mysqld/mysqld.sock", // For UNIX on localhost
94 "Database" : "orthanc",
95 "Username" : "orthanc",
96 "Password" : "orthanc",
97 "Lock" : true // See section about Locking
98 },
99 "Plugins" : [
100 "/home/user/orthanc-databases/BuildMySQL/libOrthancMySQLIndex.so",
101 "/home/user/orthanc-databases/BuildMySQL/libOrthancMySQLStorage.so"
102 ]
103 }
104
105 **Important:** The ``EnableIndex`` and ``EnableStorage`` options must
106 be explicitly set to ``true``, otherwise Orthanc will continue to use
107 its default SQLite back-end and the filesystem storage area.
108
109 **Remark:** When using the ``Storage`` MySQL plugin, the DICOM files
110 are stored as blobs in the database. This might actually consume more
111 space than the DICOM file itself.
112
113 Note that a typical usage of the MySQL plugin is to enable only the
114 ``Index``, using the default filesystem storage for DICOM files.
115
116
117
118 .. highlight:: text
119
120 Orthanc must of course be **restarted** after the modification of its
121 configuration file. The log will contain an output similar to::
122
123 $ ./Orthanc Configuration.json
124 W0710 14:25:35.143828 main.cpp:1298] Orthanc version: 1.3.2
125 W0710 14:25:35.146528 OrthancInitialization.cpp:120] Reading the configuration from: "./Configuration.json"
126 [...]
127 W0710 14:25:35.173652 main.cpp:671] Loading plugin(s) from: /home/jodogne/Subversion/orthanc-databases/BuildMySQL/libOrthancMySQLIndex.so
128 W0710 14:25:35.175927 PluginsManager.cpp:269] Registering plugin 'mysql-index' (version mainline)
129 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
130 W0710 14:25:35.176323 main.cpp:671] Loading plugin(s) from: /home/jodogne/Subversion/orthanc-databases/BuildMySQL/libOrthancMySQLStorage.so
131 W0710 14:25:35.177172 PluginsManager.cpp:269] Registering plugin 'mysql-storage' (version mainline)
132 W0710 14:25:35.180684 PluginsManager.cpp:168] Your MySQL server cannot store DICOM files larger than 16MB
133 W0710 14:25:35.180714 PluginsManager.cpp:168] => Consider increasing "max_allowed_packet" in "my.cnf" if this limit is insufficient for your use
134 W0710 14:25:35.246150 main.cpp:1098] Using a custom database from plugins
135 W0710 14:25:35.246210 main.cpp:1109] Using a custom storage area from plugins
136 [...]
137 W0710 14:25:37.073633 main.cpp:683] Orthanc has started
138
139
140
141 Advanced options
142 ----------------
143
144 Several advanced options are available as well to fine-tune the
145 configuration of the MySQL plugins. They are documented below.
146
147
148 Locking
149 ^^^^^^^
150
151 .. highlight:: json
152
153 By default, the plugins lock the database (using `MySQL/MariaDB
154 "GET_LOCK()"
155 <https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html#function_get-lock>`__)
156 to prevent other instances of Orthanc from using the same database. If
157 you want several instances of Orthanc to share the same database, set
158 the ``Lock`` option to ``false`` in the configuration file.
159
160 Obviously, one must be very cautious when sharing the same database
161 between instances of Orthanc. In particular, all these instances
162 should share the same configuration.