Skip to main content

db-x / runtime/src

runtime/src

Interfaces​

CommonProps​

Defined in: runtime/src/define-component.ts:19

Properties​

id?​

optional id?: string

Defined in: runtime/src/define-component.ts:21

Override the auto-derived resource id.

dependsOn?​

optional dependsOn?: string[]

Defined in: runtime/src/define-component.ts:23

Explicit dependency edges. Children implicitly depend on their parent.

children?​

optional children?: Child | Child[]

Defined in: runtime/src/define-component.ts:24

ResourceDiff​

Defined in: runtime/src/diff.ts:19

Properties​

id​

id: string

Defined in: runtime/src/diff.ts:20

kind​

kind: string

Defined in: runtime/src/diff.ts:21

action​

action: PlanAction

Defined in: runtime/src/diff.ts:22

desired​

desired: Resource | null

Defined in: runtime/src/diff.ts:24

The desired Resource. Null when the action is a destroy of a state-only resource.

current​

current: ResourceState<object, object> | null

Defined in: runtime/src/diff.ts:26

The persisted state. Null when the action is a create.

Plan​

Defined in: runtime/src/diff.ts:29

Properties​

actions​

actions: ResourceDiff[]

Defined in: runtime/src/diff.ts:30

DestructiveViolation​

Defined in: runtime/src/guard.ts:18

Properties​

id​

id: string

Defined in: runtime/src/guard.ts:19

kind​

kind: string

Defined in: runtime/src/guard.ts:20

reason​

reason: DestructiveBlockReason

Defined in: runtime/src/guard.ts:21

changes​

changes: string[]

Defined in: runtime/src/guard.ts:23

Human-readable destructive changes, from action.destructive.

DestructiveGuardOptions​

Defined in: runtime/src/guard.ts:26

Properties​

allowDestructive​

allowDestructive: boolean

Defined in: runtime/src/guard.ts:27

AnyElement​

Defined in: runtime/src/jsx-runtime.ts:17

Structural supertype every ElementNode<T> satisfies. Used in positions that need to accept JSX from concretely-typed components (Child arrays, JSX.Element) without running into the contravariance of ElementType<T>.

Properties​

$$typeof​

$$typeof: typeof ELEMENT_TYPE

Defined in: runtime/src/jsx-runtime.ts:18

type​

type: unknown

Defined in: runtime/src/jsx-runtime.ts:19

props​

props: unknown

Defined in: runtime/src/jsx-runtime.ts:20

key​

key: string | null

Defined in: runtime/src/jsx-runtime.ts:21

ElementNode​

Defined in: runtime/src/jsx-runtime.ts:30

Type Parameters​

T​

T extends object = Record<string, unknown>

Properties​

$$typeof​

$$typeof: typeof ELEMENT_TYPE

Defined in: runtime/src/jsx-runtime.ts:31

type​

type: ElementType<T>

Defined in: runtime/src/jsx-runtime.ts:32

props​

props: T & object

Defined in: runtime/src/jsx-runtime.ts:33

Type Declaration​
children​

children: Child[]

key​

key: string | null

Defined in: runtime/src/jsx-runtime.ts:34

PhaseProps​

Defined in: runtime/src/phase.ts:16

Properties​

type​

type: PhaseType

Defined in: runtime/src/phase.ts:18

Lifecycle stage these children belong to.

tags?​

optional tags?: readonly string[]

Defined in: runtime/src/phase.ts:20

Optional free-form tags surfaced by the CLI for filtering output.

children?​

optional children?: Child | Child[]

Defined in: runtime/src/phase.ts:21

SnapshotRef​

Defined in: runtime/src/snapshot.ts:13

A pointer to one captured snapshot. Persisted in the driver's store index.

Properties​

id​

id: string

Defined in: runtime/src/snapshot.ts:15

Opaque, driver-assigned id. Unique within a store.

stateRev​

stateRev: string

Defined in: runtime/src/snapshot.ts:21

The state revision this snapshot was taken from — the lastApplied timestamp of .dbx/state.json at capture time. Links a snapshot back to the exact applied state it restores to.

createdAt​

createdAt: string

Defined in: runtime/src/snapshot.ts:23

ISO 8601 capture time.

driver​

driver: string

Defined in: runtime/src/snapshot.ts:25

Driver that produced it, e.g. pg-dump.

mode​

mode: SnapshotMode

Defined in: runtime/src/snapshot.ts:26

PrunePolicy​

Defined in: runtime/src/snapshot.ts:30

Retention policy for prune. v0.1: keep the N most recent.

Properties​

keepLast​

keepLast: number

Defined in: runtime/src/snapshot.ts:32

Keep this many most-recent snapshots; older ones are removed.

SnapshotDriver​

Defined in: runtime/src/snapshot.ts:39

Capture / restore / list / prune point-in-time database snapshots. Implementations decide where artifacts live and how they are produced.

Methods​

create()​

create(stateRev): Promise<SnapshotRef>

Defined in: runtime/src/snapshot.ts:41

Capture the current database, pinning the artifact to stateRev.

Parameters​
stateRev​

string

Returns​

Promise<SnapshotRef>

restore()​

restore(ref): Promise<void>

Defined in: runtime/src/snapshot.ts:43

Restore the database to the snapshot ref points at.

Parameters​
ref​

SnapshotRef

Returns​

Promise<void>

list()​

list(): Promise<SnapshotRef[]>

Defined in: runtime/src/snapshot.ts:45

All snapshots in the store, newest first.

Returns​

Promise<SnapshotRef[]>

prune()​

prune(policy): Promise<SnapshotRef[]>

Defined in: runtime/src/snapshot.ts:47

Remove snapshots the policy excludes. Returns the refs that were pruned.

Parameters​
policy​

PrunePolicy

Returns​

Promise<SnapshotRef[]>

StateFile​

Defined in: runtime/src/state.ts:20

Properties​

version​

version: number

Defined in: runtime/src/state.ts:21

lastApplied?​

optional lastApplied?: string

Defined in: runtime/src/state.ts:22

snapshot?​

optional snapshot?: string

Defined in: runtime/src/state.ts:28

Id of the snapshot captured before this revision's apply, when that apply included destructive DDL (see the CLI's auto-snapshot). Pins the resulting state revision to the pre-change snapshot it can be rolled back to.

resources​

resources: Record<string, ResourceState>

Defined in: runtime/src/state.ts:29

LockHandle​

Defined in: runtime/src/state.ts:85

Properties​

path​

path: string

Defined in: runtime/src/state.ts:87

Absolute path of the lock file.

release​

release: () => Promise<void>

Defined in: runtime/src/state.ts:89

Idempotent — safe to call multiple times.

Returns​

Promise<void>

Resource​

Defined in: runtime/src/types.ts:6

A single resource node in the desired-state graph produced from JSX.

Properties​

id​

id: string

Defined in: runtime/src/types.ts:8

Stable resource id. Derived from props.id, props.name, or path.

kind​

kind: string

Defined in: runtime/src/types.ts:10

Namespaced component kind, e.g. @vercel/db-x:project.

props​

props: Record<string, unknown>

Defined in: runtime/src/types.ts:12

Resolved props at render time.

dependsOn​

dependsOn: string[]

Defined in: runtime/src/types.ts:14

Resource ids this resource depends on (explicit + parent-implied).

parent?​

optional parent?: string

Defined in: runtime/src/types.ts:16

Parent resource id, set for JSX children.

phase?​

optional phase?: PhaseType

Defined in: runtime/src/types.ts:18

Phase membership, propagated from the enclosing <Phase> element.

Graph​

Defined in: runtime/src/types.ts:22

Desired-state graph: the unit of diff.

Properties​

resources​

resources: Record<string, Resource>

Defined in: runtime/src/types.ts:23

outputs​

outputs: Record<string, unknown>

Defined in: runtime/src/types.ts:24

ResourceState​

Defined in: runtime/src/types.ts:28

Persisted state of a single resource after a successful apply.

Type Parameters​

TProps​

TProps = object

TOutputs​

TOutputs = object

Properties​

id​

id: string

Defined in: runtime/src/types.ts:29

kind​

kind: string

Defined in: runtime/src/types.ts:30

props​

props: TProps

Defined in: runtime/src/types.ts:31

outputs​

outputs: TOutputs

Defined in: runtime/src/types.ts:32

dependsOn​

dependsOn: string[]

Defined in: runtime/src/types.ts:33

parent?​

optional parent?: string

Defined in: runtime/src/types.ts:35

Parent resource id, set for JSX children. Persisted so destroy() can resolve parent context.

phase?​

optional phase?: PhaseType

Defined in: runtime/src/types.ts:36

lastApplied​

lastApplied: string

Defined in: runtime/src/types.ts:38

ISO 8601 timestamp of the last successful apply.

ResourceMeta​

Defined in: runtime/src/types.ts:42

Metadata about the resource currently being applied, exposed via ctx.resource.

Properties​

id​

id: string

Defined in: runtime/src/types.ts:43

kind​

kind: string

Defined in: runtime/src/types.ts:44

parent?​

optional parent?: string

Defined in: runtime/src/types.ts:45

phase?​

optional phase?: PhaseType

Defined in: runtime/src/types.ts:46

dependsOn​

dependsOn: string[]

Defined in: runtime/src/types.ts:47

CtxLogger​

Defined in: runtime/src/types.ts:51

Logger handed to component lifecycle hooks via ctx.log.

Properties​

info​

info: (msg, data?) => void

Defined in: runtime/src/types.ts:52

Parameters​
msg​

string

data?​

unknown

Returns​

void

warn​

warn: (msg, data?) => void

Defined in: runtime/src/types.ts:53

Parameters​
msg​

string

data?​

unknown

Returns​

void

error​

error: (msg, data?) => void

Defined in: runtime/src/types.ts:54

Parameters​
msg​

string

data?​

unknown

Returns​

void

debug​

debug: (msg, data?) => void

Defined in: runtime/src/types.ts:55

Parameters​
msg​

string

data?​

unknown

Returns​

void

Ctx​

Defined in: runtime/src/types.ts:59

Context passed to every apply / destroy / refresh invocation.

Properties​

secrets​

secrets: Readonly<Record<string, string | undefined>>

Defined in: runtime/src/types.ts:61

Typed view over process.env. v0.1 reads env vars only.

resource​

resource: ResourceMeta

Defined in: runtime/src/types.ts:63

Metadata about this resource.

log​

log: CtxLogger

Defined in: runtime/src/types.ts:65

Scoped logger; output appears under the resource id in CLI output.

deps​

deps: Readonly<Record<string, object>>

Defined in: runtime/src/types.ts:67

Outputs from resources this one depends on, keyed by resource id.

workDir​

workDir: string

Defined in: runtime/src/types.ts:69

Absolute path to the .dbx/ directory. Use for scratch files.

signal​

signal: AbortSignal

Defined in: runtime/src/types.ts:71

Honor this signal in long-running operations so Ctrl-C works cleanly.

dryRun​

dryRun: boolean

Defined in: runtime/src/types.ts:73

True during preview — perform reads only, no mutations.

RuntimeExec​

Defined in: runtime/src/types.ts:94

Spawn template a runtime publishes so child components can run commands inside whatever context the runtime represents — a docker container, a remote host over SSH, a local subprocess, etc. The runtime is opaque to the consumer; it just prepends command + args and inherits env/cwd.

Example (docker <Service> from @db-x/docker-library):

{ command: 'docker', args: ['compose', '-p', 'my-stack', 'exec', '-T', 'db'], env: { DOCKER_HOST: 'ssh://user@host' }, // forwarded from }

A child library (e.g. @db-x/postgres-library) appends its own command:

spawn(exec.command, [...exec.args, 'psql', '-U', 'foo', '-c', sql], { env, cwd })

Properties​

command​

command: string

Defined in: runtime/src/types.ts:95

args​

args: string[]

Defined in: runtime/src/types.ts:96

env?​

optional env?: Record<string, string | undefined>

Defined in: runtime/src/types.ts:97

cwd?​

optional cwd?: string

Defined in: runtime/src/types.ts:98

Schema​

Defined in: runtime/src/types.ts:123

Minimal validator interface. Compatible with zod, valibot, custom validators.

Type Parameters​

T​

T

Properties​

parse​

parse: (input) => T

Defined in: runtime/src/types.ts:124

Parameters​
input​

unknown

Returns​

T

ComponentSpec​

Defined in: runtime/src/types.ts:128

The full specification a third-party component author passes to defineComponent.

Type Parameters​

TProps​

TProps extends object

TOutputs​

TOutputs extends object

Properties​

kind​

kind: string

Defined in: runtime/src/types.ts:130

Globally unique kind, conventionally <package-name>:<resource-name>.

schema?​

optional schema?: Schema<TProps>

Defined in: runtime/src/types.ts:132

Optional runtime validation of props before apply.

apply​

apply: (props, ctx, prior) => Promise<TOutputs>

Defined in: runtime/src/types.ts:134

Create or update the resource. Receives prior for UPDATE actions.

Parameters​
props​

TProps

ctx​

Ctx

prior​

ResourceState<TProps, TOutputs> | null

Returns​

Promise<TOutputs>

destroy​

destroy: (state, ctx) => Promise<void>

Defined in: runtime/src/types.ts:140

Tear down the resource. Must tolerate 404 / already-gone.

Parameters​
state​

ResourceState<TProps, TOutputs>

ctx​

Ctx

Returns​

Promise<void>

refresh?​

optional refresh?: (state, ctx) => Promise<TOutputs>

Defined in: runtime/src/types.ts:142

Optional drift check — pure read, must not mutate.

Parameters​
state​

ResourceState<TProps, TOutputs>

ctx​

Ctx

Returns​

Promise<TOutputs>

plan?​

optional plan?: (props, state) => PlanAction

Defined in: runtime/src/types.ts:144

Optional custom diff. Default is shallow JSON equality on props.

Parameters​
props​

TProps

state​

ResourceState<TProps, TOutputs> | null

Returns​

PlanAction

reapplyOnDependencyRecreate?​

optional reapplyOnDependencyRecreate?: boolean

Defined in: runtime/src/types.ts:156

Re-apply this resource when something it dependsOn is being created or replaced, even though its own props and state are unchanged.

For resources whose real content lives inside a dependency rather than in their own outputs — <SeedData> writes rows into a table, so a recreated table comes back empty while the seed's state still says it ran. Opting in makes "my dependency was recreated" a reason to plan an update.

The re-apply must be idempotent: it fires on every recreate, not once.

defaults?​

optional defaults?: Partial<TProps>

Defined in: runtime/src/types.ts:158

Optional defaults merged into props before validation.

Type Aliases​

JSXComponent​

JSXComponent<TProps> = (props) => ElementNode<TProps & CommonProps> & object

Defined in: runtime/src/define-component.ts:27

Type Declaration​

__dbx​

readonly __dbx: object

__dbx.kind​

readonly kind: string

Type Parameters​

TProps​

TProps extends object

DestructiveBlockReason​

DestructiveBlockReason = "protected" | "needs-allow-destructive"

Defined in: runtime/src/guard.ts:16

Child​

Child = AnyElement | string | number | boolean | null | undefined

Defined in: runtime/src/jsx-runtime.ts:24

Props​

Props = Record<string, unknown> & object

Defined in: runtime/src/jsx-runtime.ts:26

Type Declaration​

children?​

optional children?: Child | Child[]

ElementType​

ElementType<P> = ((props) => unknown) | typeof Fragment | symbol

Defined in: runtime/src/jsx-runtime.ts:28

Type Parameters​

P​

P = object

PhaseElement​

PhaseElement = ElementNode<PhaseProps> & object

Defined in: runtime/src/phase.ts:69

Re-emit ElementNode shape for completeness (matches Phase's JSX use).

Type Declaration​

$$typeof​

$$typeof: typeof ELEMENT_TYPE

SnapshotMode​

SnapshotMode = "schema" | "full"

Defined in: runtime/src/snapshot.ts:10

What a driver captures. schema is the default; full includes row data.

PhaseType​

PhaseType = "setup" | "monitoring" | "backup" | "teardown"

Defined in: runtime/src/types.ts:3

PlanAction​

PlanAction = { type: "create"; } | { type: "update"; reason: string; destructive?: string[]; details?: string[]; } | { type: "replace"; reason: string; destructive?: string[]; details?: string[]; } | { type: "destroy"; reason: string; destructive?: string[]; details?: string[]; } | { type: "no-op"; }

Defined in: runtime/src/types.ts:115

The action the diff engine plans to take for a single resource.

destructive, when present and non-empty, lists the human-readable destructive changes this action entails (e.g. DROP INDEX "idx_old", ALTER COLUMN "amount" TYPE ...). The CLI marks these in preview and refuses to apply them without --allow-destructive — or unconditionally when the resource is under a protect-ed ancestor.

details is the exact statements the apply will run, in order. A component that already computes them at plan time should pass them through: reason is a summary ("1 addition(s)"), and a summary is not enough to review a migration. Entries that also appear in destructive are flagged as such.

Variables​

ELEMENT_TYPE​

const ELEMENT_TYPE: typeof ELEMENT_TYPE

Defined in: runtime/src/jsx-runtime.ts:9

Fragment​

const Fragment: typeof Fragment

Defined in: runtime/src/jsx-runtime.ts:10

jsxs​

const jsxs: <T>(type, props, key?) => ElementNode<T> = jsx

Defined in: runtime/src/jsx-runtime.ts:59

Type Parameters​

T​

T extends object

Parameters​

type​

ElementType<T>

props​

T & object

key?​

string

Returns​

ElementNode<T>

Phase​

const Phase: PhaseComponent

Defined in: runtime/src/phase.ts:54

PHASE_ORDER​

const PHASE_ORDER: readonly PhaseType[]

Defined in: runtime/src/phase.ts:66

The four valid phase types, in apply order.

STATE_SCHEMA_VERSION​

const STATE_SCHEMA_VERSION: 1 = 1

Defined in: runtime/src/state.ts:15

STATE_DIR​

const STATE_DIR: ".dbx" = '.dbx'

Defined in: runtime/src/state.ts:16

STATE_FILE​

const STATE_FILE: "state.json" = 'state.json'

Defined in: runtime/src/state.ts:17

LOCK_FILE​

const LOCK_FILE: "state.lock" = 'state.lock'

Defined in: runtime/src/state.ts:18

Functions​

defineComponent()​

defineComponent<TProps, TOutputs>(spec): JSXComponent<TProps>

Defined in: runtime/src/define-component.ts:33

Type Parameters​

TProps​

TProps extends object

TOutputs​

TOutputs extends object = object

Parameters​

spec​

ComponentSpec<TProps, TOutputs>

Returns​

JSXComponent<TProps>

isDbXComponent()​

isDbXComponent(value): value is JSXComponent<object>

Defined in: runtime/src/define-component.ts:64

Type guard: is this function value a component created by defineComponent?

Parameters​

value​

unknown

Returns​

value is JSXComponent<object>

plan()​

plan(desired, state): Plan

Defined in: runtime/src/diff.ts:45

Parameters​

desired​

Graph

state​

StateFile

Returns​

Plan

reverseForDestroy()​

reverseForDestroy(plan): Plan

Defined in: runtime/src/diff.ts:155

Reverse the action list for destroy iteration.

Parameters​

plan​

Plan

Returns​

Plan

isProtected()​

isProtected(id, graph, state): boolean

Defined in: runtime/src/guard.ts:35

True when id, or any ancestor, carries a truthy protect prop. Walks the desired graph first and falls back to persisted state, so resources being destroyed (absent from the graph) still resolve their protected ancestor.

Parameters​

id​

string

graph​

Graph

state​

StateFile

Returns​

boolean

findDestructiveViolations()​

findDestructiveViolations(plan, graph, state, opts): DestructiveViolation[]

Defined in: runtime/src/guard.ts:59

Scan a plan for destructive actions that must be blocked: any under a protect-ed ancestor (blocked unconditionally), plus — when allowDestructive is false — every other destructive action. An empty result means the plan is safe to apply.

Parameters​

plan​

Plan

graph​

Graph

state​

StateFile

opts​

DestructiveGuardOptions

Returns​

DestructiveViolation[]

jsx()​

jsx<T>(type, props, key?): ElementNode<T>

Defined in: runtime/src/jsx-runtime.ts:42

Type Parameters​

T​

T extends object

Parameters​

type​

ElementType<T>

props​

T & object

key?​

string

Returns​

ElementNode<T>

isPhaseComponent()​

isPhaseComponent(value): value is PhaseComponent

Defined in: runtime/src/phase.ts:57

Type guard for the reconciler.

Parameters​

value​

unknown

Returns​

value is PhaseComponent

renderToGraph()​

renderToGraph(node): Graph

Defined in: runtime/src/reconciler.ts:36

Parameters​

node​

Child | Child[]

Returns​

Graph

getComponentSpec()​

getComponentSpec(kind): AnySpec | undefined

Defined in: runtime/src/registry.ts:44

Parameters​

kind​

string

Returns​

AnySpec | undefined

listComponents()​

listComponents(): string[]

Defined in: runtime/src/registry.ts:48

Returns​

string[]

emptyState()​

emptyState(): StateFile

Defined in: runtime/src/state.ts:32

Returns​

StateFile

readState()​

readState(workDir): Promise<StateFile>

Defined in: runtime/src/state.ts:45

Parameters​

workDir​

string

Returns​

Promise<StateFile>

writeState()​

writeState(workDir, state): Promise<void>

Defined in: runtime/src/state.ts:74

Parameters​

workDir​

string

state​

StateFile

Returns​

Promise<void>

acquireLock()​

acquireLock(workDir): Promise<LockHandle>

Defined in: runtime/src/state.ts:92

Parameters​

workDir​

string

Returns​

Promise<LockHandle>

withLock()​

withLock<T>(workDir, fn): Promise<T>

Defined in: runtime/src/state.ts:129

Run fn while holding the state lock. Releases on success or error.

Type Parameters​

T​

T

Parameters​

workDir​

string

fn​

() => Promise<T>

Returns​

Promise<T>