When Orthanc's SQLite index stops being enough for production
SQLite fits a single Orthanc instance with modest volume. PostgreSQL fits once the archive grows, several Orthanc instances must share one database, or high availability is required. An imaging team or hospital IT lead whose archive is growing needs to decide which side of that line the site is on before the index becomes a bottleneck during a clinical workday. The Orthanc Book's scalability FAQ says the built-in SQLite index should be replaced by an enterprise database engine once Orthanc stores several hundred thousand DICOM instances, and it recommends the PostgreSQL plugin for large datasets. That threshold is a documented starting point, not a switch that flips at an exact count, so the first check is to measure the current instance count and its growth rate per month.
The choice is also a licensing and operations decision, not only a database one. The Orthanc core is GPLv3 or later, but the PostgreSQL plugin is licensed AGPLv3 or later, so the team must review what that means for its own distribution and any modifications, with its legal counsel. Operationally, PostgreSQL adds a database service that someone must back up, patch, monitor and restore, and a DBA or platform engineer should own it. Since Orthanc 1.9.2 with PostgreSQL/MySQL plugins 4.0, multiple instances can read and write the same database, which is the route to horizontally scaled and highly available setups. Confirm with Orthanc Team which plugin versions match your Orthanc release before you commit to a design, and review the Orthanc Book scalability FAQ for the current guidance.
SQLite and PostgreSQL compared on the factors that drive the decision
This table compares Orthanc's built-in SQLite index with the PostgreSQL plugin across scale, multi-instance operation, licensing, operating components, backup and migration. Read each row for the condition under which that option is the better fit, since the right answer depends on instance volume, how many Orthanc nodes you run and whether you already operate PostgreSQL.
| Factor | SQLite index (built-in) | PostgreSQL plugin |
|---|---|---|
| Scale guidance | The Orthanc Book says the built-in index should be replaced once several hundred thousand DICOM instances are stored. Fine for a single site with a modest archive. | The docs recommend the PostgreSQL plugin for large datasets. Choose it once your archive approaches the volume where the built-in index is no longer advised. |
| Multi-instance support | Designed for one Orthanc process using its own local database file. Not suited to several nodes sharing one archive. | Since Orthanc 1.9.2 with PostgreSQL/MySQL plugins 4.0, multiple Orthanc instances can read and write the same database. Needed for horizontally scaled setups. |
| High availability | No shared index to fail over to. Availability depends on restoring the single node and its files. | Enables highly available setups when paired with a database that you operate with its own failover. Confirm the failover design with your DBA and Orthanc Team. |
| Plugin license | No separate plugin license applies because the index is part of the Orthanc core, licensed GPLv3 or later. | The PostgreSQL plugin is licensed AGPLv3 or later. Have legal review the AGPL terms, especially if you modify the plugin or offer it as a network service. |
| Operating components | Single Orthanc service with its local index. Minimal moving parts for a small team. | Adds a PostgreSQL server to operate, including patching, connection management, monitoring and access control. Plan for a database administrator or a managed service. |
| Backup approach | Back up the Orthanc storage folder and the SQLite index together so they stay consistent. Test restores on a separate host. | Back up the PostgreSQL database and the DICOM object storage together. Confirm point-in-time recovery needs with your database team and test restores regularly. |
| Migration effort | Starting point for most new installations. Moving off it later requires a migration to the PostgreSQL plugin, so plan a rehearsal on a copy of production data. | Target state for growth. Migrating a live archive needs a tested procedure, a maintenance window and verification of instance counts after the move. Ask Orthanc Team to scope the migration in writing. |
What instance counts the Orthanc docs give for switching
The Orthanc Book's scalability FAQ says the built-in SQLite index should be replaced by an enterprise database engine once Orthanc stores several hundred thousand DICOM instances, and it recommends the PostgreSQL plugin for large datasets. That is the documented trigger to plan for, not a hard limit that Orthanc enforces. Treat it as the point where you start a migration plan, and check your own instance count against it on the server you run today, including any archives you expect to receive from modalities over the next year.
The same FAQ cites production hospital deployments holding more than 65 TB of data, 340,000 studies and around 150 million instances. These figures show the scale that the PostgreSQL route has been used at, but they describe other sites' hardware, storage layouts and workloads, so they do not predict your performance. Ask your Orthanc partner or the vendor which deployment profile, storage back end and query pattern produced those numbers before you use them to justify a design.
Instance count is one signal, not the decision. Concurrency matters because many radiologists, a PACS gateway and automated pipelines querying at once put more load on the index than a large but quiet archive. Availability matters because a single SQLite file on one host is a single point of failure. Growth rate matters because a server that is fine today can cross the threshold within a budget cycle. Record peak concurrent users and API clients, the required recovery time, and the monthly instance growth, then compare them with the instance count before you decide.
What the PostgreSQL plugin adds beyond storage
The PostgreSQL plugin moves the Orthanc index out of a local file and into a database server that several parts of your imaging stack can share. The cards below separate what that enables, such as shared state and high availability, from what it asks of your team, such as running and backing up another service.
Shared database across instances
With the PostgreSQL plugin, the metadata index lives in a database server instead of a SQLite file on one host. Teams that run more than one Orthanc node, or that need a second node for maintenance, can point them at the same database. Before you rely on it, confirm which plugin versions your deployment pins, because the shared-access behavior depends on the plugin generation. The trade-off is that the database becomes a dependency you must back up, monitor and patch.
Horizontally scaled and highly available setups
Since Orthanc 1.9.2 with PostgreSQL or MySQL plugins 4.0, several Orthanc instances can read and write the same database. This is the basis for load-spreading and failover designs. Availability then depends on the database and the storage area as much as on Orthanc itself, so the team must plan replication, failover testing and storage redundancy. Ask your architect to document which component is the single point of failure.
PostgreSQL and MySQL/MariaDB back ends
Official plugins cover PostgreSQL and MySQL/MariaDB, and an ODBC back end is also available. Choose the engine your database team already operates, since they will carry the backup, patching and access control work. Note that the scalability and cloud plugins are licensed AGPLv3 or later, so confirm with counsel how that license applies to your distribution and any internal modifications before deployment.
Object storage through S3, Azure or Google Cloud
Official plugins store DICOM files in S3, Azure or Google Cloud object storage rather than on local disks. This pairs well with a database server because both the index and the files can live in managed services. It also changes your recovery plan: index and objects must be restored to a consistent point. Confirm how your team will keep the database and the bucket in step during backup and restore tests.
DICOMweb and Orthanc Explorer 2
The DICOMweb plugin exposes standard web interfaces for other clients, and Orthanc Explorer 2 provides a newer browser interface. Both are useful once several users or systems query one archive. Each adds an exposed interface to secure, so check authentication settings and the reverse proxy in front of them. Remote access stays off by default, and the security FAQ recommends HTTPS and a reverse proxy for any Internet exposure.
How the AGPL plugin license changes what you must share
The first question is which code you are licensing for. The Orthanc core is licensed GPLv3 or later, while the scalability and cloud plugins, including the PostgreSQL and web viewer plugins, are licensed AGPLv3 or later. The practical difference is network use. The GPL triggers source obligations when you distribute a program. The AGPL extends those obligations to software that users interact with over a network, so if you modify the PostgreSQL plugin and make it available to users who reach it through your servers, you may have to offer them the corresponding source of that modified plugin. Running an unmodified plugin internally usually creates a lighter set of duties, but that depends on how your deployment is structured and who can access it.
The licensing picture also depends on who owns the code. Copyright in Orthanc is shared among the University Hospital of Liege (2012 to 2016), Osimis S.A. (2017 to 2024, now defunct), Orthanc Team SRL (2024 to present) and UCLouvain (2021 to present). The Orthanc Book states that UCLouvain contributions since September 1, 2021 cannot be dual licensed. That limits what a commercial arrangement can offer. Before you assume a proprietary exception is available, ask Orthanc Team in writing what it can and cannot grant for the specific plugin versions you plan to run, and check the Orthanc Book licensing FAQ for the current position.
Have counsel review the obligations for your own deployment and for any modifications before go-live. Ask them to examine whether your team will change the plugin, whether a vendor or contractor will, and whether the service is offered to users outside your organization. Record the plugin version, any patches and the source location in your configuration baseline so you can answer a source request quickly. This review is a legal task that DeployOpen does not perform, and its outcome should be documented in your own compliance file.
Operating effort for SQLite and PostgreSQL deployments
This table compares what each storage option asks of your team after go-live: plugin alignment, backups, monitoring, failover and skills. Read each row as a question to answer for your own environment, since the SQLite option carries less moving parts while the PostgreSQL option adds a database team's worth of duties. The main takeaway is that PostgreSQL buys shared state and high availability, and you pay for them with database administration and high availability design work.
| Area | SQLite index | PostgreSQL plugin |
|---|---|---|
| Plugin version alignment | Nothing separate to align beyond the Orthanc build itself | Orthanc core and the PostgreSQL plugin must be matched and upgraded together, so each Orthanc release needs a compatibility check |
| Upgrades | One process and one index file to stage, test and roll back | Database engine, PostgreSQL plugin and every Orthanc node are upgraded in a planned order, ideally with a rehearsal on a copy |
| Database backup and restore | Back up the storage area and index together while Orthanc is stopped or in a consistent state | Schedule database dumps or physical backups and test restores, and keep the DICOM storage area in step with the database |
| Connection and storage monitoring | Watch disk space and Orthanc logs on one host | Track database connections, query latency, disk growth and replication lag alongside Orthanc logs |
| Failover | Restoring a single host from backup is the usual recovery path | Requires a designed high availability setup with several Orthanc instances sharing one database, which your team must build and rehearse |
| Orthanc administration skills | Needed for both options: DICOM concepts, modalities, security settings and plugin configuration | Needed for both options, with added attention to shared configuration across nodes |
| PostgreSQL administration skills | Not required for day-to-day operation | Needed in house or through a contracted partner: roles, tuning, vacuum and maintenance, backup tooling and patching |
| High availability design skills | Not required for a single-instance setup | Needed to design load balancing, shared storage access, failover testing and recovery objectives |
How to migrate an Orthanc SQLite index to PostgreSQL
This sequence moves an existing Orthanc index from its built-in SQLite database to a PostgreSQL database that you can back up, rehearse and verify before production users depend on the new setup.
Inventory instance count and storage
The Orthanc administrator records how many DICOM instances and studies the server holds, where the storage area lives, how much disk it uses, and which plugins and configuration files are in place. The Orthanc Book says the built-in SQLite index should be replaced once a server stores several hundred thousand instances, so this count tells you whether the move is due now or is planned ahead of growth. The step is done when the counts, storage path and configuration are written into the change record.
Confirm Orthanc and plugin versions
The platform engineer checks that the Orthanc core and the PostgreSQL plugin are a compatible pair. Shared access by several Orthanc instances requires Orthanc 1.9.2 or later with PostgreSQL plugin 4.0, so this check decides whether you are planning a single-server move or a shared database for several instances. Read the release notes for the target version before any upgrade, including Orthanc 1.13.0, released on 2026-08-15, which rewrote storage-area access and DICOM parsing. The step is done when the target versions are pinned in the change record and the vendor or Orthanc Team confirms support for your environment.
Stand up PostgreSQL and take a backup
The database administrator provisions a PostgreSQL instance in the same network zone as Orthanc, with storage, access controls and a backup schedule agreed with the security team. Before any data moves, take a full backup of the existing SQLite index and the storage area, and confirm you can restore it to a separate host. Record the database version, the Orthanc connection settings you intend to use and the restore test result. The step is done when a restore of the backup has been tested and signed off.
Rehearse the move on a copy
The Orthanc administrator runs the migration on a copy of the production index and storage area in a non-production environment, using the same Orthanc and plugin versions planned for cutover. The rehearsal shows how long the import takes on your hardware, whether the PostgreSQL configuration works, and whether any custom scripts, DICOMweb clients or modality settings break. Record each problem and its fix so the cutover runbook reflects what you actually saw. The step is done when a full rehearsal completes without unresolved errors.
Cut over with a rollback path
During an agreed maintenance window, the operations team stops new writes from modalities, places the SQLite-based server in read-only or offline state, runs the final migration against the production copy and starts Orthanc on PostgreSQL. The SQLite files and the original configuration stay untouched so the team can restart the previous service if a critical failure appears. Notify the clinical and imaging owners before the window opens. The step is done when Orthanc accepts a test study and the team has written the rollback trigger and steps into the runbook.
Verify instance counts and DICOM queries
The verifier compares the instance and study counts in PostgreSQL with the pre-migration inventory, then runs DICOM C-FIND queries from a known modality or test client using patient, study and date filters. Counts that differ from the inventory, or queries that return different results, mean the migration must be investigated before release. Keep the comparison output with the change record. The step is done when counts match and sample queries return the expected studies.
Verify retrieval and sign off the cutover
The verifier retrieves a sample of studies over DICOM C-GET or C-MOVE and over the DICOMweb or Orthanc REST interface, then checks that the images open correctly in the viewer your clinicians use. If you have enabled remote access, confirm that the authentication settings and HTTPS reverse proxy still apply after the move. The owners of the imaging service sign the cutover record, and the old SQLite files are kept under the retention rule your organization sets. The step is done when retrieval tests pass and the sign-off is filed.
What remote access and HA setups need from security controls
By default, Orthanc only accepts HTTP connections from localhost, so the security question starts the moment you enable remote access. The Orthanc Book's security FAQ says that when RemoteAccessAllowed is set to true, AuthenticationEnabled should also be true, with every permitted user listed under RegisteredUsers. Treat that pair as the minimum baseline, not an optional hardening step. Before any clinician, referring site or integration engine reaches the server over the network, confirm which accounts exist, who owns each one and how credentials are rotated.
The same guidance recommends HTTPS and a reverse proxy when the server is exposed to the Internet. Terminate TLS at the proxy, restrict which paths and methods it forwards, and keep the Orthanc REST port off the public interface. Note that a PostgreSQL-backed setup adds more than one listening instance. Each Orthanc node is another HTTP endpoint to configure, patch and monitor, and the shared database is another connection that needs its own network rules and credentials. Horizontal scaling therefore widens the attack surface even when the storage gets more robust.
If your requirements go beyond username and password access, such as per-user or per-role limits on studies, modalities or actions, check the advanced authorization plugin, which the Orthanc Book lists among the official plugins. Confirm with Orthanc Team or against the plugin documentation whether it covers your access model before you design around it. Whichever controls you choose, test them against your own scenarios, including a user who should see one study set and not another, before the design is signed off.
Questions teams ask before moving Orthanc off SQLite
At what size should a team move Orthanc off SQLite?
The Orthanc Book's scalability FAQ says the built-in SQLite index should be replaced by an enterprise database engine once Orthanc stores several hundred thousand DICOM instances, and it recommends the PostgreSQL plugin for large datasets. Treat that as a threshold to plan against, not a switch to flip on a date. Growth rate matters as much as the current count: a site adding studies every day reaches the threshold sooner than an archive that grows slowly. Plan the move before query times or maintenance windows start to hurt clinical workflows, and check your own instance count against the threshold with your current deployment.
Is Orthanc migration cost fixed or does it vary with archive size?
It varies. The main drivers are the number of stored instances and the volume of data that must be re-indexed or verified, the number of connected modalities, DICOMweb clients, viewers and scripts that depend on the current setup, the amount of downtime your clinical operations can accept, and whether the new database runs on infrastructure you already operate. Each of these changes the hours of planning, testing and cutover work. Ask any implementation partner for a written scope that lists the archive size, the integrations to re-point, the rollback plan and the acceptance tests, then compare quotes against that same scope.
Can our own team run the PostgreSQL database behind Orthanc?
Often yes, if you already run and back up PostgreSQL for other systems. The database itself is standard infrastructure, but Orthanc stores imaging metadata and depends on it for every query, so the team needs routine skills in backups, restore testing, connection management, upgrades and monitoring. Confirm these questions internally: who is on call for the database, how restores are tested, who owns the schema upgrades that come with plugin upgrades, and whether your change process allows the database to be maintained separately from the imaging server. If any answer is unclear, a managed or partner-run database may suit you better.
What does high availability need beyond the PostgreSQL database?
Since Orthanc 1.9.2 with PostgreSQL/MySQL plugins 4.0, multiple Orthanc instances can read and write the same database, which makes horizontally scaled and highly available setups possible. The database is only one layer. You also need shared access to the stored DICOM files, such as shared storage or an object storage plugin, a load balancer or reverse proxy in front of the instances, health checks, a consistent authentication setup on every node, and a tested failover procedure. Network paths from modalities and viewers must also survive a node loss. Confirm each layer in writing, because a database with two healthy nodes does not protect an archive whose files sit on one disk.
What does the AGPL plugin license mean for internal use versus distribution?
The Orthanc core is GPLv3 or later, while the PostgreSQL and web viewer plugins are AGPLv3 or later. Running these plugins inside your own organization for your own users is generally a different situation from distributing software to others, but whether any specific use triggers obligations depends on how you deploy, modify and expose the software. If you modify the plugins, offer them as a network service to outside users, or bundle them into a product you sell, get written advice from counsel before you proceed. Also note that UCLouvain contributions since September 1, 2021 cannot be dual licensed, so a separate commercial license is not a general option.
Does Orthanc Team SRL sell deployment and support for Orthanc?
Yes. Orthanc Team SRL sells deployment, configuration and development services, including pre-paid dedicated support hours that are valid for 12 months, and it quotes these on request. There is no paid edition of Orthanc itself, so you pay for the people doing the work rather than for a license. Confirm with the vendor which hours are included, how urgent requests are handled, and whether the terms cover PostgreSQL plugin upgrades. DeployOpen is a separate company that plans, implements, hardens, backs up and supports self-hosted platforms in your infrastructure, and its engagements are fixed-scope and agreed in writing before work starts.
What should we ask for in a quote for an Orthanc database migration?
Ask for a written scope that names the current instance count and storage size, the target database and version, the plugins in use, and every system that talks to Orthanc. Request a step-by-step migration plan with a rollback path, the downtime window the plan assumes, data verification steps, and acceptance tests your clinical and imaging teams sign off. Ask who performs backups before cutover, how security settings carry over (for example, whether authentication and HTTPS remain enabled once remote access is on), what documentation and runbooks you receive, and what post-migration support is included. Compare quotes on this scope, not on headline price.
A decision path for choosing the storage backend
This sequence takes a team from its current instance count to a clear storage decision, so the choice between SQLite and PostgreSQL follows from facts about scale, topology, uptime, staffing and licensing rather than preference. Each step ends with an outcome: stay on SQLite, move to PostgreSQL, or get an assessment first.
Measure current and projected instance counts
Start by counting the DICOM instances the archive holds today and estimating how fast new studies arrive, using your own modality volumes and retention rules. Ask the team that owns the modalities or the PACS for these figures in writing, not from memory. The Orthanc docs say the built-in SQLite index should be replaced by an enterprise database engine once several hundred thousand instances are stored, so compare your count against that threshold. Outcome: if you are well below several hundred thousand instances and growth is slow, stay on SQLite and re-run this check at each quarterly review. If you are near or above the threshold, move to step two with PostgreSQL as the likely target.
Confirm whether multiple instances must share data
Decide whether more than one Orthanc process must read and write the same archive, for example behind a load balancer or across two sites. Since Orthanc 1.9.2 with PostgreSQL or MySQL plugins 4.0, several instances can share one database, which is what enables horizontally scaled and highly available setups. A single SQLite-backed instance cannot offer this. Outcome: if one instance is enough, stay on SQLite unless step one already pointed to PostgreSQL. If the design requires shared access, move to PostgreSQL and document the topology in your architecture record.
Define how much downtime the archive can absorb
Ask clinical operations, radiology leadership and the imaging informatics lead how long the archive can be unavailable during a failure, an upgrade or a maintenance window, and whether a second node must take over without manual steps. Write the answer down as a stated requirement, because it drives whether a single-node SQLite design is defensible. Outcome: if short, planned outages are acceptable and recovery from backup is tested, stay on SQLite. If automatic failover or near-continuous access is required, move to PostgreSQL and plan the highly available topology in step two.
Check whether your team can operate PostgreSQL
Identify who will patch, back up, monitor, tune and restore the database, and whether that person or team already runs PostgreSQL in your environment. Moving to PostgreSQL adds a database to operate alongside Orthanc, with its own backups, access control and upgrades. If that skill is missing, confirm with your database team or an implementation partner what training or support is needed before you commit. Outcome: if the team can run PostgreSQL with tested backup and restore, move to PostgreSQL. If not, get an assessment first, covering the staffing, training and support options, before choosing either backend.
Review AGPL obligations for the plugin
Have legal or compliance review the licensing position. The Orthanc core is GPLv3 or later, but the PostgreSQL plugin is licensed AGPLv3 or later, and the Orthanc Book licensing FAQ explains how that affects what you must provide when you modify or network-expose the software. Confirm with counsel whether your planned use, internal deployment or any custom changes trigger obligations you can meet. Outcome: if counsel confirms the AGPL terms are acceptable for your use, continue to the final step. If the position is unclear or unacceptable, get an assessment first, or keep SQLite and revisit once the review is complete.
Record the decision and the migration plan
Write a short decision record that lists the answers from each step, names the accountable owner and states the chosen backend. If the outcome is PostgreSQL, add a migration plan: a rehearsal on a copy of the data, a verified backup before cutover, and a rollback path. Confirm with the Orthanc Book migration guidance or your implementation partner how the data and configuration move, since those steps are specific to your version. Outcome: a signed decision record that either keeps SQLite with a review date or moves to PostgreSQL with a rehearsed migration.
How DeployOpen scopes and delivers an Orthanc storage migration
DeployOpen plans, implements, hardens, backs up, documents and supports self-hosted open-source platforms inside the client's own infrastructure. For Orthanc SQLite vs PostgreSQL, we start from the instance count, access pattern and availability requirements of your Orthanc deployment, then agree a written scope before any migration work begins.
How we scope
- Inventory the current Orthanc version, plugins, storage paths and instance counts before proposing a target design.
- Document whether a shared PostgreSQL database, multiple Orthanc instances or high availability are actually required.
- Agree deliverables, timelines and responsibilities in writing; most engagements are fixed-scope.
How we build
- Stand up PostgreSQL and the Orthanc PostgreSQL plugin inside your cloud account, data center or air-gapped network.
- Review plugin license obligations under AGPLv3 with your legal team before any production rollout.
- Test the migration in a non-production copy, checking study counts, retrieval and DICOM connectivity against the source index.
How we hand over
- Provide written runbooks for configuration, access control, backup, restore and rollback steps.
- Document the cutover plan, the verification checklist and the sign-off evidence collected during testing.
- Walk your operations team through the running system so they can operate and troubleshoot it independently.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after handover.
- Plan Orthanc version upgrades and plugin updates against your own change windows and test results.
- Confirm with your team which support hours, response expectations and escalation paths the retainer should include.
