testing/schema_introspect.ts

PostgreSQL schema introspection — produces a normalized, JSON-serializable snapshot of a database's structure for cross-impl parity checks.

The snapshot covers:

- schema_version rows (namespace, name, sequence) — captures migration set state across impls - Tables with columns (data type, nullability, default, identity) - Indexes with canonical Postgres-rendered definitions - Constraints (CHECK, FOREIGN KEY, PRIMARY KEY, UNIQUE, EXCLUSION) - Sequences with data type — distinguishes int4 (SERIAL) from int8 (BIGSERIAL)

Designed for pg_catalog introspection — works against both PostgreSQL and PGlite. The snapshot is fully deterministic: every collection sorts by a stable key and excludes time-varying fields like applied_at.

Paired with schema_parity.ts for comparison + assertion helpers.

Declarations
#

7 declarations

view source

ColumnSnapshot
#

testing/schema_introspect.ts view source

ColumnSnapshot

Per-column structural metadata.

data_type

SQL standard type name from information_schema.columns.data_type.

type string
readonly

udt_name

Postgres-native type name from information_schema.columns.udt_name.

type string
readonly

is_nullable

true when the column accepts NULL.

type boolean
readonly

column_default

Default-value expression as Postgres reports it, or null if none.

type string | null
readonly

is_identity

true when the column was declared GENERATED ... AS IDENTITY.

type boolean
readonly

query_schema_snapshot
#

testing/schema_introspect.ts view source

(db: Db, options?: QuerySchemaSnapshotOptions): Promise<SchemaSnapshot>

Introspect a live database into a deterministic SchemaSnapshot.

Reads information_schema and pg_catalog to capture tables, columns, indexes, constraints, sequences, and schema_version migration tracker rows. The applied_at timestamp is deliberately excluded — only the set of applied migrations matters for parity.

The schema_version table itself never appears in the tables field; its structure is identical across consumers and would only add noise.

db

type Db

options

type QuerySchemaSnapshotOptions
default {}

returns

Promise<SchemaSnapshot>

throws

  • Error - when the `schema_version` table is missing — callers must

QuerySchemaSnapshotOptions
#

testing/schema_introspect.ts view source

QuerySchemaSnapshotOptions

Filter options for query_schema_snapshot.

schema

Schema name to introspect — defaults to 'public'. Single-schema only; cross-schema introspection isn't a current need.

type string
readonly

exclude_tables

Tables to exclude from the snapshot. The schema_version table itself is always excluded (its content is captured separately).

type ReadonlyArray<string>
readonly

SchemaSnapshot
#

testing/schema_introspect.ts view source

SchemaSnapshot

Normalized database schema snapshot for parity comparison.

All fields are deterministically ordered on capture so structural equality via JSON.stringify or per-key comparison yields stable results.

schema_version

Migration tracker rows, sorted by (namespace, sequence).

type ReadonlyArray<SchemaVersionRow>
readonly

tables

Tables keyed by name.

type Record<string, TableSnapshot>
readonly

sequences

Sequences keyed by name.

type Record<string, SequenceSnapshot>
readonly

SchemaVersionRow
#

SequenceSnapshot
#

TableSnapshot
#

testing/schema_introspect.ts view source

TableSnapshot

Per-table structural metadata.

columns

Column metadata keyed by column name (sorted on serialization).

type Record<string, ColumnSnapshot>
readonly

indexes

Index definitions as Postgres renders them via pg_indexes.indexdef.

type ReadonlyArray<{readonly name: string; readonly definition: string}>
readonly

constraints

Constraint definitions as Postgres renders them via pg_get_constraintdef.

type ReadonlyArray<{ readonly name: string; readonly type: string; readonly definition: string; }>
readonly

Depends on
#