Enum MigrationsCommand 

pub enum MigrationsCommand {
    Compose {
        name: String,
        allow_destructive: bool,
        force_overwrite: bool,
        workspace: Option<PathBuf>,
    },
    Status {
        workspace: Option<PathBuf>,
    },
    Verify {
        workspace: Option<PathBuf>,
        strict: bool,
    },
    Attune {
        target: Option<String>,
        apply: bool,
        record: bool,
        record_ledger: bool,
        record_reason: String,
        squash: bool,
        from: Option<String>,
        publish: bool,
        app: Option<String>,
        workspace: Option<PathBuf>,
    },
    Apply {
        workspace: Option<PathBuf>,
        fake: bool,
        reason: Option<String>,
        node_id: Option<u32>,
        single_node_dev: bool,
    },
    Repair {
        command: RepairSubcommand,
    },
    Baseline {
        version: String,
        description: String,
        reason: String,
        app: Option<String>,
        database: Option<String>,
        workspace: Option<PathBuf>,
        node_id: Option<u32>,
        single_node_dev: bool,
    },
}

Variants

Compose

Compose a new migration from descriptor inventory + last snapshot.

Fields

name: String

Operator-facing migration name. Sanitised down to a strict identifier; defaults to migration when empty.

allow_destructive: bool

Allow destructive (drop) operations or tombstoned-app migrations. Without this flag the compose path refuses destructive deltas with a structural error.

force_overwrite: bool

Discard hand-edits to existing migration files. Without this flag compose refuses to overwrite any up or down migration file whose current bytes do NOT match what the deterministic emitter would freshly produce — the byte-equality check stands in for a checksum compare because the emitter is deterministic (same inputs always produce the same bytes). The check is purely byte-level; it does not read the pending JSON’s checksum_up field.

workspace: Option<PathBuf>

Workspace root override. Defaults to the current working directory.

Status

Print the current state of the migration ledger, grouped by app. Read-only — does not acquire the workspace lock. Requires PostgreSQL 18 or later.

Fields

workspace: Option<PathBuf>

Workspace root override (only used when reading Djogi.toml).

Verify

Compare live database catalog against the schema snapshot. Read-only — does not acquire the workspace lock or execute DDL. Exits 0 if no error-level diagnostics are found. Exits 1 on runtime errors (config / pool / SQL). Exits 2 if the Postgres server is below version 18. Use --strict to upgrade out-of-order migration warnings (D622) to errors, causing verify to exit non-zero when the ledger contains out-of-order applied rows.

Fields

workspace: Option<PathBuf>

Workspace root override (only used when reading Djogi.toml).

strict: bool

Upgrade D622 out-of-order diagnostics from Warning to Error.

Attune

Reconcile local migration history with the ledger. Default mode is a read-only diff between the on-disk SQL files and the ledger. Attune is read-only by default — pass --apply to commit ledger inserts / squash / parent-pointer writes. --record updates the parent repo’s recorded submodule pointer to the resolved Git target after successful attunement. --squash --from <ver> collapses local history into a single migration (localhost + dev_mode + dev profile + DJOGI_ENV gates). Requires PostgreSQL 18 or later — exits with code 2 if the server is below the minimum. Exit codes: 0 on success, 1 on runtime error (config / network / SQL / git), 2 on refusal (gate failure, arg validation, below PG 18).

Fields

target: Option<String>

Optional Git target to attune the local migration history to — a local or remote commit / tag / branch. When omitted, attune reconciles against the current on-disk state. Resolution: tries local first, then git fetch --all + retries on failure.

apply: bool

Mutate the database / parent index. Without --apply, attune is a dry-run — it scans, prints the diff, and exits without inserting / deleting ledger rows or updating the parent submodule pointer (per docs/spec/configuration.md §14: “does not mutate the database unless --apply is explicitly passed”).

record: bool

In Record mode (--record-ledger), insert ledger rows for SQL files present on disk but absent from the ledger. With a resolved <target> argument AND --apply, also update the parent repo’s recorded submodule pointer to the target SHA.

record_ledger: bool

Activate Record mode — insert ledger rows for SQL files present on disk but absent from the ledger. Distinct from --record (which controls the parent submodule pointer). Records the operator-supplied reason in partial_apply_note. Does NOT execute SQL.

record_reason: String

When --record-ledger is set, the rationale recorded on every inserted ledger row’s partial_apply_note.

squash: bool

Coalesce every committed migration from --from to HEAD into a single squashed migration. HISTORY REWRITE — gated on localhost + dev profile + dev_mode + DJOGI_ENV.

from: Option<String>

Inclusive starting version for --squash (e.g. V20260101000000__init).

publish: bool

After a successful squash, push the rewritten migrations/ submodule to its remote. Without this flag the rewrite stays local. Squash NEVER auto-publishes.

app: Option<String>

Optional explicit app label to scope --squash to a single bucket. Required when --from matches a version in multiple buckets; auto-detected when the version is unique to one bucket.

workspace: Option<PathBuf>

Workspace root override.

Apply

Apply all pending migrations in ledger order. This is the canonical spelling; djogi migrate apply is a compatibility alias. Transaction semantics are per-segment: transactional segments roll back on error; non-transactional segments autocommit and may leave partial progress. On crash or unexpected termination, re-run djogi migrations apply. For partial non-transactional progress, use djogi migrations repair resume-partial. Existing-database adoption: use --fake to mark pending migrations as applied without executing their SQL. This is for databases whose schema already exists (from a prior tool, manual DDL, or restored backup). Use djogi migrations verify or manual inspection to confirm the schema matches the target state before faking. The --fake flag respects the same out-of-order policy as real apply; if CI/prod policy is Reject, fake-apply on an out-of-order version is also rejected. Node identity: for operations that execute SQL, supply --node-id <id> (explicit cluster node) or --single-node-dev (dev mode, binds node 1). Mutually exclusive. Falls back to HEER_NODE_ID env var when neither flag is set. Refuses without identity for non-dev operations (exit 2). For previewing pending work without executing it, use djogi migrations status. If the command is interrupted after recording a ledger row with a terminal status (applied, faked, baseline), re-running reports VersionAlreadyApplied (exit 2). For non-terminal statuses (failed, rolled_back), the stale row is removed and re-apply proceeds automatically. If the snapshot is missing or stale, reconcile it with djogi migrations attune or repair snapshot-rebuild.

Fields

workspace: Option<PathBuf>

Workspace root override. Defaults to the current working directory.

fake: bool

Record pending migrations as applied without executing their SQL. For existing-database adoption only. Requires --reason. Subject to the same out-of-order policy as real apply; if CI/prod policy is Reject, fake-apply on an out-of-order version is also rejected.

reason: Option<String>

Reason for faking these migrations. Required when --fake is set. Persisted to the ledger’s audit trail so future inspections can understand why this version was recorded without SQL execution. Has no effect on normal (non-fake) apply.

node_id: Option<u32>

Explicit cluster node identity (0..=511). Wins over HEER_NODE_ID env var. Mutually exclusive with --single-node-dev. Required for identity-bearing operations unless --single-node-dev is supplied or HEER_NODE_ID is set.

single_node_dev: bool

Single-node development mode — binds node 1 for the duration of this operation. Mutually exclusive with --node-id. Refused in production profile or DJOGI_ENV=production.

Repair

Operator-confirmed repair flows for ledger drift, partial applies, and missing snapshots. Every subcommand requires explicit confirmation — invoking the CLI subcommand IS the operator acknowledgment.

Fields

command: RepairSubcommand

The specific repair operation to perform.

Baseline

Project the live database schema into a baseline ledger row and snapshot. Use for existing databases being adopted under Djogi’s migration ledger, where the schema already exists and compose + apply cannot run on a populated database without a starting point. Projects the live catalog into a single baseline ledger row (no SQL runs against user tables) and writes the projected snapshot so future migrations diff against the real DB state. Invoking the subcommand IS the operator acknowledgment. Requires PostgreSQL 18 or later — exits with code 2 if the server is below the minimum. Exit codes: 0 on success, 1 on runtime error (config / network / SQL / projection failure), 2 on refusal (empty --reason, duplicate version, unresolvable database URL, snapshot-persist failure after ledger insert, session-pinning correctness failure, or below PG 18).

Fields

version: String

Version label for the baseline ledger row (e.g. V00000000000000__baseline). Must be unique in the ledger.

description: String

One-line description stored in the ledger row.

reason: String

Required non-empty reason recorded in the baseline note (audit trail entry).

app: Option<String>

App label for the migration bucket. Defaults to the global bucket (empty string) when not specified.

database: Option<String>

Database name. Defaults to main if not specified.

workspace: Option<PathBuf>

Workspace root override.

node_id: Option<u32>

Explicit cluster node identity (0..=511). Required for baseline unless --single-node-dev is supplied.

single_node_dev: bool

Single-node development mode — binds node 1 for baseline. Refused in production profile or DJOGI_ENV=production.

Trait Implementations

impl FromArgMatches for MigrationsCommand

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut<'b>( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Subcommand for MigrationsCommand

fn augment_subcommands<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_subcommands_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

fn has_subcommand(__clap_name: &str) -> bool

Test whether Self can parse a specific subcommand