sql/extensions/convergence/propose
Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0019-sql-convergence FR-004, 0019-sql-convergence FR-005, 0019-sql-convergence FR-006
Proposals (commons data 0019-sql-convergence FR-004 to FR-006): the plan from the state a database is in to the state wanted, pinned to the state it was computed from. A reviewed proposal is a file a person reads and approves; applying it checks that the text is the one that was approved and that the database is still in the state it was pinned to.
Source: commons/data/sql/extensions/convergence/propose.ts
5 of 10 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.
function applyProposal(text: string, approved: string, driver: Driver, dialect: Dialect, wanted: State, options?: Omit<RunOptions, "empty"> & { readonly ignore?: readonly string[] | undefined; }): Promise<Result<Applied, readonly ApplyError[]>>
Applies a proposal that was approved.
| Parameter | What it is |
|---|
text | the proposal's text |
approved | the hash of the text that was approved |
driver | the database |
dialect | its dialect |
wanted | the state wanted, to read the database against |
options | what the run is given and the names the reader leaves out |
Returns: what was applied, or why not
Imported by 13 tests of the run (13 passed, 0 failed): the library's results
ApplyErrortypeno test imports ittype ApplyError =
| { readonly kind: "unapproved"; readonly approved: string; readonly actual: string }
| { readonly kind: "unreadable"; readonly why: string }
| { readonly kind: "read"; readonly errors: readonly ReadError[] }
| { readonly kind: "stale"; readonly pinned: string; readonly found: string }
| RunError;
What is wrong with applying one.
function desiredState(schema: LogicalSchema, desired: Desired): State | undefined
The state wanted, as a value.
Imported by 13 tests of the run (13 passed, 0 failed): the library's results
function propose(driver: Driver, schema: LogicalSchema, desired: Desired, options?: ProposeOptions): Promise<Result<{ readonly proposal: Proposal; readonly plan: Plan; readonly live: State; readonly wanted: State; }, readonly ProposeError[]>>
The plan from the state a database is in to the state wanted, pinned.
| Parameter | What it is |
|---|
driver | the database |
schema | the logical schema wanted |
desired | the dialect, naming, schema and what extensions add |
options | what plan is given, and the names the reader leaves out |
Returns: the proposal and what it is made of, or why not
Imported by 13 tests of the run (13 passed, 0 failed): the library's results
Proposalinterfaceno test imports itinterface Proposal
A plan pinned to the state it was computed from.
| Member | Type | What it is |
|---|
format | 1 | |
dialect | string | |
base | string | The hash of the state the database was in. |
to | string | The hash of the state the plan ends in. |
steps | readonly ProposalStep[] | |
held? | readonly string[] | What is in the database and not in the model, and is held: no step touches it. |
repeatable | readonly { readonly key: string; readonly hash: string; readonly of: readonly string[]; readonly statements: readonly StepStatement[]; }[] | |
ProposalStepinterfaceno test imports itinterface ProposalStep
A step as a proposal holds it.
| Member | Type | What it is |
|---|
number | number | |
id | string | |
name | string | |
kind | string | |
class | string | |
why? | string | |
reversibility | string | |
idempotency? | string | |
from | string | |
to | string | |
of | readonly string[] | |
up | readonly StepStatement[] | |
down? | readonly StepStatement[] | |
verify? | Verification | |
ProposeErrortypeno test imports ittype ProposeError =
{ readonly kind: "read"; readonly errors: readonly ReadError[] } | { readonly kind: "plan"; readonly errors: readonly PlanError[] };
What is wrong with a proposal.
ProposeOptionsinterfaceno test imports itinterface ProposeOptions extends PlanOptions
What a proposal is made with.
| Member | Type | What it is |
|---|
ignore? | readonly string[] | The names of tables the reader leaves out, besides the ledger's. |
ledgerTable? | string | The ledger's table; lifecycle_ledger by default. |
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). |
const proposalText: (p: Proposal) => string
The text a person approves: the proposal, the same every time.
Imported by 13 tests of the run (13 passed, 0 failed): the library's results
function renderProposal(p: Proposal, stem: string): readonly Artifact[]
The files of a proposal: the text that is approved and a page to read it by.
| Parameter | What it is |
|---|
p | the proposal |
stem | what the files are called |
Returns: the files
Imported by 10 tests of the run (10 passed, 0 failed): the library's results