MariaDB Driver v0.1.6¶

MariaDB URI Format (Recommended)¶

The driver accepts a MariaDB-specific URI:

mariadb://[user[:[password]]@]host[:port][/schema][?attribute1=value1&attribute2=value2...]

Examples:

• mariadb://localhost/mydb

• mariadb://user:pass@localhost:3306/mydb

• mariadb://user:pass@host/db?charset=utf8mb4&timeout=30s

• mariadb://user@(/path/to/socket.sock)/db (Unix domain socket)

• mariadb://user@localhost/mydb (no password)

URI Components:

• scheme: mariadb:// (required)

• user: Optional (for authentication)

• password: Optional (for authentication, requires user)

• host: Required (must be explicitly specified)

• port: Optional (defaults to 3306)

• schema: Optional (can be empty, MariaDB database name)

• Query params: MariaDB connection attributes

Unix Domain Sockets: When connecting via Unix domain sockets, use the parentheses syntax to wrap the socket path: mariadb://user@(/path/to/socket.sock)/db

The mysql:// scheme is intentionally rejected. Native Go DSNs remain supported for compatibility with the underlying wire-protocol library.

Go MariaDB Driver DSN Format (Alternative)¶

The driver also accepts the Go MariaDB Driver DSN format :

[username[:password]@][protocol[(address)]]/dbname[?param1=value1&...&paramN=valueN]

Examples:

• user:pass@tcp(localhost:3306)/mydb

• user@tcp(127.0.0.1:3306)/mydb

• user:pass@unix(/tmp/mariadb.sock)/mydb

Database to Arrow¶

Arrow to Database¶

In addition to the shared SQL types, metadata-based schema discovery supports:

• UUID as the standard Arrow arrow.uuid extension type.

• VECTOR(n) as fixed_size_list<float32>[n]. If a query result omits the vector width, the driver conservatively returns packed binary data with mariadb.vector_encoding=float32_le metadata.

• INET4 and INET6 as canonical strings carrying the intended logical type in mariadb.logical_arrow_type. The driver deliberately avoids unregistered ARROW:extension:name values, since some consumers reject the entire schema.

• Spatial columns as WKB binary with mariadb.logical_arrow_type=geoarrow.wkb. The driver removes MariaDB’s internal four-byte SRID prefix while reading and uses ST_GeomFromWKB during bulk ingest.

• JSON as the standard Arrow arrow.json extension type. Because MariaDB stores JSON as LONGTEXT, GetTableSchema recognizes its JSON_VALID constraint to recover the logical type.

• ENUM and SET as strings. Their declared values are JSON arrays in the mariadb.enum_values and mariadb.set_values field metadata.

• Unsigned integers as Arrow unsigned integers, including BIGINT UNSIGNED as uint64. DECIMAL values up to precision 38 use the narrowest Arrow decimal type. Wider decimals are lossless UTF-8 strings with precision, scale, mariadb.logical_arrow_type, and mariadb.arrow_fallback=string metadata, avoiding consumer failures on decimal256 schemas.

• BIT(n) as binary with its bit width in sql.length, and YEAR as int16. Binary collations remain Arrow binary while textual collations remain UTF-8.

• TIME as an Arrow duration, preserving MariaDB’s negative values and values up to 838 hours. DATE, DATETIME, and TIMESTAMP retain fractional-second precision; zero dates follow mariadb.query.zero_datetime_behavior.

MariaDB’s result-set protocol sometimes reports logical aliases using their storage types: notably UUID as CHAR and JSON as LONGTEXT. For arbitrary SQL query results the driver does not guess from values. Cast at the consumer or use GetTableSchema when native logical types are required.

FLOAT precision¶

MariaDB formats FLOAT values with only 6 significant digits when results are sent over the text protocol, which the driver uses for queries executed without parameters or a prior Prepare. Values are stored exactly, but such reads may be rounded (for example, 16777216 is returned as 16777200). This is a server behavior shared by all text-protocol clients.

To read FLOAT values exactly, prepare the statement before executing it, so results use the binary protocol:

with conn.cursor() as cursor:
    cursor.adbc_prepare("SELECT v FROM t")
    cursor.execute("SELECT v FROM t")

Alternatively, use DOUBLE columns or CAST(v AS DOUBLE).