`sql.driver`

import sql.driver

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.driver.* needs import sql.driver.

The contract every database adapter implements, and the capability flags that let one adapter differ from another without the code above them having to know which is in use.

An adapter supplies four things: a Driver that knows how to read a connection string and open a connection, a DriverConnection that runs statements, a DriverStatement for a prepared one, and a DriverCursor for reading a result a batch at a time. Everything a program touches directly is built on top of these, so an adapter that implements them gets pooling, transactions, the CRUD helpers, placeholder translation and the error hierarchy without writing any of it.

The methods here raise NotImplementedError. An adapter that forgets one fails where the gap is rather than somewhere further down, and an adapter for an engine that genuinely cannot do something raises NotSupportedError from its own override instead, which reads differently on purpose: the first is an unfinished adapter, the second is an honest limit of the engine.

Constants

`READ_COMMITTED`

sql.READ_COMMITTED = 'read committed'

Each transaction sees rows committed before its own statement started, and nothing a concurrent transaction commits afterwards within that statement.

`REPEATABLE_READ`

sql.REPEATABLE_READ = 'repeatable read'

A transaction reads the same rows throughout, whatever anyone else commits while it runs.

`SERIALIZABLE`

sql.SERIALIZABLE = 'serializable'

Concurrent transactions produce a result some serial order of them could also have produced. The engine may abort one to keep that promise, which surfaces as SerializationError.

`READ_UNCOMMITTED`

sql.READ_UNCOMMITTED = 'read uncommitted'

A transaction can see rows another has written and not committed. PostgreSQL accepts the name and gives read committed anyway, which its own documentation is explicit about.

Functions

`default_capabilities()`

sql.default_capabilities() -> dict

The capability flags a driver reports, with the value each takes when a driver does not say otherwise.

A driver’s capabilities() starts from this and overrides what differs, so a flag added here later does not break an adapter written before it existed.

Flag	Meaning
`placeholder_style`	How the engine spells a parameter.
`named_parameters`	Whether the engine binds parameters by name.
`last_insert_id`	Whether the engine reports the id of the row just inserted.
`returning`	Whether `INSERT ... RETURNING` works.
`transactions`	Whether BEGIN, COMMIT and ROLLBACK work.
`savepoints`	Whether SAVEPOINT works, which is what nested transactions are built on.
`transactional_ddl`	Whether CREATE, ALTER and DROP stay inside
a transaction, rather than committing it.
`isolation_levels`	The levels the engine will accept.
`server_side_cursors`	Whether a result can be read without the whole of it arriving first.
`prepared_statements`	Whether a statement can be compiled once and run repeatedly.
`multiple_statements`	Whether one call may carry several
statements separated by semicolons.
`arrays`	Whether the engine has an array type.
`json`	Whether the engine has a JSON type, as opposed to storing JSON in text.
`blobs`	Whether the engine stores binary values.
`decimals`	Whether the engine has an exact decimal type.
`booleans`	Whether the engine has a real boolean type.
`upsert`	Whether an insert can update the row it collided
with, however the engine spells it.
`schemas`	Whether tables live in named schemas.
`concurrent_writers`	Whether two connections can write at once.
`max_parameters`	Most parameters one statement may bind, or nil for no practical limit.
`identifier_quote`	The character an identifier is quoted with.
`default_port`	The port used when a connection string omits
one, or nil for an engine with no port.

Returns dict

Classes

`Driver`

class sql.Driver

Opens connections to one kind of database.

A driver holds no connection of its own and no state worth sharing, so one instance per engine is registered with sql.register() and reused for every connection it opens.

`Driver.name()`

sql.Driver.name() -> string

The name this driver is registered under, such as 'sqlite'.

Appears on every error the adapter raises, so it wants to be the name a reader would recognise.

Returns string

`Driver.schemes()`

sql.Driver.schemes() -> list[string]

The URL schemes this driver claims, without the ://.

sql.open() picks a driver by matching a connection string’s scheme against these, which is what lets the same call open any of the engines. Several are allowed: PostgreSQL answers to both postgres and postgresql.

Returns list[string]

`Driver.capabilities()`

sql.Driver.capabilities() -> dict

What this engine can and cannot do.

Built from default_capabilities() with the differences applied.

Returns dict

`Driver.parse_dsn()`

sql.Driver.parse_dsn(dsn) -> dict

Turns a connection string or an options dictionary into the normalised options connect() takes.

Each adapter reads the forms its own engine’s tooling uses, so a connection string copied from somewhere else works unchanged.

Parameters

dsn (string|dict)

Returns dict

`Driver.connect()`

sql.Driver.connect(options: dict) -> DriverConnection

Opens a connection with options from parse_dsn().

Parameters

options (dict)

Returns DriverConnection

`Driver.quote_identifier()`

sql.Driver.quote_identifier(name: string) -> string

Quotes name so the engine reads it as an identifier whatever it contains or collides with.

The default doubles the engine’s own quote character, which is what the SQL standard says and what the built-in adapters do, MySQL included once its quote character is taken into account. An engine whose quoting differs overrides this.

Parameters

name (string)

Returns string

`Driver.supports()`

sql.Driver.supports(flag: string) -> bool

Whether this driver supports flag.

Parameters

flag (string) — A key of default_capabilities().

Returns bool

`DriverConnection`

class sql.DriverConnection

One open connection to a database, as the layer above it sees one.

Adapters implement this; programs use sql.Connection, which wraps it and adds everything that is the same across engines.

Fields

Field	Type	Description
`driver`	`Driver`	The `Driver` that opened this connection.

`DriverConnection.execute()`

sql.DriverConnection.execute(sql: string, values: list) -> dict

Runs a statement for its effect and reports what it did.

Parameters

sql (string) — Already translated into this engine’s own placeholder style.
values (list) — Bound in order.

Returns dict — { rows_affected, last_insert_id }, the second nil on an engine that does not report one.

`DriverConnection.select()`

sql.DriverConnection.select(sql: string, values: list) -> dict

Runs a statement and reads its whole result.

Parameters

sql (string)
values (list)

Returns dict — { columns, rows }, where columns is a list of { name, type } dictionaries and rows a list of value lists in the same order.

`DriverConnection.open_cursor()`

sql.DriverConnection.open_cursor(sql: string, values: list, options: dict) -> DriverCursor

Runs a statement and returns a cursor over its result rather than reading all of it.

On an engine without server side cursors this still avoids holding every row at once only as far as the engine allows; the capability flag says which.

Parameters

sql (string)
values (list)
options (dict) — { batch }, the rows to fetch at a time.

Returns DriverCursor

`DriverConnection.prepare()`

sql.DriverConnection.prepare(sql: string) -> DriverStatement

Compiles a statement for repeated use.

Parameters

sql (string)

Returns DriverStatement

`DriverConnection.begin()`

sql.DriverConnection.begin(isolation)

Opens a transaction.

Parameters

isolation (string|nil) — One of the level constants, or nil for the engine’s default.

`DriverConnection.commit()`

sql.DriverConnection.commit()

Commits the open transaction.

`DriverConnection.rollback()`

sql.DriverConnection.rollback()

Rolls the open transaction back.

`DriverConnection.savepoint()`

sql.DriverConnection.savepoint(name: string)

Marks a point inside the open transaction that can be returned to.

Parameters

name (string)

`DriverConnection.release_savepoint()`

sql.DriverConnection.release_savepoint(name: string)

Discards a savepoint, keeping everything done since it was taken.

Parameters

name (string)

`DriverConnection.rollback_to()`

sql.DriverConnection.rollback_to(name: string)

Undoes everything done since name was taken, leaving the transaction open and the savepoint still in place.

Parameters

name (string)

`DriverConnection.in_transaction()`

sql.DriverConnection.in_transaction() -> bool

Whether a transaction is currently open on this connection.

Returns bool

`DriverConnection.last_insert_id()`

sql.DriverConnection.last_insert_id() -> number|bigint|nil

The id of the row most recently inserted on this connection.

Only meaningful where last_insert_id is supported; elsewhere it raises NotSupportedError, and Connection.insert() uses RETURNING instead.

Returns number|bigint|nil

`DriverConnection.ping()`

sql.DriverConnection.ping() -> bool

Checks the connection is still usable, cheaply.

A pool calls this before handing a connection out, so it wants to be the smallest round trip the engine offers.

Returns bool

`DriverConnection.server_version()`

sql.DriverConnection.server_version() -> string

The engine’s version, as the engine reports it.

Returns string

`DriverConnection.schema_adapter()`

sql.DriverConnection.schema_adapter() -> SchemaAdapter

This engine’s introspection, which Connection.schema goes through.

The default refuses, so an adapter that has not written the queries says so plainly rather than reporting an empty database.

Returns SchemaAdapter

Raises NotSupportedError if the adapter has no introspection.

`DriverConnection.close()`

sql.DriverConnection.close()

Closes the connection. Calling this more than once does nothing.

`DriverConnection.is_closed()`

sql.DriverConnection.is_closed() -> bool

Whether this connection has been closed.

Returns bool

`DriverStatement`

class sql.DriverStatement

A statement compiled once and run many times.

`DriverStatement.execute()`

sql.DriverStatement.execute(values: list) -> dict

Runs the statement for its effect.

Parameters

values (list)

Returns dict — { rows_affected, last_insert_id }

`DriverStatement.select()`

sql.DriverStatement.select(values: list) -> dict

Runs the statement and reads its whole result.

Parameters

values (list)

Returns dict — { columns, rows }

`DriverStatement.open_cursor()`

sql.DriverStatement.open_cursor(values: list, options: dict) -> DriverCursor

Runs the statement and returns a cursor over its result.

Parameters

values (list)
options (dict)

Returns DriverCursor

`DriverStatement.columns()`

sql.DriverStatement.columns() -> list[dict]

The columns this statement returns, as { name, type } dictionaries.

Returns list[dict]

`DriverStatement.parameter_count()`

sql.DriverStatement.parameter_count() -> number

How many parameters this statement binds.

Returns number

`DriverStatement.close()`

sql.DriverStatement.close()

Releases the statement. Calling this more than once does nothing.

`DriverCursor`

class sql.DriverCursor

A result being read a batch at a time rather than all at once.

`DriverCursor.columns()`

sql.DriverCursor.columns() -> list[dict]

The columns of this result, as { name, type } dictionaries.

Returns list[dict]

`DriverCursor.next_row()`

sql.DriverCursor.next_row() -> list|nil

The next row as a list of values, or nil once the result is exhausted.

Returns list|nil

`DriverCursor.close()`

sql.DriverCursor.close()

Releases the cursor. Calling this more than once does nothing.

`SchemaAdapter`

class sql.SchemaAdapter

The introspection queries for one engine.

Every method returns the same shape whichever engine answered, which is the whole point of routing introspection through here rather than letting each program write its own information_schema query.

`SchemaAdapter.tables()`

sql.SchemaAdapter.tables(schema) -> list[string]

The names of the tables the application created, leaving out the ones the engine keeps for itself.

Parameters

schema (string|nil)

Returns list[string]

`SchemaAdapter.views()`

sql.SchemaAdapter.views(schema) -> list[string]

The names of the views.

Parameters

schema (string|nil)

Returns list[string]

`SchemaAdapter.columns()`

sql.SchemaAdapter.columns(table, schema) -> list[dict]

The columns of table, in order, each shaped as schema.column_shape() describes.

Parameters

table (string)
schema (string|nil)

Returns list[dict]

`SchemaAdapter.primary_key_columns()`

sql.SchemaAdapter.primary_key_columns(table, schema) -> list[string]

The columns making up table’s primary key, in key order, or an empty list for a table with none.

Parameters

table (string)
schema (string|nil)

Returns list[string]

`SchemaAdapter.indexes()`

sql.SchemaAdapter.indexes(table, schema) -> list[dict]

The indexes on table, each { name, columns, unique }.

Parameters

table (string)
schema (string|nil)

Returns list[dict]

`SchemaAdapter.foreign_keys()`

sql.SchemaAdapter.foreign_keys(table, schema) -> list[dict]

The foreign keys on table, each { columns, references_table, references_columns, on_delete, on_update }.

Parameters

table (string)
schema (string|nil)

Returns list[dict]

2026, Richard Ore and Zuri contributors

Keyboard shortcuts

The Zuri Standard Library