paperspec/sql/README.md

SQL

Table definitions for the database form of packages, a team's store, and the bundle.

File	Holds	Runs on
doc.sql	Documents: works, documents, witnesses, nodes, pages, locations, references, citations, corrections, IDs, receipts, revocations, suspects and package files.	SQLite, Dolt, PostgreSQL
store.sql	What a team adds: roster keys, projects, members, reading paths, layers, annotations, datasets, digitizations, views, policies, submissions and grades. Load doc.sql first.	SQLite, Dolt, PostgreSQL
bundle-sqlite.sql	The bundle's extra tables: metadata, a full-text index (FTS5) and room for embeddings. Load both files above first.	SQLite

Creating a database

sqlite3 lab.db < sql/doc.sql && sqlite3 lab.db < sql/store.sql
psql -d lab -f sql/doc.sql && psql -d lab -f sql/store.sql
dolt sql < sql/doc.sql && dolt sql < sql/store.sql

To load packages into SQLite with nothing installed, use python3 tools/load.py --sqlite lab.db PACKAGE…; docs/examples.md has queries to try.

Conventions

• No foreign keys: validators check references, so the same file runs everywhere.
• Enumerations are VARCHAR with a CHECK; JSON values are canonical JSON in TEXT; booleans are INTEGER 0 or 1.
• No table, column or index name is reserved in any of the three engines, so the formats' key, index, at, by, before and after become doc_key, idx, made_at, signer, before_hash and after_hash.
• Each row keeps every property of its record, so a package loaded into the tables unloads back to the same bytes.
• citations, receipt_nodes and annotation_targets are derived on load, for queries.

A first query

Every sentence that cites a given reference, which is the citation's context:

SELECT c.sentence
FROM citations c
JOIN refs r ON r.doc_key = c.doc_key AND r.node = c.ref_node
WHERE c.doc_key = 'hale2026harmonic' AND r.label = '2';

Chapter 13 defines the mapping from files to tables.