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