parallax-postgres 0.1.0__tar.gz → 0.2.0__tar.gz

{parallax_postgres-0.1.0/src/parallax_postgres.egg-info → parallax_postgres-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: parallax-postgres
-Version: 0.1.0
+Version: 0.2.0
 Summary: Parallax Postgres database adapter: the concrete database runtime over psycopg and its companion pool.
 Author: Parallax
 License-Expression: Apache-2.0
@@ -11,15 +11,16 @@ Requires-Python: >=3.14
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: parallax-core==0.1.0
+Requires-Dist: parallax-core==0.2.0
 Requires-Dist: psycopg[binary]<3.4,>=3.3.6
 Requires-Dist: psycopg-pool>=3.3.1
+Requires-Dist: pyyaml>=6.0
 Dynamic: license-file
 
 # parallax-postgres
 
 Parallax's Postgres database adapter over `psycopg` and its companion
-`psycopg-pool`. Install `parallax-postgres==0.1.0` with the application packages
+`psycopg-pool`. Install `parallax-postgres==0.2.0` with the application packages
 shown in the [getting-started guide](https://github.com/davidsunglee/parallax/blob/main/languages/python/docs/guide/01-getting-started.md#install).
 That guide links the authoritative Python, platform and PostgreSQL support
 declarations and the C-driver and source-build installation paths. The normal
@@ -31,7 +32,7 @@ for publication status. The distribution includes Apache-2.0 `LICENSE` and `NOTI
 ## Connecting
 
 ```python
-from parallax.core.db_port import Password
+from parallax.core import Password
 from parallax.postgres import OnDemandOptions, PoolOptions, PostgresAdapter, PostgresEndpoint
 from parallax.snapshot import connect
 
@@ -63,10 +64,10 @@ PostgresEndpoint("postgresql://app:<password>@db.internal/app", credentials=Pass
 ValueError: connection_string must not carry a password; supply it through credentials.
 ```
 
-There are three spellings, all exported from `parallax.core.db_port`:
+There are three spellings, all exported from `parallax.core`:
 
 ```python
-from parallax.core.db_port import DRIVER_MANAGED, Password
+from parallax.core import DRIVER_MANAGED, Password
 
 # a constant secret; `Password` is its own source and keeps it out of every repr
 PostgresEndpoint("postgresql://app@db.internal:5432/app", credentials=Password("s3cret"))

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/README.md

@@ -1,7 +1,7 @@
 # parallax-postgres
 
 Parallax's Postgres database adapter over `psycopg` and its companion
-`psycopg-pool`. Install `parallax-postgres==0.1.0` with the application packages
+`psycopg-pool`. Install `parallax-postgres==0.2.0` with the application packages
 shown in the [getting-started guide](https://github.com/davidsunglee/parallax/blob/main/languages/python/docs/guide/01-getting-started.md#install).
 That guide links the authoritative Python, platform and PostgreSQL support
 declarations and the C-driver and source-build installation paths. The normal
@@ -13,7 +13,7 @@ for publication status. The distribution includes Apache-2.0 `LICENSE` and `NOTI
 ## Connecting
 
 ```python
-from parallax.core.db_port import Password
+from parallax.core import Password
 from parallax.postgres import OnDemandOptions, PoolOptions, PostgresAdapter, PostgresEndpoint
 from parallax.snapshot import connect
 
@@ -45,10 +45,10 @@ PostgresEndpoint("postgresql://app:<password>@db.internal/app", credentials=Pass
 ValueError: connection_string must not carry a password; supply it through credentials.
 ```
 
-There are three spellings, all exported from `parallax.core.db_port`:
+There are three spellings, all exported from `parallax.core`:
 
 ```python
-from parallax.core.db_port import DRIVER_MANAGED, Password
+from parallax.core import DRIVER_MANAGED, Password
 
 # a constant secret; `Password` is its own source and keeps it out of every repr
 PostgresEndpoint("postgresql://app@db.internal:5432/app", credentials=Password("s3cret"))

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "parallax-postgres"
-version = "0.1.0"
+version = "0.2.0"
 description = "Parallax Postgres database adapter: the concrete database runtime over psycopg and its companion pool."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -8,7 +8,7 @@ license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
 authors = [{ name = "Parallax" }]
 dependencies = [
-    "parallax-core==0.1.0",
+    "parallax-core==0.2.0",
     # The binary extra bundles libpq so the adapter installs self-contained (no
     # system libpq required); the adapter owns that capability, so a sibling
     # that imports psycopg declares it without the extra. The compiled loaders
@@ -18,6 +18,8 @@ dependencies = [
     # The companion pool the runtime owns: the same project, released
     # separately.
     "psycopg-pool>=3.3.1",
+    # Reads and writes YAML binding documents; imported only by those calls.
+    "pyyaml>=6.0",
 ]
 
 [project.urls]

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/src/parallax/postgres/__init__.py

@@ -1,16 +1,28 @@
+"""Connect Parallax to PostgreSQL."""
+
 from __future__ import annotations
 
+from parallax.postgres._adapter import PostgresAdapter
 from parallax.postgres._authorization import PostgresRole
+from parallax.postgres._binding import (
+    PostgresBinding,
+    PostgresLocation,
+    PostgresSequence,
+    PostgresTable,
+)
 from parallax.postgres._endpoint import PostgresEndpoint
 from parallax.postgres._isolation import isolation_spelling
 from parallax.postgres._options import OnDemandOptions, PoolOptions
-from parallax.postgres.adapter import PostgresAdapter
 
 __all__ = [
     "OnDemandOptions",
     "PoolOptions",
     "PostgresAdapter",
+    "PostgresBinding",
     "PostgresEndpoint",
+    "PostgresLocation",
     "PostgresRole",
+    "PostgresSequence",
+    "PostgresTable",
     "isolation_spelling",
 ]

parallax_postgres-0.1.0/src/parallax/postgres/adapter.py → parallax_postgres-0.2.0/src/parallax/postgres/_adapter.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Final, cast, get_args
 
-from parallax.core.dialect import POSTGRES
+from parallax.core.internal.dialect import POSTGRES
 from parallax.postgres._endpoint import PostgresEndpoint
 from parallax.postgres._options import positive_seconds
 from parallax.postgres._runtime import PostgresRuntime
@@ -140,7 +140,7 @@ class PostgresAdapter:
         unbounded instant, a structured document, and a Float32 and a Float64
         exactly, and it was given back — the reader's having authenticated the
         writer's login — unless an unreachable reader was deferred. A failure at
-        any of those raises :class:`~parallax.core.db_port.DatabaseStartupError`
+        any of those raises :class:`~parallax.core.internal.db_port.DatabaseStartupError`
         naming the route and the phase, and publishes no runtime: every pool is
         closed and a startup connection already acquired goes through the
         ordinary cleanup path, which reports what it established rather than

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/src/parallax/postgres/_authorization.py

@@ -5,7 +5,8 @@ from typing import TYPE_CHECKING, Any
 
 from psycopg.sql import SQL, Composed, Identifier
 
-from parallax.core.db_port import InvalidAuthorizationError
+from parallax.core.internal.base import UsageError
+from parallax.core.internal.db_port import AUTHORIZATION_INVALID
 from parallax.postgres._connection import (
     _complete_first_send,  # pyright: ignore[reportPrivateUsage] - the lease's shared first-send markers
     _start_first_send,  # pyright: ignore[reportPrivateUsage] - the lease's shared first-send markers
@@ -28,9 +29,9 @@ class PostgresRole:
 
     def __post_init__(self) -> None:
         if not isinstance(self.name, str):  # pyright: ignore[reportUnnecessaryIsInstance] - validates untyped callers at the public boundary
-            raise InvalidAuthorizationError("a PostgreSQL role name must be a string")
+            raise UsageError(AUTHORIZATION_INVALID, "a PostgreSQL role name must be a string")
         if not self.name:
-            raise InvalidAuthorizationError("a PostgreSQL role name must not be empty")
+            raise UsageError(AUTHORIZATION_INVALID, "a PostgreSQL role name must not be empty")
 
 
 def _role_statement(role: PostgresRole) -> Composed:

parallax_postgres-0.2.0/src/parallax/postgres/_binding.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import functools
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final, Self
+
+from parallax.core.internal.database_binding import (
+    BINDING_DEFINITION_REJECTED,
+    BINDING_SYNTAX_INVALID,
+    BindingError,
+    BindingIssue,
+    BindingParts,
+    LocationCodec,
+    binding_document,
+    binding_from_document,
+)
+from parallax.core.internal.dialect import POSTGRES, Dialect
+from parallax.core.internal.metamodel import EntityIdentity
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import yaml
+
+__all__ = ["PostgresBinding", "PostgresLocation", "PostgresSequence", "PostgresTable"]
+
+
+@dataclass(frozen=True, slots=True)
+class PostgresLocation:
+    """A PostgreSQL schema within the database the adapter's endpoint selects."""
+
+    schema: str
+
+    @property
+    def qualifier(self) -> tuple[str, ...]:
+        return (self.schema,)
+
+
+@dataclass(frozen=True, slots=True)
+class PostgresTable:
+    """Overrides one mapping owner's schema, table name, or both.
+
+    An omitted schema comes from the binding's namespace or default location;
+    an omitted name is the model's declared table name.
+    """
+
+    schema: str | None = None
+    name: str | None = None
+
+    @property
+    def location(self) -> PostgresLocation | None:
+        return None if self.schema is None else PostgresLocation(self.schema)
+
+
+@dataclass(frozen=True, slots=True)
+class PostgresSequence:
+    """Overrides one logical allocator's schema, sequence name, or both.
+
+    An omitted schema comes from the binding's default location, never a
+    namespace; an omitted name is the allocator key.
+    """
+
+    schema: str | None = None
+    name: str | None = None
+
+    @property
+    def location(self) -> PostgresLocation | None:
+        return None if self.schema is None else PostgresLocation(self.schema)
+
+
+_CODEC: Final = LocationCodec(
+    backend="postgres",
+    keys=("schema",),
+    location_type=PostgresLocation,
+    table_type=PostgresTable,
+    sequence_type=PostgresSequence,
+    load=lambda components: PostgresLocation(components["schema"]),
+    dump=lambda location: {"schema": location.schema},
+    table=lambda location, name: PostgresTable(None if location is None else location.schema, name),
+    sequence=lambda location, name: PostgresSequence(
+        None if location is None else location.schema, name
+    ),
+)
+
+
+@dataclass(frozen=True, slots=True, init=False, repr=False)
+class PostgresBinding:
+    """Where one deployment places a model's tables and sequences in PostgreSQL.
+
+    ``default`` places every table and sequence nothing more specific places;
+    ``namespaces`` places the tables of each exact Entity Namespace;
+    ``entities`` overrides individual mapping owners, keyed by canonical Entity
+    name; ``sequences`` overrides individual allocators, keyed by allocator name.
+    The value is immutable and owns copies of the maps it was given, keyed by
+    ``EntityIdentity`` for ``entities``. Construction, ``from_document``,
+    ``from_json``, and ``from_yaml`` all raise :class:`~parallax.core.BindingError`
+    with every problem at its document path.
+    """
+
+    default: PostgresLocation | None
+    namespaces: Mapping[str, PostgresLocation]
+    entities: Mapping[EntityIdentity, PostgresTable]
+    sequences: Mapping[str, PostgresSequence]
+
+    def __init__(
+        self,
+        *,
+        default: PostgresLocation | None = None,
+        namespaces: Mapping[str, PostgresLocation] | None = None,
+        entities: Mapping[str, PostgresTable]
+        | Mapping[EntityIdentity, PostgresTable]
+        | None = None,
+        sequences: Mapping[str, PostgresSequence] | None = None,
+    ) -> None:
+        document = binding_document(
+            _CODEC,
+            default=default,
+            namespaces=namespaces,
+            entities=entities,
+            sequences=sequences,
+        )
+        self._adopt(binding_from_document(document, _CODEC))
+
+    @property
+    def dialect(self) -> Dialect:
+        """The backend this binding places objects in."""
+        return POSTGRES
+
+    def _adopt(
+        self, parts: BindingParts[PostgresLocation, PostgresTable, PostgresSequence]
+    ) -> None:
+        object.__setattr__(self, "default", parts.default)
+        object.__setattr__(self, "namespaces", parts.namespaces)
+        object.__setattr__(self, "entities", parts.entities)
+        object.__setattr__(self, "sequences", parts.sequences)
+
+    @classmethod
+    def _from_parts(
+        cls, parts: BindingParts[PostgresLocation, PostgresTable, PostgresSequence]
+    ) -> Self:
+        binding = cls.__new__(cls)
+        binding._adopt(parts)
+        return binding
+
+    @classmethod
+    def from_document(cls, document: Mapping[str, object]) -> Self:
+        """The binding a decoded binding document describes."""
+        return cls._from_parts(binding_from_document(document, _CODEC))
+
+    @classmethod
+    def from_json(cls, text: str | bytes) -> Self:
+        """The binding a JSON binding document describes."""
+        document = _decoded(text, json.loads, json.JSONDecodeError, "JSON")
+        return cls._from_parts(binding_from_document(document, _CODEC))
+
+    @classmethod
+    def from_yaml(cls, text: str | bytes) -> Self:
+        """The binding a YAML binding document describes, read under the YAML 1.2
+        core schema: a plain scalar is null, a boolean, an integer, or a float
+        only in that schema's spellings, and otherwise the string written."""
+        import yaml
+
+        loader = _yaml_loader()
+        document = _decoded(
+            text, lambda source: yaml.load(source, Loader=loader), yaml.YAMLError, "YAML"
+        )
+        return cls._from_parts(binding_from_document(document, _CODEC))
+
+    def to_document(self) -> dict[str, object]:
+        """This binding as a canonical binding document."""
+        return binding_document(
+            _CODEC,
+            default=self.default,
+            namespaces=self.namespaces,
+            entities=self.entities,
+            sequences=self.sequences,
+        )
+
+    def to_json(self) -> str:
+        """This binding as canonical, byte-deterministic JSON text."""
+        return json.dumps(self.to_document(), indent=2, ensure_ascii=False) + "\n"
+
+    def to_yaml(self) -> str:
+        """This binding as canonical, byte-deterministic YAML text.
+
+        Every string a YAML 1.1 or 1.2 core reader would resolve to another type
+        is quoted, so either reads it back as the string it is.
+        """
+        import yaml
+
+        return yaml.dump(
+            self.to_document(),
+            Dumper=_yaml_dumper(),
+            sort_keys=False,
+            allow_unicode=True,
+            default_flow_style=False,
+        )
+
+    def __hash__(self) -> int:
+        return hash(
+            (
+                self.default,
+                tuple(self.namespaces.items()),
+                tuple(self.entities.items()),
+                tuple(self.sequences.items()),
+            )
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"PostgresBinding(default={self.default!r}, namespaces={dict(self.namespaces)!r}, "
+            f"entities={dict(self.entities)!r}, sequences={dict(self.sequences)!r})"
+        )
+
+
+# The YAML 1.2 core schema's implicit resolvers (`m-database-binding`), each with
+# the first characters a matching plain scalar can start with; the empty string
+# is PyYAML's bucket for an empty plain scalar, which resolves to null.
+_CORE_SCHEMA: Final[tuple[tuple[str, str, tuple[str, ...]], ...]] = (
+    ("tag:yaml.org,2002:null", r"^(?:null|Null|NULL|~|)$", ("~", "n", "N", "")),
+    ("tag:yaml.org,2002:bool", r"^(?:true|True|TRUE|false|False|FALSE)$", ("t", "T", "f", "F")),
+    (
+        "tag:yaml.org,2002:int",
+        r"^(?:[-+]?[0-9]+|0o[0-7]+|0x[0-9a-fA-F]+)$",
+        ("-", "+", *"0123456789"),
+    ),
+    (
+        "tag:yaml.org,2002:float",
+        r"^(?:[-+]?(?:\.[0-9]+|[0-9]+(?:\.[0-9]*)?)(?:[eE][-+]?[0-9]+)?"
+        r"|[-+]?\.(?:inf|Inf|INF)|\.(?:nan|NaN|NAN))$",
+        ("-", "+", ".", *"0123456789"),
+    ),
+)
+
+
+def _core_int(text: str) -> int:
+    if text.lstrip("-+")[:2] in ("0o", "0x"):
+        return int(text, 0)
+    return int(text)
+
+
+def _core_float(text: str) -> float:
+    lowered = text.lower()
+    if lowered.lstrip("-+") == ".inf":
+        return float("-inf") if text.startswith("-") else float("inf")
+    if lowered == ".nan":
+        return float("nan")
+    return float(text)
+
+
+@functools.cache
+def _yaml_loader() -> type[yaml.SafeLoader]:
+    import yaml
+
+    class _CoreLoader(yaml.SafeLoader):
+        pass
+
+    resolvers: dict[str, list[tuple[str, re.Pattern[str]]]] = {}
+    for tag, pattern, first_characters in _CORE_SCHEMA:
+        compiled = re.compile(pattern)
+        for first in first_characters:
+            resolvers.setdefault(first, []).append((tag, compiled))
+    _CoreLoader.yaml_implicit_resolvers = resolvers
+
+    def construct_int(loader: yaml.SafeLoader, node: yaml.ScalarNode) -> int:
+        return _core_int(str(loader.construct_scalar(node)))
+
+    def construct_float(loader: yaml.SafeLoader, node: yaml.ScalarNode) -> float:
+        return _core_float(str(loader.construct_scalar(node)))
+
+    _CoreLoader.add_constructor("tag:yaml.org,2002:int", construct_int)
+    _CoreLoader.add_constructor("tag:yaml.org,2002:float", construct_float)
+    return _CoreLoader
+
+
+@functools.cache
+def _yaml_dumper() -> type[yaml.SafeDumper]:
+    import yaml
+
+    class _BindingDumper(yaml.SafeDumper):
+        pass
+
+    # A plain scalar either schema resolves to a non-string must be quoted: the
+    # 1.1 resolvers the dumper inherits cover PyYAML readers, and the core
+    # schema's cover 1.2 readers.
+    resolvers = {
+        first: list(entries) for first, entries in yaml.SafeDumper.yaml_implicit_resolvers.items()
+    }
+    for tag, pattern, first_characters in _CORE_SCHEMA:
+        compiled = re.compile(pattern)
+        for first in first_characters:
+            resolvers.setdefault(first, []).append((tag, compiled))
+    _BindingDumper.yaml_implicit_resolvers = resolvers
+
+    def represent_text(_dumper: yaml.SafeDumper, text: str) -> yaml.ScalarNode:
+        # PyYAML folds a NEL into a space in every scalar style except double-quoted,
+        # where it escapes it.
+        style = '"' if "\x85" in text else None
+        return yaml.ScalarNode("tag:yaml.org,2002:str", text, style=style)
+
+    _BindingDumper.add_representer(str, represent_text)
+    return _BindingDumper
+
+
+def _decoded(
+    text: str | bytes,
+    decode: Callable[[str], object],
+    error: type[Exception],
+    format_name: str,
+) -> object:
+    try:
+        source = text if isinstance(text, str) else text.decode("utf-8")
+        document = decode(source)
+    # PyYAML's scalar constructors raise these, not a YAMLError, for a scalar its
+    # tag cannot convert, such as `!!int invalid` or the date `2026-02-30`.
+    except (ValueError, LookupError, AttributeError, error) as exc:
+        raise BindingError(
+            BINDING_DEFINITION_REJECTED,
+            (BindingIssue(BINDING_SYNTAX_INVALID, (), message=f"not well-formed {format_name}"),),
+        ) from exc
+    return document

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/src/parallax/postgres/_cloaders.pxi

@@ -14,7 +14,7 @@ from datetime import UTC
 from psycopg import DataError
 from psycopg.pq import Format
 
-from parallax.core.base import INFINITY, nearest_binary32_of_spelling
+from parallax.core.internal.base import INFINITY, nearest_binary32_of_spelling
 
 
 cdef extern from "Python.h":

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/src/parallax/postgres/_connection.py

@@ -20,27 +20,30 @@ from psycopg.pq.abc import PGresult
 from psycopg.rows import RowMaker, TupleRow, tuple_row
 from psycopg.types.json import Jsonb, JsonbBinaryLoader, JsonbLoader
 
-from parallax.core.base import (
+from parallax.core.internal.base import (
     INFINITY,
     Boolean,
     Bytes,
     Date,
-    Decimal,
     Float32,
     Float64,
     Int32,
     Int64,
+    InternalError,
     Json,
     NeutralType,
+    Numeric,
     String,
     TemporalBound,
     Time,
     Timestamp,
     Uuid,
 )
-from parallax.core.db_error import DatabaseError, classify_error
-from parallax.core.db_port import (
+from parallax.core.internal.database_binding import PhysicalTable
+from parallax.core.internal.db_error import DatabaseError, classify_error
+from parallax.core.internal.db_port import (
     JSON_NULL,
+    WRITE_RESULT_INTEGRITY_VIOLATED,
     AccessMode,
     ArrayBind,
     BeginFailed,
@@ -54,7 +57,6 @@ from parallax.core.db_port import (
     DatabaseConnection,
     DocumentReadOrdinals,
     IsolationLevel,
-    JsonDocument,
     OrderedWriteResult,
     OrderedWriteResultComplete,
     OrderedWriteResultInterrupted,
@@ -66,11 +68,11 @@ from parallax.core.db_port import (
     Row,
     StatementFailed,
     StatementNotExecuted,
+    StructuredDocument,
     TransactionOutcome,
-    WriteResultIntegrityError,
 )
-from parallax.core.dialect import POSTGRES, Dialect
-from parallax.core.wire._json import dump_document, prepared_loads
+from parallax.core.internal.dialect import POSTGRES, Dialect
+from parallax.core.internal.wire._json import dump_document, prepared_loads
 from parallax.postgres._compiled_loaders import compiled_loaders
 
 if TYPE_CHECKING:
@@ -156,7 +158,8 @@ def translate_driver_error(dialect: Dialect, exc: psycopg.Error) -> DatabaseErro
 
     Extracts psycopg's driver-specific SQLSTATE (``exc.sqlstate`` — ``None`` for a
     non-database failure such as a dropped connection), its message, and the
-    structured constraint name libpq reports beside them, then delegates category
+    structured constraint name, schema, and table libpq reports beside them,
+    then delegates category
     interpretation to ``m-db-error`` (which consults ``dialect``'s own code
     table). libpq treats an index as a constraint whether or not it was created
     with constraint syntax, so a bare ``create unique index`` reports its own
@@ -173,9 +176,20 @@ def translate_driver_error(dialect: Dialect, exc: psycopg.Error) -> DatabaseErro
         exc.sqlstate,
         str(exc),
         constraint_name=None if diagnostic is None else diagnostic.constraint_name,
+        constraint_table=None if diagnostic is None else _constraint_table(diagnostic),
     )
 
 
+def _constraint_table(diagnostic: psycopg.errors.Diagnostic) -> PhysicalTable | None:
+    """The table libpq reports a failure against, when it reports both its schema
+    and its name."""
+    schema = diagnostic.schema_name
+    table = diagnostic.table_name
+    if schema is None or table is None:
+        return None
+    return PhysicalTable((schema,), table)
+
+
 def reported_failure(dialect: Dialect, exc: psycopg.Error) -> DatabaseError:
     """The neutral error for a driver failure that is reported rather than raised.
 
@@ -196,7 +210,7 @@ def reported_failure(dialect: Dialect, exc: psycopg.Error) -> DatabaseError:
 def translating_driver_errors(dialect: Dialect) -> Generator[None]:
     """Re-raise any psycopg exception inside the block as a neutral ``DatabaseError``.
 
-    A :class:`~parallax.core.db_error.DatabaseError` raised by an inner port call
+    A :class:`~parallax.core.internal.db_error.DatabaseError` raised by an inner port call
     is **not** a ``psycopg.Error``, so a nested transaction never re-wraps an
     already-translated error, and a non-driver exception (a rollback signal, a
     callback's own error) propagates unchanged.
@@ -216,7 +230,7 @@ _ARRAY_ELEMENT_TYPES: Final[Mapping[type[NeutralType], str]] = {
     Int64: "int8",
     Float32: "float4",
     Float64: "float8",
-    Decimal: "numeric",
+    Numeric: "numeric",
     String: "text",
     Bytes: "bytea",
     Date: "date",
@@ -357,15 +371,15 @@ class _ArrayBindDumper(RecursiveDumper):
 def adapt_binds(binds: Sequence[object]) -> list[object]:
     """Adapt neutral binds to psycopg's driver bind types at the adapter boundary.
 
-    A :class:`~parallax.core.db_port.JsonDocument` (the neutral ``json`` /
-    value-object carrier) becomes a psycopg ``Jsonb``. An
-    :class:`~parallax.core.db_port.ArrayBind` passes through unchanged to the
+    A :class:`~parallax.core.internal.db_port.StructuredDocument` becomes a psycopg
+    ``Jsonb``. An
+    :class:`~parallax.core.internal.db_port.ArrayBind` passes through unchanged to the
     dumper :func:`initialize_connection` registers for it, as does every other
     bind. This keeps the psycopg bind mechanics internal to the adapter — no
     driver type is exported to the developer surface (m-db-port).
     """
     return [
-        Jsonb(bind.value, dumps=dump_document) if isinstance(bind, JsonDocument) else bind
+        Jsonb(bind.document, dumps=dump_document) if isinstance(bind, StructuredDocument) else bind
         for bind in binds
     ]
 
@@ -479,6 +493,18 @@ context, and nothing is marked.
 """
 
 type _PreparedStatement = tuple[bytes, list[object], Sequence[DocumentReadOrdinals]]
+type _PreparedWriteStatement = tuple[bytes, list[object]]
+
+
+def to_driver_sql(canonical_sql: str) -> str:
+    """Convert canonical placeholders while preserving quoted text and psycopg percent escapes.
+
+    Psycopg scans percent markers even inside literals and quoted identifiers, so
+    existing percent characters are doubled before the unquoted `?` markers
+    become `%s` binds.
+    """
+    runs = re.split(r"""('(?:[^']|'')*'|"(?:[^"]|"")*")""", canonical_sql.replace("%", "%%"))
+    return "".join(run if index % 2 else run.replace("?", "%s") for index, run in enumerate(runs))
 
 
 def _start_first_send(context: PostgresConnectionContext | None) -> None:
@@ -814,7 +840,7 @@ class ConnectionEstablishment:
         would inherit.
 
         Anything the source raises that is not already a
-        :class:`~parallax.core.db_port.CredentialResolutionError` is wrapped in
+        :class:`~parallax.core.internal.db_port.CredentialResolutionError` is wrapped in
         one with fixed text and the original chained, so classification does not
         depend on a provider's discipline and the pool's own warning line — which
         prints the exception's text — carries nothing a source put in a message.
@@ -972,7 +998,7 @@ def _write_in_order(
     connection: psycopg.Connection[TupleRow],
     context: PostgresConnectionContext | None,
     dialect: Dialect,
-    statements: Sequence[CanonicalWriteStatement],
+    statements: Sequence[_PreparedWriteStatement],
 ) -> OrderedWriteResult:
     """Present ``statements`` in one pipeline and answer what it established.
 
@@ -991,9 +1017,7 @@ def _write_in_order(
     try:
         with connection.pipeline():
             try:
-                for statement in statements:
-                    query = dialect.to_driver_sql(statement.sql).encode()
-                    binds = adapt_binds(statement.binds)
+                for query, binds in statements:
                     cursor = _CountCursor(connection, intake)
                     cursors.append(cursor)
                     _start_first_send(context)
@@ -1051,9 +1075,10 @@ def _answered(
     for index, cursor in enumerate(recorded):
         outcome = cast("_Established", cursor.outcome)
         if isinstance(outcome, _Unexpected):
-            raise WriteResultIntegrityError(
+            raise InternalError(
+                WRITE_RESULT_INTEGRITY_VIOLATED,
                 f"PostgreSQL answered statement {index} of an ordered write with "
-                f"{outcome.description}, which no count-only statement produces"
+                f"{outcome.description}, which no count-only statement produces",
             )
         established.append(outcome)
     confirmed = _confirmed(established)
@@ -1208,7 +1233,7 @@ class PostgresConnection:
         unchanged, on the connection the context replaces it with; an
         undesignated one never is.
         """
-        query = sql.encode()
+        query = to_driver_sql(sql).encode()
         adapted = adapt_binds(binds)
         with translating_driver_errors(self.dialect):
             return self._invoke_native(
@@ -1232,7 +1257,11 @@ class PostgresConnection:
             self._current_native()
             return []
         prepared = tuple(
-            (statement.sql.encode(), adapt_binds(statement.binds), statement.document_reads)
+            (
+                to_driver_sql(statement.sql).encode(),
+                adapt_binds(statement.binds),
+                statement.document_reads,
+            )
             for statement in statements
         )
         with translating_driver_errors(self.dialect):
@@ -1241,7 +1270,7 @@ class PostgresConnection:
             )
 
     def execute_write(self, sql: str, binds: Sequence[object]) -> int:
-        query = sql.encode()
+        query = to_driver_sql(sql).encode()
         adapted = adapt_binds(binds)
         with translating_driver_errors(self.dialect):
             return self._invoke_native(_execute_write, query, adapted, replay_safe=False)
@@ -1264,10 +1293,12 @@ class PostgresConnection:
         self._current_native()
         if not statements:
             return OrderedWriteResultComplete(())
+        prepared = tuple(
+            (to_driver_sql(statement.sql).encode(), adapt_binds(statement.binds))
+            for statement in statements
+        )
         try:
-            result = self._invoke_native(
-                _write_in_order, self.dialect, statements, replay_safe=False
-            )
+            result = self._invoke_native(_write_in_order, self.dialect, prepared, replay_safe=False)
         except BaseException:
             self._mark_suspect()
             raise
@@ -1301,7 +1332,7 @@ class PostgresConnection:
         work may be retried and whether this connection is still trustworthy.
 
         An exception ``body`` itself raises is the CALLER's failure rather than
-        one this made, so :class:`~parallax.core.db_port.CallbackRaised` carries
+        one this made, so :class:`~parallax.core.internal.db_port.CallbackRaised` carries
         the identical object (``m-db-port``). Translating it would substitute a
         port error for the caller's own — and a body-authored deadlock-class
         exception would then read as retriable to ``m-auto-retry``, which would
@@ -1321,7 +1352,7 @@ class PostgresConnection:
         from, assigned while the session is idle, so the request governs this
         transaction alone and costs no request of its own. A request the
         database refuses ends the boundary
-        :class:`~parallax.core.db_port.BeginFailed`: no work of the caller's was
+        :class:`~parallax.core.internal.db_port.BeginFailed`: no work of the caller's was
         attempted, and a request silently downgraded to one the caller did not
         make is worse than one refused. Once the outer boundary ends, both
         attributes are cleared so the session's own defaults govern the next one.
@@ -1334,7 +1365,7 @@ class PostgresConnection:
         twice. An outer boundary that is the first submission after entry is
         still the acquisition's setup: one that opens past the acquisition's
         deadline, or after the runtime closed, raises that acquisition's
-        :class:`~parallax.core.db_port.ConnectionAcquisitionError` before the
+        :class:`~parallax.core.internal.db_port.ConnectionAcquisitionError` before the
         callback runs.
 
         A call made while this session's transaction is already open joins it

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/src/parallax/postgres/_context.py

@@ -11,7 +11,7 @@ import psycopg_pool
 from psycopg.pq import TransactionStatus
 from psycopg.rows import TupleRow
 
-from parallax.core.db_port import (
+from parallax.core.internal.db_port import (
     CleanupCode,
     CleanupIssue,
     CleanupPhase,
@@ -24,8 +24,8 @@ from parallax.core.db_port import (
     Returned,
     RouteSelection,
 )
-from parallax.core.diagnostics import diagnostic_for
-from parallax.core.dialect import POSTGRES
+from parallax.core.internal.diagnostics import diagnostic_for
+from parallax.core.internal.dialect import POSTGRES
 from parallax.postgres._authorization import (
     PostgresRole,
     _install_role,  # pyright: ignore[reportPrivateUsage] - the one role installation, run as the lease's first send

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/src/parallax/postgres/_endpoint.py

@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING
 import psycopg
 import psycopg.conninfo
 
-from parallax.core.db_port import DRIVER_MANAGED, CredentialSource, DriverManaged
+from parallax.core.internal.db_port import DRIVER_MANAGED, CredentialSource, DriverManaged
 from parallax.postgres._options import OnDemandOptions, PoolOptions, RetentionOptions
 
 if TYPE_CHECKING:
@@ -104,8 +104,7 @@ def _retention(pool: object) -> RetentionOptions:
 
 @dataclass(frozen=True, slots=True)
 class PostgresEndpoint:
-    """Where one route's connections go, how its login authenticates, and how
-    its connections are retained.
+    """Where one route connects, how it logs in, and how it keeps connections.
 
     ``connection_string`` is libpq's own grammar — keyword/value pairs, a
     ``postgresql://`` URI, a ``service=`` reference, or the empty string, which
@@ -117,16 +116,16 @@ class PostgresEndpoint:
 
     ``credentials`` says HOW the login that string names authenticates, and is
     required: either a
-    :class:`~parallax.core.db_port.CredentialSource` — a
-    :class:`~parallax.core.db_port.Password`, or a provider's own source, asked
+    :class:`~parallax.core.internal.db_port.CredentialSource` — a
+    :class:`~parallax.core.internal.db_port.Password`, or a provider's own source, asked
     where each physical connection is established — or
-    :data:`~parallax.core.db_port.DRIVER_MANAGED`, which declares that Parallax
+    :data:`~parallax.core.internal.db_port.DRIVER_MANAGED`, which declares that Parallax
     supplies no secret and leaves authentication to the driver and the server
     (peer, trust, a client certificate, Kerberos, or libpq's own environment:
     ``PGPASSWORD``, ``.pgpass``, a ``service`` file). There is no default and no
     ``None``, so which of the two a deployment chose is visible on the line. It
     is kept out of this value's representation for the same reason the string
-    is: :class:`~parallax.core.db_port.Password` hides its own secret, but a
+    is: :class:`~parallax.core.internal.db_port.Password` hides its own secret, but a
     source is any object a provider wrote, and one holding broker material in an
     ordinary repr would otherwise reach every log line this value does.
 

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/src/parallax/postgres/_isolation.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import Final
 
-from parallax.core.db_port import IsolationLevel
+from parallax.core.internal.db_port import IsolationLevel
 
 __all__ = ["isolation_spelling"]
 

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/src/parallax/postgres/_pool_metrics.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from collections.abc import Callable, Mapping
 from typing import Final, Protocol
 
-from parallax.core.db_port import (
+from parallax.core.internal.db_port import (
     PoolAvailable,
     PoolDetached,
     PoolMeasurements,
@@ -12,7 +12,7 @@ from parallax.core.db_port import (
     Route,
     RouteReadiness,
 )
-from parallax.core.diagnostics import diagnostic_for
+from parallax.core.internal.diagnostics import diagnostic_for
 
 __all__ = ["PostgresPoolMetrics"]
 

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/src/parallax/postgres/_route.py

@@ -6,8 +6,8 @@ from typing import TYPE_CHECKING, Final, Literal
 
 import psycopg_pool
 
-from parallax.core.base import INFINITY
-from parallax.core.db_port import (
+from parallax.core.internal.base import INFINITY
+from parallax.core.internal.db_port import (
     CredentialSource,
     DatabaseStartupError,
     DriverManaged,
@@ -273,7 +273,7 @@ def _build_pool(
     Where a credential source is configured, those keywords become a CALLABLE
     the pool resolves on every connection attempt, which is what makes the
     secret late rather than frozen into configuration. Under
-    :data:`~parallax.core.db_port.DRIVER_MANAGED` the static dictionary is
+    :data:`~parallax.core.internal.db_port.DRIVER_MANAGED` the static dictionary is
     passed exactly as it would be otherwise and carries no ``password`` at all,
     leaving authentication to the driver and the server.
 

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/src/parallax/postgres/_route_plan.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Final, Literal
 
-from parallax.core.db_port import AcquisitionReason, FallbackReason, Route, RoutePolicy
+from parallax.core.internal.db_port import AcquisitionReason, FallbackReason, Route, RoutePolicy
 
 __all__ = ["PlanStep", "RoutePlan"]
 

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/src/parallax/postgres/_runtime.py

@@ -7,12 +7,13 @@ from time import monotonic
 from types import MappingProxyType
 from typing import TYPE_CHECKING, Final
 
-from parallax.core.db_port import (
+from parallax.core.internal.base import UsageError
+from parallax.core.internal.db_port import (
+    AUTHORIZATION_INVALID,
     CleanupIssue,
     ConnectionAcquisitionError,
     ConnectionContext,
     ConnectionContextSource,
-    InvalidAuthorizationError,
     PoolMetricsSource,
     ReleaseUnconfirmed,
     Route,
@@ -20,8 +21,8 @@ from parallax.core.db_port import (
     RoutePolicy,
     report_resource_issues,
 )
-from parallax.core.diagnostics import diagnostic_for
-from parallax.core.dialect import POSTGRES, Dialect
+from parallax.core.internal.diagnostics import diagnostic_for
+from parallax.core.internal.dialect import POSTGRES, Dialect
 from parallax.postgres._authorization import PostgresRole
 from parallax.postgres._context import PostgresConnectionContext, Step
 from parallax.postgres._route_plan import RoutePlan
@@ -117,8 +118,8 @@ class PostgresRuntime:
     def principal_source(self, authorization: PostgresRole) -> ConnectionContextSource:
         """Bind execution under ``authorization`` without acquiring."""
         if not isinstance(authorization, PostgresRole):  # pyright: ignore[reportUnnecessaryIsInstance] - validates untyped callers at the public boundary
-            raise InvalidAuthorizationError(
-                "PostgreSQL principal execution requires a PostgresRole"
+            raise UsageError(
+                AUTHORIZATION_INVALID, "PostgreSQL principal execution requires a PostgresRole"
             )
         return _PostgresContextSource(self, authorization)
 

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/src/parallax/postgres/_startup.py

@@ -3,8 +3,8 @@ from __future__ import annotations
 from time import monotonic
 from typing import TYPE_CHECKING, Literal
 
-from parallax.core.db_error import DatabaseError
-from parallax.core.db_port import (
+from parallax.core.internal.db_error import DatabaseError
+from parallax.core.internal.db_port import (
     CleanupResult,
     ConnectionAcquisitionError,
     DatabaseStartupError,

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0/src/parallax_postgres.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: parallax-postgres
-Version: 0.1.0
+Version: 0.2.0
 Summary: Parallax Postgres database adapter: the concrete database runtime over psycopg and its companion pool.
 Author: Parallax
 License-Expression: Apache-2.0
@@ -11,15 +11,16 @@ Requires-Python: >=3.14
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: parallax-core==0.1.0
+Requires-Dist: parallax-core==0.2.0
 Requires-Dist: psycopg[binary]<3.4,>=3.3.6
 Requires-Dist: psycopg-pool>=3.3.1
+Requires-Dist: pyyaml>=6.0
 Dynamic: license-file
 
 # parallax-postgres
 
 Parallax's Postgres database adapter over `psycopg` and its companion
-`psycopg-pool`. Install `parallax-postgres==0.1.0` with the application packages
+`psycopg-pool`. Install `parallax-postgres==0.2.0` with the application packages
 shown in the [getting-started guide](https://github.com/davidsunglee/parallax/blob/main/languages/python/docs/guide/01-getting-started.md#install).
 That guide links the authoritative Python, platform and PostgreSQL support
 declarations and the C-driver and source-build installation paths. The normal
@@ -31,7 +32,7 @@ for publication status. The distribution includes Apache-2.0 `LICENSE` and `NOTI
 ## Connecting
 
 ```python
-from parallax.core.db_port import Password
+from parallax.core import Password
 from parallax.postgres import OnDemandOptions, PoolOptions, PostgresAdapter, PostgresEndpoint
 from parallax.snapshot import connect
 
@@ -63,10 +64,10 @@ PostgresEndpoint("postgresql://app:<password>@db.internal/app", credentials=Pass
 ValueError: connection_string must not carry a password; supply it through credentials.
 ```
 
-There are three spellings, all exported from `parallax.core.db_port`:
+There are three spellings, all exported from `parallax.core`:
 
 ```python
-from parallax.core.db_port import DRIVER_MANAGED, Password
+from parallax.core import DRIVER_MANAGED, Password
 
 # a constant secret; `Password` is its own source and keeps it out of every repr
 PostgresEndpoint("postgresql://app@db.internal:5432/app", credentials=Password("s3cret"))

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/src/parallax_postgres.egg-info/SOURCES.txt

@@ -4,7 +4,9 @@ README.md
 pyproject.toml
 setup.py
 src/parallax/postgres/__init__.py
+src/parallax/postgres/_adapter.py
 src/parallax/postgres/_authorization.py
+src/parallax/postgres/_binding.py
 src/parallax/postgres/_cloaders.pxi
 src/parallax/postgres/_cloaders_binary.pyi
 src/parallax/postgres/_cloaders_binary.pyx
@@ -21,7 +23,6 @@ src/parallax/postgres/_route.py
 src/parallax/postgres/_route_plan.py
 src/parallax/postgres/_runtime.py
 src/parallax/postgres/_startup.py
-src/parallax/postgres/adapter.py
 src/parallax/postgres/py.typed
 src/parallax/postgres/_psycopg_layout/cloader.pxi
 src/parallax/postgres/_psycopg_layout/psycopg_binary/__init__.pxd

{parallax_postgres-0.1.0 → parallax_postgres-0.2.0}/src/parallax_postgres.egg-info/requires.txt

@@ -1,3 +1,4 @@
-parallax-core==0.1.0
+parallax-core==0.2.0
 psycopg[binary]<3.4,>=3.3.6
 psycopg-pool>=3.3.1
+pyyaml>=6.0