The on-disk schema
The index is one SQLite file. Get the canonical DDL with nci sql --schema. The tables below are the public surface that query and sql read from — column names match what the live database exposes.
The authoritative source
That command prints the live CREATE TABLE statements straight from the open database. Everything below summarises those statements; if anything here disagrees with --schema, trust --schema.
Tables on the public surface
| Table | What it stores | Primary join |
|---|---|---|
packages | One row per indexed package install: name, version, index_cache_key (per-package crawl cache), backfill_revision (symbol SQL migrations). | symbols.package_id = packages.package_id |
symbols | One row per merged graph symbol — declarations, signatures, JSDoc, source-package ownership, internal/global flags. | Filter by package_id first, then by name / kind_name. |
symbol_additional_files | Extra declaration files folded into the same merged symbol row. | symbol_id = symbols.symbol_id |
symbol_dependencies | Resolved “uses” edges between symbols, after graph resolution (nci-dep-v1). | from_symbol_id + to_symbol_id_text |
symbol_surface_dependencies | Rolled-up namespace/module-surface deps. Not interchangeable with symbol_dependencies on member rows. | Same id shape as symbol_dependencies |
symbol_inherited_from_sources | For synthesised inherited members, the base/source symbols that contributed. | symbol_id + source_symbol_id_text |
symbol_heritage | Verbatim extends / implements clause text per symbol. | symbol_id |
symbol_modifiers, symbol_decorators | Structured modifiers (declare, readonly, …) and decorators per symbol. | symbol_id |
package_dependencies | Declared npm dependency names per indexed package — package-level, not symbol-level. | package_id |
symbols_fts (FTS5) | Full-text index over symbol name / signature / JSDoc. Backs nci query find and nci query evidence. | External content table over symbols |
Inspecting it
nci sql only accepts read-only statements. Mutating SQL (INSERT, UPDATE, DELETE, DROP) is rejected before it ever touches the database.
Migrations and journaling
The CLI applies pending schema migrations on nci db init, nci db migrate, and the first nci index. Symbol-only work after a Backfill migration runs during nci index or via nci db backfill.
Migrate records one pending_backfill target (latest Backfill version in the batch). The engine then runs every registered per-package step with backfill_revision < step_version <= pending_backfill in order — Instant-only versions register no step. See SQLite migrations contract.
Plain output includes schema_version (stored DDL), indexer_output_revision (embedded crawl fingerprint), and engine_version (crate release). Use --check for PRAGMA quick_check, --deep for full integrity_check, and nci db wal-checkpoint to truncate the WAL after a long indexing run.