Analyze Migration
Analyze a SQL migration and return a unified response.
Parses the SQL, validates against the schema, identifies blast radius, scores risk, generates rollback DDL, runs sandbox validation, and returns an HMAC-signed approval token for execution. By default, enriches the report with an AI-powered business narrative and impact chains. Use ?enrich=false to skip enrichment.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Query Parameters
Section titled “Query Parameters ”Set to false to skip AI enrichment
Set to false to skip AI enrichment
Request Body required
Section titled “Request Body required ”object
Raw SQL DDL migration text. Can contain multiple statements separated by semicolons.
Responses
Section titled “ Responses ”Successful Response
Response for POST /migrations/analyze (full analysis with enrichment).
object
Whether the request succeeded.
Full analysis response with sandbox results and approval token.
object
ID of the database connection the migration was analyzed against.
Number of SQL statements in the migration.
Aggregate risk score from 0-100 across all statements. Uses the maximum individual statement score for conservative reporting.
Aggregate risk classification. ‘low’ (0-25) = schema-only changes, ‘medium’ (26-50) = data modifications, ‘high’ (51-75) = locking operations, ‘critical’ (76-100) = destructive or high-impact changes.
Per-statement breakdown of the migration. Each entry analyzes one SQL statement’s risk, affected tables, and rollback steps.
object
Zero-based position of this statement in the migration.
The SQL DDL statement being analyzed.
Type of DDL operation. Examples: ‘ALTER TABLE’, ‘CREATE TABLE’, ‘DROP TABLE’, ‘CREATE INDEX’.
Column names explicitly referenced in this statement. Empty for table-level operations (CREATE TABLE, DROP TABLE). Populated for ALTER TABLE column operations.
Risk score from 0-100 for this individual statement. Factors: lock severity, FK cascades, destructive potential, index complexity.
Risk classification derived from score. ‘low’ (0-25) = schema-only changes, ‘medium’ (26-50) = data modifications, ‘high’ (51-75) = locking operations, ‘critical’ (76-100) = destructive or high-impact changes.
Tables affected by this statement, including FK cascade targets.
object
Name of the database table affected by this migration statement.
How this table is affected. ‘direct’ means the statement explicitly modifies it; ‘cascade’ means it is impacted through foreign key relationships.
Columns in this table affected by the statement. Empty list means all columns are affected (table-level operation like DROP TABLE or CREATE TABLE).
Rollback step to reverse this specific statement.
object
Zero-based index of the original migration statement this rollback reverses.
Whether this migration statement can be automatically reversed.
List of warning messages about potential risks or side effects.
Deduplicated list of all tables affected across all statements, including FK cascade targets.
object
Name of the database table affected by this migration statement.
How this table is affected. ‘direct’ means the statement explicitly modifies it; ‘cascade’ means it is impacted through foreign key relationships.
Columns in this table affected by the statement. Empty list means all columns are affected (table-level operation like DROP TABLE or CREATE TABLE).
Complete rollback plan with transaction-wrapped script to reverse the entire migration.
object
Ordered list of rollback steps, one per original migration statement.
object
Zero-based index of the original migration statement this rollback reverses.
Whether this migration statement can be automatically reversed.
True if any migration statement cannot be automatically reversed.
Aggregate warning messages across all statements.
object
Plain-language explanation of the migration’s risk and business impact, generated by the AI narrative engine.
Business processes that may be impacted by the migration, inferred from document context and schema relationships.
References to uploaded documents that informed the narrative. Empty when no relevant documents exist.
object
Name of the source document this citation references.
Relevant text excerpt from the document.
Brief explanation of why this document is relevant to the migration analysis.
True when no RAG documents were available and the narrative was generated from schema metadata alone.
Tree of cascading impacts starting from directly affected tables, through FK cascades, views, and RAG-inferred dependencies.
object
Name of the impacted entity (table, view, or inferred report).
Type of entity. ‘table’ for database tables, ‘view’ for database views, ‘report’ for RAG-inferred business reports.
How this entity is connected to the migration. ‘direct’ = explicitly modified, ‘fk_cascade’ = affected via foreign key, ‘view_reference’ = depends via view definition, ‘rag_inferred’ = inferred from document context.
object
Whether the migration applied successfully and all validation queries passed.
Whether the migration SQL was successfully executed against the sandbox schema.
Number of tables created in the sandbox from the schema snapshot.
Total number of synthetic data rows inserted across all tables.
Results of each validation query run against the post-migration sandbox.
Total sandbox execution time in milliseconds, including schema setup, data generation, migration, and validation.
Zero-based indices of statements that cannot run inside a transaction (e.g., CREATE INDEX CONCURRENTLY). These are executed with AUTOCOMMIT isolation.
Validation Error