Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/odbc.rst @ 1113:a588960a72e5 default tip
spelling
| author | Alain Mazy <am@orthanc.team> |
|---|---|
| date | Mon, 28 Oct 2024 09:23:08 +0100 |
| parents | 17bf6fafb884 |
| children |
| rev | line source |
|---|---|
| 750 | 1 .. _odbc: |
| 2 | |
| 3 | |
| 4 ODBC 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 `ODBC database | |
| 12 <https://en.wikipedia.org/wiki/Open_Database_Connectivity>`__. This | |
| 13 can notably be used to connect Orthanc to Microsoft SQL Server. | |
| 14 | |
| 15 The source code of the ODBC plugins can be found in the | |
| 16 ``orthanc-databases`` `Mercurial repository | |
|
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
789
diff
changeset
|
17 <https://orthanc.uclouvain.be/hg/orthanc-databases/>`__, next to the |
| 750 | 18 source code of the :ref:`PostgreSQL <postgresql>` and |
| 19 :ref:`MySQL/MariaDB <mysql>` plugins. | |
| 20 | |
| 21 | |
| 22 When to use ODBC? | |
| 23 ----------------- | |
| 24 | |
| 25 In general, you'll always get better performance by using native C/C++ | |
| 26 plugins dedicated to one single database engine, instead of the ODBC | |
| 27 plugins that can connect to any database driver. This is the price of | |
| 28 genericity: Some specific optimisations can only be done if focusing | |
| 29 on one single database. | |
| 30 | |
| 31 That being said, there are multiple use cases for the ODBC plugins: | |
| 32 | |
| 751 | 33 * Connection to Microsoft SQL Server (MSSQL), including Microsoft |
| 34 Azure SQL, is only possible with ODBC. Note that the ODBC plugins | |
| 35 were only validated against MSSQL 2017 and MSSQL 2019, under | |
| 36 GNU/Linux. | |
| 750 | 37 |
| 38 * Contrarily to the built-in SQLite engine and to the MySQL/MariaDB | |
| 39 index plugin, the ODBC index plugin supports the :ref:`revision | |
| 40 mechanism <revisions>` to protect metadata and attachments from | |
| 41 concurrent modifications. | |
| 42 | |
| 43 * Because of its genericity, the ODBC storage area plugin does not | |
| 44 implement the :ref:`read-range primitive <registry>`. As a | |
| 45 consequence, using it will write two attachments for each stored | |
| 46 DICOM instance (namely, ``Attachment 1`` that corresponds to the | |
| 47 DICOM instance itself, and ``Attachment 3`` that corresponds to the | |
| 48 tags before the pixel data). | |
| 49 | |
| 50 * The Linux Standard Base (LSB) `pre-compiled binaries | |
|
993
05b106383b2a
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
991
diff
changeset
|
51 <https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc-odbc/index.html>`__ of the ODBC plugins |
| 750 | 52 are not compatible with the ``libsqliteodbc`` `Debian/Ubuntu package |
| 53 <http://www.ch-werner.de/sqliteodbc/>`__ because the latter package | |
| 54 was compiled with the ``HAVE_SQLITE3LOADEXTENSION`` flag. | |
| 55 | |
| 56 * Finally, make sure to read the :ref:`recommended setup for best | |
| 57 scalability <scalability>`. | |
| 58 | |
| 59 Very importantly, pay attention to the fact that the ODBC plugins use | |
| 60 a different database schema than the built-in SQLite driver, and than | |
| 61 the PostgreSQL/MariaDB/MySQL plugins. As a consequence, it is **not | |
| 62 possible to switch back and forth** between ODBC and the native | |
| 63 drivers without running a :ref:`full replication procedure | |
| 64 <replication>`. As a consequence, pay attention to choose the right | |
| 65 plugin from the beginning, as you will need to stick to it. | |
| 66 | |
| 67 Summarizing, here are two tables containing our recommendations about | |
| 68 when to use the ODBC plugins: | |
| 69 | |
| 70 +------------------------------+--------------------------------------------------------+ | |
| 71 | Database management system | Recommended index plugin | | |
| 72 +==============================+========================================================+ | |
| 73 | Microsoft SQL server (MSSQL) | ODBC plugin | | |
| 751 | 74 | or Microsoft Azure SQL | | |
| 750 | 75 +------------------------------+--------------------------------------------------------+ |
| 76 | MySQL (with revisions) | ODBC plugin | | |
| 77 +------------------------------+--------------------------------------------------------+ | |
| 78 | MySQL (without revisions) | :ref:`MySQL plugin <mysql>` | | |
| 79 +------------------------------+--------------------------------------------------------+ | |
| 80 | PostgreSQL | :ref:`PostgreSQL plugin <postgresql>` | | |
| 81 +------------------------------+--------------------------------------------------------+ | |
| 82 | SQLite (with revisions) | ODBC plugin | | |
| 83 +------------------------------+--------------------------------------------------------+ | |
| 84 | SQLite (without revisions) | No plugin needed | | |
| 85 +------------------------------+--------------------------------------------------------+ | |
| 86 | Other | Create a :ref:`dedicated plugin <creating-plugins>` | | |
| 87 | | or implement a new dialect in the ODBC plugins | | |
| 88 +------------------------------+--------------------------------------------------------+ | |
| 89 | |
| 90 | |
| 91 +------------------------------+--------------------------------------------------------+ | |
| 92 | Type of storage area | Recommended storage plugin | | |
| 93 +==============================+========================================================+ | |
| 94 | Filesystem | No plugin needed | | |
| 95 +------------------------------+--------------------------------------------------------+ | |
| 96 | Microsoft SQL server (MSSQL) | ODBC plugin | | |
| 751 | 97 | or Microsoft Azure SQL | | |
| 750 | 98 +------------------------------+--------------------------------------------------------+ |
| 99 | MySQL | :ref:`MySQL plugin <mysql>` | | |
| 100 +------------------------------+--------------------------------------------------------+ | |
| 101 | PostgreSQL | :ref:`PostgreSQL plugin <postgresql>` | | |
| 102 +------------------------------+--------------------------------------------------------+ | |
| 103 | SQLite | ODBC plugin | | |
| 104 +------------------------------+--------------------------------------------------------+ | |
| 105 | Google Cloud Storage, Azure | :ref:`Cloud object storage plugins <object-storage>` | | |
| 106 | blob storage, AWS S3 | | | |
| 107 +------------------------------+--------------------------------------------------------+ | |
| 108 | Other | Create a :ref:`dedicated plugin <creating-plugins>`, | | |
| 109 | | implement a new dialect in the ODBC plugins, | | |
| 110 | | or prototype using :ref:`Python <python_storage_area>` | | |
| 111 +------------------------------+--------------------------------------------------------+ | |
| 112 | |
| 113 | |
| 114 Compilation | |
| 115 ----------- | |
| 116 | |
| 117 Static linking | |
| 118 ^^^^^^^^^^^^^^ | |
| 119 | |
| 120 .. highlight:: text | |
| 121 | |
| 122 The procedure to compile these plugins is similar to that for the | |
| 123 :ref:`core of Orthanc <compiling>`. The following commands should work | |
| 124 for most UNIX-like distribution (including GNU/Linux):: | |
| 125 | |
| 126 $ mkdir BuildOdbc | |
| 127 $ cd BuildOdbc | |
| 128 $ cmake ../Odbc -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release | |
| 129 $ make | |
| 130 | |
| 131 The compilation will produce 2 shared libraries, each containing one plugin for Orthanc: | |
| 132 | |
| 133 * ``OrthancOdbcIndex`` replaces the default SQLite index of Orthanc by ODBC. | |
| 134 * ``OrthancOdbcStorage`` makes Orthanc store the DICOM files it receives into ODBC. | |
| 135 | |
| 136 | |
| 137 Microsoft Windows and Apple OS X | |
| 138 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 139 | |
| 140 Pre-compiled binaries for Microsoft Windows 32bit `are also available | |
|
1004
17bf6fafb884
added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
993
diff
changeset
|
141 <https://orthanc.uclouvain.be/downloads/windows-32/orthanc-odbc/index.html>`__, |
|
17bf6fafb884
added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
993
diff
changeset
|
142 as well as for `Apple macOS |
|
17bf6fafb884
added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
993
diff
changeset
|
143 <https://orthanc.uclouvain.be/downloads/macos/orthanc-odbc/index.html>`__. |
| 750 | 144 |
| 145 | |
| 146 .. _odbc-ubuntu1604: | |
| 147 | |
| 148 Dynamic linking on Ubuntu 16.04 | |
| 149 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 150 | |
| 151 .. highlight:: text | |
| 152 | |
| 153 If static linking is not desired, here are build instructions for | |
| 154 Ubuntu 16.04 (provided build dependencies for the :ref:`core of | |
| 155 Orthanc <compiling>` have already been installed):: | |
| 156 | |
| 157 $ sudo apt-get install libodbc1 unixodbc unixodbc-dev | |
| 158 $ mkdir BuildOdbc | |
| 159 $ cd BuildOdbc | |
| 160 $ cmake ../Odbc -DCMAKE_BUILD_TYPE=Release \ | |
| 161 -DALLOW_DOWNLOADS=ON \ | |
| 162 -DUSE_SYSTEM_GOOGLE_TEST=OFF \ | |
| 163 -DUSE_SYSTEM_ORTHANC_SDK=OFF | |
| 164 $ make | |
| 165 | |
| 166 | |
| 167 | |
| 168 Usage | |
| 169 ----- | |
| 170 | |
| 171 You of course first have to :ref:`install Orthanc <binaries>`, with a | |
| 172 version above 0.9.5. You then have to **configure an ODBC data | |
| 173 source** dedicated to Orthanc. The procedure depends upon your | |
| 174 operating system: | |
| 175 | |
| 176 * Many UNIX-like platforms (including Debian and Ubuntu) use `unixODBC | |
| 177 <https://en.wikipedia.org/wiki/UnixODBC>`__. You first have to | |
| 178 install at least one ODBC driver (e.g. on Debian, installing the | |
| 179 packages ``libsqliteodbc`` and ``odbc-postgresql`` will respectively | |
| 180 install the driver for SQLite and for PostgreSQL). Secondly, you | |
| 181 have to edit your ``~/.odbc.ini`` to define the data sources | |
| 182 (i.e. the actual databases). | |
| 183 | |
| 184 * On Microsoft Windows, the configuration tool ``odbcad32.exe`` ("ODBC | |
| 185 Data Source Administrator") allows to define the data sources. You | |
| 186 also have to install at least one ODBC driver. For instance, the | |
| 187 `SQLite ODBC Driver <http://www.ch-werner.de/sqliteodbc/>`__ can be | |
| 188 used to access SQLite. | |
| 189 | |
| 190 * If you are interested in interfacing Orthanc with Microsoft SQL | |
| 191 Server, the corresponding ODBC drivers can be `downloaded from | |
| 192 Microsoft | |
| 193 <https://docs.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server>`__. | |
| 194 | |
| 751 | 195 .. highlight:: json |
| 196 | |
| 750 | 197 Once Orthanc is installed and the data sources have been defined, you |
| 198 must add a section in the :ref:`configuration file <configuration>` | |
| 199 that specifies the **data source(s) to be used**. You also have to | |
| 200 tell Orthanc in which path it can find the plugins: This is done by | |
| 201 properly modifying the ``Plugins`` option. You could for instance | |
| 202 adapt the following configuration file:: | |
| 203 | |
| 204 { | |
| 205 "Name" : "MyOrthanc", | |
| 206 "Odbc" : { | |
| 207 "EnableIndex" : true, | |
| 208 "EnableStorage" : true, | |
| 209 "IndexConnectionString" : "DSN=index", | |
| 210 "StorageConnectionString" : "DSN=storage", | |
| 751 | 211 "MaximumConnectionRetries" : 10, |
| 212 "ConnectionRetryInterval" : 5, | |
| 213 "IndexConnectionsCount" : 1 | |
| 750 | 214 }, |
| 215 "Plugins" : [ | |
| 216 "/home/user/orthanc-databases/BuildOdbc/libOrthancOdbcIndex.so", | |
| 217 "/home/user/orthanc-databases/BuildOdbc/libOrthancOdbcStorage.so" | |
| 218 ] | |
| 219 } | |
| 220 | |
| 221 The values of ``IndexConnectionString`` and | |
| 222 ``StorageConnectionString`` are known as `ODBC connection strings | |
| 223 <https://www.connectionstrings.com/>`__, and define how to connect to | |
| 224 the ODBC data source. These connection strings are specific to the | |
| 225 different types of ODBC drivers. In the following sections, we'll | |
| 226 review connection strings for SQLite, PostgreSQL, MySQL and Microsoft | |
| 227 SQL Server. | |
| 228 | |
| 229 **Important:** The ``EnableIndex`` and ``EnableStorage`` options must | |
| 230 be explicitly set to ``true``, otherwise Orthanc will continue to use | |
| 231 its default SQLite back-end and the filesystem storage area. | |
| 232 | |
| 233 **Remark 1:** When using the ODBC storage area plugin, the DICOM files | |
| 234 are stored as large objects in the database. This might actually | |
| 235 consume more space than the DICOM file itself. | |
| 236 | |
| 237 **Remark 2:** A typical usage of the ODBC plugins is to enable only | |
| 238 the index plugin, and to use the default filesystem storage for DICOM | |
| 239 files (on a NAS with proper disaster recovery strategies). | |
| 240 | |
| 241 Orthanc must of course be **restarted** after the modification of its | |
| 242 configuration file. | |
| 243 | |
| 244 | |
| 245 Supported ODBC drivers | |
| 246 ---------------------- | |
| 247 | |
| 248 The ODBC plugins for Orthanc are universal, in the sense that they can | |
| 249 connect to any ODBC driver. However, there are some minor variations | |
| 250 in the SQL language, that are known as "dialects" in the `source code | |
|
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
789
diff
changeset
|
251 of the plugins <https://orthanc.uclouvain.be/hg/orthanc-databases/>`__. |
| 750 | 252 |
| 253 As of ODBC plugins 1.0, the supported dialects are Microsoft SQL | |
| 254 Server, PostgreSQL, MySQL and SQLite. Orthanc auto-detects the dialect | |
| 255 to be used. Adapting the ODBC plugins to support more dialects should | |
| 256 be fairly easy by adding new values to the | |
| 257 ``OrthancDatabases::Dialect`` enumeration in the C++ source code. | |
| 258 | |
| 259 Also, note that the database for the index and the database for the | |
| 260 storage area can mix different type of ODBC drivers. | |
| 261 | |
| 262 We now review sample `connection strings | |
| 263 <https://www.connectionstrings.com/>`__ for the supported ODBC drivers | |
| 264 under Ubuntu 18.04. | |
| 265 | |
| 266 | |
| 267 Microsoft SQL Server | |
| 268 ^^^^^^^^^^^^^^^^^^^^ | |
| 269 | |
| 270 .. highlight:: bash | |
| 271 | |
| 272 1. Install the `ODBC driver for SQL server | |
| 273 <https://docs.microsoft.com/fr-fr/sql/connect/odbc/download-odbc-driver-for-sql-server>`__ | |
| 274 (version 2017). | |
| 275 | |
| 276 2. A **non-persistent** developer instance of MSSQL 2019 can be | |
| 277 started using the `Docker image provided by Microsoft | |
| 278 <https://hub.docker.com/_/microsoft-mssql-server>`__ as follows:: | |
| 279 | |
| 280 $ docker run --name mssql --rm -t -i -e 'ACCEPT_EULA=Y' -e 'SA_PASSWORD=MyStrOngPa55word!' \ | |
| 281 -e MSSQL_MEMORY_LIMIT_MB=512 -p 1433:1433 mcr.microsoft.com/mssql/server:2019-latest | |
| 282 | |
| 283 3. Create a database dedicated to Orthanc in MSSQL:: | |
| 284 | |
| 285 $ /opt/mssql-tools/bin/sqlcmd -S 192.168.0.17 -U sa -P 'MyStrOngPa55word!' -Q 'CREATE DATABASE orthanctest' | |
| 286 | |
| 287 .. highlight:: text | |
| 288 | |
| 289 4. Create the following sample `unixODBC | |
| 290 <https://en.wikipedia.org/wiki/UnixODBC>`__ configuration file:: | |
| 291 | |
| 292 $ cat ~/.odbc.ini | |
| 293 [orthanctest] | |
| 294 Driver = ODBC Driver 17 for SQL Server | |
| 295 Server = tcp:localhost,1433 | |
| 296 Database = orthanctest | |
| 297 | |
| 298 Note that there exist `many more configuration options | |
| 299 <https://docs.microsoft.com/en-us/sql/relational-databases/native-client/applications/using-connection-string-keywords-with-sql-server-native-client>`__ | |
| 751 | 300 for Microsoft SQL Server. In particular, ``Encrypt`` and |
| 301 ``TrustServerCertificate`` and ``Connect Timeout`` can be | |
| 302 interesting in the case of a connection to Microsoft Azure SQL. | |
| 750 | 303 |
| 304 .. highlight:: json | |
| 305 | |
| 306 5. Start Orthanc using the following :ref:`configuration file | |
| 307 <configuration>` for ODBC:: | |
| 308 | |
| 309 { | |
| 310 "Odbc" : { | |
| 311 "EnableIndex" : true, | |
| 312 "EnableStorage" : true, | |
| 313 "IndexConnectionString" : "DSN=orthanctest;Uid=sa;Pwd=MyStrOngPa55word!", | |
| 314 "StorageConnectionString" : "DSN=orthanctest;Uid=sa;Pwd=MyStrOngPa55word!" | |
| 315 } | |
| 316 } | |
| 317 | |
| 318 In the connection strings: | |
| 319 | |
| 320 * ``DSN`` corresponds to the name of the entry in ``~/.odbc.ini``. | |
| 321 * ``Uid`` is the user name in MSSQL (by default, the Docker image uses ``sa``). | |
| 751 | 322 * ``Pwd`` is the password that has been provided in the ``SA_PASSWORD`` |
| 323 environment variable when starting Docker. | |
| 750 | 324 * For security reasons, the ``Uid`` and ``Pwd`` parameters cannot |
| 325 be set in ``~/.odbc.ini``. | |
| 751 | 326 |
| 327 **Remark:** It is actually not necessary to create an entry in | |
| 328 ``~/.odbc.ini``. All the parameters can indeed be provided directly | |
| 329 in the connection strings, for instance:: | |
| 330 | |
| 331 { | |
| 332 "Odbc" : { | |
| 333 "EnableIndex" : true, | |
| 334 "EnableStorage" : true, | |
| 335 "IndexConnectionString" : "Driver={ODBC Driver 17 for SQL Server};Server=tcp:localhost,1433;Database=orthanctest;Uid=sa;Pwd=MyStrOngPa55word!", | |
| 336 "StorageConnectionString" : "Driver={ODBC Driver 17 for SQL Server};Server=tcp:localhost,1433;Database=orthanctest;Uid=sa;Pwd=MyStrOngPa55word!" | |
| 337 } | |
| 338 } | |
| 339 | |
| 789 | 340 **Remark:** On Windows systems, we have noticed that the ODBC drivers character encoding |
| 341 seems to depend on a system level configuration. This configuration needs to enforce UTF-8. | |
| 342 Therefore, it is advised to configure the system locale as follow: | |
| 343 | |
| 344 .. image:: ../images/odbc-windows-system-locale.png | |
| 345 :align: center | |
| 346 :width: 600px | |
| 347 | |
| 348 | | |
| 751 | 349 |
| 750 | 350 PostgreSQL |
| 351 ^^^^^^^^^^ | |
| 352 | |
| 353 1. Install the ``odbc-postgresql`` package. | |
| 354 | |
| 751 | 355 .. highlight:: text |
| 356 | |
| 750 | 357 2. Create the following sample `unixODBC |
| 358 <https://en.wikipedia.org/wiki/UnixODBC>`__ configuration file:: | |
| 359 | |
| 360 $ cat ~/.odbc.ini | |
| 361 [orthanctest] | |
| 362 Driver = PostgreSQL Unicode | |
| 363 Servername = localhost | |
| 364 Database = orthanctest | |
| 365 UserName = postgres | |
| 366 Password = postgres | |
| 367 Port = 5432 | |
| 368 | |
| 751 | 369 .. highlight:: json |
| 370 | |
| 750 | 371 3. Start Orthanc using the following :ref:`configuration file |
| 372 <configuration>` for ODBC:: | |
| 373 | |
| 374 { | |
| 375 "Odbc" : { | |
| 376 "EnableIndex" : true, | |
| 377 "EnableStorage" : true, | |
| 378 "IndexConnectionString" : "DSN=orthanctest", | |
| 379 "StorageConnectionString" : "DSN=orthanctest" | |
| 380 } | |
| 381 } | |
| 382 | |
| 383 | |
| 384 MySQL | |
| 385 ^^^^^ | |
| 386 | |
| 387 1. Install the official `Connect/ODBC package | |
| 388 <https://dev.mysql.com/downloads/connector/odbc/>`__ (it is not | |
| 389 packaged for Ubuntu 18.04). | |
| 390 | |
| 751 | 391 .. highlight:: text |
| 392 | |
| 750 | 393 2. Create the following sample `unixODBC |
| 394 <https://en.wikipedia.org/wiki/UnixODBC>`__ configuration file:: | |
| 395 | |
| 396 $ cat ~/.odbc.ini | |
| 397 [orthanctest] | |
| 398 Driver = MySQL ODBC 8.0 Unicode Driver | |
| 399 Servername = localhost | |
| 400 Database = orthanctest | |
| 401 UID = root | |
| 402 PWD = root | |
| 403 Port = 3306 | |
| 404 | |
| 751 | 405 .. highlight:: json |
| 406 | |
| 750 | 407 3. Start Orthanc using the following :ref:`configuration file |
| 408 <configuration>` for ODBC:: | |
| 409 | |
| 410 { | |
| 411 "Odbc" : { | |
| 412 "EnableIndex" : true, | |
| 413 "EnableStorage" : true, | |
| 414 "IndexConnectionString" : "DSN=orthanctest;charset=utf8", | |
| 415 "StorageConnectionString" : "DSN=orthanctest;charset=utf8" | |
| 416 } | |
| 417 } | |
| 418 | |
| 419 The ``charset=utf8`` option is necessary if using MySQL 8.x. | |
| 420 | |
| 421 | |
| 422 SQLite | |
| 423 ^^^^^^ | |
| 424 | |
| 425 1. Install the ``libsqliteodbc`` package. | |
| 426 | |
| 751 | 427 .. highlight:: text |
| 428 | |
| 750 | 429 2. Create the following sample `unixODBC |
| 430 <https://en.wikipedia.org/wiki/UnixODBC>`__ configuration file:: | |
| 431 | |
| 432 $ cat ~/.odbc.ini | |
| 433 [index] | |
| 434 Driver=SQLite3 | |
| 435 Database=/tmp/test-odbc-index.sqlite | |
| 436 | |
| 437 [storage] | |
| 438 Driver=SQLite3 | |
| 439 Database=/tmp/test-odbc-storage.sqlite | |
| 440 | |
| 441 Note that we define two different data sources, one for the index | |
| 442 and another for the storage area, because a SQLite database can | |
| 443 only be opened by one client at once. | |
| 444 | |
| 751 | 445 .. highlight:: json |
| 446 | |
| 750 | 447 3. Start Orthanc using the following :ref:`configuration file |
| 448 <configuration>` for ODBC:: | |
| 449 | |
| 450 { | |
| 451 "Odbc" : { | |
| 452 "EnableIndex" : true, | |
| 453 "EnableStorage" : true, | |
| 454 "IndexConnectionString" : "DSN=index", | |
| 455 "StorageConnectionString" : "DSN=storage", | |
| 456 "IndexConnectionsCount" : 1 | |
| 457 } | |
| 458 } | |
| 459 | |
| 460 **Remark 1:** As written just above, one SQLite database should | |
| 461 only be opened by one client at a time. This implies that the | |
| 462 ``IndexConnectionsCount`` must be set to ``1``, and that the index | |
| 463 and storage area must never have connection strings corresponding | |
| 464 to the same SQLite database. | |
| 465 | |
| 466 **Remark 2:** As written above, the ODBC plugin supports the | |
| 467 :ref:`revision mechanism <revisions>`. This contrasts with the | |
| 468 built-in SQLite database of Orthanc. So, it might be interesting to | |
| 469 use the ODBC index plugin instead of the built-in SQLite database | |
| 470 of Orthanc, if you are a developer who wants to test revisions | |
| 471 before a :ref:`large-scale deployment <scalability>`. | |
| 472 | |
| 473 | |
| 474 Advanced options | |
| 475 ---------------- | |
| 476 | |
| 477 Several advanced options are available as well to fine-tune the | |
| 478 configuration of the ODBC plugins. They are documented below. | |
| 479 | |
| 480 | |
| 481 .. _odbc-multiple-writers: | |
| 482 | |
| 483 Multiple writers or connections | |
| 484 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 485 | |
| 486 Starting with Orthanc 1.9.2, it is possible to use :ref:`multiple | |
| 487 writers or connections in large-scale deployments | |
| 488 <multiple-writers>`. Here is the list of configuration that control | |
| 489 this behaviour: | |
| 490 | |
| 491 * ``MaximumConnectionRetries`` governs how many times Orthanc tries to | |
| 492 connect to the database, as well as how many times Orthanc replays | |
| 493 transactions to deal with collisions between multiple writers. | |
| 494 | |
| 495 * ``IndexConnectionsCount`` controls the number of connections from | |
| 496 the index plugin to the ODBC database. It is set to ``1`` by | |
| 497 default, which corresponds to the old behaviour of Orthanc <= 1.9.1. | |
| 498 | |
| 499 * ``ConnectionRetryInterval`` is only used when opening one database | |
| 500 connection to ODBC. | |
| 501 | |
| 502 * These options cannot be used in the case of SQLite databases, that | |
| 503 only support one client at once. |