The Zuri Standard Library Zuri

Databases

sql.ddl

import sql.ddl
Zuri

sql lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled sql.ddl.* needs import 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
Zuri

Turns 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)
Zuri

Parameters

  • driver (Driver)

DdlAdapter.type_name()

sql.DdlAdapter.type_name(column) -> string
Zuri

The 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
Zuri

Everything 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
Zuri

The 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
Zuri

A bool as a literal.

Parameters

  • value (bool)

Returns string

DdlAdapter.string_literal()

sql.DdlAdapter.string_literal(text: string) -> string
Zuri

A 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
Zuri

The 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
Zuri

What follows the closing parenthesis of create table.

Returns string

DdlAdapter.parenthesised_default()

sql.DdlAdapter.parenthesised_default(column) -> bool
Zuri

Whether 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
Zuri

Whether indexes are declared inside create table, instead of with create index statements afterwards.

Returns bool

DdlAdapter.quote()

sql.DdlAdapter.quote(name: string) -> string
Zuri

An identifier, quoted.

Parameters

  • name (string)

Returns string

DdlAdapter.table_name()

sql.DdlAdapter.table_name(name: string) -> string
Zuri

A 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
Zuri

An 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
Zuri

The 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
Zuri

The default of column, as SQL.

Parameters

  • column (Column)

Returns string

DdlAdapter.literal()

sql.DdlAdapter.literal(value) -> string
Zuri

A 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
Zuri

A 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
Zuri

A create index statement.

Parameters

  • table (string)
  • kind (string) — index or unique.
  • 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
Zuri

An index declared inside create table, for an engine whose inline_indexes() is true.

Parameters

  • kind (string) — index or unique.
  • name (string)
  • columns (list[string])

Returns string

DdlAdapter.create_table_statements()

sql.DdlAdapter.create_table_statements(blueprint, options: dict) -> list[string]
Zuri

The 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)
Zuri

Checks 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)
Zuri

Checks 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)
Zuri

Creates the table blueprint describes.

Parameters

  • connection (Connection)
  • blueprint (Blueprint)
  • options (dict) — { if_not_exists }.

DdlAdapter.alter_table()

sql.DdlAdapter.alter_table(connection, blueprint)
Zuri

Carries 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)
Zuri

Carries out one change to a table that exists.

Parameters

  • connection (Connection)
  • blueprint (Blueprint)
  • operation (dict) — One of blueprint.operations.

DdlAdapter.add_column()

sql.DdlAdapter.add_column(connection, table: string, column)
Zuri

Adds 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]
Zuri

The 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]
Zuri

The 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]
Zuri

The 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]
Zuri

The 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]
Zuri

The 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)
Zuri

Drops 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)
Zuri

Renames 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
Zuri

Runs 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
Zuri

Runs 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)
Zuri

Runs 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