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 a migration block.
START MIGRATION TO "{"
sdl-declaration ;
[ ... ]
"}" ;
Complete schema defined with the declarative EdgeDB schema definition language.
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).
The START MIGRATION
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.
Create a new migration using an explicit EdgeQL script.
CREATE MIGRATION "{"
edgeql-statement ;
[ ... ]
"}" ;
Any valid EdgeQL statement, except DATABASE
, ROLE
, CONFIGURE
,
MIGRATION
, or TRANSACTION
statements.
Abort the current migration block and discard the migration.
ABORT MIGRATION ;
ABORT MIGRATION
is used to abort a migration block started by
START MIGRATION
. Issuing ABORT MIGRATION
outside of a
migration block is an error.
Populate the current migration with system-generated statements.
POPULATE MIGRATION ;
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.
POPULATE MIGRATION
may generate statements that drop schema objects,
which may result in data loss. Make sure to inspect the generated
migration using DESCRIBE CURRENT MIGRATION
before running
COMMIT MIGRATION
!
Describe the migration in the current migration block.
DESCRIBE CURRENT MIGRATION [ AS {DDL | JSON} ];
DESCRIBE CURRENT MIGRATION
generates a description of the migration
in the current migration block in the specified output format:
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
.
Provide a machine-readable description of the migration using the following JSON format:
{
// Name of the parent migration
"parent": "<parent-migraiton-name>",
// Whether the confirmed DDL makes the migration complete,
// i.e. there are no more statements to issue.
"complete": {true|false},
// List of confirmed migration statements
"confirmed": [
"<stmt text>",
...
],
// The variants of the next statement
// suggested by the system to advance
// the migration script.
"proposed": {
"statements": [{
"text": "<stmt text template>"
}],
"required-user-input": [
{
"placeholder": "<placeholder variable>",
"prompt": "<statement prompt>",
},
...
],
"confidence": (0..1), // confidence coefficient
"prompt": "<operation prompt>",
"prompt_id": "<prompt id>",
// Whether the operation is considered to be non-destructive.
"data_safe": {true|false}
}
}
Where:
Regular statement text.
Statement text template with interpolation points using the \(name)
syntax.
The name of an interpolation variable in the statement text template for which the user prompt is given.
The text of a user prompt for an interpolation variable.
Prompt for the proposed migration step.
An opaque string identifier for a particular operation prompt. The client should not repeat prompts with the same prompt id.
Commit the current migration to the database.
COMMIT MIGRATION ;
COMMIT MIGRATION
runs 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.