Mercurial > hg > orthanc-book
annotate Sphinx/source/faq/orthanc-storage.rst @ 660:a6e371768a70
dicom-as-json
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Thu, 29 Apr 2021 12:41:31 +0200 |
parents | b3e75cef601d |
children | 17c1ff4e6ae4 |
rev | line source |
---|---|
46
12b204ee328d
remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
37
diff
changeset
|
1 .. _orthanc-storage: |
12b204ee328d
remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
37
diff
changeset
|
2 |
37 | 3 How does Orthanc store its database? |
4 ==================================== | |
35
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
5 |
318
83d822f11e78
SeriesMetadata and StudiesMetadata in DICOMweb
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
6 Storage area |
83d822f11e78
SeriesMetadata and StudiesMetadata in DICOMweb
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
7 ------------ |
35
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
8 |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
9 **By default** (i.e. if no database plugin such as :ref:`PostgreSQL |
154 | 10 <postgresql>` or :ref:`MySQL <mysql>` is used), Orthanc stores all the |
11 DICOM files it receives in a folder called ``OrthancStorage`` on the | |
622
debcf6b6d070
dicom-as-json is now deprecated
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
618
diff
changeset
|
12 filesystem. |
35
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
13 |
622
debcf6b6d070
dicom-as-json is now deprecated
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
618
diff
changeset
|
14 More precisely, the ``OrthancStorage`` folder contains a set of |
35
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
15 so-called **attachments**, that may correspond to either a DICOM file, |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
16 a JSON file, or any user-defined file. Internally, each attachment is |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
17 automatically associated with an `universally unique identifier (UUID) |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
18 <https://en.wikipedia.org/wiki/Universally_unique_identifier>`__. |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
19 Orthanc can be configured to compress these files on-the-fly in order |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
20 to save disk space (cf. the ``StorageCompression`` :ref:`configuration |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
21 option <configuration>`). |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
22 |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
23 To reduce the number of files in a single directory (which is |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
24 something that some operating systems might not like), a 3-level |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
25 hierarchy of directories is created to store the attachments: The |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
26 first two hexadecimal characters of the UUID give the first-level |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
27 folder, and the two next characters give the second-level folder. |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
28 |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
29 |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
30 SQLite index |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
31 ------------ |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
32 |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
33 Inside the same ``OrthancStorage`` folder, Orthanc maintains a `SQLite |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
34 database <https://en.wikipedia.org/wiki/SQLite>`__ called ``index`` |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
35 that **indexes** all these attachments. The database records, for each |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
36 attachment, its compression method, and its MD5 hashes before and |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
37 after compression in order to detect disk corruption (cf. the |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
38 ``StoreMD5ForAttachments`` :ref:`configuration option |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
39 <configuration>`). |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
40 |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
41 One attachment must be associated with one :ref:`DICOM resource |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
42 <model-world>` (patient, study, series, or instance). Incoming DICOM |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
43 files and associated JSON summary are associated with one |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
44 instance-level resource, but user-defined attachments can be |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
45 associated with any kind of resource. |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
46 |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
47 Given one DICOM resource, all of its child attachments are identified |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
48 by a number between 0 and 65535. Identifiers <= 1023 are reserved for |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
49 the Orthanc core, whereas identifiers >= 1024 can be user-defined for |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
50 external applications. |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
51 |
272 | 52 Besides the attachments, the database index maintains other |
53 information for each DICOM resource, notably the :ref:`metadata | |
54 <metadata>`, the :ref:`history of changes <changes>`, and an | |
55 associative map that stores the so-called "main" DICOM tags (to avoid | |
56 accessing the storage folder are when this is not needed). The SQLite | |
57 database schema is kept as simple as possible, and can be found in the | |
58 following two files of the source code of Orthanc: | |
59 `PrepareDatabase.sql | |
638 | 60 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.9.2/OrthancServer/Sources/Database/PrepareDatabase.sql>`__ |
272 | 61 and `InstallTrackAttachmentsSize.sql |
638 | 62 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.9.2/OrthancServer/Sources/Database/InstallTrackAttachmentsSize.sql>`__. |
272 | 63 |
35
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
64 |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
65 Direct access |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
66 ------------- |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
67 |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
68 Directly accessing the content of the ``OrthancStorage`` folder and |
409 | 69 the content of the SQLite/MySQL/PostgreSQL database is strongly |
70 discouraged for several reasons: | |
35
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
71 |
409 | 72 * The internal organization outlined above is only true when no |
73 database plugin is used (e.g. the :ref:`PostgreSQL <postgresql>` and | |
74 :ref:`MySQL <mysql>` plugins can be configured to store the | |
75 attachments inside a database). | |
35
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
76 * Orthanc can be configured to compress the attachments before writing |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
77 them on the disk (cf. the ``StorageCompression`` option). |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
78 * By directly reading the content of ``OrthancStorage``, you bypass |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
79 all the locking mechanisms used by Orthanc, which might result in |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
80 data corruption. |
36 | 81 * One SQLite database should be accessed by at most one process at any |
82 time to avoid any problem (e.g. with NFS filesystems), for reasons | |
83 that are `explained in the SQLite FAQ | |
84 <https://www.sqlite.org/faq.html#q5>`__. Orthanc will stop if it | |
85 receives the ``SQLITE_BUSY`` status. | |
35
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
86 |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
87 As a consequence, it is **HIGHLY recommended NOT to directly access** |
409 | 88 the ``OrthancStorage`` folder and the SQLite/MySQL/PostgreSQL |
89 database. Use the :ref:`REST API <rest>` instead, which contains | |
90 primitives to access the attachments (cf. the ``.../attachments/...`` | |
91 URIs). | |
35
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
92 |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
93 The only exception to this rule is for **read-only access when Orthanc |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
94 is stopped**, e.g. as a part of a :ref:`backup <backup>` or |
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
95 :ref:`upgrade/replication <replication>` process. |