Skip to content
SQLBraid

Inspectors and metadata snapshots

Metadata is optional, Node-first tooling. Runtime dialect imports do not install or require the metadata or codegen packages.

Install the dialect, the driver and the optional metadata package explicitly:

Terminal window
pnpm add @sqlbraid/postgres pg @sqlbraid/metadata

The inspector is a subpath export of the dialect package. It is not a separate package. Inspect a physical client that is already connected:

import { writeFile } from "node:fs/promises";
import pg from "pg";
import { hashSnapshot, validateSnapshot } from "@sqlbraid/metadata";
import { createPostgresInspector } from "@sqlbraid/postgres/inspector";


const client = new pg.Client({ connectionString: process.env.DATABASE_URL });
await client.connect();


const metadata = await createPostgresInspector(client).inspect();
validateSnapshot(metadata);
console.log(hashSnapshot(metadata));
await writeFile("db/main.metadata.json", JSON.stringify(metadata, null, 2));
await client.end();

Save this code as inspect.mjs in a project with an existing db directory, and run node inspect.mjs. The codegen configuration reads the snapshot file that this script writes.

All first-party dialects export dedicated inspectors from their /inspector subpaths:

  • createPostgresInspector (@sqlbraid/postgres/inspector);
  • createMysqlInspector (@sqlbraid/mysql/inspector);
  • createMariaDbInspector (@sqlbraid/mariadb/inspector);
  • createSqliteInspector (@sqlbraid/sqlite/inspector);
  • createOracleInspector (@sqlbraid/oracle/inspector);
  • createMssqlInspector (@sqlbraid/mssql/inspector).

Keeping inspectors under /inspector subpaths ensures that runtime database imports stay free of schema-inspection code.

Snapshots use:

{ "format": "sqlbraid-metadata", "formatVersion": 1 }

The snapshot format can represent namespaces, types, relations, columns, constraints, indexes, routines, server evidence and capture metadata.

  • Inspector coverage is partial. PostgreSQL currently leaves namespaces empty. It does not fill relation constraints or indexes.
  • Missing fields are not evidence of absence.
  • Canonicalization and hashing ignore capture timestamps. They keep the database facts.
  • validateSnapshot rejects malformed snapshots and old snapshots without the discriminator.
  • sqlbraid drift --before ... --after ... compares validated snapshots.

Metadata is evidence. It is not a lock on the database schema.

  • Routine argumentsComplete: false means that an empty argument list does not prove zero arity.
  • SQLite emits no routine records.
  • Identity means proven identity or autoincrement generation. Membership in the primary key alone is not identity.
  • Unknown write flags stay unknown.