IF Commons GitHub

sql/lifecycle/run

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0011-sql-lifecycle FR-011

Running a plan (commons data 0011-sql-lifecycle FR-011): the steps are applied to a driver, a way to run statements and read rows, each in a transaction with its ledger entry, so that a step that fails leaves the database and the ledger as they were. A database is found among the states of the plan by the ledger, and one that is in none of them is refused: a plan only runs on the database it was made for. Run again, it does nothing.

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

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

Appliedinterfaceno test imports it
interface Applied

What a run did.

MemberTypeWhat it is
stepsreadonly string[]
repeatablereadonly string[]
ledgerreadonly LedgerEntry[]
applyStatementfunction
function applyStatement(driver: Driver, statement: StepStatement): Promise<boolean>

Runs one statement of a step, unless its guard says its work is done.

ParameterWhat it is
driverthe database
statementthe statement

Returns: whether it was run

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

Driverinterface
interface Driver

A way to run statements on a database and read rows back.

MemberTypeWhat it is
exec(sql: string) => Promise<void>
query(sql: string) => Promise<readonly Record<string, unknown>[]>

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

executefunction
function execute(plan: RunPlan, driver: Driver, dialect: Dialect, options: RunOptions): Promise<Result<Applied, readonly RunError[]>>

Applies a plan to a database.

ParameterWhat it is
planthe plan
driverthe database
dialectits dialect
optionsthe ledger's table, who applies, the clock and the hash of the empty state

Returns: what was applied, or why it was not

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

ledgerDdlfunctionno test imports it
function ledgerDdl(dialect: Dialect, table?: string): string

The statement that makes the ledger's table where there is none.

readLedgerfunction
function readLedger(driver: Driver, dialect: Dialect, table?: string): Promise<readonly LedgerEntry[]>

Reads the ledger of a database.

ParameterWhat it is
driverthe database
dialectits dialect
tablethe ledger's table

Returns: the entries, in order

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

RunErrortypeno test imports it
type RunError =
  | { readonly kind: "ledger"; readonly broken: ChainBreak }
  | { readonly kind: "base"; readonly found: string; readonly expected: readonly string[] }
  | { readonly kind: "step"; readonly key: string; readonly name: string; readonly message: string };

What is wrong with a run.

RunOptionsinterfaceno test imports it
interface RunOptions

What a run is given besides the plan.

MemberTypeWhat it is
ledgerTable?stringThe ledger's table; lifecycle_ledger by default.
by?stringWho applies, written in the ledger.
now?(() => string)The moment, as text; the clock by default.
before?readonly string[]Statements run at the start of each transaction, such as a setting that says a migration is running (0014-sql-protected-access FR-009).
retry?{ readonly attempts: number; readonly delayMs: number; readonly when: (message: string) => boolean; readonly sleep?: ((ms: number) => Promise<void>) | undefined; }Try a step again when its error is of a kind the project names, such as a lock timeout (0015-sql-safety FR-002).
emptystringThe hash of the empty state, for a database that has no ledger yet.

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