Migrations

EdgeDB's baked-in migration system lets you painlessly evolve your schema throughout the development process.

Whereas other migration tools redundantly store copies of your schema in opaque files or create additional tables to track migration history, every EdgeDB instance automatically tracks its own migration history in a fully introspectable way. Plus, all migration logic is generated by the database instance itself.

Features

01
Declarative

Your database schema is defined in a .esdl file using EdgeDB's readable, elegant schema definition language. This file is the single source of truth for your schema; just update it directly as your application evolves. EdgeDB's migration system handles the rest.

02
Database-native

When you create a migration with EdgeDB, the migration logic is generated by your database. The CLI simply sends your schema (as defined in your .esdl file) to your EdgeDB instance, which compares it against its current internal schema state, detects any changes, and generates a migration plan.

03
Interactive and inspectable

The process of creating a migration is a conversation between you and your database. Each detected schema change is presented to you for approval, so you know exactly what the migration will do. Plus, you'll be automatically prompted to resolve any ambiguities, like specifying the default value for a new required property.

04
Deterministic

The same series of migrations will always produce the same final schema when applied to a database. By sharing a common migration history among your development, staging, and production databases, you can apply migrations with confidence.

05
CI/CD Friendly

After generating a set of migrations against your development database, you can confidently apply those migrations to your staging and production instances in your continuous integration pipeline. The edgedb migrate command is is fully idempotent; previously-applied migrations won’t be applied again, so it’s safe to run this command in automated workflows.

06
Non-duplicative

Other migration tools redundantly store snapshots of your schema in migration files or create extra tables in your database to track migrations. Not EdgeDB. EdgeDB instances automatically track their own migration history in a fully introspectable way, avoiding thorny schema drift issues common with other tools.

Workflow

schema.esdl
migrations/0001.edgeql
1 2 3 4 5 6 7 8
module default { type User { required username: str; } }
1 2 3 4 5 6 7 8
CREATE MIGRATION m1kdtk6ze2irotrxzscsr5hmt55zxv... { ALTER TYPE default::User { CREATE REQUIRED PROPERTY email -> std::str { SET REQUIRED USING ('example@example.com'); }; }; };
$ 

And now step by step

/01
Update your schema file

In EdgeDB, your application schema is declaratively defined using EdgeDB's SDL. To learn more about schemas modeling in EdgeDB, check out the Data Modeling showcase page.

Copy
type User {
  required name: str;
}

type Post {
  required title: str;
  required author: User;
}

By convention, this schema lives inside of .esdl files inside the dbschema directory of your project. You can keep your entire schema in one file (typically default.esdl) or split it across several files. The EdgeDB CLI will automatically deep-merge all declarations. Directly modify these files as your application schema develops.

Copy
 type User {
   required name: str;
 }

 type BlogPost {
 type Post {
   required title: str;
   title: str;

   required upvotes: int64;

   required author: User;
 }

  type Comment {
    required content: str;
  }
/02
Generate a migration

To modify your schema, make a change to your schema file and run edgedb migration create.

Your schema files will be sent to the development database, which will compare the files to its current schema state and determine a migration plan. This plan is then presented to you interactively; every detected schema change will be individually presented to you for approval:

Copy
$ 
edgedb migration create
Did you rename object type 'default::BlogPost' to
'default::Post'? [y,n,l,c,b,s,q,?]
>y

Did you create object type 'default::Comment'?
[y,n,l,c,b,s,q,?]
>y

Did you make property 'title' of object type
'default::Post' optional? [y,n,l,c,b,s,q,?]
>y

Did you create property 'upvotes' of object type
'default::Post'? [y,n,l,c,b,s,q,?]
>y

Please specify an expression to populate existing
objects in order to make property 'upvotes' of
object type 'default::Post' required:
fill_expr> 0
Created ./dbschema/migrations/00002.edgeql,
id: m16f7cbc...

As you can see, you are presented with an exhaustive list of the detected schema changes. This is a useful sanity check, and it provides a level of visibility into the migration process that is sorely lacking from most migration tools.

For each of these prompts, you have a variety of commands at your disposal. Type ? into the prompt for an explanation of these options.

Copy
$ 
edgedb migration create
Did you create property X...? [y,n,l,c,b,s,q,?]
>?

y - confirm the prompt, use the DDL statements
n - reject the prompt
l - list the DDL statements associated with prompt
c - list already confirmed EdgeQL statements
b - revert back to previous save point, perhaps previous question
s - stop and save changes (splits migration into multiple)
q - quit without saving changes
h or ? - print help

The process of creating migrations is truly interactive. You can go back to previous prompts, split the schema changes into several individual migrations, or inspect the associated DDL commands (e.g. CREATE TYPE, etc).

Remember, migration create simply generates a migration script, it doesn't apply it! So you can safely quit at any time with q orCtrl/Cmd-C without worrying about leaving your schema in an inconsistent state.

Once you’ve completed the prompts, the CLI will generate a.edgeql file representing the migration inside your dbschema/migrations directory.

/03
Apply the migration

Just run edgedb migrate to apply all unapplied migrations.

Copy
$ 
edgedb migrate
Applied m1virjowa... (00001.edgeql)

That's it! Now you know how to migrate an EdgeDB schema. To learn how migrations work in greater detail, check out the CLI reference, the original RFC, or the Beta 1 release post, which describes the design of the migration system.