Zero-Downtime Laravel Migration Review

Review the proposed Laravel schema and data migration change set for zero-downtime feasibility and production safety using Codex and the actual repository.

Use only repository content, database evidence, command output, and operational facts that are supplied or genuinely accessible in the current Codex workspace.

## Required inputs

- Repository and change set: [Repository and change set]
- Framework and database versions: [Framework and database versions]
- Production schema evidence: [Production schema evidence]
- Workload and table evidence: [Workload and table evidence]
- Deployment topology and compatibility window: [Deployment topology and compatibility window]
- Backfill and recovery constraints: [Backfill and recovery constraints]
- Operational limits and approvals: [Operational limits and approvals]
- Acceptance evidence: [Acceptance evidence]

The repository and change-set input should identify, where relevant:

- the exact release, commit, branch, or diff under review;
- migration files;
- raw SQL;
- related models and casts;
- accessors and mutators;
- validation rules;
- services and query builders;
- controllers and API resources;
- jobs and queue payloads;
- events and listeners;
- scheduled commands;
- factories and seeders;
- tests;
- feature flags;
- application deployment order.

Production schema evidence should include, where available:

- current columns and data types;
- defaults;
- nullability;
- indexes;
- constraints;
- foreign keys;
- generated columns;
- approximate row counts;
- duplicate, null, orphan, or invalid-data counts;
- relevant database metadata;
- observed schema drift.

Workload and table evidence should describe, where available:

- read and write rates;
- transaction duration;
- long-running transactions;
- high-traffic periods;
- table growth;
- replica use and acceptable lag;
- connection pooling;
- lock or statement timeouts;
- queue throughput;
- scheduled workloads;
- disk, transaction-log, or WAL constraints.

Deployment topology should identify:

- environments;
- promotion order;
- application instances;
- queue workers;
- scheduled processes;
- deployment strategy;
- mixed-version window;
- maintenance constraints;
- maximum acceptable interruption or degradation.

Backfill and recovery constraints should identify:

- whether data transformation is required;
- acceptable batch and runtime limits;
- retry and resume requirements;
- backup scope and freshness;
- restore evidence;
- rollback and roll-forward expectations;
- data-loss tolerance.

Operational limits and approvals should state:

- permitted read-only inspection;
- permitted local commands;
- whether file edits are permitted;
- prohibited actions;
- production-access restrictions;
- database-owner and release-owner responsibilities;
- required human approval gates.

Acceptance evidence should define the observable conditions required before:

- rehearsal;
- schema expansion;
- backfill;
- read switching;
- constraint validation;
- contract work;
- cleanup;
- production completion.

## Zero-downtime standard

Do not interpret “zero downtime” as a literal guarantee of zero locks, zero latency change, or zero operational impact.

Evaluate zero-downtime feasibility against the supplied service objectives and acceptance constraints, including:

- permitted service interruption;
- acceptable latency or error-rate change;
- write availability;
- queue delay;
- replica lag;
- maintenance allowance;
- user-visible degradation;
- compatibility requirements.

If those thresholds are not supplied, mark zero-downtime feasibility as unverified. Do not invent an acceptable outage or degradation threshold.

## Input and evidence rules

1. Begin with an input-status table. Classify every required input as:

   - supplied;
   - observed in the accessible workspace;
   - missing;
   - ambiguous;
   - conflicting;
   - not applicable.

2. Bind all material evidence to the exact release under review where possible. Record:

   - commit, revision, or diff;
   - migration filename and identifier;
   - database engine and version;
   - target environment;
   - schema snapshot date;
   - workload measurement window;
   - command or rehearsal timestamp;
   - artifact or output identity.

   Evidence from another commit, migration set, database version, schema state, environment, or execution window is not automatically evidence for this release.

3. Cite repository findings using available file paths, line ranges, classes, methods, migration names, or symbols.

4. Cite operational findings by naming the supplied:

   - schema snapshot;
   - command output;
   - metric;
   - query result;
   - runbook;
   - deployment record;
   - backup record;
   - rehearsal artifact;
   - user statement.

5. Label every material statement as one of:

   - confirmed;
   - inferred;
   - assumed;
   - unknown;
   - conflicting.

   Never convert an assumption or generic database practice into a confirmed finding.

6. If migration files are unavailable, stop after listing the exact migrations and related code required. Do not issue a deployment or zero-downtime decision.

7. If the database engine or exact version is missing or conflicting, do not make engine-specific claims about:

   - locking;
   - online DDL;
   - table rewrites;
   - transactional behavior;
   - concurrent index creation;
   - instant or in-place alterations.

   Request authoritative version output.

8. If table size, write load, production schema, long-running transactions, or deployment topology is unknown, mark lock duration and zero-downtime feasibility unknown. Do not automatically classify the operation as safe or unsafe.

9. Reconcile repository migrations with the actual production schema.

   Production schema evidence governs operational risk. Repository history remains evidence of intended state.

   Unexplained schema drift is a release blocker.

10. Distinguish clearly:

    - requested work;
    - proposed edits or commands;
    - executed checks;
    - supplied execution evidence;
    - unavailable checks;
    - unverified results.

    A command is executed only when Codex actually runs it in an authorized environment and captures its result.

    Command output supplied by the user is supplied evidence, not independently reproduced evidence.

11. Do not invent:

    - row counts;
    - batch sizes;
    - operation duration;
    - lock duration;
    - throughput;
    - replica lag;
    - backup validity;
    - restore success;
    - database behavior;
    - test output;
    - deployment success.

12. When a numerical recommendation cannot be supported, provide a calibration method or bounded range instead of false precision.

## Codex authority boundaries

Unless [Operational limits and approvals] explicitly restricts it, permit:

- read-only repository inspection;
- inspection of supplied schema metadata;
- non-mutating local diagnostics;
- review of existing test and deployment configuration.

Treat the following as unauthorized unless expressly approved:

- file edits;
- mutating commands;
- dependency changes;
- database writes;
- migrations;
- backfills;
- destructive SQL;
- production queries;
- load tests;
- cache or queue changes;
- deployments;
- rollbacks;
- external-service changes.

Even where local edits are authorized, do not execute:

- production migrations;
- production backfills;
- destructive SQL;
- production rollback commands;
- deployment;
- DNS or infrastructure changes.

Production execution, restore decisions, destructive changes, and release approval remain human-controlled actions.

Do not expose credentials, connection strings, customer records, personal data, payment data, or confidential production rows. Request redacted schema metadata, aggregate counts, and sanitized samples.

If repository edits are separately authorized, make only the smallest reviewable changes required to reduce migration risk. Keep applied changes separate from proposed but unapplied work.

## Focused review workflow

### 1. Establish the release identity and review scope

Record:

- release or commit identity;
- migration files;
- related application components;
- target database engine and version;
- target environment;
- deployment strategy;
- compatibility window;
- maintenance limits;
- supplied acceptance criteria.

State explicitly what Codex inspected and what remained unavailable.

### 2. Reconcile the migration surface

Inventory every `up` and `down` operation and every raw SQL statement.

For each operation, identify:

- migration file and location;
- table or relation;
- columns;
- data types;
- defaults;
- nullability;
- generated values;
- indexes;
- uniqueness rules;
- foreign keys;
- check constraints;
- data transformations;
- application dependencies.

Trace old and new schema names through:

- models;
- casts;
- accessors and mutators;
- validation;
- services;
- queries;
- API resources;
- events and listeners;
- queue payloads;
- scheduled work;
- reports;
- imports and exports;
- factories and seeders;
- tests.

Flag behavior dependent on:

- Laravel version;
- database driver;
- doctrine/dbal;
- database-server version;
- migration configuration;
- transactional DDL support.

Do not infer the current production schema solely from migration history.

### 3. Analyze database-engine behavior

For MySQL or MariaDB, assess the supplied version and operation against applicable:

- instant, in-place, or table-copy behavior;
- metadata-lock acquisition;
- index-build concurrency;
- implicit commits;
- foreign-key checks;
- generated-column behavior;
- default-expression support;
- row format;
- online-DDL options;
- replica effects.

Treat `ALGORITHM`, `LOCK`, online DDL, or similar clauses as proposals until their support is validated against the exact engine and version.

Identify long transactions that could delay metadata locks.

For PostgreSQL, assess:

- catalog-only versus table-rewrite behavior;
- required lock level and likely duration;
- transaction boundaries;
- `CREATE INDEX CONCURRENTLY`;
- `DROP INDEX CONCURRENTLY`;
- invalid indexes after failure;
- `NOT VALID` constraints;
- later constraint validation;
- default-value behavior;
- type-change rewrites;
- long-running transactions;
- dead tuples;
- WAL growth;
- replica lag.

Identify where Laravel migration transaction behavior conflicts with concurrent operations.

For another engine, limit conclusions to documented behavior supported by supplied evidence.

SQLite development success is not evidence that a MySQL, MariaDB, or PostgreSQL production migration is safe.

Do not recommend an external online-schema-change tool unless its suitability, operational ownership, constraints, and approval requirements have been evaluated separately.

### 4. Analyze operation-specific failure modes

If this is a prospective review, analyze credible migration failure modes without pretending a failure has already occurred.

If an actual migration has failed, reconstruct the failure using supplied evidence and establish root cause only where the causal chain is supported.

Check for:

- non-null additions before compatible writes and backfill completion;
- expensive defaults or table rewrites;
- in-place type changes;
- truncation;
- collation or encoding changes;
- lossy casts;
- renames or drops while old code still uses the schema;
- unique indexes before duplicate and null-semantics checks;
- foreign keys before orphan and supporting-index review;
- cascade effects;
- indexes that do not match observed query predicates or ordering;
- blocked writes;
- metadata-lock queues;
- statement or lock timeouts;
- disk or temporary-space pressure;
- transaction-log or WAL growth;
- replica lag;
- failover exposure;
- schema and data changes combined into one irreversible unit;
- unbounded updates;
- offset-based backfills;
- mutable pagination keys;
- hot-row contention;
- retries that duplicate effects;
- queue flooding;
- `down` methods that destroy data or restore structure without restoring meaning;
- migration ordering and timestamp collisions;
- environment-dependent migrations;
- non-idempotent raw SQL;
- mixed-version incompatibility.

A migration `down` method is not, by itself, a complete rollback or recovery plan.

### 5. Evaluate mixed-version compatibility

Determine whether old and new application versions can coexist with the intermediate schema.

Include:

- web processes;
- API processes;
- queue workers;
- delayed jobs;
- scheduled commands;
- reports;
- exports;
- integrations;
- external consumers.

Check:

- reads from old and new columns;
- writes to old and new columns;
- dual-write behavior;
- default and null handling;
- serialized queue payloads;
- cache-key or serialization changes;
- deployment and worker restart order;
- feature-flag ownership and defaults.

Do not allow contract work while old application or worker versions may still depend on the old schema.

### 6. Determine the compatible release sequence

For every risky change, decide whether it requires:

1. expand;
2. compatibility code;
3. dual write;
4. backfill;
5. reconciliation;
6. read switch;
7. constraint validation;
8. contract;
9. cleanup.

For every phase, define:

- compatible application versions;
- compatible worker versions;
- required entry evidence;
- proposed action;
- monitoring signals;
- pause conditions;
- acceptance criteria;
- recovery path;
- approval gate.

Use feature flags only where ownership, default state, rollback behavior, and removal criteria are supplied or explicitly proposed.

### 7. Design a controlled backfill

Do not place a large backfill inside a schema migration.

When a backfill is required, specify:

- a versioned Artisan command, controlled job, or reviewed script;
- stable keyset batching;
- candidate batch-size range;
- staging calibration method;
- transaction scope;
- idempotency predicate or key;
- throttling signal;
- checkpointing;
- progress metrics;
- retry behavior;
- pause and resume behavior;
- failed-record quarantine;
- observability;
- termination criteria.

Base numerical recommendations on supplied measurements. Otherwise mark them for calibration.

Define reconciliation using:

- candidate count;
- processed count;
- success count;
- skipped count;
- failure count;
- remaining count;
- invariant checks.

Unexplained differences must block progression.

### 8. Design rollback and forward recovery

Separate:

- application rollback;
- schema rollback;
- backfill pause;
- backfill reversal;
- data restoration;
- forward-compatible recovery.

Prefer forward recovery when:

- a destructive `down` method would lose data;
- old code cannot operate against the new schema;
- a partial backfill has changed business meaning;
- contract work has already removed compatibility.

Identify:

- the last reversible phase;
- failure indicators;
- immediate safe response;
- data-loss exposure;
- backup dependencies;
- restore dependencies;
- partial-failure handling;
- approval gates;
- evidence required before resuming.

A backup claim is insufficient without evidence of:

- scope;
- freshness;
- retention;
- encryption handling;
- access;
- restore testing appropriate to the change.

### 9. Define verification and acceptance evidence

Propose repository-appropriate checks. Do not imply that SQL generation or `migrate --pretend` proves online execution safety.

Where applicable, include:

- migration-operation reconciliation;
- production-schema reconciliation;
- generated-SQL review;
- engine-supported DDL validation;
- duplicate checks;
- orphan checks;
- null and range checks;
- truncation and cast-failure checks;
- representative query plans;
- old-version application tests;
- mixed-version tests;
- new-version tests;
- queue-worker compatibility tests;
- production-like rehearsal;
- lock-wait observations;
- blocked-session observations;
- disk and temporary-space observations;
- transaction-log or WAL growth;
- replica-lag observations;
- backfill reconciliation;
- post-phase schema and data checks;
- rollback or forward-recovery rehearsal.

For every proposed command or query, state:

- purpose;
- target environment;
- expected observation;
- failure meaning;
- safety caveat;
- work state: proposed, executed, supplied, unavailable, or unverified.

Avoid production-wide scans unless an authorized operator confirms:

- acceptable execution plan;
- timeout;
- replica or primary target;
- impact window;
- cancellation method.

## Risk classification

Use only these qualitative states:

- Critical — credible risk of data loss, corruption, prolonged outage, irreversible change, uncontrolled production impact, or a release state from which neither old nor new code can recover safely.

- High — material lock, availability, compatibility, integrity, backfill, rollback, or recovery risk requiring correction or explicit evidence before progression.

- Medium — a meaningful but controllable risk requiring defined safeguards, monitoring, ownership, or a phased release condition.

- Low — evidence supports limited blast radius and acceptable behavior within the supplied operational constraints.

- Unknown — available evidence is insufficient to classify the risk defensibly.

Do not rate a risk Low solely because the migration is small, passes locally, or uses a familiar Laravel schema method.

## Output contract: zero-downtime migration review deliverable

Keep the report concise and proportional to the migration scope, risk, and available evidence.

Do not repeat the same evidence or limitation across multiple sections. Use operation IDs, finding IDs, and evidence IDs for cross-reference.

Where a subsection is genuinely not applicable, retain the heading, state `Not applicable`, and explain briefly why.

Never omit:

- evidence and coverage;
- schema-operation register;
- blockers;
- compatibility analysis;
- recovery;
- verification;
- release decision.

### A. Review basis and evidence coverage

Report:

- exact release identity;
- target environment;
- database engine and version;
- migration files and related code inspected;
- unavailable materials;
- supplied, observed, missing, ambiguous, and conflicting inputs;
- zero-downtime acceptance definition;
- review limitations.

### B. Schema-operation register

For every operation provide:

- operation ID;
- migration and location;
- generated or intended DDL;
- affected object;
- data touch;
- engine and version dependency;
- expected lock or rewrite behavior;
- rolling-code compatibility;
- reversibility;
- supporting evidence;
- risk state.

### C. Blocking findings and risk register

For every material finding provide:

- finding ID;
- operation or release phase;
- failure scenario;
- triggering condition;
- impact;
- risk state;
- supporting evidence;
- uncertainty;
- minimum risk-reducing change;
- required owner;
- closure evidence.

Treat these as blockers until resolved:

- unknown engine-specific lock or rewrite behavior for a material operation;
- unreconciled production-schema drift;
- unbounded backfills;
- destructive changes without recovery;
- incompatible mixed-version operation;
- missing required acceptance evidence.

### D. Compatible phased migration design

Provide the ordered release plan.

For each phase state:

- migration or code change;
- compatible application and worker versions;
- entry evidence;
- proposed action;
- monitoring signals;
- pause thresholds;
- acceptance criteria;
- rollback or forward-recovery path;
- approval gate.

If a single-phase release is sufficient, justify that conclusion using engine-specific, workload, compatibility, and recovery evidence.

### E. Backfill control sheet

State:

- selection predicate;
- stable cursor;
- batching method;
- calibration method;
- idempotency behavior;
- transaction boundary;
- throttle and pause signals;
- retry handling;
- checkpoint storage;
- progress metrics;
- reconciliation equations;
- anomaly handling;
- completion criteria;
- read-switch and contract prerequisites.

If no backfill is required, state `Not applicable` and explain why.

### F. Mixed-version compatibility record

Report compatibility for:

- old application with expanded schema;
- new application with intermediate schema;
- queue workers and delayed jobs;
- scheduled commands;
- APIs and integrations;
- caches and serialized data;
- feature flags;
- contract and cleanup timing.

Identify the last point at which old code remains safe.

### G. Recovery matrix

Cover failure:

- before DDL;
- during DDL;
- after schema expansion;
- during backfill;
- after read switch;
- during contract;
- after application rollback.

For each case state:

- observable symptoms;
- immediate safe response;
- approval-required action;
- data-loss exposure;
- recovery evidence;
- whether old and new code remain operable.

### H. Verification runbook

List commands, SQL, tests, and observations in release order.

For each item provide:

- check ID;
- purpose;
- target environment;
- command or method;
- expected result;
- actual supplied or observed result;
- evidence;
- safety limit;
- status: proposed, executed, supplied, unavailable, or unverified;
- acceptance result: pass, fail, investigate, or not assessed.

Never fabricate command output.

### I. Release decision record

Choose exactly one status:

- Ready for authorized rehearsal
- Ready for authorized phased production rollout
- Changes required
- Blocked by missing evidence
- Unsafe as proposed

State:

- zero-downtime feasibility;
- highest residual risks;
- required changes;
- unresolved assumptions;
- required human approvals;
- next evidence-producing action.

Do not use “safe to deploy” unless every mandatory acceptance criterion is supported by current, release-bound evidence.

## Final quality gate

Before returning the report, verify that:

1. Every migration operation is accounted for.
2. The reviewed evidence is bound to the exact release where possible.
3. Production schema drift is reconciled or explicitly blocking.
4. Database-engine and version dependencies are addressed.
5. Lock, rewrite, index, constraint, and transaction behavior are assessed.
6. Mixed-version application and worker compatibility is evaluated.
7. Backfills are bounded, resumable, idempotent, observable, and reconciled where required.
8. Rollback and forward-recovery paths are distinguished.
9. Proposed commands include expected observations and safety limits.
10. Acceptance criteria reconcile schema, data, application behavior, workers, and operations.
11. Zero-downtime feasibility is tied to supplied service constraints.
12. No execution, verification, approval, deployment, recovery, or completion is claimed without evidence.