PostgreSQL plugins

The Orthanc project provides two official plugins to replace the default storage area (on the filesystem) and the default SQLite index by a PostgreSQL database.

For general information, check out the official homepage of the plugins.

Compilation

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

$ mkdir Build
$ cd Build
$ cmake .. -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.

Pre-compiled binaries for Microsoft Windows are also available. A package for Apple’s Mac OS X are available courtesy of Osimis.

Usage

You of course first have to install Orthanc, with a version above 0.9.1. You then have to create a database dedicated to Orthanc on some PostgreSQL server. Please refer to the PostgreSQL documentation.

Once Orthanc is installed and the database is created, you must add a section in the configuration file that specifies the address of the PostgreSQL server together with your credentials. You also have to tell Orthanc in which path it can find the plugins: This is done by properly modifying the Plugins option. You could for instance adapt the following configuration file:

{
  "Name" : "MyOrthanc",
  [...]
  "PostgreSQL" : {
    "EnableIndex" : true,
    "EnableStorage" : true,
    "Host" : "localhost",
    "Port" : 5432,
    "Database" : "orthanc",
    "Username" : "orthanc",
    "Password" : "orthanc"
  },
  "Plugins" : [
    "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so",
    "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLStorage.so"
  ]
}

Note that EnableIndex and EnableStorage must be explicitly set to true, otherwise Orthanc will continue to use its default SQLite back-end.

Orthanc must of course be restarted after the modification of its configuration file. The log will contain an output similar to:

$ ./Orthanc Configuration.json
W0212 16:30:34.576972 11285 main.cpp:632] Orthanc version: 0.8.6
W0212 16:30:34.577386 11285 OrthancInitialization.cpp:80] Using the configuration from: Configuration.json
[...]
W0212 16:30:34.598053 11285 main.cpp:379] Registering a plugin from: /home/jodogne/Subversion/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so
W0212 16:30:34.598470 11285 PluginsManager.cpp:258] Registering plugin 'postgresql-index' (version 1.0)
W0212 16:30:34.598491 11285 PluginsManager.cpp:148] Using PostgreSQL index
W0212 16:30:34.608289 11285 main.cpp:379] Registering a plugin from: /home/jodogne/Subversion/OrthancPostgreSQL/Build/libOrthancPostgreSQLStorage.so
W0212 16:30:34.608916 11285 PluginsManager.cpp:258] Registering plugin 'postgresql-storage' (version 1.0)
W0212 16:30:34.608947 11285 PluginsManager.cpp:148] Using PostgreSQL storage area
[...]
W0212 16:30:34.674648 11285 main.cpp:530] Orthanc has started

Instead of specifying explicit authentication parameters, you can also use the PostgreSQL connection URIs syntax. For instance:

{
  "Name" : "MyOrthanc",
  [...]
  "PostgreSQL" : {
    "EnableIndex" : true,
    "EnableStorage" : true,
    "ConnectionUri" : "postgresql://username:password@localhost:5432/database"
  },
  "Plugins" : [
    "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so",
    "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLStorage.so"
  ]
}

Remark: The Debian Med project maintains another useful set of instructions.

Advanced options

Several advanced options are available as well to fine-tune the configuration of the PostgreSQL plugins. They are documented below.

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, 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/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so",
    "/home/user/OrthancPostgreSQL/Build/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