annotate Sphinx/source/plugins/mysql.rst @ 927:dfe96daba4f8

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