Type Conversion Strategy

This document describes how rapsqlite maps Python and SQLite types, and how to work with custom types. rapsqlite supports per-connection register_adapter and register_converter (sqlite3-style).

Built-in type mapping

Parameters (Python → SQLite) Supported Python types when binding parameters: int, float, str, bytes, None. These map to SQLite INTEGER, REAL, TEXT, BLOB, and NULL. Other types raise TypeError unless you convert them before passing (see below).

Results (SQLite → Python) Result columns are decoded by declared type when available: INTEGER/INT → int, REAL/FLOAT/DOUBLE → float, TEXT/VARCHAR/CHAR → str, BLOB → bytes, NULL → None. For dynamic or unknown types, rapsqlite probes the value and returns the appropriate Python type. text_factory (e.g. str or a callable) applies to TEXT columns and can change how text is produced (e.g. return bytes).

register_adapter and register_converter (supported)

rapsqlite supports per-connection type adapters and converters (sqlite3-style):

  • ``conn.register_adapter(type, adapter)`` — When a Python object of that type is used as a parameter, call adapter(obj) and bind the result. Pass adapter=None to remove the adapter for that type.

  • ``conn.register_converter(typename, converter)`` — When a result column’s declared type (as reported by the driver) matches typename (case-insensitive), call converter(bytes) and return the result. Pass converter=None to remove. The converter receives the column value as bytes; for TEXT columns the value is UTF-8 encoded.

Example: custom type for parameters and results:

conn.register_adapter(Point, lambda p: f"{p.x},{p.y}")
conn.register_converter("DATE", lambda b: b.decode("utf-8") if b else None)

Other options for custom types

You can also use these alternatives (or in combination with adapters/converters):

  1. Application-layer conversion Convert custom Python objects to a supported type before execute, and convert result values after fetch_*.

  2. ``create_function`` For custom SQL functions that accept or return values, use conn.create_function(...). This does not change how normal parameters or result columns are converted.

  3. ``row_factory`` Set conn.row_factory to a callable that receives the raw row and returns a transformed object (e.g. a named tuple or dataclass).

  4. ``text_factory`` Affects only TEXT columns: a callable (bytes) -> Any or str.