Skip to content

Add multi-database routing for transaction.atomic(...) and runtime-bound ORM access #45

@danceroutine

Description

@danceroutine

Summary

Tango's current runtime model is centered on one selected environment and one default runtime/database target at a time. That keeps the common case straightforward, but it becomes a real limitation once transaction work needs to route across multiple databases intentionally.

Current codebase context

  • packages/orm/src/runtime/defaultRuntime.ts exposes a singleton default runtime.
  • packages/orm/src/transaction/atomic.ts always binds to getTangoRuntime().
  • packages/orm/src/manager/registerModelObjects.ts and runtime-bound managers assume the default runtime path.
  • Config today models one db block per environment rather than a routing story across multiple targets.

Problem

The core transaction API now exists, but it cannot yet express routing decisions such as:

  • run this transaction against a non-default database
  • route one model family to one database and another family to a different database
  • ensure runtime-bound managers and transaction.atomic(...) agree on the same routed client

Without a routing contract, multi-database support stays outside the supported transaction story.

Proposed implementation plan

  1. Define the routing contract.
    • Decide whether routing is explicit per call, model-based, request-scoped, or a combination.
    • Keep the first version narrow enough that transaction semantics stay understandable.
  2. Generalize runtime/database resolution.
    • Teach the runtime layer to resolve more than one database target intentionally.
    • Ensure transaction engines are keyed by the effective routed client/runtime rather than assuming one global default.
  3. Thread routing through ORM access points.
    • Align transaction.atomic(...), manager-backed writes, and runtime-bound query execution so they can share the same routed client.
    • Fail clearly when incompatible routing contexts are mixed.
  4. Update config/docs/tests.
    • Define how routing is configured or injected.
    • Cover nested transactions, default fallbacks, and misrouting cases in tests.

Acceptance criteria

  • Tango has a documented routing contract for transaction work against multiple database targets.
  • transaction.atomic(...) can target something other than the implicit default runtime path.
  • Runtime-bound managers and queryset execution can participate in the routed transaction story coherently.
  • Mixed or incompatible routing contexts fail with clear errors.
  • Tests cover routing behavior, nested transactions, and default fallback cases.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions