Mercurial > hg > orthanc-book

annotate Sphinx/source/faq/orthanc-storage.rst @ 36:6474af38dcbd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
SQLITE_BUSY
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 20 Jul 2016 15:19:08 +0200
parents 5737f51ff94e
children 38fb7bf24794
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
35
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 How does Orthanc stores its database?
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2 =====================================
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 Storage folder
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5 --------------
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
6
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
7 **By default** (i.e. if no database plugin such as :ref:`PostgreSQL
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
8 <postgresql>` is used), Orthanc stores all the DICOM files it receives
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
9 in a folder called ``OrthancStorage`` on the filesystem. Orthanc also
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
10 associates each incoming DICOM file with a JSON file that summarizes
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
11 all its DICOM tags, which speeds up subsequent processing by avoiding
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
12 a costly DICOM parsing.
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
13
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
14 More generally, the ``OrthancStorage`` folder contains a set of
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
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
52
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
53 Direct access
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
54 -------------
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
55
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
56 Directly accessing the content of the ``OrthancStorage`` folder and
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
57 the content of the SQLite database is strongly discouraged for several
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
58 reasons:
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
59
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
60 * This internal organization is only true when no database plugin is
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
61 used (e.g. the :ref:`PostgreSQL plugin <postgresql>` can be
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
62 configured to store the attachments inside a database).
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
63 * 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
64 them on the disk (cf. the ``StorageCompression`` option).
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
65 * 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
66 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
67 data corruption.
36
6474af38dcbd SQLITE_BUSY
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 35
diff changeset
68 * One SQLite database should be accessed by at most one process at any
6474af38dcbd SQLITE_BUSY
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 35
diff changeset
69 time to avoid any problem (e.g. with NFS filesystems), for reasons
6474af38dcbd SQLITE_BUSY
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 35
diff changeset
70 that are `explained in the SQLite FAQ
6474af38dcbd SQLITE_BUSY
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 35
diff changeset
71 <https://www.sqlite.org/faq.html#q5>`__. Orthanc will stop if it
6474af38dcbd SQLITE_BUSY
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 35
diff changeset
72 receives the ``SQLITE_BUSY`` status.
35
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
73
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
74 As a consequence, it is **HIGHLY recommended NOT to directly access**
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
75 the ``OrthancStorage`` folder and the SQLite database. Use the
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
76 :ref:`REST API <rest>` instead, which contains primitives to access
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
77 the attachments (cf. the ``.../attachments/...`` URIs).
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
78
5737f51ff94e How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
79 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
80 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
81 :ref:`upgrade/replication <replication>` process.