Rewrite merge methods on real Core constructs so schema_translate_map applies to loaded data

.github/workflows/ci.yml

@@ -6,18 +6,20 @@ on:
 jobs:
   label-gate:
     uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/label-gate.yml@main
-  build-test:
-    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/build-test-postgres.yml@main
+  build-test-sqlite:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/build-test.yml@main
+  build-test-postgres:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/build-test-postgres-v2.yml@main
     with:
       postgres-db: orm_loader_test
       setup-commands: |
         uv run omop-config configure orm_loader \
-          --set test_orm_db.kind=cdm \
-          --set test_orm_db.connection.dialect=postgresql+psycopg \
-          --set test_orm_db.connection.host=localhost \
-          --set test_orm_db.connection.port=5432 \
-          --set test_orm_db.connection.user=test \
-          --set test_orm_db.connection.password=test \
-          --set test_orm_db.connection.database_name=orm_loader_test \
-          --set test_orm_db.connection.test_only=true \
-          --set test_orm_db.schema_name=public
+          --set test_orm_db_pg.kind=cdm \
+          --set test_orm_db_pg.connection.dialect=postgresql+psycopg \
+          --set test_orm_db_pg.connection.host=localhost \
+          --set test_orm_db_pg.connection.port=5432 \
+          --set test_orm_db_pg.connection.user=test \
+          --set test_orm_db_pg.connection.password=test \
+          --set test_orm_db_pg.connection.database_name=orm_loader_test \
+          --set test_orm_db_pg.connection.test_only=true \
+          --set test_orm_db_pg.cdm_schema=public

docs/loaders/context.md

@@ -25,7 +25,7 @@ on globals or implicit configuration.
 | `chunksize` | Optional chunk size |
 | `normalise` | Whether to cast values to ORM types |
 | `dedupe` | Whether to deduplicate incoming data |
-| `quote_mode` | CSV quoting mode for PostgreSQL fast-path loading |
+| `quote_mode` | CSV quoting mode, resolved to the same concrete mode on both the PostgreSQL COPY fast-path and the pandas ORM fallback |
 
 ::: orm_loader.loaders.data_classes.LoaderContext
 

docs/registry/validation.md

@@ -45,3 +45,15 @@ Validates primary key presence, nullability, and alignment with specs.
 Validates structural correctness of foreign key definitions.
 
 ::: orm_loader.registry.validation.ForeignKeyShapeValidator
+
+---
+
+## `always_on_validators()`
+
+Returns the standard bundle of all four validators above
+(`ColumnPresenceValidator`, `ColumnNullabilityValidator`,
+`PrimaryKeyValidator`, `ForeignKeyShapeValidator`) as a ready-made list, for
+callers that want the default validation set without constructing each one
+individually.
+
+::: orm_loader.registry.validation_presets.always_on_validators

docs/tables/mat_view.md

@@ -105,24 +105,44 @@ PatientSummaryMV.refresh_mv(engine, concurrently=True)
 
 This is fail-closed by design. An index created manually outside `__mv_indexes__` does not satisfy the mixin's declaration contract; declare it in the class even if another migration is responsible for creating it. Expressions, partial indexes, and other index forms are outside this simple contract and should not be represented as `MaterializedViewIndex` entries.
 
-By default, `schema=None` leaves the view name unqualified. PostgreSQL resolves that name through the connection's `search_path`, matching the behavior of existing callers. Pass `schema="reporting"` only when the caller intentionally wants an explicit schema-qualified target.
+The view's physical schema comes from the bound connection's own `schema_translate_map`. `create_mv()`/`refresh_mv()`/`drop_mv()` resolve it via `oa_configurator.physical_schema_of()` before ever reaching the backend, which only ever sees an already-resolved physical schema string.
+
+The schema tag itself comes from one of three places, in order:
+
+1. an explicit `schema_tag=` argument, for a one-off override;
+2. when the class is also declaratively mapped (combined with a `Base`, with a real `__table__`), that table's own `schema` -- set the schema the same way as any other mapped table, via `__table_args__ = {"schema": ...}`, and the materialized view follows it automatically;
+3. `__mv_schema_tag__` (defaults to `"primary"`), only consulted for a Core-only declaration with no mapped table to derive anything from.
 
 ```python
-# Existing/default behavior: search_path resolves the target.
+# Core-only: no Base, no mapped table, so __mv_schema_tag__ is what resolves it.
+class VocabSummaryMV(MaterializedViewMixin):
+    __mv_name__ = "vocab_summary"
+    __mv_select__ = ...
+    __mv_schema_tag__ = Role.VOCAB.value  # resolves via the connection's vocab schema
+
+# Uses __mv_schema_tag__ ("primary" by default) via the connection's own schema_translate_map.
 RecentObservationMV.create_mv(engine)
 
-# Explicit schema: the target is quoted and schema-qualified.
-RecentObservationMV.create_mv(engine, schema="reporting")
-RecentObservationMV.refresh_mv(engine, schema="reporting")
+# Override for one call.
+RecentObservationMV.create_mv(engine, schema_tag=Role.VOCAB.value)
+
+# Declaratively mapped: the mapped table's own schema is authoritative, no
+# __mv_schema_tag__ needed (or consulted) at all.
+class VocabPatientSummaryMV(Base, MaterializedViewMixin):
+    __mv_name__ = "vocab_patient_summary"
+    __mv_select__ = ...
+    __tablename__ = "vocab_patient_summary"
+    __table_args__ = {"schema": Role.VOCAB.value}
+    patient_id = sa.Column(sa.Integer, primary_key=True)
 ```
 
-Explicit schema targets are quoted component by component. This matters for embedded quotes, spaces, and mixed-case identifiers. It also means an unqualified mixed-case name and the same name passed with `schema=` can address different PostgreSQL relations. Keep schema selection at the call site and do not assume that this API provides `schema_translate_map`, role-token, or general multi-schema behavior.
+Every generated identifier is quoted through `oa_configurator.qualified()`, which quotes each component only when the dialect actually requires it (reserved words, mixed case, embedded quotes or spaces) — the same behavior every other Core-built query in this stack has.
 
 ## Failure handling and backend support
 
 The built-in implementation is PostgreSQL-oriented. SQLite rejects materialized-view operations with `NotImplementedError`; this is intentional, not an emulation using ordinary views.
 
-`drop_mv()` and declared-index creation wrap execution failures in `MaterializationError`. 
+`create_mv()`, `drop_mv()`, and declared-index creation all wrap execution failures in `MaterializationError`.
 
 ## API reference
 
@@ -166,7 +186,3 @@ The built-in implementation is PostgreSQL-oriented. SQLite rejects materialized-
 ::: orm_loader.mappers.ConcurrentRefreshNotEligibleError
     options:
       heading_level: 3
-
-::: orm_loader.mappers.UnsupportedMaterializationDialectError
-    options:
-      heading_level: 3

pyproject.toml

@@ -10,7 +10,7 @@ license = { text = "Apache-2.0" }
 requires-python = ">=3.12"
 dependencies = [
     "chardet>=5.2.0",
-    "oa-configurator>=1.0.0,<2.0.0",
+    "oa-configurator>=2.0.0,<3",
     "pandas>=2.3.3",
     "pyarrow>=23.0.1",
     "sqlalchemy>=2.0.45",
@@ -50,7 +50,7 @@ postgres = [
   "psycopg[binary]>=3.2",
 ]
 dev = [
-    "oa-configurator[postgres]>=1.0.0,<2.0.0",
+    "oa-configurator[postgres]>=2.0.0,<3",
     "pytest>=9.0.3",
     "ty>=0.0.59",
     "ruff>=0.14.11",
@@ -82,7 +82,7 @@ testpaths = ["tests"]
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
-addopts = "-ra"
+addopts = "-ra -m 'not db_dialect'"
 
 [tool.pyright]
 reportMissingTypeStubs = false

src/orm_loader/backends/__init__.py

@@ -1,13 +1,18 @@
 from .postgres import PostgresBackend
 from .resolve import resolve_backend
 from .sqlite import SQLiteBackend
-from .base import BackendCapabilities, DatabaseBackend, STAGING_SCHEMA, Dialect
+from .base import (
+    BackendCapabilities,
+    DatabaseBackend,
+    Dialect,
+    STAGING_SCHEMA,
+    staging_schema_claim,
+)
 from ..mappers.materialised_view_errors import (
     ConcurrentRefreshNotEligibleError,
     MaterializationError,
     MaterializationFailure,
     MaterializationOperation,
-    UnsupportedMaterializationDialectError,
 )
 
 __all__ = [
@@ -21,6 +26,6 @@
     "PostgresBackend",
     "STAGING_SCHEMA",
     "SQLiteBackend",
-    "UnsupportedMaterializationDialectError",
     "resolve_backend",
+    "staging_schema_claim",
 ]