Database plugins for Orthanc
============================


General information
-------------------

This repository contains the source code of various database plugins
for Orthanc, the lightweight, RESTful DICOM server. These plugins
enable Orthanc to store its index and its storage area within
well-known relational databases systems (RDBMS).


Content
-------

* ./Framework/  : code shared by all the plugins
* ./MySQL/      : index and storage plugins for MySQL and MariaDB
* ./PostgreSQL/ : index and storage plugins for PostgreSQL
* ./Odbc/       : index and storage plugins for Odbc
* ./SQLite/     : index plugin for SQLite (for experimentation)

If you downloaded this project as a versioned release package
(.tar.gz) focused on one given RDBMS, you will only find the folders
that are related to this specific RDBMS. The full source code is
available at:
https://orthanc.uclouvain.be/hg/orthanc-databases/


Compilation and usage
---------------------

The compilation and usage of the plugins is available in the Orthanc
Book:

* MySQL/MariaDB : https://orthanc.uclouvain.be/book/plugins/mysql.html
* PostgreSQL    : https://orthanc.uclouvain.be/book/plugins/postgresql.html
* ODBC          : https://orthanc.uclouvain.be/book/plugins/odbc.html


Older releases of PostgreSQL
----------------------------

This repository supersedes the older "orthanc-postgresql" repository
that was only focused on PostgreSQL.

Releases <= 2.1 of the PostgreSQL plugins can still be found in the
following legacy repository:
https://orthanc.uclouvain.be/hg/orthanc-postgresql/


Contributing
------------

Instructions for contributing to the Orthanc project are included in
the Orthanc Book:
https://orthanc.uclouvain.be/book/developers/repositories.html


Development
-----------

PostgreSQL
==========

To quickly start a test PG server:

  docker run -p 5432:5432 --rm --env POSTGRES_HOST_AUTH_METHOD=trust postgres:13.4

And use this Orthanc configuration:
  "PostgreSQL": {
    "EnableIndex": true,
    "EnableStorage": false, // DICOM files are stored in the Orthanc container in /var/lib/orthanc/db/
    "Host": "localhost", // the name of the PostgreSQL container
    "Database": "postgres", // default database name in PostgreSQL container (no need to create it)
    "Username": "postgres", // default user name in PostgreSQL container (no need to create it)
    "Password": "postgres"
  },

MySQL
=====

To quickly start a test MySQL server:

  docker run -p 3306:3306 --rm --env MYSQL_PASSWORD=orthanc --env MYSQL_USER=orthanc --env MYSQL_DATABASE=orthanc --env MYSQL_ROOT_PASSWORD=pwd-root mysql:8.0 mysqld --default-authentication-plugin=mysql_native_password --log-bin-trust-function-creators=1

And use this Orthanc configuration:
  "MySQL": {
    "EnableIndex": true,
    "EnableStorage": false,
    "Host": "localhost",
    "Database": "orthanc",
    "Username": "orthanc",
    "Password": "orthanc",
    "UnixSocket": ""
  },


ODBC (SQL Server)
=================

To quickly start a test MySQL server:

  docker run -e "ACCEPT_EULA=Y" --rm --env "SA_PASSWORD=yourStrong-Password" --entrypoint=bash -it -p 1433:1433 mcr.microsoft.com/mssql/server:2019-latest

Then:  
   (sleep 15s && /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P yourStrong-Password -Q 'CREATE DATABASE orthanctest') & /opt/mssql/bin/sqlservr

And use this Orthanc configuration:
  "Odbc" : {
    "IndexConnectionString": "Driver={ODBC Driver 17 for SQL Server};Server=tcp:localhost,1433;Database=orthanctest;Uid=sa;Pwd=yourStrong-Password;Encrypt=yes;TrustServerCertificate=yes;Connection Timeout=30;",
    "EnableIndex": true,
    "EnableStorage": false
  }


SQLite
======

To quickly test the SQLite plugin, simply run orthanc and load the plugin (no configuration required).
  

Licensing
---------

The database plugins for Orthanc are licensed under the AGPL license.

We also kindly ask scientific works and clinical studies that make
use of Orthanc to cite Orthanc in their associated publications.
Similarly, we ask open-source and closed-source products that make
use of Orthanc to warn us about this use. You can cite our work
using the following BibTeX entry:

@Article{Jodogne2018,
  author="Jodogne, S{\'e}bastien",
  title="The {O}rthanc Ecosystem for Medical Imaging",
  journal="Journal of Digital Imaging",
  year="2018",
  month="Jun",
  day="01",
  volume="31",
  number="3",
  pages="341--352",
  issn="1618-727X",
  doi="10.1007/s10278-018-0082-y",
  url="https://doi.org/10.1007/s10278-018-0082-y"
}