Migration Execution

Overview

AutoDB uses a two-step safety model for migration execution. You must analyze a migration first to receive an approval token, then submit that token to execute the migration on production. This prevents accidental execution of unreviewed migrations and ensures every change has been risk-scored, sandbox-tested, and explicitly approved.

The Approval Token

When you analyze a migration, the response includes an approval_token. This token is the key to the safety model:

• HMAC-signed — the token cryptographically encodes the SQL text, connection ID, and a single-use nonce
• Expires after 1 hour — you must execute within the validity window or re-analyze
• Single-use — the nonce is checked against the database to prevent reuse for different migrations. Replaying the same token is idempotent (returns the same request_id)
• Byte-for-byte matching — the sql and connection_id in the execute request must match the values encoded in the token exactly

Tip

If you receive a 400 error when executing, the most common cause is whitespace differences between the SQL you analyzed and the SQL you submitted. Copy the exact sql value from your analyze request.

Execution Flow

1. Analyze the migration

   Submit your SQL to the analyze endpoint to get a risk report and approval token. See Migration Analysis for full details on the response.

   The key field for execution is approval_token in the response.

2. Execute the migration

   Submit the approval token along with the original SQL and connection ID:

   curl -X POST https://api.autodb.app/api/v1/migrations/execute \
     -H "Content-Type: application/json" \
     -H "X-API-Key: YOUR_API_KEY" \
     -d '{
       "approval_token": "eyJzcWwiOiAiQUxURVIgVEFCTEUgb3JkZXJzIC4uLiIsICJjb25uX2lkIjogIjU1MGU4NDAwLi4uIiwgIm5vbmNlIjogImFiYzEyMyIsICJleHAiOiAxNzA1MzEyMDAwfQ.a1b2c3d4e5f6",
       "sql": "ALTER TABLE orders ADD COLUMN priority VARCHAR(20) DEFAULT '\''normal'\'';",
       "connection_id": "550e8400-e29b-41d4-a716-446655440000"
     }'

   The migration starts immediately in the background. The response confirms acceptance:

   {
     "success": true,
     "data": {
       "request_id": "880e8400-e29b-41d4-a716-446655440003",
       "status": "pending"
     },
     "error": null
   }

3. Poll for status

   Use the request_id to check progress:

   curl https://api.autodb.app/api/v1/migrations/requests/880e8400-e29b-41d4-a716-446655440003 \
     -H "X-API-Key: YOUR_API_KEY"

   While the migration is running:

   {
     "request_id": "880e8400-e29b-41d4-a716-446655440003",
     "status": "executing",
     "progress": "Applying migration statements...",
     "result": null,
     "error": null,
     "created_at": "2024-01-15T11:00:00Z",
     "started_at": "2024-01-15T11:00:01Z",
     "completed_at": null
   }

   When the migration completes:

   {
     "request_id": "880e8400-e29b-41d4-a716-446655440003",
     "status": "completed",
     "progress": null,
     "sql": "ALTER TABLE orders ADD COLUMN priority VARCHAR(20) DEFAULT 'normal';",
     "connection_id": "550e8400-e29b-41d4-a716-446655440000",
     "result": {
       "tables_added": [],
       "tables_removed": [],
       "columns_added": [
         { "table": "orders", "column": "priority", "type": "varchar(20)" }
       ],
       "execution_time_ms": 85
     },
     "error": null,
     "created_at": "2024-01-15T11:00:00Z",
     "started_at": "2024-01-15T11:00:01Z",
     "completed_at": "2024-01-15T11:00:02Z"
   }

Error Handling

Status Code	Cause	Resolution
400	SQL or connection_id does not match the token	Resubmit with the exact values from your /analyze request
401	Invalid or expired token	Re-analyze the migration to get a fresh approval token
409	Another migration is already running on this connection	Wait for the current migration to complete, then retry

Caution

A 409 Conflict means a migration is already pending or executing on the same database connection. AutoDB enforces serial execution per connection to prevent conflicting schema changes. Poll the active request’s status until it completes before submitting a new one.

Full API Schema: Execute See complete request and response fields for the execute endpoint

Full API Schema: Request Status See complete response fields for the status polling endpoint