sql.mysql.connection

import sql.mysql.connection

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

One open MySQL connection, as the layer above it sees one.

Why a statement with values is always prepared

MySQL has two ways to run a statement. Sent as text it is one round trip, but there is nowhere to put a value: it would have to be written into the SQL, which means quoting it, which means being wrong about quoting it eventually. Prepared, the values travel separately in the binary encoding and the question never arises.

So a statement with no values goes as text and a statement with values is prepared. Preparing costs a round trip, which is why a connection keeps the statements it has compiled and reuses them: a query run in a loop pays for it once.

Constants

CACHE_LIMIT

sql.mysql.connection.CACHE_LIMIT = 64

How many compiled statements a connection keeps before releasing the one it has gone longest without using.

Each costs a little memory on the server, so this is a ceiling rather than a target.

Classes

MySqlConnection

class sql.mysql.MySqlConnection < DriverConnection

A connection to MySQL or MariaDB.

• printable — has a @to_string(), so echo and print() show something useful

Constructor

sql.mysql.MySqlConnection(driver, protocol, options)

Parameters

• driver (Driver)
• protocol (Protocol) — An authenticated protocol.
• options (dict)

MySqlConnection.protocol()

sql.mysql.MySqlConnection.protocol() -> Protocol

The protocol underneath, for the MySQL-only features that are not part of the shared contract.

Returns Protocol

MySqlConnection.parameters()

sql.mysql.MySqlConnection.parameters() -> dict

What the server said about itself when it answered.

Returns dict

MySqlConnection.flavor()

sql.mysql.MySqlConnection.flavor() -> string

Which server this is: 'mysql' or 'mariadb'.

Returns string

MySqlConnection.connection_id()

sql.mysql.MySqlConnection.connection_id() -> number

The id the server gave this connection.

This is what KILL names, and what a connection shows as in SHOW PROCESSLIST, so it is the handle for stopping a statement running on this connection from another one.

Returns number

MySqlConnection.schema_adapter()

sql.mysql.MySqlConnection.schema_adapter()

MySqlConnection.execute()

sql.mysql.MySqlConnection.execute(sql: string, values: list)

MySqlConnection.select()

sql.mysql.MySqlConnection.select(sql: string, values: list)

MySqlConnection.open_cursor()

sql.mysql.MySqlConnection.open_cursor(sql: string, values: list, options: dict)

MySqlConnection.prepare()

sql.mysql.MySqlConnection.prepare(sql: string)

MySqlConnection.begin()

sql.mysql.MySqlConnection.begin(isolation)

Opens a transaction, or takes a savepoint inside the one already open.

Parameters

• isolation (string|nil)

MySqlConnection.commit()

sql.mysql.MySqlConnection.commit()

Commits, or releases the innermost savepoint.

MySqlConnection.rollback()

sql.mysql.MySqlConnection.rollback()

Rolls back, or returns to the innermost savepoint and discards it.

MySqlConnection.savepoint()

sql.mysql.MySqlConnection.savepoint(name: string)

MySqlConnection.release_savepoint()

sql.mysql.MySqlConnection.release_savepoint(name: string)

MySqlConnection.rollback_to()

sql.mysql.MySqlConnection.rollback_to(name: string)

MySqlConnection.in_transaction()

sql.mysql.MySqlConnection.in_transaction()

MySqlConnection.last_insert_id()

sql.mysql.MySqlConnection.last_insert_id() -> number|bigint|nil

The id generated by the last insert on this connection.

Zero means the last statement generated none, which is what an insert into a table with no auto increment column reports, so it comes back as nil rather than as a row that does not exist.

Returns number|bigint|nil

MySqlConnection.ping()

sql.mysql.MySqlConnection.ping()

MySqlConnection.server_version()

sql.mysql.MySqlConnection.server_version()

MySqlConnection.reset()

sql.mysql.MySqlConnection.reset()

Returns the session to the state it had when it opened.

A pool calls this before handing the connection on, so that temporary tables, session variables and an unfinished transaction cannot leak from one borrower to the next.

MySqlConnection.close()

sql.mysql.MySqlConnection.close()

MySqlConnection.is_closed()

sql.mysql.MySqlConnection.is_closed()

MySqlConnection.run_simple()

sql.mysql.MySqlConnection.run_simple(sql: string) -> dict

Runs a statement as text, for the cases that have no values and so need no preparing.

Parameters

• sql (string)

Returns dict

MySqlConnection.to_string()

sql.mysql.MySqlConnection.to_string()

2026, Richard Ore and Zuri contributors