Databases
sql.ddl
import sql.ddl
Zuri
sqllifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelledsql.ddl.*needsimport sql.ddl.
Turns a Blueprint into the statements that one engine understands, and
runs them in the way that engine needs.
Every engine describes tables differently. An auto-numbered key is
autoincrement in SQLite, an identity column in PostgreSQL and
auto_increment in MySQL. A byte-for-byte comparison is the default in
SQLite, the "C" collation in PostgreSQL and utf8mb4_bin in MySQL.
And a change that SQLite's ALTER TABLE can't make has to be carried
out by rebuilding the table. DdlAdapter contains what's the same for
all of them, and each adapter's subclass supplies the rest.
Programs never call this directly. db.schema.create_table() and the
other schema methods go through Driver.ddl(). To support them in an
adapter of your own, subclass DdlAdapter and return an instance from
the driver's ddl().
Running a change
Each method takes the Connection to change and runs its statements on
it. schema_change() wraps a change when the caller has no transaction
open, and sql.migrate runs every migration in it. On an engine that
can roll back a schema change, it starts a transaction. On one that
can't, it does nothing. On SQLite, it also turns off foreign key
enforcement around the change, and checks the foreign keys again before
committing.
Classes
DdlAdapter
class sql.DdlAdapter
ZuriTurns blueprints into one engine's statements and runs them.
The methods a subclass overrides fall into two groups. What the engine
calls things: type_name(), key_definition(), exact_collation(),
boolean_literal(), string_literal(), current_default(),
table_suffix(), parenthesised_default() and inline_indexes(). And
how the engine changes a table that exists: change_column(),
drop_column(), drop_index(), drop_foreign() and drop_primary().
The defaults are standard SQL, and raise NotImplementedError where
there is no standard to fall back on.
Fields
| Field | Type | Description |
|---|---|---|
driver |
Driver |
The driver this adapter writes for. |
Constructor
sql.DdlAdapter(driver)
ZuriParameters
driver(Driver)
DdlAdapter.type_name()
sql.DdlAdapter.type_name(column) -> string
ZuriThe engine's type for column. Called for every column but an id(),
which key_definition() describes whole.
Parameters
column(Column)
Returns string
DdlAdapter.key_definition()
sql.DdlAdapter.key_definition(column) -> string
ZuriEverything after the name of an id() column: its type, and that it is
the primary key and numbered by the engine.
Parameters
column(Column)
Returns string
DdlAdapter.exact_collation()
sql.DdlAdapter.exact_collation() -> string|nil
ZuriThe collation that compares byte for byte, written as it follows a column's type, or nil where the engine's default already does.
Returns string|nil
DdlAdapter.boolean_literal()
sql.DdlAdapter.boolean_literal(value: bool) -> string
ZuriA bool as a literal.
Parameters
value(bool)
Returns string
DdlAdapter.string_literal()
sql.DdlAdapter.string_literal(text: string) -> string
ZuriA string as a literal, quoted so whatever it holds stays inside it.
Parameters
text(string)
Returns string
DdlAdapter.current_default()
sql.DdlAdapter.current_default(column) -> string
ZuriThe default that stamps a datetime() column with the moment a row is
inserted.
Parameters
column(Column)
Returns string
DdlAdapter.table_suffix()
sql.DdlAdapter.table_suffix() -> string
ZuriWhat follows the closing parenthesis of create table.
Returns string
DdlAdapter.parenthesised_default()
sql.DdlAdapter.parenthesised_default(column) -> bool
ZuriWhether a default on column has to be written in parentheses, as MySQL
requires of text, binary and JSON columns.
Parameters
column(Column)
Returns bool
DdlAdapter.inline_indexes()
sql.DdlAdapter.inline_indexes() -> bool
ZuriWhether indexes are declared inside create table, instead of with
create index statements afterwards.
Returns bool
DdlAdapter.quote()
sql.DdlAdapter.quote(name: string) -> string
ZuriAn identifier, quoted.
Parameters
name(string)
Returns string
DdlAdapter.table_name()
sql.DdlAdapter.table_name(name: string) -> string
ZuriA table name, quoted, with any schema in front of it quoted too.
Parameters
name(string)
Returns string
DdlAdapter.index_reference()
sql.DdlAdapter.index_reference(table: string, name: string) -> string
ZuriAn index name as it is addressed on its own, in the schema of the table it belongs to.
Parameters
table(string)name(string)
Returns string
DdlAdapter.column_definition()
sql.DdlAdapter.column_definition(column) -> string
ZuriThe definition of column, as it appears in create table and in add column:
its name, type, collation, whether it may be null and its default. A key
it carries is written separately, by foreign_key_sql().
Parameters
column(Column)
Returns string
DdlAdapter.default_sql()
sql.DdlAdapter.default_sql(column) -> string
ZuriThe default of column, as SQL.
Parameters
column(Column)
Returns string
DdlAdapter.literal()
sql.DdlAdapter.literal(value) -> string
ZuriA value as a literal: nil, a bool, a number, a bigint, a string, a
Decimal, or a list or dictionary as JSON text.
Parameters
value(any)
Returns string
Raises QueryError for anything else, and for a number that is not
finite.
DdlAdapter.foreign_key_sql()
sql.DdlAdapter.foreign_key_sql(table: string, key) -> string
ZuriA foreign key as a table constraint, named.
Parameters
table(string) — The referring table.key(ForeignKey)
Returns string
DdlAdapter.index_sql()
sql.DdlAdapter.index_sql(table: string, kind: string, name: string, columns: list, if_not_exists: bool) -> string
ZuriA create index statement.
Parameters
table(string)kind(string) —indexorunique.name(string)columns(list[string])if_not_exists(bool)
Returns string
DdlAdapter.inline_index_sql()
sql.DdlAdapter.inline_index_sql(kind: string, name: string, columns: list) -> string
ZuriAn index declared inside create table, for an engine whose
inline_indexes() is true.
Parameters
kind(string) —indexorunique.name(string)columns(list[string])
Returns string
DdlAdapter.create_table_statements()
sql.DdlAdapter.create_table_statements(blueprint, options: dict) -> list[string]
ZuriThe statements that create the table blueprint describes, without
running them.
Parameters
blueprint(Blueprint)options(dict) —{ if_not_exists }, false by default.
Returns list[string]
Raises QueryError if the blueprint changes or drops anything, or
declares two primary keys.
DdlAdapter.check_column()
sql.DdlAdapter.check_column(column)
ZuriChecks the engine can hold column as described, before anything is
run. The default accepts everything.
Parameters
column(Column)
Raises NotSupportedError where the engine cannot.
DdlAdapter.check_index()
sql.DdlAdapter.check_index(table: string, columns: list, described: list)
ZuriChecks the engine can index columns of table, given the columns
described alongside. The default accepts everything.
Parameters
table(string)columns(list[string])described(list[Column])
Raises NotSupportedError where the engine cannot.
DdlAdapter.create_table()
sql.DdlAdapter.create_table(connection, blueprint, options: dict)
ZuriCreates the table blueprint describes.
Parameters
connection(Connection)blueprint(Blueprint)options(dict) —{ if_not_exists }.
DdlAdapter.alter_table()
sql.DdlAdapter.alter_table(connection, blueprint)
ZuriCarries out the changes blueprint describes, one at a time, in the
order they were described.
Parameters
connection(Connection)blueprint(Blueprint)
DdlAdapter.alter()
sql.DdlAdapter.alter(connection, blueprint, operation)
ZuriCarries out one change to a table that exists.
Parameters
connection(Connection)blueprint(Blueprint)operation(dict) — One ofblueprint.operations.
DdlAdapter.add_column()
sql.DdlAdapter.add_column(connection, table: string, column)
ZuriAdds column to table, along with its key.
A required column with no default can only be added to a table with no
rows, because there's nothing to fill the existing rows with. If the
table has rows, the engine raises a NotNullViolation.
Parameters
connection(Connection)table(string)column(Column)
DdlAdapter.change_column()
sql.DdlAdapter.change_column(connection, table: string, column) -> list[string]
ZuriThe statements that give an existing column the definition column
describes.
Parameters
connection(Connection)table(string)column(Column)
Returns list[string]
DdlAdapter.drop_column()
sql.DdlAdapter.drop_column(connection, table: string, name: string) -> list[string]
ZuriThe statements that drop column name, with the indexes and keys it is
part of.
Parameters
connection(Connection)table(string)name(string)
Returns list[string]
DdlAdapter.drop_index()
sql.DdlAdapter.drop_index(connection, table: string, name: string) -> list[string]
ZuriThe statements that drop index name of table.
Parameters
connection(Connection)table(string)name(string)
Returns list[string]
DdlAdapter.drop_foreign()
sql.DdlAdapter.drop_foreign(connection, table: string, name: string) -> list[string]
ZuriThe statements that drop foreign key name of table.
Parameters
connection(Connection)table(string)name(string)
Returns list[string]
DdlAdapter.drop_primary()
sql.DdlAdapter.drop_primary(connection, table: string) -> list[string]
ZuriThe statements that drop the primary key of table.
Parameters
connection(Connection)table(string)
Returns list[string]
DdlAdapter.drop_table()
sql.DdlAdapter.drop_table(connection, table: string, options: dict)
ZuriDrops table.
A table that another table refers to through a foreign key can't be dropped, on any engine, because dropping it would also remove the rows that refer to it.
Parameters
connection(Connection)table(string)options(dict) —{ if_exists }, false by default. When it's true, a table that doesn't exist is ignored instead of causing an error.
DdlAdapter.rename_table()
sql.DdlAdapter.rename_table(connection, from: string, to: string)
ZuriRenames table from to to. Foreign keys that refer to the table
follow it, and its indexes keep their names.
Parameters
connection(Connection)from(string)to(string)
DdlAdapter.schema_change()
sql.DdlAdapter.schema_change(connection, body: function, transactional: bool) -> any
ZuriRuns body as one schema change.
On an engine that can roll back a schema change, and when
transactional is true, body runs inside a transaction and is passed
the Transaction. Otherwise, it's passed the connection and runs
directly on it.
Parameters
connection(Connection) — A connection that isn't already in a transaction.body(function)transactional(bool)
Returns any — Whatever body returned.
DdlAdapter.migration_lock()
sql.DdlAdapter.migration_lock(connection, name: string, body: function) -> any
ZuriRuns body holding a lock named name that only one connection to the
database can hold at a time, waiting for it as long as another holds it.
The default takes no lock, for an engine that has none, where
schema_change() alone has to keep two changes apart.
Parameters
connection(Connection)name(string)body(function)
Returns any — What body returned.
DdlAdapter.run()
sql.DdlAdapter.run(connection, statements: list)
ZuriRuns statements on connection, as written: nothing in them is read
as a placeholder.
Parameters
connection(Connection)statements(list[string])
2026, Richard Ore and Zuri contributors