flowmaticdb 2.2.2__tar.gz → 2.3.0__tar.gz

{flowmaticdb-2.2.2 → flowmaticdb-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowmaticdb
-Version: 2.2.2
+Version: 2.3.0
 Summary: A Python database abstraction layer supporting PostgreSQL, SQLite, and MySQL.
 Author: Flowmatic, UniForceMusic
 License: MIT
@@ -273,6 +273,7 @@ db.create_table("users").if_not_exists() \
     .integer("age") \
     .boolean("active", default=True) \
     .datetime("created_at") \
+    .json("preferences") \
     .execute()
 
 # Using raw column definitions
@@ -651,6 +652,7 @@ from flowmaticdb import raw, identifier, alias, expression, sub_query, current_t
 | `sub_query(query, alias)` | `(SELECT ...) AS alias` | `sub_query(select_q, "sq")` |
 | `current_timestamp()` | `CURRENT_TIMESTAMP` | `current_timestamp()` |
 | `now()` | `datetime.now(UTC)` | `now()` |
+| `PostgresArray(values)` | Bind a list as a PostgreSQL array instead of JSON | `PostgresArray([1, 2, 3])` |
 
 ```python
 db.select(raw("COUNT(*) AS cnt")).table("users").execute()
@@ -737,6 +739,69 @@ except DatabaseError as e:
 
 ---
 
+## Datetime and JSON Values
+
+`datetime` objects and JSON documents are serialized on the way into the database and deserialized on the way back out, on every adapter.
+
+```python
+from datetime import datetime, timezone
+
+db.create_table("events").if_not_exists() \
+    .identity("id") \
+    .datetime("happened_at") \
+    .json("payload") \
+    .execute()
+
+db.insert("events").values({
+    "happened_at": datetime.now(timezone.utc),
+    "payload": {"kind": "signup", "tags": ["a", "b"]},
+}).execute()
+
+row = db.select("events").execute().fetch_dict()
+row["happened_at"]   # datetime
+row["payload"]       # dict
+```
+
+`TypeEnum.JSON` (the `.json()` column builder) maps to the best type the server has: `JSONB` on PostgreSQL ≥ 9.4, `JSON` on PostgreSQL ≥ 9.2, MySQL ≥ 5.7.8, MariaDB ≥ 10.2.7 and SQLite, and `TEXT` on anything older. `TypeEnum.DATETIME` maps to `TIMESTAMPTZ`, `DATETIME(6)` and `DATETIME` respectively.
+
+Nested values `json` does not know are rendered rather than raising: `datetime`, `date` and `time` become ISO-8601 strings, `Decimal` becomes a string (a float would lose precision). A JSON column holding text that is not valid JSON is handed back as that text instead of failing the fetch.
+
+How each driver is wired up:
+
+| Driver | Datetime | JSON |
+|--------|----------|------|
+| psycopg | Native, both directions | Serialized on the way in; psycopg decodes `json`/`jsonb` on the way out |
+| asyncpg | Bound natively, reconciled against the placeholder's declared type | `json`/`jsonb` codecs registered on connect, both directions |
+| mysql.connector | Native, both directions | Serialized on the way in; `MySQLResult` decodes columns the server reports as `json` |
+| sqlite3 | `DATETIME`/`TIMESTAMP`/`DATE` adapters and converters registered by `SQLiteAdapter` | `JSON`/`JSONB` adapters and converters |
+
+SQLite stores only primitives, so `SQLiteAdapter` registers custom datatypes with the `sqlite3` module and opens its connections with `detect_types=sqlite3.PARSE_DECLTYPES`. Conversion is keyed off the column's *declared* type, so a `DATETIME` or `JSON` table column is converted while an expression (`count(*)`, a computed alias) has no declared type and is returned as-is. Datetimes are written as full ISO-8601, so microseconds and UTC offsets survive the round trip.
+
+### PostgreSQL arrays — `PostgresArray`
+
+A bare `list` is a JSON document on **every** dialect, PostgreSQL included. PostgreSQL also has a real array type, but nothing in the value itself says which of the two is meant, so the array reading is opt-in — wrap the value in `PostgresArray`:
+
+```python
+from flowmaticdb import PostgresArray
+
+db.insert("rows").values({
+    "id": 1,
+    "actual_json_column": [1, 2, 3, 4],
+    "postgres_array_column": PostgresArray([5, 6, 7, 8]),
+}).execute()
+
+# Also works anywhere else a value is bound, e.g. the array containment operators
+db.select("rows").where_operator("tags", "@>", PostgresArray(["a", "b"])).execute()
+```
+
+Both PostgreSQL drivers behave identically here: a bare list aimed at an array column is sent as JSON and rejected, rather than quietly being taken as an array. Element types are left to the driver, so `PostgresArray([datetime(...)])` binds as `timestamptz[]`, not `text[]`.
+
+Dialects with no array type unwrap `PostgresArray` back to JSON, so a query written for PostgreSQL still runs against SQLite and MySQL.
+
+Reading is unaffected — an array column always comes back as a plain `list`.
+
+---
+
 ## Dialect-Specific Behavior
 
 ### PostgreSQL
@@ -751,7 +816,9 @@ except DatabaseError as e:
 | Regex | ✅ | `regexp_like()` (≥ 15) or `~`/`!~` operators |
 | `GENERATED BY DEFAULT AS IDENTITY` | ✅ | (≥ 17, or falls back to `SERIAL`) |
 | Native boolean | ✅ | `BOOLEAN` type |
-| Datetime | ✅ | Microsecond precision: `%Y-%m-%d %H:%M:%S.%f` |
+| Datetime | ✅ | Microsecond precision: `%Y-%m-%d %H:%M:%S.%f`; `TypeEnum.DATETIME` → `TIMESTAMPTZ` |
+| JSON | ✅ | `TypeEnum.JSON` → `JSONB` (≥ 9.4) or `JSON` (≥ 9.2); a bare `list`/`dict` is a document |
+| Arrays | ✅ | Opt-in via `PostgresArray([...])` — see [PostgreSQL arrays](#postgresql-arrays--postgresarray) |
 
 ### SQLite
 
@@ -766,6 +833,8 @@ except DatabaseError as e:
 | Named constraints | ❌ | Names stripped from constraints |
 | Auto-increment | ✅ | `INTEGER PRIMARY KEY AUTOINCREMENT` |
 | Case-insensitive LIKE | ✅ | Default SQLite behavior |
+| Datetime | ✅ | Custom `DATETIME`/`TIMESTAMP`/`DATE` datatype via `sqlite3` adapters and converters |
+| JSON | ✅ | Custom `JSON`/`JSONB` datatype via `sqlite3` adapters and converters |
 
 ### MySQL
 
@@ -775,6 +844,8 @@ except DatabaseError as e:
 | `RETURNING` | ❌ | Not supported; emulation not implemented |
 | Auto-increment | ✅ | `AUTO_INCREMENT` |
 | Placeholders | ✅ | `?` → `%s` conversion for connector |
+| Datetime | ✅ | `TypeEnum.DATETIME` → `DATETIME(size)`, fsp clamped to 6 |
+| JSON | ✅ | `TypeEnum.JSON` → `JSON` (MySQL ≥ 5.7.8, MariaDB ≥ 10.2.7), else `TEXT` |
 
 ### General ANSI (SQLDialect base)
 
@@ -895,7 +966,7 @@ from flowmaticdb.query.enums import UnionEnum
 # UNION, UNION ALL
 
 from flowmaticdb.query.enums import TypeEnum
-# BOOL, INT, FLOAT, STRING, DATETIME
+# BOOL, INT, FLOAT, STRING, DATETIME, JSON
 
 from flowmaticdb.query.enums import ReferentialActionEnum
 # ON_UPDATE_NO_ACTION, ON_UPDATE_SET_NULL, ON_UPDATE_CASCADE,
@@ -909,6 +980,7 @@ from flowmaticdb.query.enums import ReferentialActionEnum
 A leading underscore on a module name marks it as a private implementation detail — never import from it directly. Each package's public API is exactly its `__init__.py` `__all__`; import from the package instead. This holds without exception, including the exception classes and helper functions, which live in `_exceptions.py` and `_helpers.py` and are re-exported from `flowmaticdb`.
 
 - `PsycopgAdapter`, `MySQLAdapter` — Import from `flowmaticdb.adapters`, NOT a submodule
+- `PostgresArray` — Re-exported from the top-level package: `from flowmaticdb import PostgresArray` (it also lives in `flowmaticdb.query.expressions`)
 - `PsycopgResult`, `MySQLResult` — Import from `flowmaticdb.result`, NOT a submodule
 - `raw()`, `identifier()`, `alias()`, `expression()`, `sub_query()`, `current_timestamp()`, `now()` — Module-level functions, imported from `flowmaticdb`
 - `snapshot_result()` — Import from `flowmaticdb.result`

{flowmaticdb-2.2.2 → flowmaticdb-2.3.0}/README.md

@@ -237,6 +237,7 @@ db.create_table("users").if_not_exists() \
     .integer("age") \
     .boolean("active", default=True) \
     .datetime("created_at") \
+    .json("preferences") \
     .execute()
 
 # Using raw column definitions
@@ -615,6 +616,7 @@ from flowmaticdb import raw, identifier, alias, expression, sub_query, current_t
 | `sub_query(query, alias)` | `(SELECT ...) AS alias` | `sub_query(select_q, "sq")` |
 | `current_timestamp()` | `CURRENT_TIMESTAMP` | `current_timestamp()` |
 | `now()` | `datetime.now(UTC)` | `now()` |
+| `PostgresArray(values)` | Bind a list as a PostgreSQL array instead of JSON | `PostgresArray([1, 2, 3])` |
 
 ```python
 db.select(raw("COUNT(*) AS cnt")).table("users").execute()
@@ -701,6 +703,69 @@ except DatabaseError as e:
 
 ---
 
+## Datetime and JSON Values
+
+`datetime` objects and JSON documents are serialized on the way into the database and deserialized on the way back out, on every adapter.
+
+```python
+from datetime import datetime, timezone
+
+db.create_table("events").if_not_exists() \
+    .identity("id") \
+    .datetime("happened_at") \
+    .json("payload") \
+    .execute()
+
+db.insert("events").values({
+    "happened_at": datetime.now(timezone.utc),
+    "payload": {"kind": "signup", "tags": ["a", "b"]},
+}).execute()
+
+row = db.select("events").execute().fetch_dict()
+row["happened_at"]   # datetime
+row["payload"]       # dict
+```
+
+`TypeEnum.JSON` (the `.json()` column builder) maps to the best type the server has: `JSONB` on PostgreSQL ≥ 9.4, `JSON` on PostgreSQL ≥ 9.2, MySQL ≥ 5.7.8, MariaDB ≥ 10.2.7 and SQLite, and `TEXT` on anything older. `TypeEnum.DATETIME` maps to `TIMESTAMPTZ`, `DATETIME(6)` and `DATETIME` respectively.
+
+Nested values `json` does not know are rendered rather than raising: `datetime`, `date` and `time` become ISO-8601 strings, `Decimal` becomes a string (a float would lose precision). A JSON column holding text that is not valid JSON is handed back as that text instead of failing the fetch.
+
+How each driver is wired up:
+
+| Driver | Datetime | JSON |
+|--------|----------|------|
+| psycopg | Native, both directions | Serialized on the way in; psycopg decodes `json`/`jsonb` on the way out |
+| asyncpg | Bound natively, reconciled against the placeholder's declared type | `json`/`jsonb` codecs registered on connect, both directions |
+| mysql.connector | Native, both directions | Serialized on the way in; `MySQLResult` decodes columns the server reports as `json` |
+| sqlite3 | `DATETIME`/`TIMESTAMP`/`DATE` adapters and converters registered by `SQLiteAdapter` | `JSON`/`JSONB` adapters and converters |
+
+SQLite stores only primitives, so `SQLiteAdapter` registers custom datatypes with the `sqlite3` module and opens its connections with `detect_types=sqlite3.PARSE_DECLTYPES`. Conversion is keyed off the column's *declared* type, so a `DATETIME` or `JSON` table column is converted while an expression (`count(*)`, a computed alias) has no declared type and is returned as-is. Datetimes are written as full ISO-8601, so microseconds and UTC offsets survive the round trip.
+
+### PostgreSQL arrays — `PostgresArray`
+
+A bare `list` is a JSON document on **every** dialect, PostgreSQL included. PostgreSQL also has a real array type, but nothing in the value itself says which of the two is meant, so the array reading is opt-in — wrap the value in `PostgresArray`:
+
+```python
+from flowmaticdb import PostgresArray
+
+db.insert("rows").values({
+    "id": 1,
+    "actual_json_column": [1, 2, 3, 4],
+    "postgres_array_column": PostgresArray([5, 6, 7, 8]),
+}).execute()
+
+# Also works anywhere else a value is bound, e.g. the array containment operators
+db.select("rows").where_operator("tags", "@>", PostgresArray(["a", "b"])).execute()
+```
+
+Both PostgreSQL drivers behave identically here: a bare list aimed at an array column is sent as JSON and rejected, rather than quietly being taken as an array. Element types are left to the driver, so `PostgresArray([datetime(...)])` binds as `timestamptz[]`, not `text[]`.
+
+Dialects with no array type unwrap `PostgresArray` back to JSON, so a query written for PostgreSQL still runs against SQLite and MySQL.
+
+Reading is unaffected — an array column always comes back as a plain `list`.
+
+---
+
 ## Dialect-Specific Behavior
 
 ### PostgreSQL
@@ -715,7 +780,9 @@ except DatabaseError as e:
 | Regex | ✅ | `regexp_like()` (≥ 15) or `~`/`!~` operators |
 | `GENERATED BY DEFAULT AS IDENTITY` | ✅ | (≥ 17, or falls back to `SERIAL`) |
 | Native boolean | ✅ | `BOOLEAN` type |
-| Datetime | ✅ | Microsecond precision: `%Y-%m-%d %H:%M:%S.%f` |
+| Datetime | ✅ | Microsecond precision: `%Y-%m-%d %H:%M:%S.%f`; `TypeEnum.DATETIME` → `TIMESTAMPTZ` |
+| JSON | ✅ | `TypeEnum.JSON` → `JSONB` (≥ 9.4) or `JSON` (≥ 9.2); a bare `list`/`dict` is a document |
+| Arrays | ✅ | Opt-in via `PostgresArray([...])` — see [PostgreSQL arrays](#postgresql-arrays--postgresarray) |
 
 ### SQLite
 
@@ -730,6 +797,8 @@ except DatabaseError as e:
 | Named constraints | ❌ | Names stripped from constraints |
 | Auto-increment | ✅ | `INTEGER PRIMARY KEY AUTOINCREMENT` |
 | Case-insensitive LIKE | ✅ | Default SQLite behavior |
+| Datetime | ✅ | Custom `DATETIME`/`TIMESTAMP`/`DATE` datatype via `sqlite3` adapters and converters |
+| JSON | ✅ | Custom `JSON`/`JSONB` datatype via `sqlite3` adapters and converters |
 
 ### MySQL
 
@@ -739,6 +808,8 @@ except DatabaseError as e:
 | `RETURNING` | ❌ | Not supported; emulation not implemented |
 | Auto-increment | ✅ | `AUTO_INCREMENT` |
 | Placeholders | ✅ | `?` → `%s` conversion for connector |
+| Datetime | ✅ | `TypeEnum.DATETIME` → `DATETIME(size)`, fsp clamped to 6 |
+| JSON | ✅ | `TypeEnum.JSON` → `JSON` (MySQL ≥ 5.7.8, MariaDB ≥ 10.2.7), else `TEXT` |
 
 ### General ANSI (SQLDialect base)
 
@@ -859,7 +930,7 @@ from flowmaticdb.query.enums import UnionEnum
 # UNION, UNION ALL
 
 from flowmaticdb.query.enums import TypeEnum
-# BOOL, INT, FLOAT, STRING, DATETIME
+# BOOL, INT, FLOAT, STRING, DATETIME, JSON
 
 from flowmaticdb.query.enums import ReferentialActionEnum
 # ON_UPDATE_NO_ACTION, ON_UPDATE_SET_NULL, ON_UPDATE_CASCADE,
@@ -873,6 +944,7 @@ from flowmaticdb.query.enums import ReferentialActionEnum
 A leading underscore on a module name marks it as a private implementation detail — never import from it directly. Each package's public API is exactly its `__init__.py` `__all__`; import from the package instead. This holds without exception, including the exception classes and helper functions, which live in `_exceptions.py` and `_helpers.py` and are re-exported from `flowmaticdb`.
 
 - `PsycopgAdapter`, `MySQLAdapter` — Import from `flowmaticdb.adapters`, NOT a submodule
+- `PostgresArray` — Re-exported from the top-level package: `from flowmaticdb import PostgresArray` (it also lives in `flowmaticdb.query.expressions`)
 - `PsycopgResult`, `MySQLResult` — Import from `flowmaticdb.result`, NOT a submodule
 - `raw()`, `identifier()`, `alias()`, `expression()`, `sub_query()`, `current_timestamp()`, `now()` — Module-level functions, imported from `flowmaticdb`
 - `snapshot_result()` — Import from `flowmaticdb.result`

{flowmaticdb-2.2.2 → flowmaticdb-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flowmaticdb"
-version = "2.2.2"
+version = "2.3.0"
 description = "A Python database abstraction layer supporting PostgreSQL, SQLite, and MySQL."
 readme = "README.md"
 requires-python = ">=3.11"

{flowmaticdb-2.2.2 → flowmaticdb-2.3.0}/src/flowmaticdb/__init__.py

@@ -11,11 +11,13 @@ from flowmaticdb._helpers import (
     sub_query,
 )
 from flowmaticdb._query_with_params import QueryWithParams
+from flowmaticdb.query.expressions import PostgresArray
 
 __all__ = [
     "AdapterError",
     "DatabaseError",
     "DriverError",
+    "PostgresArray",
     "QueryError",
     "QueryWithParams",
     "QueryWithParamsError",

flowmaticdb-2.3.0/src/flowmaticdb/_json.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import json
+from datetime import date, datetime
+from datetime import time as time_of_day
+from decimal import Decimal
+from typing import Any
+
+
+def _encode_fallback(value: Any) -> Any:
+    """Render the values a database document commonly carries but ``json`` does
+    not know: temporals as ISO-8601, decimals as strings (a float would silently
+    lose precision)."""
+    if isinstance(value, (datetime, date, time_of_day)):
+        return value.isoformat()
+    if isinstance(value, Decimal):
+        return str(value)
+    raise TypeError(f"object of type {type(value).__name__} is not JSON serializable")
+
+
+def encode_json(value: Any) -> str:
+    return json.dumps(value, default=_encode_fallback)
+
+
+def decode_json(value: Any) -> Any:
+    if isinstance(value, (bytes, bytearray)):
+        value = value.decode("utf-8")
+    if not isinstance(value, str):
+        return value
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError:
+        # A JSON column can hold text written outside this library (or by a
+        # driver that already decoded it); hand it back rather than failing the
+        # whole fetch.
+        return value

{flowmaticdb-2.2.2 → flowmaticdb-2.3.0}/src/flowmaticdb/adapters/_postgres.py

@@ -10,8 +10,10 @@ from datetime import time as time_of_day
 from typing import TYPE_CHECKING, Any, TypeVar
 
 from flowmaticdb import AdapterError
+from flowmaticdb._json import decode_json, encode_json
 from flowmaticdb._query_with_params import REGEX_PATTERN
 from flowmaticdb.adapters._base import AdapterABC
+from flowmaticdb.query.expressions import PostgresArray
 from flowmaticdb.result import AsyncpgResult, PsycopgResult, ResultABC
 
 if TYPE_CHECKING:
@@ -47,6 +49,9 @@ def _placeholders_to_dollar_signs(query: str) -> str:
 # Placeholder types PostgreSQL resolves to a string.
 _TEXT_TYPE_OIDS = frozenset({18, 19, 25, 705, 1042, 1043})
 
+# Placeholder types the json/jsonb codecs registered in _open() encode.
+_JSON_TYPE_OIDS = frozenset({114, 3802})
+
 
 def _cast_param(dialect: DialectABC, value: Any) -> Any:
     # asyncpg binds in the binary protocol against the type PostgreSQL declared for
@@ -55,12 +60,18 @@ def _cast_param(dialect: DialectABC, value: Any) -> Any:
     # reconciled against the real placeholder type in _adapt_params().
     if isinstance(value, (datetime, date, time_of_day)):
         return value
+    # Documents and arrays are left native for the same reason: whether a dict or
+    # list has to be rendered depends on the placeholder type, which is only
+    # known once the statement is prepared.
+    if isinstance(value, (dict, list, PostgresArray)):
+        return value
     return dialect.cast_to_driver(value)
 
 
 def _adapt_params(dialect: DialectABC, parameter_types: Sequence[Any], params: list[Any]) -> list[Any]:
-    """Render temporal values bound to a text placeholder, using the prepared
-    statement's parameter types — the only point where the target type is known.
+    """Render temporal and document values bound to a text placeholder, using the
+    prepared statement's parameter types — the only point where the target type
+    is known.
 
     psycopg can hand PostgreSQL a datetime for a text column and let the server
     render it; asyncpg encodes binary against the declared type and refuses, so
@@ -77,8 +88,20 @@ def _adapt_params(dialect: DialectABC, parameter_types: Sequence[Any], params: l
 
 
 def _adapt_param(dialect: DialectABC, oid: int, value: Any) -> Any:
-    if oid in _TEXT_TYPE_OIDS and isinstance(value, (datetime, date, time_of_day)):
-        return dialect.cast_datetime(value)
+    if isinstance(value, PostgresArray):
+        # Explicitly an array: asyncpg binds a native list as one.
+        return list(value.values)
+
+    if isinstance(value, (datetime, date, time_of_day)):
+        return dialect.cast_datetime(value) if oid in _TEXT_TYPE_OIDS else value
+
+    if isinstance(value, (dict, list)):
+        # A document reaches the json/jsonb codecs untouched and is rendered
+        # anywhere else. That also means a bare list bound to an array column is
+        # handed over as JSON and rejected, rather than quietly becoming an
+        # array -- the same outcome as psycopg, which cannot tell them apart.
+        return value if oid in _JSON_TYPE_OIDS else dialect.cast_json(value)
+
     return value
 
 
@@ -345,7 +368,21 @@ class AsyncpgAdapter(AdapterABC):
     async def _open(self, connect_options: dict[str, Any]) -> AsyncpgConnection:
         import asyncpg
 
-        return await asyncpg.connect(**connect_options)
+        connection: AsyncpgConnection = await asyncpg.connect(**connect_options)
+
+        # asyncpg hands json/jsonb over as raw text unless a codec says otherwise.
+        # These make dicts and lists bind to a json column and come back decoded,
+        # matching what psycopg does out of the box.
+        for type_name in ("json", "jsonb"):
+            await connection.set_type_codec(
+                type_name,
+                encoder=encode_json,
+                decoder=decode_json,
+                schema="pg_catalog",
+                format="text",
+            )
+
+        return connection
 
     async def _fetch(self, query: str) -> AsyncpgResult:
         statement = await self._connection.prepare(query)

{flowmaticdb-2.2.2 → flowmaticdb-2.3.0}/src/flowmaticdb/adapters/_sqlite.py

@@ -3,8 +3,10 @@ from __future__ import annotations
 import sqlite3
 import time
 from collections.abc import Callable
+from datetime import date, datetime
 from typing import TYPE_CHECKING, Any
 
+from flowmaticdb._json import decode_json, encode_json
 from flowmaticdb.adapters._base import AdapterABC
 from flowmaticdb.result import ResultABC, SQLite3Result
 
@@ -13,6 +15,73 @@ if TYPE_CHECKING:
     from flowmaticdb.dialects import DialectABC
 
 
+def _adapt_datetime(value: datetime) -> str:
+    """ISO-8601 with a space separator: keeps microseconds and the UTC offset
+    (both of which the dialect's SQL-literal format drops) while staying
+    readable to SQLite's own date/time functions."""
+    return value.isoformat(sep=" ")
+
+
+def _adapt_date(value: date) -> str:
+    return value.isoformat()
+
+
+def _adapt_json(value: dict[str, Any] | list[Any]) -> str:
+    return encode_json(value)
+
+
+def _convert_datetime(value: bytes) -> datetime | str:
+    text = value.decode("utf-8")
+    try:
+        return datetime.fromisoformat(text)
+    except ValueError:
+        # A DATETIME column can hold anything SQLite accepted -- an epoch
+        # number or a partial date written by another tool. Return it as text
+        # rather than failing the fetch.
+        return text
+
+
+def _convert_date(value: bytes) -> date | str:
+    text = value.decode("utf-8")
+    try:
+        return date.fromisoformat(text)
+    except ValueError:
+        return text
+
+
+def _convert_json(value: bytes) -> Any:
+    return decode_json(value)
+
+
+def _register_types() -> None:
+    """Teach ``sqlite3`` the DATETIME/DATE and JSON column types SQLite itself
+    does not have, in both directions.
+
+    The ``sqlite3`` registry is a process-wide module singleton, so this is
+    global state -- but the converters only fire on connections opened with
+    ``PARSE_DECLTYPES``, which is exactly the connections this adapter opens.
+    Registering is idempotent (each call overwrites the same registry entry),
+    so it runs per connect instead of at import time.
+    """
+    sqlite3.register_adapter(datetime, _adapt_datetime)
+    sqlite3.register_adapter(date, _adapt_date)
+    sqlite3.register_adapter(dict, _adapt_json)
+    sqlite3.register_adapter(list, _adapt_json)
+    sqlite3.register_converter("DATETIME", _convert_datetime)
+    sqlite3.register_converter("TIMESTAMP", _convert_datetime)
+    sqlite3.register_converter("DATE", _convert_date)
+    sqlite3.register_converter("JSON", _convert_json)
+    sqlite3.register_converter("JSONB", _convert_json)
+
+
+def _cast_param(dialect: DialectABC, value: Any) -> Any:
+    """Temporals and documents are left native so the registered ``sqlite3``
+    adapters above serialize them; everything else goes through the dialect."""
+    if isinstance(value, (datetime, date, dict, list)):
+        return value
+    return dialect.cast_to_driver(value)
+
+
 class SQLiteAdapter(AdapterABC):
     def __init__(
         self,
@@ -32,14 +101,23 @@ class SQLiteAdapter(AdapterABC):
         self._connect()
 
     def _connect(self) -> None:
+        _register_types()
+
         db_name = self._database_name
         read_only = self._options.get("read_only", False)
 
+        # PARSE_DECLTYPES is what routes a column declared DATETIME or JSON
+        # through the converters registered above. Columns that are expressions
+        # rather than table columns have no declared type and stay untouched.
         if read_only:
             uri = f"file:{db_name}?mode=ro"
-            self._connection = sqlite3.connect(uri, uri=True, isolation_level=None)
+            self._connection = sqlite3.connect(
+                uri, uri=True, isolation_level=None, detect_types=sqlite3.PARSE_DECLTYPES
+            )
         else:
-            self._connection = sqlite3.connect(db_name, isolation_level=None)
+            self._connection = sqlite3.connect(
+                db_name, isolation_level=None, detect_types=sqlite3.PARSE_DECLTYPES
+            )
 
         self._connection.row_factory = sqlite3.Row
 
@@ -112,7 +190,7 @@ class SQLiteAdapter(AdapterABC):
     ) -> ResultABC:
         query_with_params = query_with_params.percent_s_to_question_marks()
         sql = query_with_params.query
-        params = [dialect.cast_to_driver(param) for param in query_with_params.params]
+        params = [_cast_param(dialect, param) for param in query_with_params.params]
 
         start = time.time()
         error: str | None = None

{flowmaticdb-2.2.2 → flowmaticdb-2.3.0}/src/flowmaticdb/dialects/_base.py

@@ -169,6 +169,10 @@ class DialectABC(ABC):
     def cast_datetime(self, value: Any) -> str:
         ...
 
+    @abstractmethod
+    def cast_json(self, value: Any) -> str:
+        ...
+
     @abstractmethod
     def cast_to_driver(self, value: Any) -> Any:
         ...
@@ -181,6 +185,10 @@ class DialectABC(ABC):
     def parse_datetime(self, value: Any) -> Any:
         ...
 
+    @abstractmethod
+    def parse_json(self, value: Any) -> Any:
+        ...
+
     @abstractmethod
     def type(self, type_enum: TypeEnum, bits: int | None = None) -> str:
         ...

{flowmaticdb-2.2.2 → flowmaticdb-2.3.0}/src/flowmaticdb/dialects/_mysql.py

@@ -51,6 +51,9 @@ class MySQLDialect(SQLDialect):
         self.lateral = (not self._is_mariadb) and self._version >= 80014
         self.on_conflict = True if self._is_mariadb else self._version >= 40100
         self.returning = self._is_mariadb and self._version >= 100500
+        # MariaDB spells JSON as a LONGTEXT alias from 10.2.7; MySQL has a real
+        # native JSON type from 5.7.8. Older servers fall back to TEXT.
+        self.json = self._version >= 100207 if self._is_mariadb else self._version >= 50708
 
     def begin_transaction(self, name: str | None = None) -> QueryWithParams:
         return QueryWithParams(query="START TRANSACTION")

{flowmaticdb-2.2.2 → flowmaticdb-2.3.0}/src/flowmaticdb/dialects/_postgres.py

@@ -10,6 +10,7 @@ from flowmaticdb.dialects._sql_dialect import SQLDialect
 from flowmaticdb.query import Condition, OnConflict
 from flowmaticdb.query.ddl import Column
 from flowmaticdb.query.enums import ConditionEnum, TypeEnum
+from flowmaticdb.query.expressions import PostgresArray
 
 _TZ_OFFSET_RE = re.compile(r"([+-]\d{2})$")
 
@@ -48,6 +49,8 @@ class PostgresqlDialect(SQLDialect):
         self.on_conflict = v >= 90500
         self.generated_by_default_as_identity = v >= 170000
         self.returning = v >= 80200
+        self.json = v >= 90200
+        self.jsonb = v >= 90400
 
     def _build_on_conflict(
         self,
@@ -118,8 +121,26 @@ class PostgresqlDialect(SQLDialect):
         if isinstance(value, bool):
             return "TRUE" if value else "FALSE"
 
+        if isinstance(value, PostgresArray):
+            if not value.values:
+                return "'{}'"
+            items = ", ".join(self.cast_to_query(item) for item in value.values)
+            return f"ARRAY[{items}]"
+
         return super().cast_to_query(value)
 
+    def cast_to_driver(self, value: Any) -> Any:
+        # PostgreSQL is the one supported engine with a real array type, and both
+        # drivers bind a Python list as one -- which is exactly why the array
+        # reading has to be asked for. A bare list stays a JSON document (base
+        # behaviour); only PostgresArray is unwrapped for the driver to bind as
+        # an array. Element types are left alone so the driver types them
+        # natively (a list of datetimes becomes timestamptz[], not text[]).
+        if isinstance(value, PostgresArray):
+            return list(value.values)
+
+        return super().cast_to_driver(value)
+
     def cast_bool(self, value: bool) -> bool | int:
         return value
 
@@ -150,4 +171,6 @@ class PostgresqlDialect(SQLDialect):
             return "DOUBLE PRECISION" if size > 32 else "REAL"
         if type_enum == TypeEnum.DATETIME:
             return "TIMESTAMPTZ"
+        if type_enum == TypeEnum.JSON and self.jsonb:
+            return "JSONB"
         return super().type(type_enum, bits)