PostgreSQL plugins¶

Static linking¶

The procedure to compile these plugins is similar to that for the core of Orthanc. The following commands should work for most UNIX-like distribution (including GNU/Linux):

$ mkdir BuildPostgreSQL
$ cd BuildPostgreSQL
$ cmake ../PostgreSQL -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
$ make

The compilation will produce 2 shared libraries, each containing one plugin for Orthanc:

• OrthancPostgreSQLIndex replaces the default SQLite index of Orthanc by PostgreSQL.
• OrthancPostgreSQLStorage makes Orthanc store the DICOM files it receives into PostgreSQL.

Microsoft Windows and Apple OS X¶

Pre-compiled binaries for Microsoft Windows 32bit are also available. A package for Apple’s Mac OS X is available courtesy of Orthanc Team.

Dynamic linking on Ubuntu 16.04¶

If static linking is not desired, here are build instructions for Ubuntu 16.04 (provided build dependencies for the core of Orthanc have already been installed):

$ sudo apt-get install libpq-dev postgresql-server-dev-all
$ mkdir BuildPostgreSQL
$ cd BuildPostgreSQL
$ cmake ../PostgreSQL -DCMAKE_BUILD_TYPE=Release \
                      -DALLOW_DOWNLOADS=ON \
                      -DUSE_SYSTEM_GOOGLE_TEST=OFF \
                      -DUSE_SYSTEM_ORTHANC_SDK=OFF
$ make

Dynamic linking on other GNU/Linux distributions¶

The build instructions should always be very similar to those for Ubuntu 16.04. One difficulty that could however arise is that it is possible that the CMake environment that is shipped with the GNU/Linux distribution cannot locate a recent version of the development headers for PostgreSQL. This leads to an error while invoking CMake that looks like:

-- Could NOT find PostgreSQL (missing: PostgreSQL_TYPE_INCLUDE_DIR)

In such a situation, please add your version of PostgreSQL to the macro PostgreSQL_ADDITIONAL_VERSIONS that is defined at the end of the Resources/CMake/PostgreSQLConfiguration.cmake file in the sources of the project.

Multiple writers or connections¶

Starting with Orthanc 1.9.2 and PostgreSQL 4.0, it is possible to use multiple writers or connections in large-scale deployments. Here is the list of configuration that control this behavior:

• Lock must be set to false (cf. below)
• MaximumConnectionRetries governs how many times Orthanc tries to connect to the database, as well as how many times Orthanc replays transactions to deal with collisions between multiple writers.
• IndexConnectionsCount controls the number of connections from the index plugin to the PostgreSQL database. It is set to 1 by default, which corresponds to the old behavior of Orthanc <= 1.9.1.
• ConnectionRetryInterval is only used when opening one database connection to PostgreSQL.
• The PostgreSQL plugin supports the revision mechanism to protect metadata and attachments from concurrent modifications.

Locking¶

By default, the plugins lock the database (using PostgreSQL advisory locks) to prevent other instances of Orthanc from using the same PostgreSQL database. If you want several instances of Orthanc to share the same database or if you need multiple connections to the PostgreSQL database, set the Lock option to false in the configuration file:

{
  "Name" : "MyOrthanc",
  "PostgreSQL" : {
    "EnableIndex" : true,
    "EnableStorage" : true,
    "Lock" : false,
    "ConnectionUri" : "postgresql://username:password@localhost:5432/database"
  },
  "Plugins" : [
    "/home/user/orthanc-databases/BuildPostgreSQL/libOrthancPostgreSQLIndex.so",
    "/home/user/orthanc-databases/BuildPostgreSQL/libOrthancPostgreSQLStorage.so"
  ]
}

Obviously, one must be very cautious when sharing the same database between instances of Orthanc. In particular, all these instances should share the same configuration.

Keep-alive¶

After some period of inactivity (users have reported 10 hours), you might experience an error such as:

E0220 03:20:51.562601 PluginsManager.cpp:163] Exception in database back-end: Error in PostgreSQL: server closed the connection unexpectedly.
This probably means the server terminated abnormally before or while processing the request.
E0220 06:51:03.924868 PluginsManager.cpp:163] Exception in database back-end: Error in PostgreSQL: no connection to the server

This is due to a timeout in the PostgreSQL server. Please make sure to enable keep-alive in the configuration of your PostgreSQL server

Scalability¶

When configuring your PostgreSQL plugin, ensure you’ve read the scalability section

SCRAM authentication¶

In the releases 3.2 of the PostgreSQL plugins, the precompiled binaries use an old, but stable version of the PostgreSQL client (libpq 9.6.1). This makes these binaries very portable, however they might not be compatible with more recent features of PostgreSQL.

In particular, the precompiled binaries are not compatible with SCRAM authentication that is available since PostgreSQL 10. If you get the error psql: authentication method 10 not supported, this indicates that the PostgreSQL plugins cannot connect to a PostgreSQL server because SCRAM is enabled.

Ian Smith has reported the following method to disable SCRAM:

1. Drop/delete the orthanc database and user in PostgreSQL.
2. Edit the files postgresql.conf and pg_hba.conf and change scram-sha-256 to md5 in all cases.
3. Add the orthanc user and database in PostgreSQL again.
4. Restart Orthanc.