Crate alembic_engine 

engine orchestration: load, validate, plan, apply.

Re-exports

pub use external::run_external_adapter;

pub use external::ExternalAdapter;

pub use external::ExternalEnvelope;

pub use external::ExternalEnvelopeRef;

pub use external::ExternalObject;

pub use external::ExternalRequest;

pub use external::ExternalRequestRef;

pub use external::ExternalResponse;

pub use external::EXTERNAL_PROTOCOL_VERSION;

pub use journal::Journal;

Modules

external

helpers for implementing external adapters.

journal

Keep track of successfully applied ops to enable resume after an error.

mapping

shared mapping helpers used by multiple adapters.

Macros

alembic_external_main

convenience macro to define an external adapter main.

Structs

AppliedOp

result for a single applied operation.

ApplyReport

aggregated apply report.

ChangedEntry

an object present in both intent and backend, but with diverging fields.

DriftEntry

an object that exists on only one side of the diff (missing or extra).

DriftReport

read-only report of how observed backend state diverges from declared intent.

FieldChange

field-level change for an update op.

ImportReport

MapSpec

a map specification: the target schema plus the transformation rules.

ObservedObject

observed backend object representation.

ObservedState

observed backend state indexed by id and key.

Plan

full plan document.

PlanSummary

high-level summary of plan operations.

ProvisionReport

report from ensure_schema provisioning.

RetryApplyResult

StateData

on-disk state schema.

StateMappings

per-type backend-id -> uid map for read-side ref normalization.

StateStore

state store wrapper with load/save helpers.

TransformsSpec

the transforms: block of a map spec: starlark source from a file or inline. exactly one of the two must be set.

Enums

AdapterApplyError

Backend

a constructed backend, tagged with its capability.

BackendId

generic backend identifier (integer or string/uuid).

Op

plan operation.

PostgresTlsMode

TLS configuration for postgres state backend connections.

Traits

Adapter

full adapter contract for read+write backends; may also provision schema.

Emitter

write capability: apply a plan’s operations.

Observer

read capability: observe backend state.

RetryApplyDriver

Functions

apply_non_delete_journaled

journal-wiring shared by the internal apply-adapters: build the journal from state, run the retry loop, and return the result plus the resumed count (None when none), ready for ApplyReport::previously_applied_count.

apply_non_delete_with_retries

apply_plan

apply a plan and update the state store. full adapters provision schema before writing; emitters only write.

backend_id_from_value

read a backend id out of a raw json value: a number, a string, or an object with an id field (a nested brief).

build_key_from_schema

build_plan

observe backend state and produce a deterministic plan.

build_request_body

compile_map

transform an ir inventory into another ir inventory under the target schema.

describe_missing_refs

comma-joined referenced uids in ops that are absent from resolved.

eval_map_transform

evaluate a single named transform from a map spec against a json value, consulting the spec’s user transforms first, then the built-ins. backs alembic map transform, the iteration loop for writing transforms: one value in, the typed result out, no inventory or backend involved.

guard_schema_deletes

refuse destructive schema provisioning (deleting custom object types/fields the inventory no longer declares) unless allow_delete is set. these deletes cascade to their objects on the backend, so they are gated behind the same flag as object deletes. preview is the read-only schema preview both plan (before provisioning) and apply compute.

import_inventory

is_missing_ref_error

true when err is a retryable missing-ref apply error.

load_inventory

load a inventory file (yaml or json) and merge any includes.

load_map_spec

load a map spec from a yaml file. the spec remembers the file’s directory so transforms.file and starlark load() paths resolve relative to it.

normalize_attrs_refs

rewrite every reference-typed field of attrs from backend ids back to canonical uids. read-side inverse of build_request_body.

normalize_endpoint

normalize a rest-api endpoint to its canonical app/resource/ path, dropping a trailing object-id segment when is_object_id matches it. netbox and nautobot share this and differ only in is_object_id (integer vs uuid pks).

plan

build a deterministic plan from desired and observed state.

plan_write_only

produce a plan for a write-only backend, which cannot report existing state. the inventory is validated, then planned against an empty observation, so every declared object becomes a create (and nothing is updated or deleted).

pluralize

pluralize a django/drf endpoint segment, the way django’s url router does. shared by the netbox, nautobot, and django adapters.

query_filters_from_key

render_plan

render a plan’s operations as a human-readable summary: a one-line count header, then each op grouped under create / update / delete with its type and human key (and per-field from -> to for updates). long categories are truncated with an ... and N more line so a large plan stays readable.

report_to_result

helper to format a validation report into a Result.

report_to_result_with_sources

helper to format a validation report with source locations into a Result.

resolve_value_for_type

resolved_ids_from_state

project the state store into a flat uid -> backend-id map, keeping only the backend ids extract accepts. companion to state_mappings_by_id.

resolved_ids_identity

project the state store into a flat uid -> backend-id map, keeping every mapping. identity companion to resolved_ids_from_state.

sort_ops_for_apply

order operations for apply: creates/updates first (topologically sorted so referenced objects are created before the objects that reference them), then deletes (reverse-toposorted so an object is deleted only after everything referencing it). reference cycles fall back to a stable order.

state_mappings_by_id

project the state store into a per-type backend-id -> uid map, keeping only the backend ids extract accepts (the variant a given adapter retains).

validate

validate an inventory and return the report.