ros-apartment 4.0.0.alpha12 → 4.0.0.alpha13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bb81b710aa16f388e8861ad84d358eee5ec751ff6cce1ad3121513e9a0ef46e
-  data.tar.gz: 49adf108763c408b893a314f223756697ccaf21b950087656b357aeb93f33dcd
+  metadata.gz: b8e5931794be153df0c2443c215f142fa9f07c8e0a0830f5efac616e0c306e58
+  data.tar.gz: e97bbef33052e8bae6a0ce036afc61aeb19a9b1a04895ddcdfb138b5bf89f031
 SHA512:
-  metadata.gz: 773ee7eff98a2f2287c53aef4b1b8172c97b2251c3d82e3f4b099e60b9602f7093cec92b8bdef9669d71a864bece4f767a2ba7dad9109816a80e8478b6087ed7
-  data.tar.gz: 1cf4884cd5b476e57481e8f928c39575e95cdc75249b86fa24dbfeb6885d28f9af1567795f22d1d71270cd402755711727f6614ecc566998d85a47cae780635c
+  metadata.gz: 362d681d9a275c070521d0f7dff72d8562e3395262df60ea1d61d8a6865956cc700047b5e12a99b132c6a51c41bdaf813592c434f0ca8f10dcdaef65bc876dbb
+  data.tar.gz: 56ab684ddbdc3db9ec820a5b833538fedf3e10ae6358edc0283020cbd352578870d9277620d4fe230b34f13308f2c7d0382c810cba66f2ac8a5d60947ea277a2

data/README.md

@@ -182,9 +182,20 @@ See the [Elevators](#elevators) section for available options.
 
 ### RBAC
 
-`migration_role`: a Symbol naming the database role used for migrations (default: nil, uses the connection's default role).
+Apartment guarantees which role executes tenant DDL and leaves privilege policy to you. Full guide: [docs/rbac.md](docs/rbac.md).
 
-`app_role`: a String or callable returning the restricted role for application queries (default: nil).
+`ddl_role`: a Symbol naming an ActiveRecord `connects_to` role used for all tenant DDL (default: nil, uses the connection's default role). It covers migrations, tenant creation and tenant drop alike: the container, both privilege-policy phases, and any `schema_load_strategy` import all run on it. Seeding does not — rows carry no ownership.
+
+`tenant_privilege_policy`: a callable invoked twice per create, once before the schema import and once after, with a context carrying the tenant, the physical container name, the connection, the resolved database role and the phase (default: nil). Apartment issues no grants of its own; a policy runs only because you configured one.
+
+```ruby
+Apartment.configure do |config|
+  config.ddl_role = :db_manager
+  config.tenant_privilege_policy = Apartment::Privileges.standard(grant_to: 'app_user')
+end
+```
+
+`Apartment::Privileges.standard` ships the engine-specific grant SQL as a library rather than as implicit behaviour, including PostgreSQL's `ALTER DEFAULT PRIVILEGES FOR ROLE`, which with no `FOR ROLE` is scoped to whichever role executed it and so has to name the database principal `ddl_role` resolves to. Two phases because position is policy: a default-privileges-only model must record its rules before the schema import, and a model granting existing objects must run after. [docs/rbac.md](docs/rbac.md) covers writing your own policy, the MySQL `GRANT OPTION` prerequisite, and what happens when a policy raises.
 
 ### PostgreSQL
 

data/lib/apartment/CLAUDE.md

@@ -23,14 +23,18 @@ lib/apartment/
 │   ├── connection_handling.rb # Prepends on AR::Base — tenant-aware connection_pool
 │   ├── connection_registry.rb # Prepends on AR's PoolManager + ConnectionHandler — serializes the pool registry
 │   └── postgresql_sequence_name.rb # Prepends on the PG adapter — schema-agnostic Model.sequence_name memoization
+├── privileges/            # Tenant privilege policy support
+│   └── context.rb         # Privileges::Context: what a tenant_privilege_policy receives, one per phase
 ├── tasks/                 # Rake task utilities; v4.rake for apartment:create/drop/migrate/seed/rollback
 ├── config.rb              # Configuration with validate!/freeze!
 ├── current.rb             # Fiber-safe tenant context (CurrentAttributes)
 ├── errors.rb              # Exception hierarchy
 ├── instrumentation.rb     # ActiveSupport::Notifications wrapper
+├── migration_role.rb      # Runs a block on config.ddl_role (shared by Migrator, CLI, adapters)
 ├── migrator.rb            # Migration orchestrator: sequential/parallel, Result/MigrationRun value objects
 ├── pool_manager.rb        # Concurrent::Map pool cache with monotonic timestamps
 ├── pool_reaper.rb         # Background idle/LRU pool eviction
+├── privileges.rb          # Privileges.standard: prebuilt tenant_privilege_policy factory
 ├── railtie.rb             # Rails initialization (activate!, middleware, rake tasks)
 ├── schema_dumper_patch.rb # Rails 8.1 schema dump fix: strips public. prefix from table names
 ├── tenant.rb              # Public API facade (switch, current, reset, lifecycle)
@@ -97,12 +101,14 @@ All inherit from `AbstractAdapter`. Override `resolve_connection_config`, `creat
 
 **Identity:** `apartment_pinned?` — the class answers whether it is pinned (ivars + superclass walk). `Apartment.pinned_model?(klass)` delegates to `klass.apartment_pinned?` when the concern is included; otherwise it falls back to registry lookup (`pinned_models`) for `excluded_models` shim classes that never included the concern.
 
-**Table naming:** `apartment_explicit_table_name?` — whether the cached `@table_name` is one Rails' convention machinery would rebuild (compares `@table_name` to `compute_table_name`). Lives here so adapters do not read `@table_name` or call `compute_table_name` from outside; **class instance variable access for pinning is confined to this concern**. It selects a **restore** strategy only — it is *not* a qualification discriminator, and using it as one shipped three silent no-ops (see `docs/designs/v4-shared-pinned-connections.md`): `compute_table_name` honours `full_table_name_prefix` only on its `base_class?` branch, so prefix-based qualification is discarded outright for subclasses and for models whose module parent defines `table_name_prefix`. Qualification always assigns `table_name` directly.
+**Table naming:** `apartment_explicit_table_name?` — whether the cached `@table_name` is one Rails' convention machinery would rebuild (compares `@table_name` to `compute_table_name`). Lives here so adapters do not read `@table_name` or call `compute_table_name` from outside; **class instance variable access for pinning is confined to this concern**. It answers one question — "would convention rebuild this cached name?" — and that answer feeds three decisions: the restore strategy (`:explicit` vs `:computed`), whether a subclass shares its base's table (`inherits_pinned_table?`), and whether an unregistered descendant declared its own (`unregistered_pinned_subclass?`). It must **not** select the qualification *strategy* — assignment vs `table_name_prefix` — which is the misuse that shipped three silent no-ops (see `docs/designs/v4-shared-pinned-connections.md`): `compute_table_name` honours `full_table_name_prefix` only on its `base_class?` branch, so prefix-based qualification is discarded outright for subclasses and for models whose module parent defines `table_name_prefix`. Qualification always assigns `table_name` directly.
 
 **Lifecycle:** `apartment_pinned_processed?`, `apartment_mark_processed!`, `apartment_restore!` — qualification state and teardown. Paths are `:computed` (convention rebuilds the name; restore drops the `@table_name` override and recomputes), `:explicit` (restore assigns the saved name back verbatim), `:prefix` (abstract base; restore puts back the app's `table_name_prefix`), and `nil` (separate-pool; nothing to undo). **Abstract bases are the one case still qualified via `table_name_prefix`**, because `pin_tenant` early-returns once a superclass is pinned — so concrete descendants are never registered and only a `class_attribute` broadcast reaches them. Adapters call these; `Apartment.clear_config` uses `apartment_restore!` with `respond_to?` so shim-registered models without the concern still clear safely. `apartment_mark_pinned!` — sets the pinned flag without triggering processing (used by `process_pinned_model` for shim classes to avoid `pin_tenant` recursion).
 
 **Subclasses of a pinned model:** `pin_tenant` is idempotent **per class**, not per hierarchy — it keys on the class's own flag, not `apartment_pinned?` (which walks the superclass chain). A subclass declaring its own table must register and qualify on its own merits, since the parent's qualification cannot reach a different table; keying on the chain made that call silently no-op. A subclass that *shares* the parent's table still needs nothing and is skipped at qualification time by `AbstractAdapter#inherits_pinned_table?`. A subclass that declares its own table and is never registered gets a boot warning (`warn_unregistered_pinned_subclasses`, descendants-based, so complete only under eager loading). See `docs/designs/v4-shared-pinned-connections.md`.
 
+**Qualification proves itself:** `verify_pinned_qualification!` checks the post-condition after qualifying — the table name actually carries the qualifier. The **registered model raises** (`ConfigurationError`); its **descendants only warn**. That split is the rule "raise on what you can prove": the model's own check is complete and unambiguous, while the descendant walk is `descendants`-based and so complete only under eager loading — the same reasoning `warn_unregistered_pinned_subclasses` documents. Descendants that are themselves registered but not yet processed are skipped (they are qualified on their own turn); the test is registry membership, **not** `apartment_pinned?`, which walks the superclass chain and would skip every descendant.
+
 **Descendant memos:** Rails memoizes `@table_name` per class and never invalidates a descendant's copy when an ancestor changes, so an early read (initializer, gem, route constraint) would freeze the *unqualified* name and the pinned model would read the tenant's table forever. `qualify_pinned_table_name` and `apartment_restore!` bracket their mutation with `apartment_descendants_inheriting_table_name` (collected **before**, while a stale memo is still distinguishable from a declaration) and `apartment_resync_descendant_table_names!` (`reset_table_name` after, which clears `@quoted_table_name`/`@arel_table` via Rails' own setter).
 
 **Guards:** `pin_tenant` raises `ArgumentError` if called on a non-AR class or module. For anonymous classes (`Class.new`), it warns that `TracePoint(:end)` won't fire and skips deferral; call `process_pinned_model` explicitly after assigning the constant.
@@ -126,6 +132,18 @@ Three hooks in Rails boot order:
 
 `Apartment::Migrator` runs migrations across all tenants with optional thread-based parallelism. Delegates to `Apartment::Tenant.switch` for each tenant — the `ConnectionHandling` patch routes `AR::Base.connection_pool` to the tenant's pool, so Rails' migration machinery (which hardcodes `AR::Base.lease_connection`) uses the correct connection automatically. No standalone pools or handler swaps. Disables PG advisory locks for tenant migrations (database-wide locks serialize parallel execution; see issue #298). `Result` (Data.define) tracks per-tenant success/failure/skip. `MigrationRun` aggregates results with `#success?`, `#summary`. Primary migration aborts the run on failure (tenants are never touched). Constructor accepts `threads:` (0=sequential). RBAC credential separation (`migration_db_config`) is deferred to Phase 5.
 
+### migration_role.rb — DDL Role Wrap
+
+`Apartment::MigrationRole.wrap` runs a block inside `connected_to(role: config.ddl_role)`, or yields when no role is configured. It exists as its own module because both `Migrator` and the adapters need it and an adapter cannot depend on `Migrator`; `Migrator.with_migration_role` stays as the documented entry point and delegates here. All tenant DDL goes through it — migrations, `Tenant.create`, and `Tenant.drop`'s engine call — because PostgreSQL scopes an `ALTER DEFAULT PRIVILEGES` rule with no `FOR ROLE` to the role that executed it, and because `DROP SCHEMA` needs ownership of a container `ddl_role` owns. See `docs/designs/v4-rbac-contract.md`.
+
+An unresolvable role is translated here: `ActiveRecord::ConnectionNotEstablished` becomes an `Apartment::ConfigurationError` naming `ddl_role` and the symbol given. `connected_to` resolves no pool — it pushes onto `connected_to_stack` and yields — so the failure arrives from *inside* the block and cannot be detected before it; a wrap whose block never touches the database stays silent by design. What discriminates is not the error class but a probe: `retrieve_connection_pool` for our role, nil meaning the failure is ours to explain and a pool meaning it belongs to the caller's block and re-raises untouched. The rescue names `ConnectionNotEstablished` and **only** that class, because `ConnectionNotDefined` does not exist before Rails 8.0 and Ruby resolves rescue constants at raise time, so naming the subclass raised `NameError` on the Rails floor and destroyed the error it was classifying. No wrapped error still needs translating: `Patches::ConnectionHandling#connection_pool` scopes its relabelling rescue to the tenant-resolution path, so errors do still arrive wrapped from inside it — but those are genuine tenant-pool failures that belong to the tenant rather than to `ddl_role`, and translating them would misattribute. A ddl_role failure is not one of them: it surfaces from the default-path lookup outside that boundary, and the tenant path establishes a pool for the role itself so it never fails on an unregistered one. The `ApartmentError` clause and one-layer unwrap this rescue once carried belonged to the old method-level rescue and went with it. Checked at first use rather than at `activate!`, which runs in `after_initialize`, after the eager-load initializer: under lazy loading no model has run `connects_to` yet and a boot-time check would fail on every boot.
+
+### privileges.rb / privileges/context.rb — Adopter-Owned Privilege Policy
+
+`Apartment::Privileges.standard(grant_to:, include_functions: true)` returns a callable suitable for `config.tenant_privilege_policy`. It owns its own phase mapping — default-privileges rules before the schema import, grants on existing objects after — so an adopter never re-derives which statements belong where. It validates `grant_to` when the policy is built, not when a tenant is created, and resolves `Apartment.adapter` at call time (the adapter is not set at `configure` time). The SQL itself lives behind the adapter seam `#standard_privilege_statements`; see `adapters/CLAUDE.md`.
+
+`Privileges::Context` is what a policy receives, one instance per phase, frozen. It is deliberately **not** `Data.define` even though `Data` is house style for value objects (`Migrator::Result`, `PoolObserver::Sample`): it carries a live connection, so value equality, hashing and positional decomposition are wrong semantics, and `Data` cannot deliver the additive-only promise — appending a member adds a required positional argument and a required keyword to `.new`, and `Data` responds to `#deconstruct`. New fields arrive as keyword arguments with defaults and unknown keywords are ignored, so a policy reading attributes off a context keeps working. Construction is the gem's business. Full contract: `docs/rbac.md`, rationale in `docs/designs/v4-rbac-contract.md`.
+
 ### schema_dumper_patch.rb — Rails 8.1 Schema Fix
 
 Patches `ActiveRecord::SchemaDumper` to strip `public.` prefix from table names in `schema.rb` output. Applied conditionally for Rails 8.1+ via `SchemaDumperPatch.apply!` (called by Railtie). Respects `PostgresqlConfig#include_schemas_in_dump` for non-public schemas that should retain their prefix.

data/lib/apartment/adapters/CLAUDE.md

@@ -65,6 +65,19 @@ AbstractAdapter
 
 **Tenant creation**: Runs callbacks, creates tenant via subclass, switches context, imports schema, optionally seeds data. See `AbstractAdapter#create` method.
 
+The create sequence inside `#run_tenant_ddl`, all of it on `config.ddl_role`: `create_tenant`, the policy at `:before_schema_load`, the schema import when `schema_load_strategy` is set, then the policy at `:after_schema_load`. Seeding runs outside that wrap, because rows carry no ownership. `#drop` wraps its `drop_tenant` call for the same ownership reason and leaves the pool removal and shard deregistration outside. PostgreSQL scopes an `ALTER DEFAULT PRIVILEGES` rule with no `FOR ROLE` to the role that executed it, so creation and migrations must share one role.
+
+Two phases because position is policy: a default-privileges-only model has to record its rules before the import or imported tables fall outside them, while a model granting existing objects has to run after. Both fire even when no schema is loaded. The database role the policy is told about is resolved once per create, inside the wrap, and passed to both phases as an argument — never memoized on the adapter, which is one instance per process and therefore shared across concurrent creates.
+
+### Privilege Seams (Custom Adapters Implement These)
+
+- `#standard_privilege_statements(ctx, grant_to:, include_functions: true)` → `Array<String>`. Builds the statements for `ctx.phase` and returns them; it does not execute, so the SQL unit-tests without a database. Return `[]` for a phase the engine does not need, and branch on `ctx.phase` by name with a raising `else` rather than falling out of a predicate guard — a silent nothing is the defect this contract replaces. The base raises `Apartment::ConfigurationError`, not `NotImplementedError`: the latter descends from `ScriptError`, so an adopter's `rescue StandardError` around `Tenant.create` would miss it. `PostgresqlSchemaAdapter` and `Mysql2Adapter` implement it; `PostgresqlDatabaseAdapter` and `Sqlite3Adapter` inherit the raise as a reasoned exclusion, each pinned by its own spec.
+- `#current_db_role(connection)` → `String` or `nil`. The executing database role, for policies that name it explicitly. The token shape differs by engine, which is why each adapter answers: PostgreSQL returns `current_user`, MySQL returns `role@host`, the base returns nil.
+
+Quote role names with `quote_column_name`, not `quote_table_name`: the latter splits on dots, and a legal role like `svc.migrator` would come back as two identifiers. Container names go through `quoted_container`, which is safe because they pass `TenantNameValidator` and it rejects dots.
+
+Guide: `docs/rbac.md`. Rationale: `docs/designs/v4-rbac-contract.md`.
+
 **Tenant switching**: Stores previous tenant, switches, yields to block, ensures rollback in ensure clause with fallback to default. See `AbstractAdapter#switch` method.
 
 **Schema import**: Loads `db/schema.rb` or custom schema file. See schema import logic in `abstract_adapter.rb`.

data/lib/apartment/adapters/abstract_adapter.rb

@@ -58,18 +58,22 @@ module Apartment
           strategy: Apartment.config.tenant_strategy,
           adapter_name: base_config['adapter']
         )
-        run_callbacks(:create) do
-          create_tenant(tenant)
-          grant_tenant_privileges(tenant)
-          import_schema(tenant) if Apartment.config.schema_load_strategy
-          seed(tenant) if Apartment.config.seed_after_create
-          Instrumentation.instrument(:create, tenant: tenant)
+        suppressing_pending_migration_check do
+          run_callbacks(:create) do
+            run_tenant_ddl(tenant)
+            seed(tenant) if Apartment.config.seed_after_create
+            Instrumentation.instrument(:create, tenant: tenant)
+          end
         end
       end
 
       # Drop a tenant.
       def drop(tenant)
-        drop_tenant(tenant)
+        # Wrapped for the same reason create is: the container is owned by ddl_role,
+        # and DROP SCHEMA requires ownership, so the writing role generally cannot drop
+        # what the gem created. Only the engine call — the pool removal and shard
+        # deregistration below are local bookkeeping and need no role.
+        MigrationRole.wrap { drop_tenant(tenant) }
         removed_pools = Apartment.pool_manager&.remove_tenant(tenant) || []
         removed_pools.each do |pool_key, pool|
           # remove_tenant already took these out of the manager, so deregister_shard's
@@ -148,6 +152,29 @@ module Apartment
         !tenant_container_exists?(tenant)
       end
 
+      # The statements Privileges.standard should execute for ctx.phase, or [] when
+      # this engine needs none in that phase. A pure function of its inputs: build,
+      # do not execute, so the SQL is unit-testable without a database.
+      #
+      # ConfigurationError rather than NotImplementedError. An adopter who configured
+      # the standard policy on a strategy that has none made a configuration mistake,
+      # and NotImplementedError descends from ScriptError, so `rescue StandardError`
+      # around Tenant.create would not catch it. The NotImplementedError raises
+      # elsewhere in this class mean something different: a subclass owes an
+      # implementation.
+      def standard_privilege_statements(_ctx, grant_to:, include_functions: true) # rubocop:disable Lint/UnusedMethodArgument
+        raise(Apartment::ConfigurationError,
+              "Apartment::Privileges.standard does not support #{self.class.name}. " \
+              'Write a tenant_privilege_policy for this strategy; see docs/rbac.md.')
+      end
+
+      # The executing database role, for policies that need to name it explicitly
+      # (PostgreSQL's ALTER DEFAULT PRIVILEGES FOR ROLE). nil where the engine has
+      # no role system. Token shape differs by engine, so each adapter answers.
+      def current_db_role(_connection)
+        nil
+      end
+
       # The namespace that makes the default tenant's tables reachable from any
       # tenant connection — a schema (PostgreSQL) or a database (MySQL).
       # Subclasses must implement when shared_pinned_connection? returns true.
@@ -172,16 +199,29 @@ module Apartment
       #   * overwriting the prefix drops one the app set, silently retargeting
       #     the model at a different table.
       #
-      # Each case left the model resolving to the *tenant's* table with no
-      # error. Reading table_name first lets Rails compute the conventional
+      # In each case the model resolves to the *tenant's* table and nothing
+      # raises. Reading table_name first lets Rails compute the conventional
       # name — honouring any prefix, suffix, or nesting the app declared —
       # before we qualify the result.
       def qualify_pinned_table_name(klass)
         # Captured before the mutation below: afterwards there is no way to
         # tell a descendant's stale memo from a table it declared itself.
         inheriting = klass.apartment_descendants_inheriting_table_name
+        # Evaluated before the mutation, which is what inherits_pinned_table?
+        # inspects.
+        mutates = pinned_qualification_mutates?(klass)
         apply_pinned_qualification(klass)
         klass.apartment_resync_descendant_table_names!(inheriting)
+        verify_pinned_qualification!(klass) if mutates
+      end
+
+      # Whether qualifying +klass+ will actually change its naming. False for
+      # the branch that deliberately mutates nothing, which must not be
+      # verified: a subclass sharing an already-pinned base's table is correct
+      # by construction, and if its base has not been qualified yet (registry
+      # order) it is about to become so.
+      def pinned_qualification_mutates?(klass)
+        klass.abstract_class? || !inherits_pinned_table?(klass)
       end
 
       def apply_pinned_qualification(klass)
@@ -196,6 +236,118 @@ module Apartment
         klass.apartment_mark_processed!(path, (original if path == :explicit))
       end
 
+      # Prove the qualification took effect rather than assuming it did.
+      #
+      # A failed qualification is otherwise indistinguishable from a successful
+      # one: the model is marked processed, nothing raises, and it serves the
+      # current tenant's rows. Checking the post-condition surfaces that class
+      # of failure at the point it happens — including one introduced by a
+      # future Rails change to the naming internals, since compute_table_name
+      # is not public API.
+      #
+      # An abstract base has no table of its own, so it is proven through the
+      # descendants its prefix was meant to reach; a `nil` name is skipped.
+      #
+      # The descendant set is computed here rather than reused from the resync
+      # pass: that one is deliberately limited to descendants holding a memo,
+      # while a descendant with no memo inherits its name lazily and can be
+      # just as wrong. Descendants that declare their own table are excluded —
+      # an ancestor's qualification was never meant to reach them, and
+      # warn_unregistered_pinned_subclasses already reports that shape.
+      # The model itself RAISES; its descendants only WARN. The asymmetry is
+      # the point, and it is the same rule warn_unregistered_pinned_subclasses
+      # follows: raise only on what this pass can actually prove.
+      #
+      # For the registered model, the check is complete and unambiguous — it
+      # was just qualified, so if the name is not qualified something is
+      # genuinely broken, every time, on every boot.
+      #
+      # For descendants it is neither. Detection walks `descendants`, so it is
+      # complete under eager loading and partial under Zeitwerk lazy loading:
+      # raising would fail production boots for a condition that dev never
+      # reports, while still missing the descendants that load later. A warning
+      # carries the same signal without making detection completeness a
+      # boot-time dependency.
+      def verify_pinned_qualification!(klass)
+        prefix = "#{verified_pinned_qualifier}."
+
+        name = pinned_table_name_for(klass)
+        if name && !name.start_with?(prefix)
+          raise(Apartment::ConfigurationError, unqualified_pinned_message(klass, name, prefix))
+        end
+
+        warn_unqualified_descendants(klass, prefix)
+      end
+
+      def warn_unqualified_descendants(klass, prefix)
+        inheriting_descendants(klass).each do |sub|
+          sub_name = pinned_table_name_for(sub)
+          next if sub_name.nil? || sub_name.start_with?(prefix)
+
+          warn(unqualified_pinned_message(sub, sub_name, prefix))
+        end
+      end
+
+      # A model whose table_name raises cannot be verified. Say so rather than
+      # skipping silently: the thesis of this check is proving rather than
+      # assuming, and an unverifiable model is exactly what it must not wave
+      # through unremarked.
+      def pinned_table_name_for(model)
+        model.table_name
+      rescue StandardError => e
+        warn '[Apartment] could not verify the pinned table name for ' \
+             "#{model.name || model.inspect}: #{e.class}: #{e.message}"
+        nil
+      end
+
+      # A nil or empty qualifier produces a bare ".table", which start_with?(".")
+      # would happily accept — the check proving nothing in exactly the case it
+      # exists for. On MySQL this is a connection config with no 'database' key.
+      def verified_pinned_qualifier
+        qualifier = pinned_table_qualifier
+        return qualifier unless qualifier.nil? || qualifier.to_s.empty?
+
+        raise(Apartment::ConfigurationError,
+              "[Apartment] #{self.class}#pinned_table_qualifier is #{qualifier.inspect}, so pinned " \
+              'models were qualified to a bare ".table" and would not resolve. On MySQL this ' \
+              "usually means the connection config carries no 'database' key.")
+      end
+
+      def inheriting_descendants(klass)
+        return [] unless klass.respond_to?(:descendants)
+
+        klass.descendants.select do |sub|
+          sub.respond_to?(:apartment_inherited_table_name) &&
+            !awaiting_own_qualification?(sub) &&
+            sub.table_name == sub.apartment_inherited_table_name
+        rescue StandardError => e
+          warn "[Apartment] could not classify pinned descendant #{sub.name || sub.inspect}: " \
+               "#{e.class}: #{e.message}"
+          false
+        end
+      end
+
+      # A descendant that is registered but not yet processed gets qualified on
+      # its own turn, by direct assignment, which reaches names the ancestor's
+      # broadcast cannot. Registry order is always parent-first — defining a
+      # subclass loads its parent, and pin_tenant registers during class-body
+      # execution — so verifying the base's descendants would otherwise raise
+      # on a model that is about to become correct, aborting the very iteration
+      # that would have fixed it. That is the remedy this check's own error
+      # message prescribes, so it has to keep working.
+      def awaiting_own_qualification?(klass)
+        Apartment.pinned_models.include?(klass) && !klass.apartment_pinned_processed?
+      end
+
+      def unqualified_pinned_message(model, name, prefix)
+        "[Apartment] #{model.name || model.inspect} is pinned but its table name " \
+          "(#{name.inspect}) is not qualified with #{prefix.inspect}, so it would read the " \
+          'current tenant instead of the default tenant. This usually means Rails composed ' \
+          "the name from something the qualifier cannot reach — a module parent's " \
+          'table_name_prefix, or a base class outside the pinned hierarchy. Call pin_tenant ' \
+          'on the model directly, or set self.table_name to an already-qualified name.'
+      end
+
       # An abstract class has no table of its own — table_name is nil — so
       # there is nothing to assign. Pinning one is a supported pattern (an
       # abstract `connects_to` base is pinned so Apartment does not build
@@ -452,21 +604,151 @@ module Apartment
         error.is_a?(Apartment::ApartmentError) && error.cause ? error.cause : error
       end
 
-      def grant_tenant_privileges(tenant)
-        app_role = Apartment.config.app_role
-        return unless app_role
-
-        conn = ActiveRecord::Base.connection
-        if app_role.respond_to?(:call)
-          app_role.call(tenant, conn)
-        else
-          grant_privileges(tenant, conn, app_role)
+      # Every DDL step of a create runs on config.ddl_role when one is set: the
+      # container, both privilege-policy phases, and any schema import.
+      #
+      # PostgreSQL scopes an ALTER DEFAULT PRIVILEGES rule with no FOR ROLE to the
+      # role that EXECUTES it, never to the role named in the GRANT. Recording such a
+      # rule under one role while migrations create tables under another leaves every
+      # migration-created table outside it — the same missing-grant failure as running
+      # the migrations themselves on the writing role, only it surfaces later, from
+      # whatever ordinary query first touches the new table.
+      #
+      # Two further constraints keep the steps in ONE wrap rather than wrapping only
+      # the policy. The container is owned by whoever created it, and ALTER on a table
+      # needs ownership. And a policy that hands the app role USAGE plus DML, never
+      # CREATE, leaves a schema import on the writing role unable to add tables to a
+      # container it does not own.
+      #
+      # Seeding stays outside the wrap: it writes rows, and rows carry no ownership.
+      def run_tenant_ddl(tenant)
+        MigrationRole.wrap do
+          create_tenant(tenant)
+          db_role = resolve_privilege_db_role
+          apply_privilege_policy(tenant, :before_schema_load, db_role)
+          import_schema(tenant) if Apartment.config.schema_load_strategy
+          apply_privilege_policy(tenant, :after_schema_load, db_role)
         end
+      ensure
+        discard_ddl_role_pool(tenant)
       end
 
-      # No-op base implementation — PG schema and MySQL adapters override.
-      def grant_privileges(tenant, connection, role_name)
-        # intentional no-op
+      # import_schema switches into the new tenant, and a pool key carries the role it
+      # was resolved under (Patches::ConnectionHandling), so that switch registers a
+      # DDL-role pool nothing else will claim.
+      #
+      # Two narrowings, both about not disconnecting somebody else's work. This
+      # discards a single key rather than calling PoolManager#evict_by_role, which
+      # Migrator uses at the end of a run and which would also drop a pool another
+      # thread is migrating through. And it skips a pool that is still in use, since
+      # the SAME key is what a concurrent migration of this tenant leases: creating a
+      # tenant that a Migrator run is already covering would otherwise pull the pool
+      # out from under it. What lingers instead is one idle pool, which the reaper
+      # collects on its own terms.
+      #
+      # The release comes first because our own import_schema lease is on this pool;
+      # without it the in-use check would see this thread and skip every discard.
+      #
+      # The in-use check is a narrowing, not a lock: another thread can lease between
+      # pool_in_use? and deregister_shard. Accepted, and documented with the reasoning
+      # at PoolManager#remove — leasing bypasses the manager's map entirely, so the race
+      # cannot be closed there.
+      def discard_ddl_role_pool(tenant)
+        role = Apartment.config.ddl_role
+        return unless role
+
+        pool_key = Apartment.pool_key(tenant, role)
+        pool = Apartment.pool_manager&.peek(pool_key)
+        release_pool_connection(tenant, pool)
+        return if Apartment.pool_in_use?(pool)
+
+        Apartment.deregister_shard(pool_key)
+      end
+
+      # Releasing a lease must not mask the create's own outcome, and it has thrown
+      # before: see Migrator#release_tenant_pool_connection, which learned the same
+      # lesson from a ThreadError during teardown.
+      def release_pool_connection(tenant, pool)
+        pool&.release_connection
+      rescue StandardError => e
+        warn "[Apartment] Connection release failed for '#{tenant}': #{e.class}: #{e.message}"
+      end
+
+      # Schema import and seeding switch into the tenant being created, and resolving
+      # that pool is where ConnectionHandling runs its pending-migration check. The
+      # container is seconds old and has of course run no migration, so the check
+      # fires against the very thing create is building and create raises instead of
+      # finishing. Only reproducible where the check is live — check_pending_migrations
+      # true (the default) and Rails.env.local? — so development and test, which is
+      # where creating a tenant by hand is most common.
+      #
+      # A switch alone does not trip it; the pool is resolved by the first query. That
+      # is why the failure looks intermittent across configurations: it needs a schema
+      # import, or seeds that actually touch the database.
+      #
+      # Migrator suppresses the same check with the same flag around its own switches.
+      # The previous value is restored rather than cleared, so a create nested inside a
+      # migration — an adopter's :create callback, a create-then-migrate helper — does
+      # not disarm the migration's own suppression on the way out.
+      #
+      # The window covers the whole :create callback chain, deliberately. Provisioning
+      # rows in the tenant just created is what those callbacks are for, and with the
+      # default schema_load_strategy of nil that tenant has no schema_migrations yet, so
+      # a narrower window would leave every such callback raising the very error this
+      # method exists to prevent.
+      #
+      # The cost of that width: Current.migrating is a boolean, not tenant-scoped, so a
+      # callback that switches to some OTHER cold tenant also skips that tenant's check
+      # and leaves its pool warm and unchecked. Accepted rather than overlooked. The
+      # check is a development convenience (config.check_pending_migrations plus
+      # Rails.env.local?), the effect is one missed warning until that pool is evicted,
+      # and closing it properly means making the flag tenant-aware — which Migrator also
+      # sets, per worker, so it is a change to a shared contract and belongs on its own.
+      def suppressing_pending_migration_check
+        previous = Apartment::Current.migrating
+        Apartment::Current.migrating = true
+        yield
+      ensure
+        Apartment::Current.migrating = previous
+      end
+
+      # The database role both phases report, resolved once per create inside the
+      # ddl_role wrap so the round trip is paid once. nil when no policy is
+      # configured: an adopter without one should pay nothing at all.
+      #
+      # Deliberately a local in run_tenant_ddl rather than an ivar. Apartment.adapter
+      # is one instance for the life of the process, so an adapter ivar is shared
+      # across concurrent creates — thread B could read the role thread A resolved and
+      # name it in ALTER DEFAULT PRIVILEGES FOR ROLE while creating objects as its
+      # own. That is the bug this design exists to prevent, arriving through shared
+      # state, and it is invisible whenever both creates share a ddl_role.
+      def resolve_privilege_db_role
+        return unless Apartment.config.tenant_privilege_policy
+
+        current_db_role(ActiveRecord::Base.connection)
+      end
+
+      # Invoke the adopter's policy for one phase. Two calls per create, because
+      # position is policy: a default-privileges-only model has to record its rules
+      # before the schema import or imported tables fall outside them, while a model
+      # granting existing objects has to run after. See
+      # docs/designs/v4-rbac-contract.md.
+      #
+      # A fresh context per phase; the two share nothing but the resolved role, which
+      # arrives as an argument.
+      def apply_privilege_policy(tenant, phase, db_role)
+        policy = Apartment.config.tenant_privilege_policy
+        return unless policy
+
+        policy.call(
+          Privileges::Context.new(
+            tenant: tenant,
+            container_name: physical_tenant_name(tenant),
+            connection: ActiveRecord::Base.connection,
+            db_role: db_role,
+            phase: phase
+          )
+        )
       end
 
       # Connection config with string keys (used by subclasses to build tenant configs).

data/lib/apartment/adapters/mysql2_adapter.rb

@@ -35,6 +35,43 @@ module Apartment
         [ActiveRecord::NoDatabaseError, Apartment::ApartmentError]
       end
 
+      # MySQL has no ALTER DEFAULT PRIVILEGES. `ON db.*` is pattern-based and covers
+      # objects created later, so one statement in the first phase is the whole
+      # policy and include_functions has nothing to control here.
+      #
+      # grant_to takes bare role names and every grant lands on `role@'%'`. Splitting
+      # an account on its last @ would be wrong, because `me@localhost` is itself a
+      # legal MySQL username, so a value carrying @ is refused rather than guessed at.
+      # A specific host is what a custom policy is for.
+      #
+      # Branching on the phase by name, rather than falling out of a
+      # before_schema_load? guard, so the empty after-phase is a stated decision and an
+      # unrecognised phase raises. A silent nothing is the defect this whole design
+      # replaces: app_role's String form did nothing on two adapters and told nobody.
+      def standard_privilege_statements(ctx, grant_to:, include_functions: true) # rubocop:disable Lint/UnusedMethodArgument
+        case ctx.phase
+        when :before_schema_load
+          roles = Array(grant_to)
+          validate_bare_role_names!(roles)
+          accounts = roles.map { |role| "#{ctx.connection.quote(role)}@'%'" }.join(', ')
+          ["GRANT SELECT, INSERT, UPDATE, DELETE ON #{ctx.quoted_container}.* TO #{accounts}"]
+        when :after_schema_load
+          # Nothing to do: the grant above already covers tables the import and later
+          # migrations create.
+          []
+        else
+          raise(Apartment::ConfigurationError, "Unknown privilege policy phase: #{ctx.phase.inspect}")
+        end
+      end
+
+      # Returns MySQL's `role@host` form, for a policy that needs to name the
+      # executing account. The statement builder above does not consume it: it assumes
+      # the `%` host, and MySQL's GRANT syntax wants the halves quoted separately
+      # (`'role'@'host'`), which a whole `role@host` token cannot express.
+      def current_db_role(connection)
+        connection.select_value('SELECT CURRENT_USER()')
+      end
+
       protected
 
       def create_tenant(tenant)
@@ -51,12 +88,13 @@ module Apartment
 
       private
 
-      def grant_privileges(tenant, connection, role_name)
-        db_name = environmentify(tenant)
-        quoted_role = connection.quote(role_name)
-        connection.execute(
-          "GRANT SELECT, INSERT, UPDATE, DELETE ON #{connection.quote_table_name(db_name)}.* TO #{quoted_role}@'%'"
-        )
+      def validate_bare_role_names!(roles)
+        hosted = roles.grep(/@/)
+        return if hosted.empty?
+
+        raise(Apartment::ConfigurationError,
+              "Apartment::Privileges.standard takes bare role names and grants to role@'%'. " \
+              "Got: #{hosted.inspect}. Write a tenant_privilege_policy to grant to another host.")
       end
 
       def container_error?(error)

data/lib/apartment/adapters/postgresql_database_adapter.rb

@@ -27,6 +27,17 @@ module Apartment
         [ActiveRecord::NoDatabaseError, Apartment::ApartmentError]
       end
 
+      # The engine is the same as the schema strategy's, so the token is identical.
+      # Implemented rather than inherited because this is the strategy most likely to
+      # need it: standard_privilege_statements raises here (see below), so privileges
+      # come from a hand-written policy, and that policy is exactly the code that wants
+      # ALTER DEFAULT PRIVILEGES FOR ROLE. Inheriting the base nil would leave it
+      # resolving the grantor itself, which is correct-by-position — the coupling this
+      # design removes.
+      def current_db_role(connection)
+        connection.select_value('SELECT current_user')
+      end
+
       protected
 
       def create_tenant(tenant)
@@ -49,11 +60,12 @@ module Apartment
         )
       end
 
-      # grant_privileges: inherits no-op from AbstractAdapter.
-      # Database-per-tenant RBAC grants require cross-database ordering
-      # (GRANT CONNECT on server, table grants inside tenant DB).
-      # Use the callable app_role escape hatch for this strategy.
-      # See docs/designs/v4-phase5-rbac-roles-schema-cache.md.
+      # standard_privilege_statements: inherits the ConfigurationError raise from
+      # AbstractAdapter. Database-per-tenant RBAC grants require cross-database
+      # ordering (GRANT CONNECT on the server, table grants inside the tenant DB),
+      # which Privileges.standard does not implement. Write a
+      # tenant_privilege_policy for this strategy instead.
+      # See docs/designs/v4-rbac-contract.md.
 
       private