Migrations

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

How it works

The migration plan is generated by the database itself. 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.

Migrations are fully interactive. 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. You’ll be automatically prompted to resolve any ambiguities, like specifying the default value for a new required property.

Migration history is automatically tracked. EdgeDB instances automatically track their own migration history.

Migrations are 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, even in CI/CD pipelines.

Workflow

1. Update your schema file

In EdgeDB, your application schema is declaratively defined using EdgeDB’s schema definition language.

  1. type User {
  2.   required property name -> str;
  3. }
  5. type Post {
  6.   required property title -> str;
  7.   required link author -> User;
  8. }

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 called default.esdl) or split it across several files. The EdgeDB CLI will automatically deep-merge all declarations. Your .esdl file(s) can be directly modified to reflect changes to your schema.

  1. type User {
  2.   required property name -> str;
  3. }
  5. type BlogPost {
  6.   required property title -> str;
  7.   property title -> str;
  9.   property upvotes -> int64;
  11.   required link author -> User;
  12. }
  14. type Comment {
  15.   required property content -> str;
  16. }

2. Generate a migration

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

Your schema file(s) will be sent to the appropriate EdgeDB instance, which will compare the files to the 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:

  1. $
  1. edgedb migration create
  1. Did you create object type 'default::Comment'?
  2. [y,n,l,c,b,s,q,?]
  3. > y
  4. Did you make property 'title' of object type
  5. 'default::BlogPost' optional? [y,n,l,c,b,s,q,?]
  6. > y
  7. Did you create property 'upvotes' of object type
  8. 'default::BlogPost'? [y,n,l,c,b,s,q,?]
  9. > y
  10. Created ./dbschema/migrations/00002.edgeql,
  11. 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.

  1. $
  1. edgedb migration create
  1. Did you create property X...? [y,n,l,c,b,s,q,?]
  2. >?
  4. y - confirm the prompt, use the DDL statements
  5. n - reject the prompt
  6. l - list the DDL statements associated with prompt
  7. c - list already confirmed EdgeQL statements
  8. b - revert back to previous save point, perhaps previous question
  9. s - stop and save changes (splits migration into multiple)
  10. q - quit without saving changes
  11. 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).

Running migration create simply generates a migration script, it doesn’t apply it! So you can safely quit at any time with q or Ctrl/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.

3. Apply the migration

Simply run edgedb migrate to apply all unapplied migrations.

  1. $
  1. edgedb migrate
  1. 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 or the Beta 1 blog post, which describes the design of the migration system.