Migrations

This section describes the DDL commands pertaining to migrations.

Like all DDL commands, start migration and other migration commands are considered low-level. Users are encouraged to use the built-in migration tools instead.

Start migration

Start a migration block.

  1. start migration to "{"
  2.     sdl-declaration ;
  3.     [ ... ]
  4. "}" ;

Parameters

sdl-declaration

Complete schema defined with the declarative EdgeDB schema definition language.

Description

The command start migration defines a migration of the schema to a new state. The target schema state is described using SDL and describes the entire schema. This is important to remember when creating a migration to add a few more things to an existing schema as all the existing schema objects and the new ones must be included in the start migration command. Objects that aren’t included in the command will be removed from the new schema (which may result in data loss).

This command also starts a transaction block if not inside a transaction already.

While inside a migration block, all issued EdgeQL statements are not executed immediately and are instead recorded to be part of the migration script. Aside from normal EdgeQL commands the following special migration commands are available:

  • describe current migration – return a list of statements currently recorded as part of the migration;

  • populate migration – auto-populate the migration with system-generated DDL statements to achieve the target schema state;

  • abort migration – abort the migration block and discard the migration;

  • commit migration – commit the migration by executing the migration script statements and recording the migration into the system migration log.

Examples

Create a new migration to a target schema specified by the EdgeDB Schema syntax:

  1. start migration to {
  2.     module default {
  3.         type User {
  4.             property username -> str;
  5.         };
  6.     };
  7. };

create migration

Create a new migration using an explicit EdgeQL script.

  1. create migration "{"
  2.     edgeql-statement ;
  3.     [ ... ]
  4. "}" ;

Parameters

edgeql-statement

Any valid EdgeQL statement, except database, role, configure, migration, or transaction statements.

Description

The command create migration executes all the nested EdgeQL commands and records the migration into the system migration log.

Examples

Create a new migration to a target schema specified by the EdgeDB Schema syntax:

  1. create migration {
  2.     create type default::User {
  3.         create property username -> str;
  4.     }
  5. };

Abort migration

Abort the current migration block and discard the migration.

  1. abort migration ;

Description

The command abort migration is used to abort a migration block started by start migration. Issuing abort migration outside of a migration block is an error.

Examples

Start a migration block and then abort it:

  1. start migration to {
  2.     module default {
  3.         type User;
  4.     };
  5. };
  7. abort migration;

Populate migration

Populate the current migration with system-generated statements.

  1. populate migration ;

Description

The command populate migration is used within a migration block started by start migration to automatically fill the migration with system-generated statements to achieve the desired target schema state. If the system is unable to automatically find a satisfactory sequence of statements to perform the migration, an error is returned. Issuing populate migration outside of a migration block is also an error.

The statements generated by populate migration may drop schema objects, which may result in data loss. Make sure to inspect the generated migration using describe current migration before running commit migration!

Examples

Start a migration block and populate it with auto-generated statements.

  1. start migration to {
  2.     module default {
  3.         type User;
  4.     };
  5. };
  7. populate migration;

Describe current migration

Describe the migration in the current migration block.

  1. describe current migration [ as {ddl | json} ];

Description

The command describe current migration generates a description of the migration in the current migration block in the specified output format:

as ddl

Show a sequence of statements currently recorded as part of the migration using valid DDL syntax. The output will indicate if the current migration is fully defined, i.e. the recorded statements bring the schema to the state specified by start migration.

as json

Provide a machine-readable description of the migration using the following JSON format:

  1. {
  2.   // Name of the parent migration
  3.   "parent": "<parent-migraiton-name>",
  5.   // Whether the confirmed DDL makes the migration complete,
  6.   // i.e. there are no more statements to issue.
  7.   "complete": {true|false},
  9.   // List of confirmed migration statements
  10.   "confirmed": [
  11.     "<stmt text>",
  12.     ...
  13.   ],
  15.   // The variants of the next statement
  16.   // suggested by the system to advance
  17.   // the migration script.
  18.   "proposed": {
  19.     "statements": [{
  20.       "text": "<stmt text template>"
  21.     }],
  22.     "required-user-input": [
  23.       {
  24.         "placeholder": "<placeholder variable>",
  25.         "prompt": "<statement prompt>",
  26.       },
  27.       ...
  28.     ],
  29.     "confidence": (0..1), // confidence coefficient
  30.     "prompt": "<operation prompt>",
  31.     "prompt_id": "<prompt id>",
  32.     // Whether the operation is considered to be non-destructive.
  33.     "data_safe": {true|false}
  34.   }
  35. }

Where:

  • <stmt text>

    Regular statement text.

    <stmt text template>

    Statement text template with interpolation points using the \(name) syntax.

    <placeholder variable>

    The name of an interpolation variable in the statement text template for which the user prompt is given.

    <statement prompt>

    The text of a user prompt for an interpolation variable.

    <operation prompt>

    Prompt for the proposed migration step.

    <prompt id>

    An opaque string identifier for a particular operation prompt. The client should not repeat prompts with the same prompt id.

Commit migration

Commit the current migration to the database.

  1. commit migration ;

Description

The command commit migration executes all the commands defined by the current migration and records the migration as the most recent migration in the database.

Issuing commit migration outside of a migration block initiated by start migration is an error.

Example

Create and execute the current migration:

  1. commit migration;