Mercurial > hg > orthanc-book

comparison Sphinx/source/plugins/postgresql.rst @ 27:c23f02a64caf

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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