Schema

Complete catalog model

Understand the database facts Qubu records before creating a snapshot.

Qubu keeps database discovery in a normalized catalog before producing a snapshot. The catalog is a read-only record of observed facts; it does not contain a connection, execute catalog SQL, or assign database catalog keys as persisted logical IDs.

The optional qubu/introspection entry point exposes the complete object families and an immutable materializer:

import {
  createCompleteIntrospectionCatalog,
  mapCatalogToCompleteSnapshot,
} from "qubu/introspection"

const completeCatalog = createCompleteIntrospectionCatalog(catalog)
const result = mapCatalogToCompleteSnapshot(completeCatalog)

Recorded objects

The catalog has typed records for:

  • Tables and columns.
  • Views and materialized views.
  • Sequences, enums, and domains.
  • Collations.
  • Triggers and routines.
  • Partitions and row-level policies.
  • Extension objects.
  • Comments and ownership metadata.

When a reader cannot fully describe an observed object, it retains a deferred or opaque record. The record can keep catalog data and SQL text, along with their source and dialect metadata. The object remains visible for review.

Names and identities

Physical names and references describe the current database. Stable logical IDs are evidence selected by the adapter's identity policy. PostgreSQL OIDs, SQLite implementation names, and similar catalog keys stay in current-run references and are not used as logical IDs.

Snapshot v1

qubu/snapshot provides the strict complete format as a separate API:

import { decodeCompleteSchemaSnapshot, encodeCompleteSchemaSnapshot } from "qubu/snapshot"

const encoded = encodeCompleteSchemaSnapshot(snapshotV1)
const decoded = decodeCompleteSchemaSnapshot(encoded)

Snapshot v1 uses the same qubu-schema envelope with version: 1. Its namespace, capability facts, object-family arrays, cross-object references, provenance, typed dialect extensions, and deferred/opaque boundaries are strictly validated. Arrays are ordered by logical ID (with ordinal sequences and index terms ordered by their semantic position), and the fingerprint is computed from the deterministic encoding.

References to nested objects

Normalized references to nested catalog objects retain their owner scope. A table-local index or constraint reference is mapped with owner: { kind: "table", id }; view columns use the view kind and ID; domain constraints use the domain kind and ID. The legacy tableId shorthand on catalog entity references is converted to that owner form at the Snapshot v1 boundary. Top-level references have no owner. This scope prevents equal child IDs from different tables or object families from overwriting one another.

Opaque data and validation

Catalog extension payloads and configuration records are opaque JSON. Their keys and values are preserved through normalization and canonical encoding; objects inside those payloads are not treated as Snapshot expressions or native storage declarations.

Snapshot v1 is the only strict schema snapshot format. decodeSchemaSnapshot and decodeCompleteSchemaSnapshot both validate the same version-1 envelope, reject unknown fields and future versions, and never evaluate database-provided SQL.