Schema Definition Language

This section describes the high-level language used to define EdgeDB schema. It is called the EdgeDB schema definition language or SDL. There’s a correspondence between this declarative high-level language and the imperative low-level DDL.

SDL is a declarative language optimized for human readability and expressing the state of the EdgeDB schema without getting into the details of how to arrive at that state. Each SDL block represents the complete schema state for a given database.

Syntactically, an SDL declaration mirrors the CREATE DDL for the corresponding entity, but with all of the CREATE and SET keywords omitted. The typical SDL structure is to use module blocks with the rest of the declarations being nested in their respective modules.

Since SDL is declarative in nature, the specific order of declarations of module blocks or individual items does not matter.

SDL is used to specify a migration to a to a specific schema state. For example:

db> 
START TRANSACTION;
START TRANSACTION
db> 
... 
... 
... 
... 
... 
... 
... 
... 
... 
... 
... 
... 
... 
... 
... 
CREATE MIGRATION movies TO {
    # "default" module block
    module default {
        type Movie {
            required property title -> str;
            # the year of release
            property year -> int64;
            required link director -> Person;
            required multi link actors -> Person;
        }
        type Person {
            required property first_name -> str;
            required property last_name -> str;
        }
    }
};
CREATE MIGRATION
db> 
COMMIT MIGRATION movies;
COMMIT MIGRATION
db> 
COMMIT;
COMMIT TRANSACTION

It is possible to also omit the module blocks, but then individual declarations must use fully-qualified names so that they can be assigned to their respective modules. For example the following is equivalent to the previous migration:

db> 
START TRANSACTION;
START TRANSACTION
db> 
... 
... 
... 
... 
... 
... 
... 
... 
... 
... 
... 
... 
... 
CREATE MIGRATION movies TO {
    # no module block
    type default::Movie {
        required property title -> str;
        # the year of release
        property year -> int64;
        required link director -> default::Person;
        required multi link actors -> default::Person;
    }
    type default::Person {
        required property first_name -> str;
        required property last_name -> str;
    }
};
CREATE MIGRATION
db> 
COMMIT MIGRATION movies;
COMMIT MIGRATION
db> 
COMMIT;
COMMIT TRANSACTION