|
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
|
|
|
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
|
|
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
|
|
27
|
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
|
|
28
|
49 You of course first have to :ref:`install Orthanc <compiling>`, with a
|
|
|
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
|
|
|
85 .. highlight:: text
|
|
|
86
|
|
|
87 Orthanc must of course be **restarted** after the modification of its
|
|
|
88 configuration file. The log will contain an output similar to::
|
|
|
89
|
|
|
90 $ ./Orthanc Configuration.json
|
|
|
91 W0212 16:30:34.576972 11285 main.cpp:632] Orthanc version: 0.8.6
|
|
|
92 W0212 16:30:34.577386 11285 OrthancInitialization.cpp:80] Using the configuration from: Configuration.json
|
|
|
93 [...]
|
|
|
94 W0212 16:30:34.598053 11285 main.cpp:379] Registering a plugin from: /home/jodogne/Subversion/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so
|
|
|
95 W0212 16:30:34.598470 11285 PluginsManager.cpp:258] Registering plugin 'postgresql-index' (version 1.0)
|
|
|
96 W0212 16:30:34.598491 11285 PluginsManager.cpp:148] Using PostgreSQL index
|
|
|
97 W0212 16:30:34.608289 11285 main.cpp:379] Registering a plugin from: /home/jodogne/Subversion/OrthancPostgreSQL/Build/libOrthancPostgreSQLStorage.so
|
|
|
98 W0212 16:30:34.608916 11285 PluginsManager.cpp:258] Registering plugin 'postgresql-storage' (version 1.0)
|
|
|
99 W0212 16:30:34.608947 11285 PluginsManager.cpp:148] Using PostgreSQL storage area
|
|
|
100 [...]
|
|
|
101 W0212 16:30:34.674648 11285 main.cpp:530] Orthanc has started
|
|
|
102
|
|
|
103
|
|
|
104 .. highlight:: json
|
|
|
105
|
|
|
106 Instead of specifying explicit authentication parameters, you can also
|
|
|
107 use the `PostgreSQL connection URIs syntax
|
|
|
108 <https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING>`__. For
|
|
|
109 instance::
|
|
|
110
|
|
|
111 {
|
|
|
112 "Name" : "MyOrthanc",
|
|
|
113 [...]
|
|
|
114 "PostgreSQL" : {
|
|
|
115 "EnableIndex" : true,
|
|
|
116 "EnableStorage" : true,
|
|
|
117 "ConnectionUri" : "postgresql://username:password@localhost:5432/database"
|
|
|
118 },
|
|
|
119 "Plugins" : [
|
|
|
120 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so",
|
|
|
121 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLStorage.so"
|
|
|
122 ]
|
|
|
123 }
|
|
|
124
|
|
|
125
|
|
|
126 **Remark:** The Debian Med project maintains `another useful set of
|
|
|
127 instructions
|
|
|
128 <https://anonscm.debian.org/viewvc/debian-med/trunk/packages/orthanc-postgresql/trunk/debian/README.Debian?view=markup>`__.
|
|
|
129
|
|
|
130
|
|
|
131 Advanced options
|
|
|
132 ----------------
|
|
|
133
|
|
|
134 Several advanced options are available as well to fine-tune the
|
|
|
135 configuration of the PostgreSQL plugins. They are documented below.
|
|
|
136
|
|
|
137
|
|
|
138 Locking
|
|
|
139 ^^^^^^^
|
|
|
140
|
|
|
141 .. highlight:: json
|
|
|
142
|
|
|
143 By default, the plugins lock the database (using `PostgreSQL advisory
|
|
|
144 locks
|
|
|
145 <https://www.postgresql.org/docs/current/static/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS>`__)
|
|
|
146 to prevent other instances of Orthanc from using the same PostgreSQL
|
|
|
147 database. If you want several instances of Orthanc to share the same
|
|
|
148 database, set the ``Lock`` option to ``false`` in the configuration
|
|
|
149 file::
|
|
|
150
|
|
|
151 {
|
|
|
152 "Name" : "MyOrthanc",
|
|
|
153 [...]
|
|
|
154 "PostgreSQL" : {
|
|
|
155 "EnableIndex" : true,
|
|
|
156 "EnableStorage" : true,
|
|
|
157 "Lock" : false,
|
|
|
158 "ConnectionUri" : "postgresql://username:password@localhost:5432/database"
|
|
|
159 },
|
|
|
160 "Plugins" : [
|
|
|
161 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so",
|
|
|
162 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLStorage.so"
|
|
|
163 ]
|
|
|
164 }
|
|
|
165
|
|
|
166 Obviously, one must be very cautious when sharing the same database
|
|
|
167 between instances of Orthanc. In particular, all these instances
|
|
|
168 should share the same configuration.
|
|
|
169
|
|
|
170
|
|
|
171 Keep-alive
|
|
|
172 ^^^^^^^^^^
|
|
|
173
|
|
|
174 .. highlight:: text
|
|
|
175
|
|
|
176 After some period of inactivity (users have reported 10 hours), you
|
|
|
177 might `experience an error
|
|
|
178 <https://bitbucket.org/sjodogne/orthanc/issues/15/postgresql-exceptions-after-time>`__
|
|
|
179 such as::
|
|
|
180
|
|
|
181 E0220 03:20:51.562601 PluginsManager.cpp:163] Exception in database back-end: Error in PostgreSQL: server closed the connection unexpectedly.
|
|
|
182 This probably means the server terminated abnormally before or while processing the request.
|
|
|
183 E0220 06:51:03.924868 PluginsManager.cpp:163] Exception in database back-end: Error in PostgreSQL: no connection to the server
|
|
|
184
|
|
|
185 This is due to a timeout in the PostgreSQL server. Please make sure to
|
|
|
186 `enable keep-alive
|
|
|
187 <http://dba.stackexchange.com/questions/97534/is-there-a-timeout-option-for-remote-access-to-postgresql-database>`__
|
|
|
188 in the configuration of your PostgreSQL server
|
