Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/postgresql.rst @ 258:a073419272c7
typo
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Wed, 26 Jun 2019 22:41:33 +0200 |
parents | c7551e19ae95 |
children | 39609c9a2c41 |
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 | |
154 | 26 The procedure to compile these plugins is similar to that for the |
27 | 27 :ref:`core of Orthanc <compiling>`. The following commands should work |
154 | 28 for most UNIX-like distribution (including GNU/Linux):: |
27 | 29 |
154 | 30 $ mkdir BuildPostgreSQL |
31 $ cd BuildPostgreSQL | |
32 $ cmake ../PostgreSQL -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 | |
154 | 61 $ mkdir BuildPostgreSQL |
62 $ cd BuildPostgreSQL | |
63 $ cmake ../PostgreSQL -DCMAKE_BUILD_TYPE=Release \ | |
64 -DALLOW_DOWNLOADS=ON \ | |
65 -DUSE_SYSTEM_GOOGLE_TEST=OFF \ | |
66 -DUSE_SYSTEM_ORTHANC_SDK=OFF | |
128 | 67 $ make |
68 | |
69 | |
27 | 70 Usage |
71 ----- | |
72 | |
73 .. highlight:: json | |
74 | |
31
93bbfaf0e62c
worklist instructions migrated to a specific page, indexing of Osimis Web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
30
diff
changeset
|
75 You of course first have to :ref:`install Orthanc <binaries>`, with a |
154 | 76 version above 0.9.5. You then have to **create a database** dedicated |
28 | 77 to Orthanc on some PostgreSQL server. Please refer to the `PostgreSQL |
78 documentation | |
27 | 79 <https://www.postgresql.org/docs/current/static/tutorial-createdb.html>`__. |
80 | |
81 Once Orthanc is installed and the database is created, you must add a | |
82 section in the :ref:`configuration file <configuration>` that | |
83 specifies the address of the **PostgreSQL server together with your | |
84 credentials**. You also have to tell Orthanc in which path it can find | |
85 the plugins: This is done by properly modifying the ``Plugins`` | |
86 option. You could for instance adapt the following configuration | |
87 file:: | |
88 | |
89 { | |
90 "Name" : "MyOrthanc", | |
91 "PostgreSQL" : { | |
92 "EnableIndex" : true, | |
93 "EnableStorage" : true, | |
94 "Host" : "localhost", | |
95 "Port" : 5432, | |
96 "Database" : "orthanc", | |
97 "Username" : "orthanc", | |
181 | 98 "Password" : "orthanc", |
99 "EnableSsl" : false // New in version 3.0 | |
27 | 100 }, |
101 "Plugins" : [ | |
154 | 102 "/home/user/orthanc-databases/BuildPostgreSQL/libOrthancPostgreSQLIndex.so", |
103 "/home/user/orthanc-databases/BuildPostgreSQL/libOrthancPostgreSQLStorage.so" | |
27 | 104 ] |
105 } | |
106 | |
154 | 107 **Important:** The ``EnableIndex`` and ``EnableStorage`` options must |
108 be explicitly set to ``true``, otherwise Orthanc will continue to use | |
109 its default SQLite back-end and the filesystem storage area. | |
27 | 110 |
181 | 111 **Remark 1:** When using the ``Storage`` PostgreSQL plugin, the DICOM |
154 | 112 files are stored as large objects in the database. This might |
113 actually consume more space than the DICOM file itself. We have | |
114 observed overhead up to 40%. However, it seems this overhead is | |
115 temporary and comes from Write-Ahead Logging. Check this `discussion | |
116 <https://groups.google.com/d/msg/orthanc-users/pPzHOpb--iw/QkKZ808gIgAJ>`__ | |
117 on the Orthanc Users group for more info). | |
118 | 118 |
181 | 119 **Remark 2:** A typical usage of the PostgreSQL plugin is to enable |
120 only the ``Index``, and to use the default filesystem storage for | |
121 DICOM files (on a NAS with proper disaster recovery strategies). This | |
122 setup provides best performance for large-scale databases. | |
123 | |
124 **Remark 3:** Setting the ``EnableSsl`` to ``true`` forces the use of | |
125 `SSL connections | |
126 <https://www.postgresql.org/docs/current/libpq-ssl.html>`__ between | |
127 Orthanc and the PostgreSQL server. It is a synonym for | |
128 ``sslmode=require`` in connections URI (see below). Setting | |
129 ``EnableSsl`` to ``false`` corresponds to ``sslmode=disable`` | |
130 (i.e. SSL is not used, even if it is both available in Orthanc and | |
131 PostgreSQL). To choose other values for the SSL mode (i.e. ``allow`` | |
132 and ``prefer``), please use connection URIs. | |
118 | 133 |
134 | |
94
b0a71b880ca0
fix link + remark about disk usage overhead
Alain Mazy <alain@mazy.be>
parents:
81
diff
changeset
|
135 |
27 | 136 .. highlight:: text |
137 | |
138 Orthanc must of course be **restarted** after the modification of its | |
139 configuration file. The log will contain an output similar to:: | |
140 | |
141 $ ./Orthanc Configuration.json | |
142 W0212 16:30:34.576972 11285 main.cpp:632] Orthanc version: 0.8.6 | |
143 W0212 16:30:34.577386 11285 OrthancInitialization.cpp:80] Using the configuration from: Configuration.json | |
144 [...] | |
154 | 145 W0212 16:30:34.598053 11285 main.cpp:379] Registering a plugin from: /home/jodogne/Subversion/orthanc-databases/BuildPostgreSQL/libOrthancPostgreSQLIndex.so |
27 | 146 W0212 16:30:34.598470 11285 PluginsManager.cpp:258] Registering plugin 'postgresql-index' (version 1.0) |
147 W0212 16:30:34.598491 11285 PluginsManager.cpp:148] Using PostgreSQL index | |
154 | 148 W0212 16:30:34.608289 11285 main.cpp:379] Registering a plugin from: /home/jodogne/Subversion/orthanc-databases/BuildPostgreSQL/libOrthancPostgreSQLStorage.so |
27 | 149 W0212 16:30:34.608916 11285 PluginsManager.cpp:258] Registering plugin 'postgresql-storage' (version 1.0) |
150 W0212 16:30:34.608947 11285 PluginsManager.cpp:148] Using PostgreSQL storage area | |
151 [...] | |
152 W0212 16:30:34.674648 11285 main.cpp:530] Orthanc has started | |
153 | |
154 | |
155 .. highlight:: json | |
156 | |
157 Instead of specifying explicit authentication parameters, you can also | |
158 use the `PostgreSQL connection URIs syntax | |
159 <https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING>`__. For | |
160 instance:: | |
161 | |
162 { | |
163 "Name" : "MyOrthanc", | |
164 "PostgreSQL" : { | |
165 "EnableIndex" : true, | |
166 "EnableStorage" : true, | |
181 | 167 "ConnectionUri" : "postgresql://username:password@localhost:5432/database?sslmode=prefer" |
27 | 168 }, |
169 "Plugins" : [ | |
154 | 170 "/home/user/orthanc-databases/BuildPostgreSQL/libOrthancPostgreSQLIndex.so", |
171 "/home/user/orthanc-databases/BuildPostgreSQL/libOrthancPostgreSQLStorage.so" | |
27 | 172 ] |
173 } | |
174 | |
175 | |
176 **Remark:** The Debian Med project maintains `another useful set of | |
177 instructions | |
178 <https://anonscm.debian.org/viewvc/debian-med/trunk/packages/orthanc-postgresql/trunk/debian/README.Debian?view=markup>`__. | |
179 | |
180 | |
181 Advanced options | |
182 ---------------- | |
183 | |
184 Several advanced options are available as well to fine-tune the | |
185 configuration of the PostgreSQL plugins. They are documented below. | |
186 | |
187 | |
188 Locking | |
189 ^^^^^^^ | |
190 | |
191 .. highlight:: json | |
192 | |
193 By default, the plugins lock the database (using `PostgreSQL advisory | |
194 locks | |
195 <https://www.postgresql.org/docs/current/static/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS>`__) | |
196 to prevent other instances of Orthanc from using the same PostgreSQL | |
197 database. If you want several instances of Orthanc to share the same | |
198 database, set the ``Lock`` option to ``false`` in the configuration | |
199 file:: | |
200 | |
201 { | |
202 "Name" : "MyOrthanc", | |
203 "PostgreSQL" : { | |
204 "EnableIndex" : true, | |
205 "EnableStorage" : true, | |
206 "Lock" : false, | |
207 "ConnectionUri" : "postgresql://username:password@localhost:5432/database" | |
208 }, | |
209 "Plugins" : [ | |
154 | 210 "/home/user/orthanc-databases/BuildPostgreSQL/libOrthancPostgreSQLIndex.so", |
211 "/home/user/orthanc-databases/BuildPostgreSQL/libOrthancPostgreSQLStorage.so" | |
27 | 212 ] |
213 } | |
214 | |
215 Obviously, one must be very cautious when sharing the same database | |
216 between instances of Orthanc. In particular, all these instances | |
217 should share the same configuration. | |
218 | |
219 | |
220 Keep-alive | |
221 ^^^^^^^^^^ | |
222 | |
223 .. highlight:: text | |
224 | |
225 After some period of inactivity (users have reported 10 hours), you | |
226 might `experience an error | |
227 <https://bitbucket.org/sjodogne/orthanc/issues/15/postgresql-exceptions-after-time>`__ | |
228 such as:: | |
229 | |
230 E0220 03:20:51.562601 PluginsManager.cpp:163] Exception in database back-end: Error in PostgreSQL: server closed the connection unexpectedly. | |
231 This probably means the server terminated abnormally before or while processing the request. | |
232 E0220 06:51:03.924868 PluginsManager.cpp:163] Exception in database back-end: Error in PostgreSQL: no connection to the server | |
233 | |
234 This is due to a timeout in the PostgreSQL server. Please make sure to | |
235 `enable keep-alive | |
236 <http://dba.stackexchange.com/questions/97534/is-there-a-timeout-option-for-remote-access-to-postgresql-database>`__ | |
237 in the configuration of your PostgreSQL server |