Database and migrations

Connecting your database makes Dev and your agents schema-aware: they write SQL, migrations and backend code against your real tables and columns instead of guessing them. DevSpec also watches the migration files you commit and tells you which ones have reached each database.

DevSpec works with Supabase databases. You connect one in Project settings → Integrations → Databases, or from Connect a database on a project's Project setup page. Connecting a database is optional.

Why connect your database

With a database connected:

• Dev can look up your tables, columns, relationships, functions and row-level security policies when you ask about data, queries or a migration, and answers from what's really there.
• Dev can report Supabase's security and performance advisors for your database, so you can ask "is anything misconfigured?".
• Your agents can read the same schema from DevSpec while they work.
• The Migrations page shows which committed migrations have been applied to each database, so a missing migration doesn't surprise you after a deploy.

A project can have several databases, for example staging and production.

Connect a Supabase database

Project Maintainers connect databases.

1. Open Project settings → Integrations → Databases and click Connect database.
2. Fill in the form:
   • Database type: Supabase.
   • Connection name: a label for you, such as "Staging" or "Production DB". It doesn't need to match anything in Supabase.
   • Environment: Staging or Production. DevSpec strongly recommends starting with a staging database while you evaluate it.
   • Project ID: your Supabase project's ID, found in Supabase under Settings → General → Project ID. The Open in Supabase link takes you there.
   • Personal Access Token: a Supabase access token, which starts with sbp_. Create one in the Supabase dashboard under your avatar (top right) → Account → Access Tokens, or use the Generate a token link. Read "Give DevSpec the least access" below before you create it.
   • Deploys from branch: the git branch whose changes deploy to this database, such as staging for a staging database and main for production. Choose All branches if everything deploys to one database. This drives migration tracking.
3. Click Test connection. When it says Connection verified, click Connect database. The button stays disabled until the test passes, so broken credentials can't be saved.

DevSpec reads your schema straight away. The connection card shows Syncing..., then Synced with the time.

Give DevSpec the least access

DevSpec only ever reads your database. But a Supabase personal access token can't be limited to read-only: it carries the full access of the Supabase account that creates it.

For the least exposure:

• Create the token from a dedicated Supabase account that has access to only this Supabase project.
• Set an expiry on the token.
• Start with a staging database while you evaluate DevSpec.

When you disconnect a database, delete its token in Supabase too.

What DevSpec reads from your database

DevSpec reads the structure of your database's public schema, never its contents:

• tables and columns, with their types and defaults
• relationships (foreign keys), indexes and enums
• functions and triggers
• row-level security policies
• approximate row counts, from Postgres's own statistics

It also reads:

• your migration history, the record of which migrations have been applied, so the Migrations page can show what's applied
• Supabase's security and performance advisors and your installed extensions

DevSpec never reads your application data and never writes to your database.

Dev reads the schema when a conversation needs it, and every member of the project can ask Dev about it. Your agents can read it too.

Keep the schema up to date

DevSpec keeps your schema up to date automatically as tracked migrations are applied and through regular background syncs.

To re-read it now, a Maintainer clicks Re-sync schema (the refresh icon) on the database's card in Project settings → Integrations → Databases. The card shows when the schema was last synced. While a database is syncing, the session header shows Indexing... with a tooltip naming the database and noting "Responses may have incomplete context".

Track migrations on the Migrations page

The Migrations page, under Ship → Migrations in the project sidebar, lists the SQL migration files (.sql) committed to your tracked repositories and whether each has been applied to each connected database. It needs at least one database connected.

• Scan repository finds migration files already in your repositories. New migrations are picked up as you push.
• Verify Now re-reads your databases and checks every migration that isn't applied yet. It can take up to a minute; statuses update as results arrive.

Each migration shows one of these statuses:

You can filter by status, by database (All databases or one connection) and by date. Click a migration to see what it does, when it was committed, when it was last verified and applied, its commit, and the task it came from. From there you can Verify it on its own, Describe it in plain words, Create task to get it applied, or, for a pending or not-applied migration, Mark as applied or Skip it with a reason.

DevSpec re-checks pending and not-applied migrations periodically in the background, so a migration you apply by hand or from CI shows as applied without you doing anything.

Map each database to a branch

Each connection's Deploys from branch decides which migrations are tracked against it. With a staging database mapped to staging and production mapped to main, a migration pushed to staging is tracked against the staging database, and a migration pushed to main against production. A connection set to All branches tracks migrations from every branch. The connection card shows the branch it tracks.

Disconnect a database or replace its token

To disconnect a database, a Maintainer clicks Disconnect database (the icon on its card in Project settings → Integrations → Databases). Check the database named in the confirmation, then choose Disconnect. Dev stops seeing that database's schema, and DevSpec stops checking migrations against it. Delete the token in Supabase afterwards.

If the token expires or is revoked, the card shows Error with a message such as "Database credentials need re-entering — reconnect the database in DevSpec", and an icon appears in the project header. To fix it, create a new token in Supabase, disconnect the database, and connect it again with the new token.

What a database connection costs

Work around your database is background work, charged to your organization's balance per piece of work. It doesn't count toward anyone's personal allowance, though it does count toward the project's limit if it has one. On Settings → Billing → Transactions it appears as Running your project: making your schema searchable, so Dev can find the right tables for a question, and checking a migration against your schema when the migration history alone can't settle whether it's applied.

When you press Describe on a migration, or Dev looks up your schema during a conversation, that's asking Dev: it appears as Asking Dev and counts toward your personal allowance. While the project is paused, for example because your organization's balance ran out, the background work waits, and catches up once the project starts again. See Billing, usage and limits.