Database
Schema & Migration

Schemas & Migrations

This document outlines the process of managing database schemas and migrations using the Supabase CLI. Schemas define the structure of your database, while migrations allow you to version control and manage changes to your database schema over time.

💡

Check out the official Supabase CLI documentation (opens in a new tab) on migrations, schema management, and seeding.

Supabase CLI

We use the Supabase CLI to manage our database schemas and migrations. The CLI provides a set of commands to create, apply, and manage database migrations.

Project Structure

      • 20230801120000_initial_schema.sql - Example Schema Definition
    • seed.sql - Database Seed Data
  • Running Example Migrations and Seed

    To run the example migrations and seed data:

    supabase db reset

    This command resets your database, applies all migrations, and runs the seed.sql file.

    Key Commands

    • Create a new migration:
    supabase migration new <migration_name>
    • Apply migrations:
    supabase db push
    • Reset database and reapply all migrations:
    supabase db reset
    • Check migration status:
    supabase db status

    Local vs. Linked Project Operations

    By default, commands operate on your local development database. For linked remote projects, you need to authenticate and link your project first, then use the --linked flag.

    Prerequisites for Linked Projects

    For fresh projects working with remote Supabase projects, you must complete these steps first:

    npx supabase login
    npx supabase link

    Working with Linked Projects

    Once authenticated and linked, you can use the --linked flag with database commands:

    npx supabase db push --linked
    npx supabase db reset --linked
    npx supabase db status --linked

    Complete Setup for Fresh Projects

    For a fresh project, the complete sequence is:

    npx supabase login
    npx supabase link
    npx supabase db reset --linked

    Remember to exercise caution when operating on remote databases, especially in production environments.