improvement: support strategy :context multitenancy via a tenant binder

[C-Sinclair]

Closes the data layer half of #127.

• Adds the tenant_binder option and the AshSqlite.TenantBinder behaviour. The data layer asks it for a connection once per statement.
• Turns on can?(_, :multitenancy) (strategy :context currently fails to compile with Data layer does not support multitenancy).
• Reads the tenant from the transaction reason, which improvement: passing tenant in the transaction reason ash#2917 added. That merged as f1602c4 and is not in a release yet, so mix.exs and mix.lock point ash at git. Restore ash_version("~> 3.34") once a release carries it.

Why not the documented workaround

Setting %{data_layer: %{repo: ...}} in a change and a preparation looks like it should work. The read path (repo.all/2) and the write path (repo.insert_all/3, through AshSql.dynamic_repo/3) both invoke the result as a module, so a repo instance raises:

** (ArgumentError) Modules (the first argument of apply) must always be an atom

That override selects between repo modules. Database-per-tenant needs a repo instance, for which Ecto binds instances with put_dynamic_repo/1.

What a tenant is here

One database file per tenant. SQLite has no schema to prefix, so the SQL is identical for every tenant and isolation comes from the connection.

• set_tenant/3 is a no-op on the query.
• The tenant is not passed to AshSql.repo_opts/5. Passing it reached Ecto as a table prefix and raised SQLite3 does not support table prefixes on every write.

Usage

sqlite do
  table "posts"
  repo MyApp.Repo
  tenant_binder MyApp.TenantBinder
end

defmodule MyApp.TenantBinder do
  @behaviour AshSqlite.TenantBinder

  @impl true
  def bind(tenant, _opts, fun) do
    previous = MyApp.Repo.get_dynamic_repo()
    MyApp.Repo.put_dynamic_repo(MyApp.Tenants.connection!(tenant))

    try do
      fun.()
    after
      MyApp.Repo.put_dynamic_repo(previous)
    end
  end
end

There is no default binder. AshSqlite.Verifiers.VerifyTenantBinder fails compilation for strategy :context resources without one.

Why the data layer picks the connection

flowchart LR
  A["Ash action"] --> B["AshSqlite.DataLayer"]
  B --> C["bind_tenant/4"]
  C -->|"tenant"| D["binder.bind/3"]
  C -->|"no tenant"| E["unbound/2 raises"]
  D --> F["put_dynamic_repo/1"]
  F --> G[("tenant.db")]

Loading

Every callback that issues SQL goes through bind_tenant/4. A caller cannot wrap a path it never sees:

• Ash.count/2 never enters Ash.Actions.Read, so no preparation or around_transaction hook runs for it.
• Ash calls atomic/3 rather than change/3 whenever it can build one statement, so a hook-installing change forces require_atomic? false.
• A dynamic repo binding is per process. It does not survive Task.async, an Ash.load fan-out, or a background job.

bind/3 also receives the resource and a usage of :read, :write or :transaction. Only the data layer knows which a given statement is, and a binder can use it to serve reads from a replica. Binders that do not care can ignore it.

Transactions

• transaction/4 reads the tenant from the reason, which improvement: passing tenant in the transaction reason ash#2917 put there.
• Writes open as BEGIN IMMEDIATE. A deferred transaction that reads then writes has to upgrade its lock, and SQLite fails an upgrade immediately regardless of busy_timeout.
• A transaction cannot span two tenants. Their rows are in separate files on separate connections, and SQLite cannot commit across databases atomically in WAL mode, even with ATTACH. A statement for a second tenant inside an open transaction raises rather than committing on its own and surviving the rollback around it.

global?

global? true with strategy :context is refused for now, until we have given it greater thought, as @zachdaniel suggested.

Not in this PR

• The runtime. AshSqlite.MultiTenancy is improvement: manage tenant databases, so strategy :context works out of the box #225: a registry, per-tenant connections, lazy migration, residency limits, quarantine, all_tenants/1 and rename/3.
• Documentation. None here and none in improvement: manage tenant databases, so strategy :context works out of the box #225. The guide gets written once the whole feature has landed.
• Tenant migration tooling. mix ash_sqlite.generate_migrations has no tenant awareness, so the tenant migrations directory is yours to maintain. AshPostgres routes tenanted resources to priv/repo/tenant_migrations; this PR does not attempt that.
• Per-tenant rollback. There is no counterpart to mix ash_postgres.rollback --tenants. Tenant migrations are forward-only for now.

[zachdaniel]

I'm feeling like if we are offering this as a feature that we should just "do this for them". AshPostgres context multitenancy automatically manages schemas for you and the selection of schemas.

For example, we could use something like :persistent_term to manage repos globally, stopping/starting them as needed etc. In its current form it feels like we're offering context multitenancy but with a lot of manual management still left to the end user.

[C-Sinclair]

Yeah I agree. It's something I was looking at in my experimental repo (ash_cell)
I'd love to have a great default exposed from AshSqlite instead!

My suggestion, if you're open to it: keep the tenant_binder + behaviour as an escape hatch. That way you expose the option for clients like Turso or Litestream etc to be implemented in the application layer. But we ship a default Binder as part of AshSqlite, that provides one connection/one db file per tenant, so zero code required to get that nice multitenancy behaviour!

:persistent_term is great, but I don't think it's the right shape here. Every put/erase copies the table and triggers a global GC scan across all processes to find references, activating and evicting tenants hits that costly write path. So the more tenant churn, the worse it gets.
Instead, we could just use a specific Registry, where connection processes are added and removed behind the scenes by the library.

I can take a look at extending this PR to include that implementation 👍

[zachdaniel]

Fair point. Will look to review the changes on Friday of this week, got a busy week ahead.

[C-Sinclair]

I opted for a follow on PR to provide a default engine for this. That way this PR stays focused on exposing the required extension points, and #225 can focus on implementation

[C-Sinclair]

We'll therefore remove this Verifier once a default is available

[C-Sinclair]

Aggregates need to be tested separately as they don't go via Ash.Actions.Read, so preparations nor around_transaction can touch them. Fortunately, tenant_binder is at the Datalayer ...layer.

[zachdaniel]

We should have Ash do this if needed then, setting something into the transaction metadata you get here.

[zachdaniel]

We could then leverage that to support Ash.transaction(...., tenant: "tenant")

[C-Sinclair]

Implemented in ash-project/ash#2917
I added optional(:tenant) => term() added Ash.DataLayer.transaction_reason/0, so we can pluck it out here!

[zachdaniel]

I think we can probably make this a simpler name. Like AshSqlite.TenantToRepo or something. Lets try to make the module and function themselves make it more obvious what they are meant to do.

[C-Sinclair]

Good shout. AshSqlite.TenantToRepo doesn't quite describe it tho, as you're ultimately trying to give a way of wrapping every data layer connection with app layer code. Its not quite a repo being returned, its an active connection for that particular query.

How about tenant_connection for the DSL & then AshSqlite.TenantConnection as the module name? The callback on the behaviour could then be with_connection(tenant, opts, fun)
Shows that you're providing a wrapper over the connection which provides the tenant. Tenant could just be one of the opts as well if we wanted it not tied just to multitenancy 🤔

Or maybe, to be more generic connection_source in DSL & AshSqlite.ConnectionSource mod, same callback?