1 files changed, 105 insertions, 0 deletions
diff --git a/doc/dbschema.rst b/doc/dbschema.rst
new file mode 100644
index 00000000..aa838fdf
--- /dev/null
+++ b/doc/dbschema.rst
@@ -0,0 +1,105 @@
+.. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
+
+.. _dbschema:
+
+===========================
+Coverage.py database schema
+===========================
+
+.. versionadded:: 5.0
+
+.. module:: coverage
+
+Coverage.py stores data in a SQLite database, by default called ``.coverage``.
+For most needs, the :class:`CoverageData` API will be sufficient, and should be
+preferred to accessing the database directly.  Only advanced uses will need to
+use the database.
+
+You can use SQLite tools such as the :mod:`sqlite3 <python:sqlite3>` module in
+the Python standard library to access the data.  Some data is stored in a
+packed format that will need custom functions to access.  See
+:func:`register_sqlite_functions`.
+
+
+Database schema
+---------------
+
+This is the database schema.
+
+TODO: explain more. Readers: what needs explaining?
+
+.. copied_from: coverage/sqldata.py
+
+.. code::
+
+    CREATE TABLE coverage_schema (
+        -- One row, to record the version of the schema in this db.
+        version integer
+    );
+
+    CREATE TABLE meta (
+        -- Key-value pairs, to record metadata about the data
+        key text,
+        value text,
+        unique (key)
+        -- Keys:
+        --  'has_arcs' boolean      -- Is this data recording branches?
+        --  'sys_argv' text         -- The coverage command line that recorded the data.
+        --  'version' text          -- The version of coverage.py that made the file.
+        --  'when' text             -- Datetime when the file was created.
+    );
+
+    CREATE TABLE file (
+        -- A row per file measured.
+        id integer primary key,
+        path text,
+        unique (path)
+    );
+
+    CREATE TABLE context (
+        -- A row per context measured.
+        id integer primary key,
+        context text,
+        unique (context)
+    );
+
+    CREATE TABLE line_bits (
+        -- If recording lines, a row per context per file executed.
+        -- All of the line numbers for that file/context are in one numbits.
+        file_id integer,            -- foreign key to `file`.
+        context_id integer,         -- foreign key to `context`.
+        numbits blob,               -- see the numbits functions in coverage.numbits
+        foreign key (file_id) references file (id),
+        foreign key (context_id) references context (id),
+        unique (file_id, context_id)
+    );
+
+    CREATE TABLE arc (
+        -- If recording branches, a row per context per from/to line transition executed.
+        file_id integer,            -- foreign key to `file`.
+        context_id integer,         -- foreign key to `context`.
+        fromno integer,             -- line number jumped from.
+        tono integer,               -- line number jumped to.
+        foreign key (file_id) references file (id),
+        foreign key (context_id) references context (id),
+        unique (file_id, context_id, fromno, tono)
+    );
+
+    CREATE TABLE tracer (
+        -- A row per file indicating the tracer used for that file.
+        file_id integer primary key,
+        tracer text,
+        foreign key (file_id) references file (id)
+    );
+
+.. end_copied_from
+
+
+.. _numbits:
+
+Numbits
+-------
+
+.. automodule:: coverage.numbits
+    :members: