annotate Sphinx/source/plugins/mysql.rst @ 708:cd70d23f34bc

Lookup DICOM dictionary in Python scripts
author Sebastien Jodogne <s.jodogne@gmail.com>
date Fri, 11 Jun 2021 14:09:21 +0200
parents 96574b57249a
children 8b8df1be0cf9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
154
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. _mysql:
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 MySQL/MariaDB plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5 =====================
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
6
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
7 .. contents::
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
8
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
9 The Orthanc project provides two **official** plugins to replace the
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
10 default storage area (on the filesystem) and the default SQLite index
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
11 by a MySQL or a MariaDB database.
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
12
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
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
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
15
643
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
16 For information about scalability, make sure to read the section about
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
17 :ref:`multiple writers in large-scale deployments <multiple-writers>`.
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
18
230
0a1c9ef57b52 warning
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 158
diff changeset
19 **Warning:** According to `this thread on our discussion group
231
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 230
diff changeset
20 <https://groups.google.com/d/msg/orthanc-users/yV3LSTh_TjI/Fb4ShaYMBAAJ>`__,
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 230
diff changeset
21 the MySQL/MariaDB plugins require MySQL 8.x if running on Microsoft
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 230
diff changeset
22 Windows.
230
0a1c9ef57b52 warning
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 158
diff changeset
23
154
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
24
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
25
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
26 Compilation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
27 -----------
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
28
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
29 Static linking
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
30 ^^^^^^^^^^^^^^
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
31
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
32 .. highlight:: text
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
33
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
34 The procedure to compile these plugins is similar to that for the
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
35 :ref:`core of Orthanc <compiling>`. The following commands should work
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
36 for most UNIX-like distribution (including GNU/Linux)::
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
37
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
38 $ mkdir BuildMySQL
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
39 $ cd BuildMySQL
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
40 $ cmake ../MySQL/ -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
41 $ make
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
42
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
43 The compilation will produce 2 shared libraries, each containing one plugin for Orthanc:
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
44
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
45 * ``OrthancMySQLIndex`` replaces the default SQLite index of Orthanc by MySQL.
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
46 * ``OrthancMySQLStorage`` makes Orthanc store the DICOM files it receives into MySQL.
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
47
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
48
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
49 Microsoft Windows
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
50 ^^^^^^^^^^^^^^^^^
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
51
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
52 Pre-compiled binaries for Microsoft Windows `are also available
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 270
diff changeset
53 <https://www.orthanc-server.com/browse.php?path=/plugin-mysql>`__.
154
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
54
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
55
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
56 Dynamic linking on Ubuntu 16.04
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
57 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
58
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
59 .. highlight:: text
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
60
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
61 If static linking is not desired, here are build instructions for
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
62 Ubuntu 16.04 (provided build dependencies for the :ref:`core of
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
63 Orthanc <compiling>` have already been installed)::
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
64
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
65 $ sudo apt-get install libmysqlclient-dev
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
66 $ mkdir BuildMySQL
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
67 $ cd BuildMySQL
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
68 $ cmake ../MySQL/ -DCMAKE_BUILD_TYPE=Release \
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
69 -DALLOW_DOWNLOADS=ON \
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
70 -DUSE_SYSTEM_GOOGLE_TEST=OFF \
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
71 -DUSE_SYSTEM_ORTHANC_SDK=OFF
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
72 $ make
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
73
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
74
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
75 Usage
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
76 -----
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
77
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
78 You of course first have to :ref:`install Orthanc <binaries>`, with a
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
79 version above 0.9.5. You then have to **create a database** dedicated
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
80 to Orthanc on some MySQL/MariaDB server. Please refer to the `MySQL
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
81 documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
82 <https://dev.mysql.com/doc/refman/8.0/en/database-use.html>`__.
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
83
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
84 .. highlight:: json
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
85
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
86 Once Orthanc is installed and the database is created, you must add a
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
87 section in the :ref:`configuration file <configuration>` that
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
88 specifies the address of the **MySQL/MariaDB server together with your
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
89 credentials**. You also have to tell Orthanc in which path it can find
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
90 the plugins: This is done by properly modifying the ``Plugins``
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
91 option. You could for instance adapt the following configuration
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
92 file::
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
93
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
94 {
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
95 "Name" : "MyOrthanc",
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
96 "MySQL" : {
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
97 "EnableIndex" : true,
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
98 "EnableStorage" : true,
158
86be4710bbae note about sockets
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 154
diff changeset
99 "Host" : "localhost", // For TCP connections (notably Windows)
86be4710bbae note about sockets
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 154
diff changeset
100 "Port" : 3306, // For TCP connections (notably Windows)
154
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
101 "UnixSocket" : "/var/run/mysqld/mysqld.sock", // For UNIX on localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
102 "Database" : "orthanc",
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
103 "Username" : "orthanc",
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
104 "Password" : "orthanc",
465
5bb6bc85f99f mysql new options
Alain Mazy <alain@mazy.be>
parents: 438
diff changeset
105 "EnableSsl" : false, // force SSL connections
643
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
106 "SslVerifyServerCertificates": true, // Verify server certificates if EnableSsl is true
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
107 "SslCACertificates": "", // Path to CA certificates to validate servers
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
108 "Lock" : true, // See section about Locking
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
109 "MaximumConnectionRetries" : 10, // New in release 3.0
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
110 "ConnectionRetryInterval" : 5, // New in release 3.0
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
111 "IndexConnectionsCount" : 1 // New in release 4.0
154
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
112 },
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
113 "Plugins" : [
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
114 "/home/user/orthanc-databases/BuildMySQL/libOrthancMySQLIndex.so",
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
115 "/home/user/orthanc-databases/BuildMySQL/libOrthancMySQLStorage.so"
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
116 ]
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
117 }
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
118
158
86be4710bbae note about sockets
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 154
diff changeset
119 **Important 1:** The ``EnableIndex`` and ``EnableStorage`` options must
154
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
120 be explicitly set to ``true``, otherwise Orthanc will continue to use
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
121 its default SQLite back-end and the filesystem storage area.
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
122
158
86be4710bbae note about sockets
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 154
diff changeset
123 **Important 2:** To force a TCP connection on the ``localhost`` in
86be4710bbae note about sockets
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 154
diff changeset
124 UNIX (i.e. to instruct Orthanc not to use UNIX socket), the
86be4710bbae note about sockets
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 154
diff changeset
125 ``UnixSocket`` can be set to the empty string.
86be4710bbae note about sockets
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 154
diff changeset
126
465
5bb6bc85f99f mysql new options
Alain Mazy <alain@mazy.be>
parents: 438
diff changeset
127 **Remark:** To force using a TLS connection, you must set ``EnableSsl``
5bb6bc85f99f mysql new options
Alain Mazy <alain@mazy.be>
parents: 438
diff changeset
128 to ``true``. Once ``EnableSsl`` is ``true``, the ``SslVerifyServerCertificates``
5bb6bc85f99f mysql new options
Alain Mazy <alain@mazy.be>
parents: 438
diff changeset
129 enables the check of server certificates (``true`` by default).
5bb6bc85f99f mysql new options
Alain Mazy <alain@mazy.be>
parents: 438
diff changeset
130 The CA certificates used to verify the server certificate can be defined
5bb6bc85f99f mysql new options
Alain Mazy <alain@mazy.be>
parents: 438
diff changeset
131 through ``SslCACertificates``; if not defined or empty, the value of the global
5bb6bc85f99f mysql new options
Alain Mazy <alain@mazy.be>
parents: 438
diff changeset
132 Orthanc configuration ``HttpsCACertificates`` is used. These options have been
5bb6bc85f99f mysql new options
Alain Mazy <alain@mazy.be>
parents: 438
diff changeset
133 introduced in the mainline in July 2020 and have not yet been released.
5bb6bc85f99f mysql new options
Alain Mazy <alain@mazy.be>
parents: 438
diff changeset
134
154
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
135 **Remark:** When using the ``Storage`` MySQL plugin, the DICOM files
158
86be4710bbae note about sockets
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 154
diff changeset
136 are stored as blobs in the database. This might actually consume more
154
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
137 space than the DICOM file itself.
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
138
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
139 Note that a typical usage of the MySQL plugin is to enable only the
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
140 ``Index``, using the default filesystem storage for DICOM files.
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
141
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
142
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
143
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
144 .. highlight:: text
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
145
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
146 Orthanc must of course be **restarted** after the modification of its
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
147 configuration file. The log will contain an output similar to::
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
148
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
149 $ ./Orthanc Configuration.json
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
150 W0710 14:25:35.143828 main.cpp:1298] Orthanc version: 1.3.2
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
151 W0710 14:25:35.146528 OrthancInitialization.cpp:120] Reading the configuration from: "./Configuration.json"
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
152 [...]
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
153 W0710 14:25:35.173652 main.cpp:671] Loading plugin(s) from: /home/jodogne/Subversion/orthanc-databases/BuildMySQL/libOrthancMySQLIndex.so
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
154 W0710 14:25:35.175927 PluginsManager.cpp:269] Registering plugin 'mysql-index' (version mainline)
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
155 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
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
156 W0710 14:25:35.176323 main.cpp:671] Loading plugin(s) from: /home/jodogne/Subversion/orthanc-databases/BuildMySQL/libOrthancMySQLStorage.so
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
157 W0710 14:25:35.177172 PluginsManager.cpp:269] Registering plugin 'mysql-storage' (version mainline)
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
158 W0710 14:25:35.180684 PluginsManager.cpp:168] Your MySQL server cannot store DICOM files larger than 16MB
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
159 W0710 14:25:35.180714 PluginsManager.cpp:168] => Consider increasing "max_allowed_packet" in "my.cnf" if this limit is insufficient for your use
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
160 W0710 14:25:35.246150 main.cpp:1098] Using a custom database from plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
161 W0710 14:25:35.246210 main.cpp:1109] Using a custom storage area from plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
162 [...]
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
163 W0710 14:25:37.073633 main.cpp:683] Orthanc has started
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
164
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
165
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
166
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
167 Advanced options
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
168 ----------------
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
169
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
170 Several advanced options are available as well to fine-tune the
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
171 configuration of the MySQL plugins. They are documented below.
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
172
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
173
643
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
174 .. _mysql-multiple-writers:
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
175
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
176 Multiple writers or connections
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
177 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
178
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
179 Starting with Orthanc 1.9.2 and MySQL 4.0, it is possible to use
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
180 :ref:`multiple writers or connections in large-scale deployments
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
181 <multiple-writers>`. Here is the list of configuration that control
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
182 this behavior:
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
183
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
184 * ``Lock`` must be set to ``false`` (cf. :ref:`below <mysql-lock>`)
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
185
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
186 * ``MaximumConnectionRetries`` governs how many times Orthanc tries to
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
187 connect to the database, as well as how many times Orthanc replays
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
188 transactions to deal with collisions between multiple writers.
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
189
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
190 * ``IndexConnectionsCount`` controls the number of connections from
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
191 the index plugin to the MySQL database. It is set to ``1`` by
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
192 default, which corresponds to the old behavior of Orthanc <= 1.9.1.
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
193
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
194 * ``ConnectionRetryInterval`` is only used when opening one database
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
195 connection to MySQL.
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
196
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
197 * As of release 4.0, the MySQL plugin does **not** support yet the
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
198 :ref:`revision mechanism <revisions>` to protect metadata and
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
199 attachments from concurrent modifications.
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
200
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 465
diff changeset
201
154
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
202 Locking
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
203 ^^^^^^^
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
204
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
205 .. highlight:: json
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
206
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
207 By default, the plugins lock the database (using `MySQL/MariaDB
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
208 "GET_LOCK()"
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 270
diff changeset
209 <https://dev.mysql.com/doc/refman/8.0/en/locking-functions.html>`__)
154
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
210 to prevent other instances of Orthanc from using the same database. If
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
211 you want several instances of Orthanc to share the same database, set
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
212 the ``Lock`` option to ``false`` in the configuration file.
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
213
270
f29d75bc5c25 more info about database locking
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 231
diff changeset
214 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
215 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
216 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
217 please check out the :ref:`documentation for PostgreSQL
f29d75bc5c25 more info about database locking
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 231
diff changeset
218 <postgresql-lock>`.
438
5d6d593bceb6 scalability section
Alain Mazy <alain@mazy.be>
parents: 358
diff changeset
219
5d6d593bceb6 scalability section
Alain Mazy <alain@mazy.be>
parents: 358
diff changeset
220 Scalability
5d6d593bceb6 scalability section
Alain Mazy <alain@mazy.be>
parents: 358
diff changeset
221 ^^^^^^^^^^^
5d6d593bceb6 scalability section
Alain Mazy <alain@mazy.be>
parents: 358
diff changeset
222
684
96574b57249a mysqldump
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
223 When configuring your MySQL plugin, ensure you've read the
96574b57249a mysqldump
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
224 :ref:`scalability section <scalability>`
96574b57249a mysqldump
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
225
96574b57249a mysqldump
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
226
96574b57249a mysqldump
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
227 Backup
96574b57249a mysqldump
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
228 ------
96574b57249a mysqldump
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
229
96574b57249a mysqldump
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
230 The MySQL plugin uses stored routines (i.e. functions/procedures) that
96574b57249a mysqldump
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
231 are not archived by default by the ``mysqldump`` tool. As a
96574b57249a mysqldump
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
232 consequence, make sure to add the ``--routines`` command-line flag to
96574b57249a mysqldump
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
233 also archive such routines in your backup.