IF Commons GitHub

sql/lifecycle/plan

Written to: 4 requirements: 4 proved, 0 partly, 0 failing, 0 with no test recorded. 0011-sql-lifecycle FR-006, 0011-sql-lifecycle FR-007, 0011-sql-lifecycle FR-008, 0011-sql-lifecycle FR-009

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.

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

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

Captureinterfaceno test imports it
interface Capture

A value to read before a step, to be compared after it (0015-sql-safety FR-001).

MemberTypeWhat it is
keystring
querystringA query that returns one row of one value.
Desiredinterfaceno test imports it
interface Desired

What a plan is made for.

MemberTypeWhat it is
dialectDialect
naming?Naming
schema?stringThe schema the tables are in (0013-sql-qualified-names).
sources?readonly StatementSource[]
tableClauses?readonly TableClause[]
dueRepeatablesconst
const 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.

ParameterWhat it is
repeatablethe plan's repeatable objects
appliedthe hash last applied, by key
touchedthe elements the steps of this run changed

Returns: those to apply, in the plan's order

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

Guardinterfaceno test imports it
interface Guard

A 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).

MemberTypeWhat it is
querystring
skipWhen"none" | "rows"rows: skip the statement when the query returns a row; none: skip it when the query returns none.
Expecttypeno test imports it
type 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 it
type 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).

fallbackFromfunction
function fallbackFrom(composition: Composition): Fallback | undefined

The fallbacks of a composition as one: the first that makes the change wins.

ParameterWhat it is
compositionthe project's composition

Returns: the fallback, or none where no extension contributes one

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

fallbackPointconstno test imports it
const fallbackPoint: ContributionPoint<Fallback>

The contribution point an extension of the lifecycle fills to make what the core cannot make in place.

Idempotencytypeno test imports it
type 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 it
interface ManualStep

A step a person wrote, for a change the lifecycle cannot or may not make by itself.

MemberTypeWhat it is
resolvesstringThe key of the change it stands for.
namestring
upreadonly string[]
down?readonly string[]
guard?GuardA guard for every statement of the step, which makes it safe to run twice.
planfunction
function 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.

ParameterWhat it is
fromthe state the database is in; none for an empty database
schemathe logical schema wanted
desiredthe dialect, the naming and what extensions add
optionswhat is allowed, the steps a person wrote and the transforms

Returns: the plan, or every error

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

Planinterface
interface Plan

A plan.

MemberTypeWhat it is
dialectstring
fromstringThe hash of the state the plan starts from.
tostringThe hash of the state it ends in.
stepsreadonly Step[]
repeatablereadonly Repeatable[]

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

PlanContextinterfaceno test imports it
interface PlanContext

What a transform is given.

MemberTypeWhat it is
dialectDialect
namingNaming
schemaLogicalSchema
PlanErrortype
type 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.

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

PlanOptionsinterface
interface PlanOptions

What a plan is told: the dialect, the schema and what it may change.

MemberTypeWhat it is
allow?{ readonly destructive?: boolean | undefined; }
fallback?FallbackMakes what the core cannot make in place, such as a table that is made again.
manual?readonly ManualStep[]
transforms?readonly StepTransform[]
requireIdempotent?booleanRefuse, as an error value, a step that is only safe to run twice because of the ledger (0012-sql-idempotency FR-007).

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

Repeatableinterfaceno test imports it
interface Repeatable

What an extension adds to the schema, applied again whenever its text changes.

MemberTypeWhat it is
keystring
hashstringThe hash of its text.
statementsreadonly Statement[]The statements that make it, applied together.
ofreadonly LogicalId[]The elements it is made from: when a step changes one, it is applied again.
RunPlaninterfaceno test imports it
interface RunPlan

What a run needs of a plan.

MemberTypeWhat it is
fromstring
tostring
stepsreadonly RunStep[]
repeatablereadonly Repeatable[]
RunStepinterfaceno test imports it
interface RunStep

What a run needs of a step: a frozen step, read back from a file, has no more than this.

MemberTypeWhat it is
idstring
namestring
fromstring
tostring
upreadonly StepStatement[]
verify?Verification
ofreadonly LogicalId[]
Reversibilitytypeno test imports it
type Reversibility = "lossless" | "quarantine" | "irreversible";

Whether a step can be undone.

Stepinterfaceno test imports it
interface Step

A step: a change made into statements, from the state it needs to the state it leaves.

MemberTypeWhat it is
idstringMade of the step's content: the states, the key and the statements.
namestringWhat a person reads.
kind"addColumn" | "addConstraint" | "alterClause" | "alterDefault" | "alterNullable" | "alterPrimaryKey" | "alterType" | "createTable" | "dropColumn" | "dropConstraint" | "dropTable" | "removeRows" | "renameColumn" | "renameConstraint" | "renameTable" | "upsertRows"
keystringStable for the same change; a hand-written step names it.
classStepClass
why?stringWhy it is not safe, where it is not.
reversibilityReversibility
fromstringThe hash of the state the step needs.
tostringThe hash of the state it leaves.
upreadonly StepStatement[]
down?readonly StepStatement[]
verify?VerificationWhat must be true after it, which the run checks in its transaction.
idempotency?IdempotencyHow it is safe to run twice, where an idempotency transform has said.
rebuild?booleanWhether the table is made again and the old one dropped (0017-sql-rewrite FR-003).
changeChangeThe change it makes, which an extension of the lifecycle reads.
ofreadonly LogicalId[]The logical elements it is made from.
manualbooleanWhether a person wrote its statements.
StepClasstypeno test imports it
type StepClass = "safe" | "data-dependent" | "destructive" | "manual";

What a change could lose.

StepContextinterfaceno test imports it
interface StepContext extends PlanContext

What 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).

MemberTypeWhat it is
beforeState
afterState
dialectDialect
namingNaming
schemaLogicalSchema
StepDrafttypeno test imports it
type 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 it
type 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.

StepTransformtype
type StepTransform = (draft: StepDraft, context: StepContext) => StepDraft;

A change an extension makes to the steps of a plan before they are hashed (idempotency, safety).

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

stepIdOfconstno test imports it
const stepIdOf: (s: { readonly from: string; readonly to: string; readonly key: string; readonly up: readonly StepStatement[]; readonly verify?: Verification | undefined; }) => string

The 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 it
const 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 it
interface Verification

What a step says must be true of the database after it, checked in its transaction (0015-sql-safety FR-001).

MemberTypeWhat it is
before?readonly Capture[]
afterreadonly Check[]
transformsFromconst
const transformsFrom: (composition: Composition) => readonly StepTransform[]

The transforms of a composition, in its order.

ParameterWhat it is
compositionthe project's composition

Returns: the transforms its extensions contribute

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

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