sql.mysql.types

import sql.mysql.types

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

What MySQL’s column types mean in Zuri, in both directions and in both of the protocol’s two encodings.

Two encodings for the same values

A statement sent as text answers with every value as text, however it is declared: an INT arrives as '42'. A prepared statement answers in the binary encoding instead, where an INT is four bytes. Both reach the same Zuri values, and the two paths are checked against each other rather than written to agree by hand: dates and times decode by way of the same text form whichever encoding carried them.

Where a type has no Zuri counterpart

BIT and GEOMETRY arrive as bytes, since neither has a shape Zuri could represent without inventing one. SET arrives as the comma separated text the server stores rather than as a list, because a list going back in would be written as JSON and the column would quietly stop matching.

Time zones

A DATETIME has no zone and a TIMESTAMP is converted to the session’s. The adapter puts the session in UTC when it connects, so both arrive as UTC and a date.Date written back converts from whatever offset it carries. Turning that off is what the time_zone connection option is for.

Constants

TYPES

sql.mysql.TYPES = {...}

The type byte the server puts on a column, and that a parameter carries back.

FLAGS

sql.mysql.FLAGS = {...}

What the server says about a column beyond its type.

BINARY_CHARSET

sql.mysql.types.BINARY_CHARSET = 63

The collation id that means a column holds bytes rather than text. It is the only thing separating BLOB from TEXT on the wire, and BINARY from CHAR.

UNSIGNED_FLAG

sql.mysql.types.UNSIGNED_FLAG = 128

The flag byte that goes with a parameter’s type to mark it unsigned.

Functions

is_binary()

sql.mysql.types.is_binary(column: dict) -> bool

Whether a column holds bytes rather than text.

Parameters

• column (dict)

Returns bool

is_unsigned()

sql.mysql.types.is_unsigned(column: dict) -> bool

Whether a column’s values are unsigned.

Parameters

• column (dict)

Returns bool

type_name_of()

sql.mysql.type_name_of(column: dict) -> string

The name of a column’s type, as MySQL itself would write it.

Parameters

• column (dict)

Returns string

describe_columns()

sql.mysql.types.describe_columns(columns: list) -> list[dict]

Reduces the server’s column descriptors to the two fields the shared contract asks for.

Parameters

• columns (list)

Returns list[dict]

decode_text()

sql.mysql.types.decode_text(raw, column: dict) -> any

Reads one value out of a text protocol row.

Parameters

• raw (bytes|nil) — The value as the server wrote it, or nil for NULL.
• column (dict)

Returns any

decode_binary()

sql.mysql.types.decode_binary(cursor, column: dict) -> any

Reads one value out of a binary protocol row.

The NULL bitmap is the caller’s business; this is only reached for a value that is present.

Parameters

• cursor (Cursor) — Positioned at the value.
• column (dict)

Returns any

parameter_type()

sql.mysql.types.parameter_type(value) -> dict

The type byte and flag a value is sent as.

write_parameter() has to agree with this exactly, since a statement sends every type first and then every value.

Parameters

• value (any)

Returns dict — { type, unsigned }

Raises QueryError for a value with no MySQL representation.

write_parameter()

sql.mysql.types.write_parameter(writer, value)

Appends a value in the form its type byte promises.

Parameters

• writer (Writer)
• value (any)

2026, Richard Ore and Zuri contributors