mainsequence-metatable 0.1.61.dev92__tar.gz → 0.1.62.dev93__tar.gz

{mainsequence_metatable-0.1.61.dev92 → mainsequence_metatable-0.1.62.dev93}/.agents/skills/client/metatables-meta-tables/SKILL.md

@@ -176,6 +176,10 @@ label=...)`; a miss rolls back and raises `MetaTableTransactionGuardError`. Neve
 put `COMMIT` or savepoints in a list. PostgreSQL and SQLite only; see the query
 guide's "Several statements in one transaction".
 
+Select or return `Uuid` columns typed, not cast to text: compiled `Uuid` results come
+back dashed on every engine, while a `CAST` or untyped SQL returns SQLite's stored hex.
+Do not reformat uids in the application to paper over engine differences.
+
 To find tables, use `MetaTable.search` as described in the
 [table discovery skill](../metatables-table-discovery/SKILL.md). Legacy convenience
 sharing/label actions are not supported API workflows.

{mainsequence_metatable-0.1.61.dev92/src/mainsequence_metatable.egg-info → mainsequence_metatable-0.1.62.dev93}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.61.dev92
+Version: 0.1.62.dev93
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

mainsequence_metatable-0.1.62.dev93/docs/adr/api/0027-compiled-sql-result-types.md

@@ -0,0 +1,60 @@
+# ADR 0027: Compiled SQL declares its Uuid result columns
+
+Status: Accepted.
+
+Implementation status: implemented on development for 0.1.62. SQLite is tested in
+process and through the local API. PostgreSQL, MySQL and SQL Server have not been run.
+
+Owner: MetaTables API, with the Python client.
+
+Related decisions: [ADR 0007](0007-database-enforced-table-access.md) (the API runs
+caller SQL as it is and does not parse it) and
+[ADR 0026](0026-atomic-statement-lists.md) (statement lists).
+Issue: [MetaTables#103](https://github.com/mainsequence-projects/MetaTables/issues/103).
+
+## Context
+
+SQLAlchemy stores a `Uuid` column as `uuid` on PostgreSQL and as 32 hex characters
+(`CHAR(32)`) on SQLite and MySQL. PostgreSQL returns a uuid, which the API renders as
+dashed text. SQLite returns the stored hex, and the API passed it on unchanged. The
+same compiled statement therefore returned `95dcdfeb-f8c0-…` on a hosted runtime and
+`95dcdfebf8c0…` on the local one. SQLAlchemy's own result processor would convert the
+hex, but compiled SQL runs without it.
+
+The API cannot tell a `Uuid` column from any other `CHAR(32)`, and an expression such
+as a `CAST` has no declared type in the database. Converting every 32-character value,
+or every value that looks like a UUID, would change text that is not one.
+
+## Decision
+
+The compiled statement names its `Uuid` result columns, and the API renders them.
+
+- `compile_sqlalchemy_statement` and `compile_sqlalchemy_statements` record each
+  result column whose SQLAlchemy type is `Uuid` in the statement's `result_types`,
+  under the name the database returns it as: `{"uid": "uuid"}`. That covers
+  `SELECT`, `RETURNING` and `text(...).columns(...)`, and names such as `uid_1` for a
+  second `uid`.
+- The API returns each `"uuid"` column as lowercase dashed text, `str(uuid.UUID(value))`,
+  on every engine. Text that is not a UUID and `NULL` return unchanged. In a statement
+  list, the last statement's `result_types` apply to the rows returned.
+- `"uuid"` is the only result type. The API refuses others with 422, as it refuses
+  any unknown field.
+- Only the compiler's types decide. A `CAST` to text, SQL sent to `run_query` and
+  other SQL without SQLAlchemy types return what the database returns.
+
+A statement with no `Uuid` result columns sends no `result_types`, so its request body
+is unchanged.
+
+## Alternatives
+
+- **A `CHAR(32)` converter in SQLite.** Converts every such column, `Uuid` or not.
+- **Converting text that looks like a UUID.** Guesses from the data.
+- **Converting in the client.** Raw HTTP callers and the API's own response would
+  still differ by engine.
+
+## Consequences
+
+- A `Uuid` column returns the same text from the local runtime as from a hosted
+  PostgreSQL runtime.
+- An API before 0.1.62 refuses a request that carries `result_types` with 422. Deploy
+  the API before clients send `Uuid` result columns to it.

{mainsequence_metatable-0.1.61.dev92 → mainsequence_metatable-0.1.62.dev93}/docs/adr/index.md

@@ -44,6 +44,7 @@ decisions belong in the SDK repository and are linked as dependencies.
 | [0023: A daily security check instead of a sweep in every deployment](api/0023-daily-security-check.md) | Accepted; implemented on development; deployment and first scheduled run pending | A deployment sets up only what the new release needs; a daily Job, which administrators can also start, repairs whatever differs from the plan without pausing caller SQL and records its outcome. |
 | [0024: Access roles for namespaces and tables](api/0024-namespace-and-table-access-roles.md) | Accepted; implemented on development (API and Admin); hosted deployment pending | Actions and roles (`metadata_viewer`, `data_viewer`, `data_writer`, `editor`, `owner`) replace Reader/Writer; `namespaces.create` and `tables.create` are checked on the parent, the creator of a namespace owns it, admins hold every action, workloads use access but never manage it, and an ordinary user deploys a new application without an admin. |
 | [0026: Atomic statement lists](api/0026-atomic-statement-lists.md) | Accepted; implemented on development for 0.1.60; SQLite tested, PostgreSQL not yet run | A write may carry up to 32 compiled statements that the API runs in order in one transaction it owns, with optional row expectations; each statement is sent alone and the driver must report the transaction still open after it, so ADR 0007's boundary holds without parsing SQL. PostgreSQL and SQLite only. |
+| [0027: Compiled SQL declares its Uuid result columns](api/0027-compiled-sql-result-types.md) | Accepted; implemented on development for 0.1.62; SQLite tested, other engines not yet run | The compiler names a statement's `Uuid` result columns in `result_types` and the API returns them as dashed text on every engine, as PostgreSQL does; only declared types decide, never the stored text. |
 
 ## Agents
 

{mainsequence_metatable-0.1.61.dev92 → mainsequence_metatable-0.1.62.dev93}/docs/api/openapi.json

@@ -3892,6 +3892,21 @@
             "title": "Paramstyle",
             "type": "string"
           },
+          "result_types": {
+            "anyOf": [
+              {
+                "additionalProperties": {
+                  "const": "uuid",
+                  "type": "string"
+                },
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Result Types"
+          },
           "sql": {
             "maxLength": 1000000,
             "minLength": 1,
@@ -4705,6 +4720,21 @@
             "title": "Paramstyle",
             "type": "string"
           },
+          "result_types": {
+            "anyOf": [
+              {
+                "additionalProperties": {
+                  "const": "uuid",
+                  "type": "string"
+                },
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Result Types"
+          },
           "sql": {
             "maxLength": 1000000,
             "minLength": 1,

{mainsequence_metatable-0.1.61.dev92 → mainsequence_metatable-0.1.62.dev93}/docs/client/query-and-mutate.md

@@ -54,6 +54,14 @@ constraints to identify the same row. Temporal parameters carry type information
 For PostgreSQL inserts, the compiler replaces an explicit `None` UUID primary key
 with `DEFAULT`; the database must define that default.
 
+A `Uuid` value binds as a `uuid.UUID` or as text, dashed or not; on SQLite and MySQL,
+text that is not a UUID raises `ValueError` naming the parameter. A `Uuid` result
+column returns as lowercase dashed text on every engine, although SQLite and MySQL
+store 32 hex characters: the compiler names those columns in the statement's
+`result_types` and the API renders them ([ADR 0027](../adr/api/0027-compiled-sql-result-types.md)).
+A `CAST` to text and SQL without SQLAlchemy types, such as `run_query`, return what
+the database stores.
+
 `table.run_query(sql)` submits a read-only request using that table's DataSource.
 It can query any table you can read in the same runtime. Compiled operations with
 `operation="select"` also use the read identity; insert/update/upsert/delete select

{mainsequence_metatable-0.1.61.dev92 → mainsequence_metatable-0.1.62.dev93}/mkdocs.yml

@@ -90,6 +90,7 @@ nav:
           - "0023: Daily security check": adr/api/0023-daily-security-check.md
           - "0024: Namespace and table access roles": adr/api/0024-namespace-and-table-access-roles.md
           - "0026: Atomic statement lists": adr/api/0026-atomic-statement-lists.md
+          - "0027: Compiled SQL result types": adr/api/0027-compiled-sql-result-types.md
       - Agents:
           - "0019: MetaTables Analyst agent": adr/agent/0019-metatables-analyst-agent.md
           - "0020: The Analyst reads as its requester": adr/agent/0020-analyst-reads-as-its-requester.md

{mainsequence_metatable-0.1.61.dev92 → mainsequence_metatable-0.1.62.dev93}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mainsequence-metatable"
-version = "0.1.61.dev92"
+version = "0.1.62.dev93"
 description = "Main Sequence MetaTables Python client and standalone API"
 readme = "README.md"
 requires-python = ">=3.13"

{mainsequence_metatable-0.1.61.dev92 → mainsequence_metatable-0.1.62.dev93/src/mainsequence_metatable.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.61.dev92
+Version: 0.1.62.dev93
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence_metatable-0.1.61.dev92 → mainsequence_metatable-0.1.62.dev93}/src/mainsequence_metatable.egg-info/SOURCES.txt

@@ -50,6 +50,7 @@ docs/adr/api/0022-concurrent-requests-and-connection-reuse.md
 docs/adr/api/0023-daily-security-check.md
 docs/adr/api/0024-namespace-and-table-access-roles.md
 docs/adr/api/0026-atomic-statement-lists.md
+docs/adr/api/0027-compiled-sql-result-types.md
 docs/adr/client/0003-api-endpoint-resolution.md
 docs/adr/client/0011-cli-local-development-with-managed-admin.md
 docs/adr/client/0025-application-encrypted-columns.md
@@ -490,6 +491,7 @@ tests/contracts/capabilities.json
 tests/contracts/client_signatures.json
 tests/contracts/database_operations.json
 tests/contracts/test_bounded_transfer.py
+tests/contracts/test_compiled_result_types.py
 tests/contracts/test_compiled_statement_lists.py
 tests/contracts/test_compiler_runtime_source.py
 tests/contracts/test_encryption.py
@@ -566,6 +568,7 @@ tests/e2e/test_update_chunk_insert_client_api.py
 tests/e2e/test_update_dependency_priority_client_api.py
 tests/e2e/test_update_index_statistics_client_api.py
 tests/e2e/test_update_registration_client_api.py
+tests/e2e/test_uuid_results.py
 tests/examples/test_documented_examples.py
 tests/examples/test_postgresql_examples.py
 tests/examples/test_setup_launch.py
@@ -586,6 +589,7 @@ tests/integrations/test_source_validation.py
 tests/integrations/test_sqlite_expanded_in.py
 tests/integrations/test_sqlite_operations.py
 tests/integrations/test_sqlite_statement_lists.py
+tests/integrations/test_sqlite_uuid_results.py
 tests/labels/test_labels.py
 tests/operations/test_bootstrap_lock.py
 tests/operations/test_create_table_operation.py

{mainsequence_metatable-0.1.61.dev92 → mainsequence_metatable-0.1.62.dev93}/src/metatables/api/app/routes/table_sql.py

@@ -63,6 +63,8 @@ class Statement(BaseModel):
     sql: str = Field(min_length=1, max_length=1000000)
     parameters: dict[str, Any] | list[Any] = Field(default_factory=dict)
     parameter_types: dict[str, str] | None = None
+    # Result columns the API renders by type; "uuid" is dashed text on every engine (ADR 0027).
+    result_types: dict[str, Literal["uuid"]] | None = None
     paramstyle: Literal["pyformat", "named", "qmark"] = "pyformat"
 
 
@@ -157,6 +159,7 @@ def execute_operation(
         sql_text=payload.statement.sql,
         parameters=payload.statement.parameters,
         parameter_types=payload.statement.parameter_types,
+        result_types=payload.statement.result_types,
         **payload.limits.model_dump(),
     )
     result["data_source_uid"] = str(payload.data_source_uid)
@@ -217,7 +220,7 @@ def execute_transaction(
         operation=payload.operation,
         statements=[
             statement.model_dump(
-                include={"sql", "parameters", "parameter_types", "expect_rows", "label"}
+                include={"sql", "parameters", "parameter_types", "result_types", "expect_rows", "label"}
             )
             for statement in payload.statements
         ],

{mainsequence_metatable-0.1.61.dev92 → mainsequence_metatable-0.1.62.dev93}/src/metatables/api/backend/backends/operations.py

@@ -160,6 +160,7 @@ def execute_sql(
     operation="select",
     parameters=None,
     parameter_types=None,
+    result_types=None,
     max_rows=1000,
     offset=0,
     statement_timeout_ms=15000,
@@ -171,6 +172,7 @@ def execute_sql(
         operation=operation,
         parameters=parameters,
         parameter_types=parameter_types,
+        result_types=result_types,
         max_rows=max_rows,
         offset=offset,
         statement_timeout_ms=statement_timeout_ms,

{mainsequence_metatable-0.1.61.dev92 → mainsequence_metatable-0.1.62.dev93}/src/metatables/api/backend/backends/restricted_sql.py

@@ -38,6 +38,22 @@ def json_value(value):
     return value
 
 
+def typed_row(row, result_types):
+    """Render the result columns the compiler typed, whatever the engine returns (ADR 0027).
+
+    SQLite and MySQL return a ``Uuid`` as the 32 hex characters they store; a "uuid"
+    column returns dashed, as PostgreSQL's does. Text that is not a UUID returns unchanged.
+    """
+    for name, token in result_types.items():
+        value = row.get(name)
+        if token == "uuid" and isinstance(value, str):
+            try:
+                row[name] = str(UUID(value))
+            except ValueError:
+                pass
+    return row
+
+
 def parameters_for(values, types, dialect):
     values = dict(values or {}) if isinstance(values, dict) or values is None else list(values)
     for key, token in (types or {}).items():
@@ -126,12 +142,14 @@ class RestrictedSQL:
         operation="select",
         parameters=None,
         parameter_types=None,
+        result_types=None,
         max_rows=1000,
         offset=0,
         statement_timeout_ms=15000,
         raw_query=False,
     ):
-        statement = dict(sql=sql_text, parameters=parameters, parameter_types=parameter_types)
+        statement = dict(sql=sql_text, parameters=parameters, parameter_types=parameter_types,
+                         result_types=result_types)
         return self._run(identity, [statement], operation=operation, max_rows=max_rows,
                          offset=offset, statement_timeout_ms=statement_timeout_ms, transaction=False)
 
@@ -237,6 +255,7 @@ class RestrictedSQL:
                             rows, full, budget = [], False, PageBudget()
                             if cursor.description:
                                 names = [column[0] for column in cursor.description]
+                                result_types = statement.get("result_types") or {}
                                 remaining = offset
                                 while remaining:
                                     if fetchone() is None:
@@ -249,7 +268,7 @@ class RestrictedSQL:
                                         incomplete = False
                                         break
                                     seen += 1
-                                    row = json_value(dict(zip(names, row)))
+                                    row = json_value(typed_row(dict(zip(names, row)), result_types))
                                     try:
                                         fits = budget.add(row)
                                     except TransferError:

{mainsequence_metatable-0.1.61.dev92 → mainsequence_metatable-0.1.62.dev93}/src/metatables/compiled_sql/v1.py

@@ -33,6 +33,7 @@ def build_operation(
     sql: str,
     parameters: Mapping[str, Any] | Sequence[Any] | None = None,
     parameter_types: Mapping[str, str] | None = None,
+    result_types: Mapping[str, str] | None = None,
     data_source_uid: str,
     dialect: MetaTableCompiledSQLDialect = "postgresql",
     paramstyle: MetaTableCompiledSQLParamstyle = "pyformat",
@@ -55,6 +56,7 @@ def build_operation(
             sql=sql,
             parameters=statement_parameters,
             parameter_types=dict(parameter_types) if parameter_types is not None else None,
+            result_types=dict(result_types) if result_types else None,
             paramstyle=paramstyle,
         ),
         data_source_uid=data_source_uid,
@@ -146,7 +148,7 @@ def _compile(
     dialect: str,
     paramstyle: str,
     compile_kwargs: Mapping[str, Any] | None,
-) -> tuple[str, dict[str, Any] | list[Any], dict[str, str]]:
+) -> tuple[str, dict[str, Any] | list[Any], dict[str, str], dict[str, str]]:
     _refuse_data_modifying_ctes(statement, dialect)
     module = _DIALECTS[dialect][0]
     resolved_compile_kwargs = {"render_postcompile": True}
@@ -200,7 +202,7 @@ def _compile(
         order = compiled.positiontup or []
         parameters = [parameters[name] for name in order]
         parameter_types = {str(i): parameter_types[name] for i, name in enumerate(order) if name in parameter_types}
-    return str(compiled), parameters, parameter_types
+    return str(compiled), parameters, parameter_types, _compiled_result_types(compiled)
 
 
 @pin_api_endpoint
@@ -216,7 +218,7 @@ def compile_sqlalchemy_statement(
 ) -> MetaTableCompiledSQLOperation:
     """Compile SQLAlchemy SQL for the selected runtime DataSource."""
     data_source_uid, dialect, paramstyle = _resolve_target(data_source_uid, dialect, paramstyle)
-    sql, parameters, parameter_types = _compile(
+    sql, parameters, parameter_types, result_types = _compile(
         statement, dialect=dialect, paramstyle=paramstyle, compile_kwargs=compile_kwargs
     )
     return build_operation(
@@ -224,6 +226,7 @@ def compile_sqlalchemy_statement(
         sql=sql,
         parameters=parameters,
         parameter_types=parameter_types,
+        result_types=result_types,
         data_source_uid=data_source_uid,
         dialect=dialect,
         paramstyle=paramstyle,
@@ -268,13 +271,14 @@ def compile_sqlalchemy_statements(
         )
     compiled = []
     for step in steps:
-        sql, parameters, parameter_types = _compile(
+        sql, parameters, parameter_types, result_types = _compile(
             step.statement, dialect=dialect, paramstyle=paramstyle, compile_kwargs=compile_kwargs
         )
         compiled.append(MetaTableTransactionStatement(
             sql=sql,
             parameters=parameters,
             parameter_types=parameter_types or None,
+            result_types=result_types or None,
             paramstyle=paramstyle,
             expect_rows=step.expect_rows,
             label=step.label,
@@ -312,6 +316,24 @@ def _uuid_from_text(name: str, value: str):
         ) from None
 
 
+def _compiled_result_types(compiled: Any) -> dict[str, str]:
+    """The statement's ``Uuid`` result columns, by the name the database returns (ADR 0027).
+
+    SQLite and MySQL store a ``Uuid`` as 32 hex characters and return that text, while
+    PostgreSQL returns a uuid that the API renders dashed. The API renders the columns
+    named here dashed on every engine. Only declared types decide; the text never does.
+    """
+    from sqlalchemy import Uuid
+
+    # The rendered result names (uid_1 for a second uid, max_1 for an unlabeled max()),
+    # in the order the database returns them. SQLAlchemy offers no public accessor.
+    return {
+        entry.keyname: "uuid"
+        for entry in compiled._result_columns or ()
+        if isinstance(entry.type, Uuid)
+    }
+
+
 def _rendered_bind_types(compiled: Any, expansion: Mapping[str, Sequence[str]]):
     """Each rendered parameter's name with its bind's type, expanded IN values included.
 

{mainsequence_metatable-0.1.61.dev92 → mainsequence_metatable-0.1.62.dev93}/src/metatables/models.py

@@ -538,6 +538,9 @@ class MetaTableStatementPayload(BasePydanticModel):
     sql: str = Field(..., min_length=1)
     parameters: dict[str, Any] | list[Any] = Field(default_factory=dict)
     parameter_types: dict[str, str] | None = None
+    # Result columns, by the name the database returns them under, that the API renders
+    # by type: "uuid" returns dashed text on every engine, as PostgreSQL does (ADR 0027).
+    result_types: dict[str, Literal["uuid"]] | None = None
     paramstyle: MetaTableCompiledSQLParamstyle = "pyformat"
 
     @model_validator(mode="after")

mainsequence_metatable-0.1.62.dev93/tests/contracts/test_compiled_result_types.py

@@ -0,0 +1,61 @@
+"""The compiler names a statement's Uuid result columns for the API (ADR 0027, MetaTables #103)."""
+
+import pytest
+from pydantic import ValidationError
+from sqlalchemy import Column, MetaData, String, Table, Uuid, cast, insert, select, update
+
+from metatables import MetaTableCompiledSQLOperation
+from metatables.api.app.routes.table_sql import CompiledOperation, CompiledTransaction
+from metatables.compiled_sql.v1 import compile_sqlalchemy_statement, compile_sqlalchemy_statements
+from metatables.models import _payload_json
+
+UID = "00000000-0000-0000-0000-000000000001"
+item = Table(
+    "item", MetaData(),
+    Column("uid", Uuid(as_uuid=True), primary_key=True),
+    Column("parent_uid", Uuid(as_uuid=False)),
+    Column("name", String),
+)
+
+
+def compile(statement, dialect="sqlite", operation="select"):
+    return compile_sqlalchemy_statement(statement, operation=operation, data_source_uid=UID, dialect=dialect)
+
+
+@pytest.mark.parametrize("dialect", ["postgresql", "sqlite", "mysql", "mssql"])
+def test_uuid_result_columns_are_named_on_every_dialect(dialect):
+    statement = compile(select(item.c.uid, item.c.parent_uid, item.c.name), dialect).statement
+    assert statement.result_types == {"uid": "uuid", "parent_uid": "uuid"}
+    returning = insert(item).values(uid=None, name="x").returning(item.c.uid.label("key"))
+    assert compile(returning, dialect, "insert").statement.result_types == {"key": "uuid"}
+
+
+def test_only_uuid_typed_results_are_named():
+    assert compile(select(cast(item.c.uid, String).label("text"))).statement.result_types is None
+    assert compile(update(item).values(name="x"), operation="update").statement.result_types is None
+
+
+def test_a_statement_without_uuid_results_keeps_its_wire_form():
+    """APIs before 0.1.62 forbid unknown fields; only Uuid results add one."""
+    assert "result_types" not in _payload_json(compile(select(item.c.name)))["statement"]
+    assert _payload_json(compile(select(item.c.uid)))["statement"]["result_types"] == {"uid": "uuid"}
+
+
+def test_each_statement_of_a_list_carries_its_own_result_types():
+    transaction = compile_sqlalchemy_statements(
+        [update(item).values(name="x"), insert(item).values(uid=None).returning(item.c.uid)],
+        operation="insert", data_source_uid=UID, dialect="sqlite",
+    )
+    assert [statement.result_types for statement in transaction.statements] == [None, {"uid": "uuid"}]
+    wire = CompiledTransaction.model_validate(_payload_json(transaction))
+    assert wire.statements[1].result_types == {"uid": "uuid"}
+
+
+def test_client_and_api_accept_only_known_result_types():
+    payload = _payload_json(compile(select(item.c.uid)))
+    assert CompiledOperation.model_validate(payload).statement.result_types == {"uid": "uuid"}
+    payload["statement"]["result_types"] = {"uid": "uuid4"}
+    with pytest.raises(ValidationError):
+        CompiledOperation.model_validate(payload)
+    with pytest.raises(ValidationError):
+        MetaTableCompiledSQLOperation.model_validate(payload)

mainsequence_metatable-0.1.62.dev93/tests/e2e/test_uuid_results.py

@@ -0,0 +1,94 @@
+"""Uuid result columns return dashed through the real client and API (ADR 0027, MetaTables #103).
+
+An application migrates a table with ``Uuid`` columns. ``execute_operation`` and
+``execute_transaction`` return them as dashed text, as PostgreSQL does, although SQLite
+stores 32 hex characters. The PostgreSQL case runs only with the disposable cluster of
+`scripts/test_postgresql.py`.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+import uuid
+
+import pytest
+from sqlalchemy import MetaData, insert, select, update
+
+from metatables import MetaTable
+from metatables.compiled_sql.v1 import compile_sqlalchemy_statement, compile_sqlalchemy_statements
+from metatables.migrations.scaffold import scaffold_migration_package
+from tests.e2e.test_application_owned_migrations import author, forget
+from tests.e2e.test_sqlite_runtime import api_runtime as api_runtime
+
+PACKAGE = "uid_app"
+MODELS = '''
+import uuid
+
+from sqlalchemy import MetaData, String, Uuid
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from metatables import PlatformManagedMetaTable
+
+
+class Base(DeclarativeBase):
+    metadata = MetaData()
+
+
+class Position(PlatformManagedMetaTable, Base):
+    __tablename__ = "uid_app_position"
+    __metatable_identifier__ = "uid_app.position"
+    __metatable_namespace__ = "uid_app"
+    uid: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True)
+    account_uid: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), nullable=False)
+    symbol: Mapped[str] = mapped_column(String(12), nullable=False)
+'''
+POSITION = uuid.UUID("95dcdfeb-f8c0-4b33-b942-4ecc3fc73431")
+ACCOUNT = uuid.UUID("0f3c2b7e-5d41-4c1a-9e57-3a1f0d6b8c22")
+
+
+@pytest.fixture
+def application(tmp_path, monkeypatch):
+    scaffold = scaffold_migration_package(
+        code_repository_root=tmp_path, package=PACKAGE, module=f"{PACKAGE}.migrations", namespace=PACKAGE,
+        metadata_ref=f"{PACKAGE}.models:Base.metadata", alembic_version_schema=None,
+        alembic_version_table_name=f"{PACKAGE}_version", alembic_version_identifier=f"{PACKAGE}.version",
+    )
+    (scaffold.root.parent / "__init__.py").touch()
+    (tmp_path / "src" / PACKAGE / "models.py").write_text(MODELS)
+    (scaffold.root / "registry.py").write_text(
+        f"from {PACKAGE}.models import Position\n"
+        "def metatable_provider_models():\n    return [Position]\n"
+    )
+    monkeypatch.syspath_prepend(str(tmp_path / "src"))
+    yield importlib.import_module(f"{PACKAGE}.migrations").migration
+    forget([PACKAGE])
+
+
+@pytest.mark.parametrize("api_runtime", ["sqlite", "sqlite_override", "postgresql"], indirect=True)
+def test_uuid_results_are_dashed_on_every_engine(api_runtime, application):
+    from metatables.migrations.runner import run_migration
+
+    author(application)
+    assert run_migration(f"{PACKAGE}.migrations:migration")["migrated"]
+    model = sys.modules[f"{PACKAGE}.models"].Position
+    position = model.__table__.to_metadata(MetaData(), schema=None)
+    dashed = {"uid": str(POSITION), "account_uid": str(ACCOUNT)}
+
+    inserted = MetaTable.execute_operation(compile_sqlalchemy_statement(
+        insert(position).values(uid=POSITION, account_uid=ACCOUNT, symbol="A")
+        .returning(position.c.uid, position.c.account_uid),
+        operation="insert",
+    ))
+    assert inserted["rows"] == [dashed]
+    # A UUID sent as hex text finds the row and returns dashed (#101, #103).
+    selected = MetaTable.execute_operation(compile_sqlalchemy_statement(
+        select(position.c.uid, position.c.account_uid).where(position.c.account_uid == ACCOUNT.hex),
+        operation="select",
+    ))
+    assert selected["rows"] == [dashed]
+    listed = MetaTable.execute_transaction(compile_sqlalchemy_statements(
+        [update(position).values(symbol="B").where(position.c.uid == POSITION).returning(position.c.uid,
+                                                                                        position.c.account_uid)],
+        operation="update",
+    ))
+    assert listed["rows"] == [dashed]