Captureinterfaceno test imports itinterface CaptureA value to read before a step, to be compared after it (0015-sql-safety FR-001).
| Member | Type | What it is |
|---|---|---|
key | string | |
query | string | A query that returns one row of one value. |
Plans (commons data 0011-sql-lifecycle FR-006 to FR-009): the ordered steps that take a database from the state it is in to the state wanted. Each change is made into statements to do it and to undo it, classified by what it could lose and whether it can be undone, and given the hash of the state it needs and the state it leaves, so that a step names the one database it is for. What the dialect cannot do in place, and what loses data, is refused as an error value unless a person has written the step or allowed it. What extensions add is repeatable.
Captureinterfaceno test imports itinterface CaptureA value to read before a step, to be compared after it (0015-sql-safety FR-001).
| Member | Type | What it is |
|---|---|---|
key | string | |
query | string | A query that returns one row of one value. |
Desiredinterfaceno test imports itinterface DesiredWhat a plan is made for.
| Member | Type | What it is |
|---|---|---|
dialect | Dialect | |
naming? | Naming | |
schema? | string | The schema the tables are in (0013-sql-qualified-names). |
sources? | readonly StatementSource[] | |
tableClauses? | readonly TableClause[] |
dueRepeatablesconstconst dueRepeatables: (repeatable: readonly Repeatable[], applied: ReadonlyMap<string, string>, touched?: ReadonlySet<string>) => readonly Repeatable[]The repeatable objects that are due: those whose text is not the one last applied, and those that are made from an element a step has just changed.
| Parameter | What it is |
|---|---|
repeatable | the plan's repeatable objects |
applied | the hash last applied, by key |
touched | the elements the steps of this run changed |
Returns: those to apply, in the plan's order
Guardinterfaceno test imports itinterface GuardA query on the catalog and the answer that means a statement's work is done and it is to be skipped (0012-sql-idempotency FR-002).
| Member | Type | What it is |
|---|---|---|
query | string | |
skipWhen | "none" | "rows" | rows: skip the statement when the query returns a row; none: skip it when the query returns none. |
Expecttypeno test imports ittype Expect = "rows" | "none" | { readonly sameAs: string };What a check expects of its query: a row, no row, or the value captured under a key.
Fallbacktypeno test imports ittype Fallback = (
change: Change,
why: string,
context: StepContext,
) => Omit<StepDraft, "name" | "kind" | "key" | "manual" | "change"> | undefined;What an extension makes of a change that the core cannot make in place: the step's draft, or none (0017-sql-rewrite FR-001).
fallbackFromfunctionfunction fallbackFrom(composition: Composition): Fallback | undefinedThe fallbacks of a composition as one: the first that makes the change wins.
| Parameter | What it is |
|---|---|
composition | the project's composition |
Returns: the fallback, or none where no extension contributes one
fallbackPointconstno test imports itconst fallbackPoint: ContributionPoint<Fallback>The contribution point an extension of the lifecycle fills to make what the core cannot make in place.
Idempotencytypeno test imports ittype Idempotency = "natural" | "guarded" | "ledger-only";How a step is safe to run twice: natural (every statement is), guarded (some are guarded and none is left) or ledger-only (some cannot be, so only the ledger keeps it from running twice).
ManualStepinterfaceno test imports itinterface ManualStepA step a person wrote, for a change the lifecycle cannot or may not make by itself.
| Member | Type | What it is |
|---|---|---|
resolves | string | The key of the change it stands for. |
name | string | |
up | readonly string[] | |
down? | readonly string[] | |
guard? | Guard | A guard for every statement of the step, which makes it safe to run twice. |
planfunctionfunction plan(from: State | undefined, schema: LogicalSchema, desired: Desired, options?: PlanOptions): Result<Plan, readonly PlanError[]>The steps that take a database from one state to the schema wanted.
| Parameter | What it is |
|---|---|
from | the state the database is in; none for an empty database |
schema | the logical schema wanted |
desired | the dialect, the naming and what extensions add |
options | what is allowed, the steps a person wrote and the transforms |
Returns: the plan, or every error
Planinterfaceinterface PlanA plan.
| Member | Type | What it is |
|---|---|---|
dialect | string | |
from | string | The hash of the state the plan starts from. |
to | string | The hash of the state it ends in. |
steps | readonly Step[] | |
repeatable | readonly Repeatable[] |
PlanContextinterfaceno test imports itinterface PlanContextWhat a transform is given.
| Member | Type | What it is |
|---|---|---|
dialect | Dialect | |
naming | Naming | |
schema | LogicalSchema |
PlanErrortypetype PlanError =
| { readonly kind: "write"; readonly errors: readonly PhysicalError[] }
| { readonly kind: "dialect… (729 characters)type PlanError =
| { readonly kind: "write"; readonly errors: readonly PhysicalError[] }
| { readonly kind: "dialect"; readonly from: string; readonly to: string }
| { readonly kind: "schema"; readonly from: string | undefined; readonly to: string | undefined }
| { readonly kind: "refused"; readonly key: string; readonly name: string; readonly class: StepClass; readonly why: string }
| { readonly kind: "manual"; readonly key: string; readonly name: string; readonly why: string }
| { readonly kind: "unresolved"; readonly resolves: string }
| { readonly kind: "not-idempotent"; readonly key: string; readonly name: string }
| { readonly kind: "inconsistent"; readonly expected: string; readonly got: string };What is wrong with a plan; plan returns all of it together.
PlanOptionsinterfaceinterface PlanOptionsWhat a plan is told: the dialect, the schema and what it may change.
| Member | Type | What it is |
|---|---|---|
allow? | { readonly destructive?: boolean | undefined; } | |
fallback? | Fallback | Makes what the core cannot make in place, such as a table that is made again. |
manual? | readonly ManualStep[] | |
transforms? | readonly StepTransform[] | |
requireIdempotent? | boolean | Refuse, as an error value, a step that is only safe to run twice because of the ledger (0012-sql-idempotency FR-007). |
Repeatableinterfaceno test imports itinterface RepeatableWhat an extension adds to the schema, applied again whenever its text changes.
| Member | Type | What it is |
|---|---|---|
key | string | |
hash | string | The hash of its text. |
statements | readonly Statement[] | The statements that make it, applied together. |
of | readonly LogicalId[] | The elements it is made from: when a step changes one, it is applied again. |
RunPlaninterfaceno test imports itinterface RunPlanWhat a run needs of a plan.
| Member | Type | What it is |
|---|---|---|
from | string | |
to | string | |
steps | readonly RunStep[] | |
repeatable | readonly Repeatable[] |
RunStepinterfaceno test imports itinterface RunStepWhat a run needs of a step: a frozen step, read back from a file, has no more than this.
| Member | Type | What it is |
|---|---|---|
id | string | |
name | string | |
from | string | |
to | string | |
up | readonly StepStatement[] | |
verify? | Verification | |
of | readonly LogicalId[] |
Reversibilitytypeno test imports ittype Reversibility = "lossless" | "quarantine" | "irreversible";Whether a step can be undone.
Stepinterfaceno test imports itinterface StepA step: a change made into statements, from the state it needs to the state it leaves.
| Member | Type | What it is |
|---|---|---|
id | string | Made of the step's content: the states, the key and the statements. |
name | string | What a person reads. |
kind | "addColumn" | "addConstraint" | "alterClause" | "alterDefault" | "alterNullable" | "alterPrimaryKey" | "alterType" | "createTable" | "dropColumn" | "dropConstraint" | "dropTable" | "removeRows" | "renameColumn" | "renameConstraint" | "renameTable" | "upsertRows" | |
key | string | Stable for the same change; a hand-written step names it. |
class | StepClass | |
why? | string | Why it is not safe, where it is not. |
reversibility | Reversibility | |
from | string | The hash of the state the step needs. |
to | string | The hash of the state it leaves. |
up | readonly StepStatement[] | |
down? | readonly StepStatement[] | |
verify? | Verification | What must be true after it, which the run checks in its transaction. |
idempotency? | Idempotency | How it is safe to run twice, where an idempotency transform has said. |
rebuild? | boolean | Whether the table is made again and the old one dropped (0017-sql-rewrite FR-003). |
change | Change | The change it makes, which an extension of the lifecycle reads. |
of | readonly LogicalId[] | The logical elements it is made from. |
manual | boolean | Whether a person wrote its statements. |
StepClasstypeno test imports ittype StepClass = "safe" | "data-dependent" | "destructive" | "manual";What a change could lose.
StepContextinterfaceno test imports itinterface StepContext extends PlanContextWhat a transform is given: the plan's context and the states a step is between, so that it can write what depends on the tables it changes (0014-sql-protected-access FR-010).
| Member | Type | What it is |
|---|---|---|
before | State | |
after | State | |
dialect | Dialect | |
naming | Naming | |
schema | LogicalSchema |
StepDrafttypeno test imports ittype StepDraft = Omit<Step, "id" | "from" | "to">;A step before it is hashed: what an extension of the lifecycle may change in it.
StepStatementtypeno test imports ittype StepStatement = Statement & {
readonly guard?: Guard;
/** Set by whoever wrote it, where it knows the statement does no harm run twice (a restore of values). */
readonly natural?: boolean;
};A statement of a step, which may carry a guard.
StepTransformtypetype StepTransform = (draft: StepDraft, context: StepContext) => StepDraft;A change an extension makes to the steps of a plan before they are hashed (idempotency, safety).
stepIdOfconstno test imports itconst stepIdOf: (s: { readonly from: string; readonly to: string; readonly key: string; readonly up: readonly StepStatement[]; readonly verify?: Verification | undefined; }) => stringThe identifier of a step, made of what it does: the states, its key, its statements with their guards and what must be true after it.
transformPointconstno test imports itconst transformPoint: ContributionPoint<StepTransform>The contribution point an extension of the lifecycle fills to change the steps of a plan before they are hashed.
Verificationinterfaceno test imports itinterface VerificationWhat a step says must be true of the database after it, checked in its transaction (0015-sql-safety FR-001).
| Member | Type | What it is |
|---|---|---|
before? | readonly Capture[] | |
after | readonly Check[] |
transformsFromconstconst transformsFrom: (composition: Composition) => readonly StepTransform[]The transforms of a composition, in its order.
| Parameter | What it is |
|---|---|
composition | the project's composition |
Returns: the transforms its extensions contribute