Skip to main content
Pro plan required. Migrations are versioned changes to your database schema — adding tables, creating columns, setting up indexes, defining RLS policies, and more. They give you a structured history of how your database has evolved.

​
How Migrations Work

When you ask the AI to change your database through chat, it doesn’t modify the schema directly. Instead, it creates a migration file containing the SQL needed to make the change.
ConceptWhat It Means
Migration fileA SQL file that describes a specific schema change
Up directionThe SQL that applies the change (e.g., create a table)
Down directionConceptually, the SQL that would undo the change (e.g., drop the table)
AppliedThe migration has been run against your database
PendingThe migration exists but hasn’t been applied yet
Migrations are applied in order. Each one builds on the last, so your database schema is the result of every migration that’s been applied from first to most recent.

​
Why Migrations Instead of Direct Changes?

Migrations give you:
  • A history of every schema change
  • Reproducibility — you can recreate the database from scratch by running all migrations in order
  • Visibility — you can see exactly what SQL will run before it runs
  • Safety — changes are explicit and reviewable, not hidden

​
Viewing Migrations

The Migrations view in the Database tab shows you all migrations for your project:
  • Pending migrations — Created by the AI but not yet applied to your database
  • Applied migrations — Already run against your database
  • Migration SQL — Click any migration to see the exact SQL it contains
  • Status indicators — Quickly see which migrations are pending and which are applied
  • Timestamps — See when each migration was created and when it was applied
This gives you full transparency into what the AI is doing to your database.

​
Applying Migrations

When the AI creates a migration, it appears as pending. To apply it:
1

Review the migration SQL

Click the pending migration to see the exact SQL it will execute. Make sure it matches what you expect.
2

Apply the migration

Click to apply the pending migration. The SQL executes against your Supabase database.
3

Check the result

Results show success or detailed error information. If it succeeds, the migration is marked as applied.
You can apply migrations one at a time, giving you control over when each change takes effect.

​
What Happens When You Apply

The migration SQL executes against your live Supabase database. If it succeeds, the migration is marked as applied. If it fails, you get an error message explaining what went wrong, and the migration stays pending so you can address the issue.

​
Common Migration Operations

Here are the kinds of schema changes that generate migrations:

​
Creating a New Table

CREATE TABLE posts (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  title text NOT NULL,
  body text,
  author_id uuid REFERENCES users(id),
  created_at timestamptz DEFAULT now()
);

​
Adding a Column

ALTER TABLE posts ADD COLUMN status text DEFAULT 'draft';

​
Creating an Index

CREATE INDEX idx_posts_author ON posts(author_id);

​
Enabling Row Level Security

ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can read all posts" ON posts
  FOR SELECT USING (true);

CREATE POLICY "Users can create their own posts" ON posts
  FOR INSERT WITH CHECK (auth.uid() = author_id);

​
Adding a Foreign Key

ALTER TABLE comments
  ADD COLUMN post_id uuid REFERENCES posts(id) ON DELETE CASCADE;
If a migration fails, read the error message carefully. Common issues: duplicate column names, missing foreign key references, or RLS policy conflicts.

​
Migration Best Practices

Follow these patterns to keep your database changes clean:
  • Let the AI generate migrations — You rarely need to write them manually. Describe what you want in chat and let the AI create the migration.
  • Review before applying — Always look at the SQL before applying. Make sure it does what you expect.
  • Apply in order — If you have multiple pending migrations, apply them in the order they were created. Later migrations may depend on earlier ones.
  • One change per migration — Each migration should do one logical thing. Adding a table is one migration. Adding RLS policies to that table is another. This keeps things easy to understand and debug.

​
Troubleshooting Failed Migrations

The migration tries to create something that already exists. This can happen if you manually created a table or column outside of migrations. Ask the AI to check the current schema before generating new migrations.
The migration references a table or column that doesn’t exist yet. This usually means migrations are being applied out of order, or a prerequisite migration failed. Check the migration order and apply any earlier pending migrations first.
A policy with the same name already exists on the table. Policy names must be unique per table. Ask the AI to use a different policy name, or drop the existing policy first.
Your Supabase API key might not have the right permissions for schema changes. Make sure you’re using the service role key for migration operations.
The AI occasionally generates SQL with minor syntax issues. Copy the SQL from the migration, paste it into the SQL Editor, fix the syntax, and run it manually. Then ask the AI to regenerate the migration with the correction.
Migrations are generated by the AI when you ask for database changes through chat. You rarely need to write them manually.

Database Overview

Learn about all the database management tools available in Nativeline.

SQL Editor

Write and execute SQL queries directly against your database.