Document SQLite access to data.

2 files changed, 120 insertions, 4 deletions

diff --git a/doc/api.rst b/doc/api.rst
index d485d90a..eb63719c 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -14,8 +14,9 @@ Coverage.py API
 .. :history: 20121111T235800, added a bit of clarification.
 .. :history: 20140819T132600, change class name to Coverage
 
+There are a few different ways to use coverage.py programmatically.
 
-The API to coverage.py is very simple, contained in a module called `coverage`.
+The API to coverage.py is in a module called `coverage`.
 Most of the interface is in the :class:`coverage.Coverage` class.  Methods on
 the Coverage object correspond roughly to operations available in the command
 line interface. For example, a simple use would be::
@@ -32,12 +33,22 @@ line interface. For example, a simple use would be::
 
     cov.html_report()
 
-The :class:`coverage.CoverageData` class provides access to coverage data
-stored in coverage.py data files.
+Coverage.py supports plugins that can change its behavior, to collect
+information from non-Python files, or to perform complex configuration.  See
+:ref:`api_plugin` for details.
+
+If you want to access the data that coverage.py has collected, the
+:class:`coverage.CoverageData` class provides an API to read coverage.py data
+files.
+
+For more intensive data use, you might want to access the coverage.py database
+file directly.  The schema is subject to change, so this is for advanced uses
+only.  :ref:`dbschema` explains more.
 
 .. toctree::
     :maxdepth: 1
 
     api_coverage
-    api_coveragedata
     api_plugin
+    api_coveragedata
+    dbschema
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: