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.
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.
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.
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.
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.
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.
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.
1 2 3 4 5 6 7 8module default { type User { required username: str; } }
1 2 3 4 5 6 7 8CREATE MIGRATION m1kdtk6ze2irotrxzscsr5hmt55zxv... { ALTER TYPE default::User { CREATE REQUIRED PROPERTY email -> std::str { SET REQUIRED USING ('example@example.com'); }; }; };
$ 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.
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.
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;
}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:
$
edgedb migration createDid 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.
$
edgedb migration createDid 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.
Just run edgedb migrate to apply all unapplied migrations.
$
edgedb migrateApplied 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.
