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