Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/postgresql.rst @ 128:f2abbac22d5c
postgresql
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Wed, 03 Jan 2018 15:32:44 +0100 |
| parents | a30abf63ccba |
| children | 61050d813d74 |
| rev | line source |
|---|---|
| 24 | 1 .. _postgresql: |
| 2 | |
| 3 | |
| 4 PostgreSQL plugins | |
| 5 ================== | |
| 6 | |
| 27 | 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 PostgreSQL database. | |
| 12 | |
| 13 For general information, check out the `official homepage of the | |
| 14 plugins <http://www.orthanc-server.com/static.php?page=postgresql>`__. | |
| 15 | |
| 16 | |
| 17 | |
| 18 Compilation | |
| 19 ----------- | |
| 20 | |
| 128 | 21 Static linking |
| 22 ^^^^^^^^^^^^^^ | |
| 23 | |
| 27 | 24 .. highlight:: text |
| 25 | |
| 26 The procedure to compile these plugins is similar of that for the | |
| 27 :ref:`core of Orthanc <compiling>`. The following commands should work | |
| 28 for every UNIX-like distribution (including GNU/Linux):: | |
| 29 | |
| 30 $ mkdir Build | |
| 31 $ cd Build | |
| 81 | 32 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release |
| 27 | 33 $ make |
| 34 | |
| 35 The compilation will produce 2 shared libraries, each containing one plugin for Orthanc: | |
| 36 | |
| 37 * ``OrthancPostgreSQLIndex`` replaces the default SQLite index of Orthanc by PostgreSQL. | |
| 38 * ``OrthancPostgreSQLStorage`` makes Orthanc store the DICOM files it receives into PostgreSQL. | |
| 39 | |
| 128 | 40 |
| 41 Microsoft Windows and Apple OS X | |
| 42 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 43 | |
| 28 | 44 Pre-compiled binaries for Microsoft Windows `are also available |
| 27 | 45 <http://www.orthanc-server.com/browse.php?path=/plugin-postgresql>`__. |
| 30 | 46 A package for `Apple's Mac OS X |
|
94
b0a71b880ca0
fix link + remark about disk usage overhead
Alain Mazy <alain@mazy.be>
parents:
81
diff
changeset
|
47 <http://www.osimis.io/en/download.html>`__ |
| 128 | 48 is available courtesy of `Osimis <http://osimis.io/>`__. |
| 27 | 49 |
| 50 | |
| 128 | 51 Dynamic linking on Ubuntu 16.04 |
| 52 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 53 | |
| 54 .. highlight:: text | |
| 55 | |
| 56 If static linking is not desired, here are build instructions for | |
| 57 Ubuntu 16.04 (provided build dependencies for the :ref:`core of | |
| 58 Orthanc <compiling>` have already been installed):: | |
| 59 | |
| 60 $ sudo apt-get install libpq-dev postgresql-server-dev-all | |
| 61 $ cmake .. -DCMAKE_BUILD_TYPE=Debug \ | |
| 62 -DALLOW_DOWNLOADS=ON \ | |
| 63 -DUSE_SYSTEM_GOOGLE_TEST=OFF \ | |
| 64 -DUSE_SYSTEM_ORTHANC_SDK=OFF | |
| 65 $ make | |
| 66 | |
| 67 | |
| 27 | 68 Usage |
| 69 ----- | |
| 70 | |
| 71 .. highlight:: json | |
| 72 | |
|
31
93bbfaf0e62c
worklist instructions migrated to a specific page, indexing of Osimis Web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
30
diff
changeset
|
73 You of course first have to :ref:`install Orthanc <binaries>`, with a |
| 28 | 74 version above 0.9.1. You then have to **create a database** dedicated |
| 75 to Orthanc on some PostgreSQL server. Please refer to the `PostgreSQL | |
| 76 documentation | |
| 27 | 77 <https://www.postgresql.org/docs/current/static/tutorial-createdb.html>`__. |
| 78 | |
| 79 Once Orthanc is installed and the database is created, you must add a | |
| 80 section in the :ref:`configuration file <configuration>` that | |
| 81 specifies the address of the **PostgreSQL server together with your | |
| 82 credentials**. You also have to tell Orthanc in which path it can find | |
| 83 the plugins: This is done by properly modifying the ``Plugins`` | |
| 84 option. You could for instance adapt the following configuration | |
| 85 file:: | |
| 86 | |
| 87 { | |
| 88 "Name" : "MyOrthanc", | |
| 89 [...] | |
| 90 "PostgreSQL" : { | |
| 91 "EnableIndex" : true, | |
| 92 "EnableStorage" : true, | |
| 93 "Host" : "localhost", | |
| 94 "Port" : 5432, | |
| 95 "Database" : "orthanc", | |
| 96 "Username" : "orthanc", | |
| 97 "Password" : "orthanc" | |
| 98 }, | |
| 99 "Plugins" : [ | |
| 100 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so", | |
| 101 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLStorage.so" | |
| 102 ] | |
| 103 } | |
| 104 | |
| 105 Note that ``EnableIndex`` and ``EnableStorage`` must be explicitly set | |
| 106 to true, otherwise Orthanc will continue to use its default SQLite | |
| 107 back-end. | |
| 108 | |
| 118 | 109 **Remark:** When using the ``Storage`` PostgreSQL plugin, the DICOM files are stored as large objects in the database. This might actually consume more space than the DICOM file itself. We have observed overhead up to 40%. However, it seems this overhead is temporary and comes from Write-Ahead Logging. Check this `discussion <https://groups.google.com/d/msg/orthanc-users/pPzHOpb--iw/QkKZ808gIgAJ>`__ on the Orthanc Users group for more info). |
| 110 | |
| 111 Note that a typical usage of the PostgreSQL plugin is to enable only the ``Index`` and continue using the default filesystem storage for DICOM files. | |
| 112 | |
| 113 | |
|
94
b0a71b880ca0
fix link + remark about disk usage overhead
Alain Mazy <alain@mazy.be>
parents:
81
diff
changeset
|
114 |
| 27 | 115 .. highlight:: text |
| 116 | |
| 117 Orthanc must of course be **restarted** after the modification of its | |
| 118 configuration file. The log will contain an output similar to:: | |
| 119 | |
| 120 $ ./Orthanc Configuration.json | |
| 121 W0212 16:30:34.576972 11285 main.cpp:632] Orthanc version: 0.8.6 | |
| 122 W0212 16:30:34.577386 11285 OrthancInitialization.cpp:80] Using the configuration from: Configuration.json | |
| 123 [...] | |
| 124 W0212 16:30:34.598053 11285 main.cpp:379] Registering a plugin from: /home/jodogne/Subversion/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so | |
| 125 W0212 16:30:34.598470 11285 PluginsManager.cpp:258] Registering plugin 'postgresql-index' (version 1.0) | |
| 126 W0212 16:30:34.598491 11285 PluginsManager.cpp:148] Using PostgreSQL index | |
| 127 W0212 16:30:34.608289 11285 main.cpp:379] Registering a plugin from: /home/jodogne/Subversion/OrthancPostgreSQL/Build/libOrthancPostgreSQLStorage.so | |
| 128 W0212 16:30:34.608916 11285 PluginsManager.cpp:258] Registering plugin 'postgresql-storage' (version 1.0) | |
| 129 W0212 16:30:34.608947 11285 PluginsManager.cpp:148] Using PostgreSQL storage area | |
| 130 [...] | |
| 131 W0212 16:30:34.674648 11285 main.cpp:530] Orthanc has started | |
| 132 | |
| 133 | |
| 134 .. highlight:: json | |
| 135 | |
| 136 Instead of specifying explicit authentication parameters, you can also | |
| 137 use the `PostgreSQL connection URIs syntax | |
| 138 <https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING>`__. For | |
| 139 instance:: | |
| 140 | |
| 141 { | |
| 142 "Name" : "MyOrthanc", | |
| 143 [...] | |
| 144 "PostgreSQL" : { | |
| 145 "EnableIndex" : true, | |
| 146 "EnableStorage" : true, | |
| 147 "ConnectionUri" : "postgresql://username:password@localhost:5432/database" | |
| 148 }, | |
| 149 "Plugins" : [ | |
| 150 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so", | |
| 151 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLStorage.so" | |
| 152 ] | |
| 153 } | |
| 154 | |
| 155 | |
| 156 **Remark:** The Debian Med project maintains `another useful set of | |
| 157 instructions | |
| 158 <https://anonscm.debian.org/viewvc/debian-med/trunk/packages/orthanc-postgresql/trunk/debian/README.Debian?view=markup>`__. | |
| 159 | |
| 160 | |
| 161 Advanced options | |
| 162 ---------------- | |
| 163 | |
| 164 Several advanced options are available as well to fine-tune the | |
| 165 configuration of the PostgreSQL plugins. They are documented below. | |
| 166 | |
| 167 | |
| 168 Locking | |
| 169 ^^^^^^^ | |
| 170 | |
| 171 .. highlight:: json | |
| 172 | |
| 173 By default, the plugins lock the database (using `PostgreSQL advisory | |
| 174 locks | |
| 175 <https://www.postgresql.org/docs/current/static/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS>`__) | |
| 176 to prevent other instances of Orthanc from using the same PostgreSQL | |
| 177 database. If you want several instances of Orthanc to share the same | |
| 178 database, set the ``Lock`` option to ``false`` in the configuration | |
| 179 file:: | |
| 180 | |
| 181 { | |
| 182 "Name" : "MyOrthanc", | |
| 183 [...] | |
| 184 "PostgreSQL" : { | |
| 185 "EnableIndex" : true, | |
| 186 "EnableStorage" : true, | |
| 187 "Lock" : false, | |
| 188 "ConnectionUri" : "postgresql://username:password@localhost:5432/database" | |
| 189 }, | |
| 190 "Plugins" : [ | |
| 191 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so", | |
| 192 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLStorage.so" | |
| 193 ] | |
| 194 } | |
| 195 | |
| 196 Obviously, one must be very cautious when sharing the same database | |
| 197 between instances of Orthanc. In particular, all these instances | |
| 198 should share the same configuration. | |
| 199 | |
| 200 | |
| 201 Keep-alive | |
| 202 ^^^^^^^^^^ | |
| 203 | |
| 204 .. highlight:: text | |
| 205 | |
| 206 After some period of inactivity (users have reported 10 hours), you | |
| 207 might `experience an error | |
| 208 <https://bitbucket.org/sjodogne/orthanc/issues/15/postgresql-exceptions-after-time>`__ | |
| 209 such as:: | |
| 210 | |
| 211 E0220 03:20:51.562601 PluginsManager.cpp:163] Exception in database back-end: Error in PostgreSQL: server closed the connection unexpectedly. | |
| 212 This probably means the server terminated abnormally before or while processing the request. | |
| 213 E0220 06:51:03.924868 PluginsManager.cpp:163] Exception in database back-end: Error in PostgreSQL: no connection to the server | |
| 214 | |
| 215 This is due to a timeout in the PostgreSQL server. Please make sure to | |
| 216 `enable keep-alive | |
| 217 <http://dba.stackexchange.com/questions/97534/is-there-a-timeout-option-for-remote-access-to-postgresql-database>`__ | |
| 218 in the configuration of your PostgreSQL server |