Appliedinterfaceno test imports itinterface AppliedWhat a run did.
| Member | Type | What it is |
|---|---|---|
steps | readonly string[] | |
repeatable | readonly string[] | |
ledger | readonly LedgerEntry[] |
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.
Appliedinterfaceno test imports itinterface AppliedWhat a run did.
| Member | Type | What it is |
|---|---|---|
steps | readonly string[] | |
repeatable | readonly string[] | |
ledger | readonly LedgerEntry[] |
applyStatementfunctionfunction applyStatement(driver: Driver, statement: StepStatement): Promise<boolean>Runs one statement of a step, unless its guard says its work is done.
| Parameter | What it is |
|---|---|
driver | the database |
statement | the statement |
Returns: whether it was run
Driverinterfaceinterface DriverA way to run statements on a database and read rows back.
| Member | Type | What it is |
|---|---|---|
exec | (sql: string) => Promise<void> | |
query | (sql: string) => Promise<readonly Record<string, unknown>[]> |
executefunctionfunction execute(plan: RunPlan, driver: Driver, dialect: Dialect, options: RunOptions): Promise<Result<Applied, readonly RunError[]>>Applies a plan to a database.
| Parameter | What it is |
|---|---|
plan | the plan |
driver | the database |
dialect | its dialect |
options | the ledger's table, who applies, the clock and the hash of the empty state |
Returns: what was applied, or why it was not
ledgerDdlfunctionno test imports itfunction ledgerDdl(dialect: Dialect, table?: string): stringThe statement that makes the ledger's table where there is none.
readLedgerfunctionfunction readLedger(driver: Driver, dialect: Dialect, table?: string): Promise<readonly LedgerEntry[]>Reads the ledger of a database.
| Parameter | What it is |
|---|---|
driver | the database |
dialect | its dialect |
table | the ledger's table |
Returns: the entries, in order
RunErrortypeno test imports ittype 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 itinterface RunOptionsWhat a run is given besides the plan.
| Member | Type | What it is |
|---|---|---|
ledgerTable? | string | The ledger's table; lifecycle_ledger by default. |
by? | string | Who 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). |
empty | string | The hash of the empty state, for a database that has no ledger yet. |