IF Commons GitHub

sql/lifecycle/introspect

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0055-sql-introspect FR-001, 0055-sql-introspect FR-002, 0055-sql-introspect FR-003

Reading a live database (commons data 0055-sql-introspect): what a database holds, read from its own catalog as a plain value (Observed): the tables, their columns with the type the engine reports, whether each may be null and its default, the primary key, the unique constraints, the foreign keys and the indexes. It is read through a driver and changes nothing. expectedOf writes the same value from a logical schema, and drift compares the two, so that what a database has and what a model says are told apart: a table or column that is missing or stray, a type of another family, a nullability that differs, a key, a foreign key, a unique or an index that is missing.

Source: commons/data/sql/lifecycle/introspect.ts

4 of 6 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

driftfunction
function drift(expected: Observed, found: Observed): readonly Drift[]

Compares what a database holds with what is expected of it, table by table. A type is of the same family where both are the same logical type (BIGINT and integer); an index is held to exist where a unique constraint or the key covers the same columns, as engines make the one with the other.

ParameterWhat it is
expectedwhat the model says (expectedOf, or a state read earlier)
foundwhat the database holds (introspect)

Returns: every difference, in the order of the tables

Imported by 13 tests of the run (13 passed, 0 failed): the library's results

Drifttypeno test imports it
type Drift = | { readonly kind: "missing-table"; readonly table: string } | { readonly kind: "stray-table"; readonly… (1023 characters)
type Drift =
  | { readonly kind: "missing-table"; readonly table: string }
  | { readonly kind: "stray-table"; readonly table: string }
  | { readonly kind: "missing-column"; readonly table: string; readonly column: string }
  | { readonly kind: "stray-column"; readonly table: string; readonly column: string }
  | { readonly kind: "type"; readonly table: string; readonly column: string; readonly expected: string; readonly found: string }
  | { readonly kind: "nullability"; readonly table: string; readonly column: string; readonly expected: boolean; readonly found: boolean }
  | { readonly kind: "primary-key"; readonly table: string; readonly expected: readonly string[]; readonly found: readonly string[] }
  | { readonly kind: "missing-foreign-key"; readonly table: string; readonly columns: readonly string[] }
  | { readonly kind: "missing-unique"; readonly table: string; readonly columns: readonly string[] }
  | { readonly kind: "missing-index"; readonly table: string; readonly columns: readonly string[] };

One way a database differs from what is expected of it.

expectedOffunction
function expectedOf(schema: LogicalSchema, dialect: Dialect, options?: { readonly naming?: Naming | undefined; readonly schema?: string | undefined; }): Observed

What a logical schema says a database holds, written as introspect reads it: the names as the naming writes them and the types as the dialect writes them.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

introspectfunction
function introspect(driver: Driver, dialect: Dialect, options?: IntrospectOptions): Promise<Observed>

Reads what a database holds.

ParameterWhat it is
driverthe database
dialectits dialect
optionsthe schema to read and the tables to leave out

Returns: the tables, in the order of their names

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

IntrospectOptionsinterfaceno test imports it
interface IntrospectOptions

What reading is told.

MemberTypeWhat it is
schema?stringThe schema to read; the connection's own (current_schema(), main) where not given.
exclude?((table: string) => boolean)Tables to leave out (the ledger of the library's own, for one).
logicalOffunction
function logicalOf(typeText: string): LogicalType | undefined

The logical type that an engine's type text is of, or none where it is of no family the library knows.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.