grizzle

type ApplyOpts struct {
	// ExpectedHash is the approved plan hash. If non-empty, Apply recomputes the plan after
	// acquiring the lock and verifies the recomputed hash matches ExpectedHash.
	// If it does not match, Apply aborts with ErrPlanDrift.
	ExpectedHash string

	// AcceptHazards specifies explicitly accepted critical hazards.
	AcceptHazards []HazardCode

	// Backfill hook function run outside the DDL lock window in batches during staged expand migration.
	Backfill BackfillFunc

	// BeforeSync runs once before any migration steps or locks are executed.
	BeforeSync SyncHook

	// AfterSync runs once after all migration steps and history recording succeed.
	AfterSync SyncHook

	// BeforeStep executes immediately prior to executing each plan step.
	BeforeStep StepHook

	// AfterStep executes immediately following the successful execution of each plan step.
	AfterStep StepHook

	// SQLiteRebuildThreshold defines the row count threshold above which SQLite table rebuilds
	// chunk data copying by keyset. Defaults to 100000.
	SQLiteRebuildThreshold int

	// SQLiteRebuildBatchSize defines the chunk size when copying data in batches during SQLite table rebuilds.
	// Defaults to 10000.
	SQLiteRebuildBatchSize int

	// SQLiteAttach maps ATTACH DATABASE schema names to filesystem paths for
	// multi-schema SQLite Apply. Not carried in the plan artifact.
	SQLiteAttach map[string]string

	// LockNamespace specifies the application namespace string used for PostgreSQL advisory locking (defaults to "grizzle").
	LockNamespace string

	// DevDatabaseURL optionally specifies an external database connection URL
	// used for shadow schema compilation during plan verification.
	DevDatabaseURL string

	// FailOnContention gates DDL execution on PostgreSQL: if concurrent sessions hold conflicting
	// locks on target tables, retry with backoff up to LockTimeout; if contention persists, abort
	// with ErrLockContention instead of proceeding. When false (default), lock contention is advisory
	// and logs a warning before proceeding.
	FailOnContention bool

	// Logger receives structured migration logs during Apply (defaults to no logging).
	// The plan artifact cannot carry a logger, so it is supplied here.
	Logger *slog.Logger

	// Tracer specifies an optional tracer for observing plan application.
	Tracer Tracer

	// Metrics specifies an optional metrics recorder for observing plan application.
	Metrics Metrics
}

type BackfillFunc func(ctx context.Context, tx *sql.Tx, table, oldCol, newCol string) error

type BaselineOptions struct {
	TargetSchema   string
	Note           string
	Force          bool // If true, record baseline even if unapplied changes exist
	DevDatabaseURL string
}

type ChangeType = plan.ChangeType

type CheckConstraintIR = schema.CheckConstraint

type ColumnIR = schema.Column

type CompositeAttributeIR = schema.CompositeAttribute

type CompositeTypeIR = schema.CompositeType

type DependencyRef = schema.DependencyRef

type DestructiveViolationError = plan.DestructiveViolationError

type Dialect string

type DriftError = plan.DriftError

type DropPolicy = plan.DropPolicy

type DryRunResult = exec.DryRunResult

type DumpOptions struct {
	TargetSchema string
}

type EnumIR = schema.Enum

type ExportArtifact = export.Artifact

type ExportFormat = export.Format

type ExtensionIR = schema.Extension

type ForeignKeyIR = schema.ForeignKey

type GeneratedColumn = schema.GeneratedColumn

type Hazard = plan.Hazard

type HazardCode = plan.HazardCode

type HazardError = plan.HazardError

type HazardLevel = plan.HazardLevel

type HistoryEntry struct {
	ID         int64     `json:"id"`
	PlanHash   string    `json:"plan_hash"`
	Status     string    `json:"status"` // applied, partial, failed, baseline, resolved
	FailedStep int       `json:"failed_step,omitempty"`
	Error      string    `json:"error,omitempty"`
	AppliedAt  time.Time `json:"applied_at"`
	DurationMs int64     `json:"duration_ms"`
	AppliedBy  string    `json:"applied_by"`
	StepsJSON  string    `json:"steps,omitempty"`
	SeedHash   string    `json:"seed_hash,omitempty"`
}

type HistoryOptions struct {
	TargetSchema string
	Limit        int
	Descending   bool
}

type HookContext = exec.HookContext

type IndexIR = schema.Index

type LintDiagnostic = lint.Diagnostic

type LintRule = lint.Rule

type LintSeverity = lint.Severity

type LockConflict = plan.LockConflict

type LockContentionError = plan.LockContentionError

type Metrics = exec.Metrics

type Option func(*Options)

type Options struct {
	// Dialect explicitly defines the database engine (DialectPostgres or DialectSQLite).
	Dialect Dialect

	// SchemaSQL contains the complete desired state. PostgreSQL role and
	// catalog statements may share this file; they bypass shadow compilation
	// and are merged with the optional side-channel files.
	SchemaSQL string

	// TargetSchema is the schema to manage (defaults to "public" for Postgres, "main" for SQLite).
	// Deprecated: Use TargetSchemas for multi-schema support.
	TargetSchema string

	// TargetSchemas specifies the database schemas to manage (defaults to [TargetSchema] or ["public"] for Postgres).
	// For SQLite, entries other than "main" are ATTACH DATABASE schema names listed in SQLiteAttach.
	TargetSchemas []string

	// TargetSchemaPattern specifies a LIKE-style pattern to discover target PostgreSQL schemas
	// dynamically from pg_namespace (e.g. "tenant_%"). Discovered schemas are sorted deterministically,
	// exclude system schemas, and are populated into TargetSchemas.
	TargetSchemaPattern string

	// SQLiteAttach maps ATTACH DATABASE schema names to filesystem paths.
	// Every TargetSchemas entry other than "main" must appear here; "main" is
	// the primary database already open and must not be listed. Unknown keys,
	// empty paths, and duplicate names are rejected. PostgreSQL ignores this field.
	SQLiteAttach map[string]string

	// ShadowSchema is the temporary schema name used for validation (defaults to "_grizzle_shadow").
	ShadowSchema string

	// AllowDrop permits all destructive operations when set to true.
	// Defaults to false for zero data loss.
	AllowDrop bool

	// AllowRevoke permits privilege revocation when a grant in RolesSQL is
	// removed (access loss). Has no granular override; REVOKE_PRIVILEGE
	// (CRITICAL) still requires AcceptHazards.
	AllowRevoke bool

	// AllowDropRole permits dropping a managed role that left RolesSQL.
	// Has no granular override; DROP_ROLE (CRITICAL) still requires
	// AcceptHazards.
	AllowDropRole bool

	// AllowDropPublication permits dropping a managed publication that
	// left CatalogSQL. Has no granular override; DROP_PUBLICATION
	// (CRITICAL) still requires AcceptHazards.
	AllowDropPublication bool

	// AllowDropEventTrigger permits dropping a managed event trigger that
	// left CatalogSQL. Has no granular override; DROP_EVENT_TRIGGER
	// (CRITICAL) still requires AcceptHazards.
	AllowDropEventTrigger bool

	// AllowDropSubscription permits dropping a managed subscription that
	// left CatalogSQL. Has no granular override; DROP_SUBSCRIPTION
	// (CRITICAL) still requires AcceptHazards. Remote slots are kept
	// (DISABLE + SET slot_name = NONE before DROP).
	AllowDropSubscription bool

	// AllowDropReplicationSlot permits dropping a standalone logical
	// replication slot via explicit SELECT pg_drop_replication_slot.
	// Live-only slots are never swept. DROP_REPLICATION_SLOT (CRITICAL)
	// still requires AcceptHazards. Active slots (active_pid IS NOT NULL)
	// are refused.
	AllowDropReplicationSlot bool

	// Granular drop overrides (nil inherits from AllowDrop):
	AllowDropTable         *bool
	AllowDropColumn        *bool
	AllowDropIndex         *bool
	AllowDropFK            *bool
	AllowDropCheck         *bool
	AllowDropExtension     *bool
	AllowDropFunction      *bool
	AllowDropPolicy        *bool
	AllowDropTrigger       *bool
	AllowDropView          *bool
	AllowDropDomain        *bool
	AllowDropType          *bool
	AllowDropRangeType     *bool
	AllowDropCompositeType *bool
	AllowDropSequence      *bool

	// ExcludeTables defines table names or glob patterns (e.g. "spatial_ref_sys", "asynq_*")
	// that Grizzle will never manage, alter, or drop.
	ExcludeTables []string

	// IncludeTables limits Grizzle's management scope to only the specified tables or patterns.
	IncludeTables []string

	// StrictScope requires IncludeTables to be non-empty. When true and IncludeTables is empty,
	// operations fail immediately with ErrStrictScope.
	// Strongly recommended for production environments to avoid accidental alterations or drops
	// of untracked tables.
	StrictScope bool

	// AcceptHazards lists critical hazard codes that are explicitly approved to execute.
	// Critical hazards not present in this list will cause Apply to fail with ErrHazardBlocked.
	AcceptHazards []plan.HazardCode

	// NonConcurrentIndexes opts out of emitting CONCURRENTLY for PostgreSQL index creation/drops.
	// When true, index operations are created inside the transaction.
	NonConcurrentIndexes bool

	// LockNamespace specifies the application namespace string used for PostgreSQL advisory locking (defaults to "grizzle").
	LockNamespace string

	// LockID is an optional explicit 64-bit integer used for the PostgreSQL advisory lock (pg_advisory_xact_lock).
	// If 0, Grizzle derives 2-int per-schema advisory locks using (hash32(LockNamespace), hash32(schema)).
	LockID int64

	// LockTimeout specifies the maximum time to wait when acquiring locks (defaults to 5s).
	LockTimeout time.Duration

	// StatementTimeout specifies the maximum execution time for any single DDL statement (defaults to 5m).
	StatementTimeout time.Duration

	// MaxRetries specifies the number of retry attempts upon lock timeout (SQLSTATE 55P03, defaults to 3).
	MaxRetries int

	// RandFloat provides an optional random source func returning in [0.0, 1.0) for deterministic jitter in tests.
	RandFloat func() float64

	// Renames maps old column names to new column names (e.g. "users.old_col": "new_col" or "old_col": "new_col")
	// to explicitly disambiguate column renames instead of treating them as DROP + ADD.
	// Keys are `table.old` or `old`; values are the new column name.
	Renames map[string]string

	// ExpandContract enables staged expand-and-contract zero-downtime migrations (ZDM).
	// In expand mode, renamed or modified columns are added alongside existing columns,
	// delaying destructive drops to a later, separately approved plan.
	ExpandContract bool

	// Backfill hook function run outside the DDL lock window in batches during staged expand migration.
	// The CLI installs a hook via --backfill / --backfill-file when --expand-contract is set; a library
	// Backfill still wins when both are configured by the caller.
	Backfill BackfillFunc

	// BeforeSync runs once before any migration steps or locks are executed.
	// If it returns an error, the migration aborts before any DDL runs and no
	// history record is written.
	BeforeSync SyncHook

	// AfterSync runs once after all migration steps and history recording succeed.
	// If it returns an error, the DDL has already committed; the error is
	// wrapped with ErrAfterSyncFailed.
	AfterSync SyncHook

	// BeforeStep executes immediately prior to executing each plan step.
	// If it returns an error, the pending step is not executed; in a
	// transactional group the transaction is rolled back and history records
	// the failure with error "before_step hook: ...".
	BeforeStep StepHook

	// AfterStep executes immediately following the successful execution of each
	// plan step. If it returns an error in a transactional group, the
	// transaction is rolled back (reverting the step); in a non-transactional
	// group the step has already committed and history records "partial".
	AfterStep StepHook

	// DryRun returns the planned SQL statements without executing them on the live database.
	DryRun bool

	// DryRunLockTimeout bounds how long live dry-run verification waits on
	// table locks before failing fast (defaults to 2s).
	DryRunLockTimeout time.Duration

	// ExecuteHooksInDryRun allows BeforeStep/AfterStep hooks to run during
	// live dry-run verification. Defaults to false to avoid accidental
	// external side effects (webhooks, message publishing, etc.).
	ExecuteHooksInDryRun bool

	// SeedSQL contains idempotent data-seed SQL executed after a successful
	// sync (Sync DDL → AfterSync → Seed). The seed runs in a single
	// transaction and is skipped when the same seed (by content hash) was
	// already applied, unless SeedForce is set.
	SeedSQL string

	// SeedForce re-runs the seed even when the same seed hash was already
	// applied.
	SeedForce bool

	// RolesSQL optionally supplies desired roles and privilege grants
	// alongside SchemaSQL. Duplicate role/grant identities in this explicit
	// side-channel override entries extracted from SchemaSQL. Role statements
	// are never shadow-compiled, and schema DDL is not valid here. Managed
	// attributes include LOGIN/NOLOGIN, PASSWORD, VALID UNTIL, CONNECTION
	// LIMIT, INHERIT, CREATEDB, CREATEROLE, and ALTER ROLE SET/RESET.
	// SUPERUSER/REPLICATION/BYPASSRLS are refused. Passwords are compared by
	// server-side hash equality and never written into Step.SQL or plan JSON.
	// PostgreSQL only — ignored on SQLite.
	RolesSQL string

	// CatalogSQL optionally supplies desired cluster-catalog objects alongside
	// SchemaSQL. Duplicate publication/event-trigger names in this explicit
	// side-channel override entries extracted from SchemaSQL. Catalog
	// statements are never shadow-compiled or run inside the shadow
	// transaction, and schema DDL is not valid here. Drops are narrow — only
	// marker-stamped (grizzle-managed) objects are considered. Event triggers
	// reference functions that must exist in SchemaSQL or as live objects.
	// PostgreSQL only — rejected on SQLite.
	CatalogSQL string

	// SQLiteRebuildThreshold defines the row count threshold above which SQLite table rebuilds
	// chunk data copying by keyset to prevent journal memory exhaustion.
	// Defaults to 100000. Set to 0 to disable batching.
	SQLiteRebuildThreshold int

	// SQLiteRebuildBatchSize defines the chunk size when copying data in batches during SQLite table rebuilds.
	// Defaults to 10000.
	SQLiteRebuildBatchSize int

	// AllowResumePartial permits Sync to resume execution after a prior run
	// ended in "partial" or "failed" status. Defaults to false (fail closed).
	AllowResumePartial bool

	// ExpectedHash specifies an approved plan hash. When non-empty, Sync
	// verifies the post-lock live plan hash against this value and aborts
	// with ErrPlanDrift if they differ.
	ExpectedHash string

	// DevDatabaseURL is an optional PostgreSQL connection string used
	// exclusively for shadow-schema compilation (the always-rolled-back
	// transaction that validates SchemaSQL). When non-empty the shadow
	// transaction runs against this external database and never touches the
	// target database. Live catalog introspection always uses the target DB.
	//
	// Use DevDatabaseURL when the target database user lacks CREATE SCHEMA
	// privilege. Without it, a privilege failure during shadow setup is
	// returned as an error that names this field and --dev-url as the fix.
	//
	// PostgreSQL only; ignored on SQLite.
	DevDatabaseURL string

	// FailOnContention gates DDL execution on PostgreSQL: if concurrent sessions hold conflicting
	// locks on target tables, retry with backoff up to LockTimeout; if contention persists, abort
	// with ErrLockContention instead of proceeding. When false (default), lock contention is advisory
	// and logs a warning before proceeding.
	//
	// NOTE: Pre-flight lock inspection is inherently racy: concurrent transactions may acquire
	// locks between the pre-flight check and subsequent DDL execution. Always configure LockTimeout
	// alongside FailOnContention to bound wait duration if a race occurs.
	FailOnContention bool

	// Logger accepts a structured logger (*slog.Logger) for migration events.
	Logger *slog.Logger

	// Tracer specifies an optional tracer (OpenTelemetry or custom) for observing migrations.
	Tracer Tracer

	// Metrics specifies an optional metrics recorder (OpenTelemetry or custom) for observing migrations.
	Metrics Metrics
}

type PartitionKey = schema.PartitionKey

type PartitionOf = schema.PartitionOf

type PartitionStrategy = schema.PartitionStrategy

type Plan = plan.Plan

type PlanDocument = plan.Document

type PolicyIR = schema.Policy

type PrimaryKeyIR = schema.PrimaryKey

type RangeTypeIR = schema.RangeType

type RepairOptions struct {
	TargetSchema string
	Note         string
}

type RoutineIR = schema.Routine

type SchemaIR = schema.Schema

type ScopeDocument = plan.ScopeDocument

type SequenceIR = schema.Sequence

type Span = exec.Span

type StatusReport struct {
	Dialect      string        `json:"dialect"`
	TargetSchema string        `json:"target_schema,omitempty"`
	InSync       bool          `json:"in_sync"`
	PendingSteps int           `json:"pending_steps"`
	AppliedCount int           `json:"applied_count"`
	PartialCount int           `json:"partial_count"`
	FailedCount  int           `json:"failed_count"`
	Latest       *HistoryEntry `json:"latest,omitempty"`
}

type Step = plan.Step

type StepHook = exec.StepHook

type SyncHook = exec.SyncHook

type TableIR = schema.Table

type Tracer = exec.Tracer

type TriggerIR = schema.Trigger

type UnmanagedKind = schema.UnmanagedKind

type UnmanagedObject = schema.UnmanagedObject

type ViewIR = schema.View