Quickstart

You need an API key to authenticate requests. All examples use the X-API-Key header.

Register a database connection

Send a POST request to register your database. Save the id from the response — you will use it in every subsequent call.

curl -X POST https://api.autodb.app/api/v1/connections \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "name": "Production Analytics DB",
    "db_type": "supabase",
    "connection_string": "postgresql://app_user:***@db.example.supabase.co:5432/analytics"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Analytics DB",
    "db_type": "supabase",
    "host": "db.example.supabase.co",
    "port": 5432,
    "database_name": "analytics",
    "is_active": true,
    "created_at": "2024-01-15T09:30:00Z",
    "last_introspected_at": null
  },
  "error": null
}

Note that last_introspected_at is null — AutoDB has not yet scanned this database’s schema.

Introspect your schema

Before analyzing migrations, AutoDB needs a snapshot of your current schema. Trigger an introspection using the connection_id from above:

curl -X POST https://api.autodb.app/api/v1/connections/550e8400-e29b-41d4-a716-446655440000/introspect \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "connection_id": "550e8400-e29b-41d4-a716-446655440000",
    "table_count": 12,
    "tables": [
      "customers",
      "order_items",
      "orders",
      "products"
    ],
    "snapshot_id": "660e8400-e29b-41d4-a716-446655440001",
    "introspected_at": "2024-01-15T10:00:00Z"
  },
  "error": null
}

AutoDB discovered 12 tables and created a schema snapshot. You are now ready to analyze migrations against this schema.

Submit a migration for analysis

Submit your SQL migration to get a risk assessment, blast radius analysis, and rollback plan.

curl -X POST https://api.autodb.app/api/v1/connections/550e8400-e29b-41d4-a716-446655440000/migrations/analyze \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "sql": "ALTER TABLE orders ADD COLUMN priority VARCHAR(20) DEFAULT '\''normal'\'';\nCREATE INDEX CONCURRENTLY idx_orders_priority ON orders(priority);"
  }'

Response (key fields shown):

{
  "success": true,
  "data": {
    "risk_score": 35,
    "risk_category": "medium",
    "total_statements": 1,
    "affected_tables": [
      {
        "table": "orders",
        "impact": "direct",
        "cascade_path": null
      },
      {
        "table": "order_items",
        "impact": "cascade",
        "cascade_path": ["orders", "order_items"]
      }
      // ...
    ],
    "sandbox_result": {
      "passed": true,
      "migration_applied": true,
      "tables_created": 8,
      "duration_ms": 4500
      // ...
    },
    "rollback_plan": {
      "has_irreversible": false,
      "combined_script": "BEGIN;\nALTER TABLE orders DROP COLUMN priority;\nCOMMIT;"
      // ...
    },
    "approval_token": "eyJzcWwiOi4uLn0.a1b2c3d4"
    // ...
  },
  "error": null
}

Review the risk report

The analysis response contains everything you need to decide whether to proceed with the migration.

Risk score and category

The risk_score (0—100) and risk_category summarize overall migration risk. The score combines lock severity and duration, destructive operation penalties, and FK cascade blast radius:

Category	Score Range	Meaning
`low`	0—24	Short locks, no data loss risk, limited blast radius
`medium`	25—49	Moderate lock impact or FK cascade depth
`high`	50—74	Destructive operations or wide FK blast radius
`critical`	75—100	Destructive changes with extensive cascade impact

In our example, a risk_score of 35 (medium) indicates moderate lock impact from the schema change without destructive operations.

Sandbox validation

The sandbox_result field shows what happened when AutoDB ran your migration in an ephemeral Postgres clone:

passed: true — the migration applied successfully without errors
migration_applied: true — all statements executed
tables_created: 8 — the sandbox seeded 8 tables from your schema snapshot
duration_ms: 4500 — total sandbox execution time

If passed is false, the migration has a syntax error or violates a constraint. Fix it before proceeding.

Affected tables

Each entry in affected_tables shows which tables the migration touches:

direct — the statement explicitly modifies this table (e.g., ALTER TABLE orders)
cascade — the table is impacted through foreign key relationships (e.g., order_items depends on orders via FK)

The cascade_path field traces the FK chain from the directly affected table to the cascade target.

Rollback plan

has_irreversible: false — every statement in this migration can be automatically reversed
combined_script — a transaction-wrapped SQL script that undoes the entire migration

If has_irreversible is true, at least one statement cannot be automatically rolled back (e.g., DROP COLUMN with data loss). Review the per-statement rollback steps for details.

Approval token

The approval_token is an HMAC-signed token that authorizes execution of this specific migration. To apply the migration to your production database, submit it to POST /api/v1/migrations/execute along with the original SQL and connection ID.

Next steps

Full API Reference: Analyze See complete request and response schema for migration analysis

Ready to execute? See the Migration Execution reference for the approval token flow.