Migrations

A migration is a named SQL block that PerSQL applies to your database exactly once, inside a single transaction. Drafts are editable; applied migrations are immutable.

Find them under each database’s Migrations tab in the console.

Lifecycle

1. Draft — appliedAt = null. Edit the name and SQL freely.
2. Apply — PerSQL captures a bookmark immediately before running the SQL, then runs it inside one DO transaction (transactionSync). On failure, the transaction rolls back and the draft stays a draft so you can fix and retry.
3. Applied — appliedAt is stamped, the SQL is frozen, and the pre-apply bookmark is kept on the row. To roll back, restore the database to that bookmark via the Backups tab.

Deleting an applied migration only removes the row from the listing — the schema change is already in your database.

Permissions

• Read & write drafts: namespace writers (database editors).
• Apply: namespace owner / admin only — applying is destructive.

REST

Method	Path
GET	/api/namespaces/:ns/databases/:db/migrations
POST	/api/namespaces/:ns/databases/:db/migrations
PATCH	/api/namespaces/:ns/databases/:db/migrations/:id
DELETE	/api/namespaces/:ns/databases/:db/migrations/:id
POST	/api/namespaces/:ns/databases/:db/migrations/:id/apply

POST/PATCH body:

{ "name": "add-orders-index", "sql": "CREATE INDEX idx_orders_customer ON orders(customer_id);" }

name is 1–80 chars; sql is up to 50 000.

Tips

• Wrap multiple statements in a single migration — the DO already runs the whole block in one transaction, so you don’t need explicit BEGIN / COMMIT.
• Pair big migrations with a manual snapshot in the Backups tab so you have a labeled checkpoint, not just an opaque bookmark.