ferro-orm 0.5.0__tar.gz → 0.6.0__tar.gz

{ferro_orm-0.5.0 → ferro_orm-0.6.0}/CHANGELOG.md

@@ -1,6 +1,15 @@
 # CHANGELOG
 
 
+## v0.6.0 (2026-04-30)
+
+### Features
+
+- Support typed binds and named database routing
+  ([#45](https://github.com/syn54x/ferro-orm/pull/45),
+  [`e3fc930`](https://github.com/syn54x/ferro-orm/commit/e3fc9300178dce7ba763b744b92acf0385b9e90e))
+
+
 ## v0.5.0 (2026-04-28)
 
 ### Bug Fixes

{ferro_orm-0.5.0 → ferro_orm-0.6.0}/Cargo.lock

@@ -294,7 +294,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.5.0"
+version = "0.6.0"
 dependencies = [
  "dashmap",
  "once_cell",
@@ -1179,9 +1179,9 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.39"
+version = "0.23.40"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7c2c118cb077cca2822033836dfb1b975355dfb784b5e8da48f7b6c5db74e60e"
+checksum = "ef86cd5876211988985292b91c96a8f2d298df24e75989a43a3c73f2d4d8168b"
 dependencies = [
  "once_cell",
  "ring",
@@ -1237,6 +1237,7 @@ checksum = "8a5d1c518eaf5eda38e5773f902b26ab6d5e9e9e2bb2349ca6c64cf96f80448c"
 dependencies = [
  "inherent",
  "sea-query-derive",
+ "uuid",
 ]
 
 [[package]]
@@ -1452,6 +1453,7 @@ dependencies = [
  "tokio-stream",
  "tracing",
  "url",
+ "uuid",
  "webpki-roots 0.26.11",
 ]
 
@@ -1532,6 +1534,7 @@ dependencies = [
  "stringprep",
  "thiserror",
  "tracing",
+ "uuid",
  "whoami",
 ]
 
@@ -1569,6 +1572,7 @@ dependencies = [
  "stringprep",
  "thiserror",
  "tracing",
+ "uuid",
  "whoami",
 ]
 
@@ -1594,6 +1598,7 @@ dependencies = [
  "thiserror",
  "tracing",
  "url",
+ "uuid",
 ]
 
 [[package]]

{ferro_orm-0.5.0 → ferro_orm-0.6.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ferro"
-version = "0.5.0"
+version = "0.6.0"
 edition = "2024"
 readme = "README.md"
 
@@ -27,8 +27,8 @@ serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 once_cell = "1.21"
 dashmap = "6.1"
-sqlx = { version = "0.8", features = ["runtime-tokio", "sqlite", "postgres", "any", "tls-rustls-ring-webpki"]}
-sea-query = "0.32"
+sqlx = { version = "0.8", features = ["runtime-tokio", "sqlite", "postgres", "any", "tls-rustls-ring-webpki", "uuid"]}
+sea-query = { version = "0.32", features = ["with-uuid"] }
 tokio = { version = "1.49", features = ["full"] }
 pyo3-async-runtimes = { version = "0.27", features = ["tokio-runtime"] }
 uuid = { version = "1.11", features = ["v4"] }

{ferro_orm-0.5.0 → ferro_orm-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.5.0
+Version: 0.6.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: alembic>=1.18.1 ; extra == 'alembic'
 Requires-Dist: sqlalchemy>=2.0.46 ; extra == 'alembic'

{ferro_orm-0.5.0 → ferro_orm-0.6.0}/docs/api/raw-sql.md

@@ -36,20 +36,26 @@ The `tx` handle owns the transaction's connection. You cannot misuse it —
 calling `tx.execute(...)` after the `async with` block exits raises
 `RuntimeError`.
 
-### Top-level (auto-picks active tx)
+### Top-level (`using` or active transaction)
 
 ```python
 from ferro import execute, fetch_all, fetch_one
 
-# Outside any tx — runs on a one-off pool connection.
+# Outside any tx — runs on the default connection.
 await execute("select pg_advisory_unlock_all()")
 
+# Route explicitly to a named connection.
+await execute("select run_pipeline_job($1)", job_id, using="service")
+
 # Inside a tx — auto-picked up via the same ContextVar that Model.create() uses.
-async with transaction():
+async with transaction(using="service"):
     await execute("select set_config('request.jwt.claims', $1, true)", claims_json)
     rows = await fetch_all("select * from foo where org_id = $1", org_id)
 ```
 
+Passing `using=...` inside an active transaction raises. A transaction is pinned to
+one connection, and unqualified raw SQL inherits that connection.
+
 ## Placeholders are native to the backend
 
 | Backend  | Placeholder syntax | Example                                |
@@ -96,9 +102,10 @@ the `sql` argument — use placeholders and pass values as positional args.
 ## Connection affinity
 
 Outside a `transaction()` block, each top-level `execute` / `fetch_all` /
-`fetch_one` call may use a different pool connection. Wrap in
-`transaction()` for connection-affinity-sensitive operations like
-`SET LOCAL`, advisory locks, or `LISTEN/NOTIFY`.
+`fetch_one` call runs on the selected named pool (`using=...`) or the default
+pool. Consecutive calls may use different physical connections from that pool.
+Wrap in `transaction(using=...)` for connection-affinity-sensitive operations
+like `SET LOCAL`, advisory locks, or `LISTEN/NOTIFY`.
 
 ## What raw SQL doesn't do
 

ferro_orm-0.6.0/docs/brainstorms/2026-04-29-named-connections-role-routing-requirements.md

@@ -0,0 +1,218 @@
+---
+
+## date: 2026-04-29
+
+topic: named-connections-role-routing
+
+# Named Connections and Role-Safe Routing
+
+## Problem Frame
+
+Ferro currently presents a single active database engine to Python callers. That keeps the API simple, but it blocks users who need to use the same database through different Postgres roles, such as a Supabase application role for user-facing data access and a service or pipeline role for trusted internal work.
+
+The feature should let users register multiple named connections and choose the intended connection at the operation or transaction boundary. The default experience should stay ergonomic for single-database apps, while multi-role apps get explicit routing, role-safe transaction behavior, separate pool settings, and clear guardrails against accidental privilege mixing.
+
+---
+
+## Actors
+
+- A1. Application developer: Configures Ferro connections and writes model/query code.
+- A2. User-facing application runtime: Handles normal product requests through the least-privileged app connection.
+- A3. Internal service or pipeline runtime: Runs trusted background work through a separate elevated connection.
+- A4. Migration or setup process: Creates or updates schema using an explicitly chosen connection.
+- A5. Downstream implementation agent: Plans and builds the feature without inventing public API semantics.
+
+---
+
+## Key Flows
+
+- F1. Single-connection app startup
+  - **Trigger:** A developer uses Ferro as they do today with one database URL.
+  - **Actors:** A1, A2
+  - **Steps:** The app calls `ferro.connect(url)`. Ferro registers that connection as `"default"` and makes it the default connection. Existing unqualified model, query, transaction, and raw SQL calls continue to work.
+  - **Outcome:** Existing apps do not need to learn named routing unless they add more connections.
+  - **Covered by:** R1, R2, R5, R14
+- F2. Multi-role Supabase startup
+  - **Trigger:** A developer needs separate app and service-role database access.
+  - **Actors:** A1, A2, A3
+  - **Steps:** The app registers an app connection with `default=True` and a service connection with its own name and pool settings. Normal model calls use the app connection. Pipeline code opts into the service connection explicitly.
+  - **Outcome:** Both roles can coexist in one process without reconnecting global state or sharing a pool.
+  - **Covered by:** R1, R2, R3, R4, R6, R12
+- F3. Service transaction with inherited routing
+  - **Trigger:** A pipeline needs a unit of work to run through the service connection.
+  - **Actors:** A3
+  - **Steps:** Pipeline code enters `async with ferro.transaction(using="service")`. Unqualified model and raw SQL operations inside the block inherit the transaction connection. Any attempt to route part of the transaction to another connection fails clearly.
+  - **Outcome:** The transaction is ergonomic and cannot silently become a cross-connection pseudo-transaction.
+  - **Covered by:** R7, R8, R9, R10, R11
+- F4. Schema setup on an explicit connection
+  - **Trigger:** A developer wants Ferro to create tables or run setup against a specific role.
+  - **Actors:** A1, A4
+  - **Steps:** The developer chooses the connection when enabling `auto_migrate` or calling schema creation APIs. Ferro does not assume that the default app connection should have migration privileges.
+  - **Outcome:** Schema writes are deliberate and can be restricted to a migration-capable connection.
+  - **Covered by:** R13, R15
+
+---
+
+## Requirements
+
+**Connection registration and defaults**
+
+- R1. Ferro must support registering more than one active connection in a process, each identified by a stable string name.
+- R2. Calling `ferro.connect(url)` without a name must remain valid and must register the connection as `"default"`.
+- R3. `ferro.connect(url, name="...", default=True)` must make that named connection the default for unqualified operations.
+- R4. Ferro must provide a way to change the default connection after registration, such as `ferro.set_default_connection("app")`.
+- R5. If more than one connection exists and no default has been selected, unqualified operations must fail with a clear error instead of guessing.
+
+**Pool configuration**
+
+- R6. Pool configuration must belong to the named connection, because app, service, pipeline, replica, and test connections can have different concurrency and lifetime needs.
+- R7. Ferro should expose pool configuration as a Ferro API object or explicit keyword arguments rather than overloading database URL query parameters.
+- R8. Native database URL settings, such as Postgres TLS parameters, must remain in the connection URL when they are part of the database driver's normal URL contract.
+- R9. The initial pool configuration surface should cover the common operational needs: maximum connections, minimum connections if supported, acquire timeout, idle timeout, max lifetime, and connection health checking if supported by the backend.
+- R10. Pool configuration must be optional; a connection with no explicit pool settings should use conservative Ferro defaults.
+
+**Routing and operation ergonomics**
+
+- R11. Ferro must support explicit per-operation routing through a named connection, using a concise API such as `Model.using("service")`, query-level `using`, or an equivalent fluent surface.
+- R12. The connection resolution order must be: explicit operation routing first, active transaction connection second, default connection third, and clear error last.
+- R13. Raw SQL APIs must participate in the same routing model as ORM APIs, including transaction inheritance.
+
+**Transactions**
+
+- R14. `ferro.transaction(using="name")` must bind the transaction to exactly one named connection for its lifetime.
+- R15. Unqualified ORM and raw SQL calls inside a transaction must inherit the transaction's named connection.
+- R16. Explicitly routing an operation to a different connection inside an active transaction must fail clearly unless Ferro later introduces an explicit cross-connection transaction feature.
+- R17. Nested transactions must inherit the parent transaction connection unless the nested call specifies the same connection; specifying a different connection must fail clearly.
+
+**Identity map and object safety**
+
+- R18. Ferro's identity map must isolate instances by connection name as well as model and primary key, so an object loaded through an elevated role cannot be reused to satisfy an app-role query.
+- R19. Model instances loaded from a named connection should carry enough internal state for later saves or relationship operations to prefer the same connection when no stronger routing context exists.
+
+**Schema management and migrations**
+
+- R20. `auto_migrate` and explicit schema creation APIs must run against a specific named connection.
+- R21. Documentation must recommend using a migration-capable connection for schema changes rather than assuming the default app connection has DDL privileges.
+- R22. Ferro must not silently run migrations across all registered connections.
+
+**Security and Supabase guidance**
+
+- R23. Documentation must warn that elevated service credentials must stay server-side and should not be exposed in public clients.
+- R24. Documentation must recommend least-privileged custom Postgres roles where possible, with service-style privileges reserved for trusted internal processes.
+- R25. Ferro must redact connection credentials in logs and user-facing errors.
+
+---
+
+## Acceptance Examples
+
+- AE1. **Covers R1, R2, R14.** Given an existing app calls `await ferro.connect(url)`, when it calls `await User.create(...)`, the operation uses the implicitly registered `"default"` connection and does not require `using`.
+- AE2. **Covers R3, R5, R11.** Given `app` and `service` connections are registered and `app` is marked default, when code calls `await User.all()`, it uses `app`; when code calls `await PipelineEvent.using("service").create(...)`, it uses `service`.
+- AE3. **Covers R12, R14, R15.** Given code is inside `async with ferro.transaction(using="service")`, when it calls `await PipelineEvent.create(...)`, the model call uses the service transaction connection without repeating `using="service"`.
+- AE4. **Covers R16, R17.** Given code is inside `async with ferro.transaction(using="service")`, when it attempts `await User.using("app").create(...)`, Ferro raises an error explaining that a transaction cannot switch from `service` to `app`.
+- AE5. **Covers R18.** Given row `User(id=1)` is loaded through `service`, when the same row is later queried through `app`, Ferro must not return the service-loaded Python instance from the identity map.
+- AE6. **Covers R6, R7, R10.** Given the app connection has `max_connections=20` and the service connection has `max_connections=5`, each named connection uses its own pool settings and neither setting affects the other.
+- AE7. **Covers R20, R22.** Given `app` and `service` connections are registered, when `create_tables(using="service")` runs, Ferro creates schema only through `service` and does not run DDL on `app`.
+- AE8. **Covers R23, R25.** Given a Supabase connection fails, the raised error and logs do not reveal passwords, service credentials, or full secret-bearing URLs.
+
+---
+
+## Success Criteria
+
+- Existing single-connection Ferro apps continue to work without API changes.
+- A user can run app-role and service-role Supabase/Postgres work in the same process without resetting global engine state.
+- The happy path for a service transaction is concise enough that users do not repeat `using="service"` on every call inside the block.
+- The API makes privilege boundaries visible at connection setup and transaction entry, not hidden in model definitions or global magic.
+- Transaction behavior never implies atomicity across more than one named connection.
+- A downstream planner can implement the feature without deciding the public API precedence rules, default behavior, pool ownership model, or Supabase safety posture from scratch.
+
+---
+
+## Scope Boundaries
+
+- The first version does not need automatic read/write splitting or policy routers like Django's `DATABASE_ROUTERS`.
+- The first version does not need distributed or two-phase transactions across named connections.
+- The first version does not need cross-database relationships or joins.
+- The first version does not need dynamic tenant connection creation beyond the same named registration primitives.
+- The first version does not need per-model static binding, though the API should not preclude it later.
+- Supabase is the motivating Postgres deployment target, but the feature should stay framed as named connection support rather than a Supabase-only capability.
+- The feature should not add support for new database backends beyond Ferro's current supported backend contract.
+
+---
+
+## Key Decisions
+
+- Named connections are the core abstraction: They cover same-database different-role access, multiple databases, replicas, and future routing without inventing a Supabase-only concept.
+- Pool settings live on the connection: This matches operational reality and avoids global pool settings that are wrong for either app traffic or pipeline work.
+- A default connection is allowed: It preserves Ferro's ergonomic model and avoids forcing `using` everywhere in normal application code.
+- Transactions create an ambient routing context: This makes service-role units of work concise while keeping all operations on one connection.
+- Explicit cross-connection operations inside a transaction are errors: This prevents accidental pseudo-atomic workflows.
+- Identity-map keys include connection identity: This is necessary for role safety when different roles can see different rows or columns.
+- Migrations are connection-specific: Schema writes should be deliberate and not fan out across registered connections.
+- Credentials must be redacted: Multi-role support increases the chance that elevated credentials pass through Ferro configuration.
+
+---
+
+## Proposed UX Shape
+
+This section is illustrative product UX, not an implementation prescription.
+
+```python
+await ferro.connect(
+    app_url,
+    name="app",
+    default=True,
+    pool=ferro.PoolConfig(max_connections=20, min_connections=2),
+)
+
+await ferro.connect(
+    service_url,
+    name="service",
+    pool=ferro.PoolConfig(max_connections=5, acquire_timeout=30),
+)
+
+await User.create(email="user@example.com")  # Uses app.
+
+async with ferro.transaction(using="service"):
+    await PipelineEvent.create(kind="sync_started")  # Uses service.
+    await ferro.execute("select set_config('app.pipeline', $1, true)", "sync")
+```
+
+Connection resolution:
+
+```text
+explicit operation using
+  -> active transaction connection
+  -> default named connection
+  -> clear "no connection selected" error
+```
+
+---
+
+## Dependencies / Assumptions
+
+- Ferro's typed backend work is the right foundation for this feature; named connections should build on explicit engine handles rather than revive URL-string or generic-pool dispatch.
+- Direct Supabase/Postgres connections can represent the needed role boundary through distinct database URLs or credentials.
+- Users who need multiple roles in one process value explicitness over fully automatic routing.
+- Keeping routers out of v1 reduces API and testing complexity without blocking the app/service-role use case.
+
+---
+
+## Outstanding Questions
+
+### Resolve Before Planning
+
+- None.
+
+### Deferred to Planning
+
+- [Affects R7, R9][Technical] Which pool settings are supported uniformly across SQLite and Postgres, and which need backend-specific validation?
+- [Affects R11, R12][Technical] Should the primary explicit routing API be `Model.using("name")`, query terminal `using="name"` arguments, or both for parity with the current query builder shape?
+- [Affects R19][Technical] How should instance stickiness interact with an active transaction when they disagree?
+- [Affects R20][Technical] Should `auto_migrate=True` remain on `connect()` only, or should schema setup move toward an explicit `create_tables(using="name")` first-class UX?
+- [Affects R26][Needs research] What exact redaction behavior should be shared across Rust logs, Python exceptions, and test diagnostics?
+
+---
+
+## Next Steps
+
+-> /ce-plan for structured implementation planning.

{ferro_orm-0.5.0 → ferro_orm-0.6.0}/docs/coming-soon.md

@@ -56,28 +56,27 @@ banned_users = await User.where(
 
 ### Raw SQL Queries
 
-**Status:** Not Implemented
+**Status:** Implemented for `execute`, `fetch_all`, and `fetch_one`
 
 **Documentation References:**
 - `docs/guide/queries.md` (lines 252-266)
 
 **Description:**
-Direct raw SQL query execution with parameterization.
+Direct raw SQL execution with parameterization is available. Raw rows are plain dictionaries of wire-close primitive values; typed model hydration still belongs to the ORM.
 
-**Example (Not Working):**
+**Example:**
 ```python
-# This does not work yet
-from ferro import raw_query
+from ferro import execute, fetch_all
 
-results = await raw_query(
+results = await fetch_all(
     "SELECT * FROM users WHERE age > $1 AND status = $2",
     18,
-    "active"
+    "active",
+    using="app",
 )
 ```
 
-**Workaround:**
-Use the query builder API for all queries.
+Additional raw helpers beyond these functions remain out of scope.
 
 ---
 
@@ -264,48 +263,40 @@ Use `transaction()` context manager for scoped database operations.
 - `docs/guide/database.md` (lines 76-104)
 
 **Description:**
-Advanced connection pool parameters like `max_connections`, `min_connections`, and `connect_timeout`.
+`PoolConfig(max_connections=..., min_connections=...)` is implemented per connection. Additional pool options like acquire timeout, idle timeout, max lifetime, and health-check toggles are still future work.
 
 **Example (Partially Working):**
 ```python
-# Support for these parameters is not confirmed
 await ferro.connect(
     "postgresql://user:password@localhost/dbname",
-    max_connections=20,      # May not work
-    min_connections=5,       # May not work
-    connect_timeout=30       # May not work
+    pool=ferro.PoolConfig(max_connections=20, min_connections=5),
 )
 ```
 
-**Workaround:**
-Use basic connection string without advanced pool parameters.
+For unsupported advanced pool options, use backend defaults.
 
 ---
 
 ### Multiple Database Support
 
-**Status:** Not Implemented
+**Status:** Implemented for explicit named connections
 
 **Documentation References:**
 - `docs/guide/database.md` (lines 123-149)
 - `docs/howto/multiple-databases.md` (entire file)
 
 **Description:**
-Connecting to and querying multiple databases with named connections.
+Connecting to and querying multiple databases or roles with explicit named connections is supported. Automatic router policies, read/write splitting, and distributed transactions remain out of scope.
 
-**Example (Not Working):**
+**Example:**
 ```python
-# This does not work yet
-await ferro.connect("postgresql://localhost/main_db", name="primary")
+await ferro.connect("postgresql://localhost/main_db", name="primary", default=True)
 await ferro.connect("postgresql://localhost/replica_db", name="replica")
 
 # Query specific database
 users = await User.using("replica").all()
 ```
 
-**Workaround:**
-Ferro currently supports only a single database connection per application.
-
 ---
 
 ## Transaction Features
@@ -489,7 +480,7 @@ profile = await user.profile
 ### Definitely Not Implemented
 1. `ilike()` - case-insensitive LIKE
 2. `not_in_()` - NOT IN operator
-3. Raw SQL queries (`raw_query`)
+3. Additional raw SQL helper APIs beyond `execute` / `fetch_all` / `fetch_one`
 4. Eager loading (`prefetch_related`)
 5. Select specific fields (partial model loading)
 6. Aggregation functions (sum, avg, min, max)
@@ -497,8 +488,8 @@ profile = await user.profile
 8. `disconnect()` function
 9. `check_connection()` function
 10. `connection_context()` context manager
-11. Connection pool advanced parameters
-12. Multiple database support (`.using()`)
+11. Additional connection pool parameters
+12. Automatic routing policies for multiple databases
 13. Nested transactions / savepoints
 
 ### Needs Verification

{ferro_orm-0.5.0 → ferro_orm-0.6.0}/docs/faq.md

@@ -137,7 +137,17 @@ Check your Ferro version's API for raw SQL support. Most versions provide an esc
 
 ### Does Ferro support multiple databases?
 
-Not yet. Ferro currently supports a single active database connection per application process.
+Yes. Register each pool with a name and route explicitly with `using`:
+
+```python
+await ferro.connect(APP_DATABASE_URL, name="app", default=True)
+await ferro.connect(SERVICE_DATABASE_URL, name="service")
+
+users = await User.all()  # app/default
+jobs = await Job.using("service").all()
+```
+
+Ferro does not provide automatic routers, cross-database joins, or distributed transactions in v1.
 
 See [How-To: Multiple Databases](howto/multiple-databases.md).
 

{ferro_orm-0.5.0 → ferro_orm-0.6.0}/docs/guide/backend.md

@@ -15,7 +15,7 @@ The backend is the runtime database engine behind Ferro's Python API. It owns:
 - backend-specific SQL generation choices
 - value binding and hydration rules
 
-The backend does not introduce a new public routing API. Ferro still uses one active engine per process. Named databases, replicas, and `using("name")`-style routing are intentionally deferred.
+The backend supports a registry of named connections. The common case still uses one default engine per process, while advanced applications can register multiple pools and route ORM, raw SQL, transaction, and schema operations with `using="name"`.
 
 ## Supported Backends
 
@@ -44,19 +44,22 @@ The important implementation detail is that URL detection happens once during `c
 1. Splits Ferro-only query parameters from the database URL.
 2. Classifies the backend from the URL scheme.
 3. Creates a typed SQLx pool for that backend.
-4. Stores an `Arc<EngineHandle>` in global engine state.
+4. Registers an `Arc<EngineHandle>` under a connection name and optionally selects it as the default.
 
-SQLite uses `SqlitePoolOptions` and PostgreSQL uses `PgPoolOptions`. Both currently use a fixed pool size of 5 connections.
+SQLite uses `SqlitePoolOptions` and PostgreSQL uses `PgPoolOptions`. `PoolConfig(max_connections=..., min_connections=...)` is applied per named connection, so app-role and service-role pools can have different sizes.
 
 ```text
-connect(url, auto_migrate)
+connect(url, name, default, auto_migrate, pool)
   -> split ferro_search_path
   -> BackendKind::from_url(url)
   -> connect typed pool
   -> optionally create tables
-  -> store EngineHandle globally
+  -> store EngineHandle in the named registry
+  -> optionally update the default connection
 ```
 
+Connection resolution is centralized. Explicit `using` wins outside a transaction; active transactions pin all work to their selected connection; instance methods prefer the instance's origin connection; unqualified calls then fall back to the selected default connection.
+
 ### PostgreSQL Search Paths
 
 Ferro supports a private `ferro_search_path` URL parameter for test isolation:

{ferro_orm-0.5.0 → ferro_orm-0.6.0}/docs/guide/database.md

@@ -85,6 +85,46 @@ If you assemble the URI yourself, percent-encode reserved characters in the pass
 
 ## Connection Options
 
+### Named Connections
+
+Ferro can keep multiple active pools in one process. Unnamed `connect()` calls register and select the `"default"` connection. Named connections are explicit and only become the default when `default=True` is passed.
+
+```python
+import os
+import ferro
+
+await ferro.connect(
+    os.environ["APP_DATABASE_URL"],
+    name="app",
+    default=True,
+    pool=ferro.PoolConfig(max_connections=10, min_connections=1),
+)
+await ferro.connect(
+    os.environ["SERVICE_DATABASE_URL"],
+    name="service",
+    pool=ferro.PoolConfig(max_connections=3),
+)
+
+# Default app role
+users = await User.all()
+
+# Explicit service role
+job = await Job.using("service").create(kind="backfill")
+await ferro.execute("select run_internal_job(?)", job.id, using="service")
+```
+
+Use constants or trusted server-side code to choose `using` values. Do not bind connection names directly from request parameters, headers, GraphQL arguments, or other untrusted input.
+
+### Transaction Inheritance
+
+Transactions are bound to one connection. Operations inside the block inherit that connection; trying to switch to another connection inside the transaction raises.
+
+```python
+async with ferro.transaction(using="service"):
+    await Job.create(kind="backfill")  # runs on service
+    await ferro.execute("select set_config('role_context', ?, true)", "pipeline")
+```
+
 ### Auto-Migration (Development)
 
 During development, automatically align the database schema with your models:
@@ -110,14 +150,31 @@ async def main():
     # Import models to register them
     from myapp.models import User, Post, Comment
 
-    # Create all tables
+    # Create all tables on the default connection
     await ferro.create_tables()
 ```
 
 ## Multiple Databases
 
-!!! warning "Feature Not Implemented"
-    Multi-database support is not yet available. Ferro currently supports only a single database connection per application. See [Coming Soon](../coming-soon.md#multiple-database-support) and [How-To: Multiple Databases](../howto/multiple-databases.md) for planned features.
+Use named connections for multiple databases, roles, or pools:
+
+```python
+await ferro.connect(os.environ["APP_DATABASE_URL"], name="app", default=True)
+await ferro.connect(os.environ["SERVICE_DATABASE_URL"], name="service")
+
+await ferro.create_tables(using="service")
+service_users = await User.using("service").all()
+```
+
+Ferro does not provide automatic router policies, read/write splitting, distributed transactions, or cross-connection joins in v1. Route each operation explicitly when it should not use the default connection.
+
+### Supabase Role Guidance
+
+For Supabase/Postgres deployments, keep elevated service credentials server-side. Prefer least-privileged custom roles where possible, and avoid making a service-role connection the default in user-facing runtimes.
+
+Named connections isolate pools and roles, not per-request RLS/JWT/session context inside one shared pool. If you set Postgres session state, prefer transaction-local settings and keep the work inside `transaction(using=...)`.
+
+Service-origin objects can contain data unavailable to the app role. Treat them as elevated data and filter them deliberately before returning user-facing responses.
 
 ## Health Checks
 
@@ -196,16 +253,12 @@ async def on_shutdown():
 !!! note "disconnect() Not Available"
     The `disconnect()` function is not yet implemented. Connection cleanup happens automatically on process exit. See [Coming Soon](../coming-soon.md#disconnect) for more information.
 
-### Use One Long-Lived Connection
-
-!!! note
-    Advanced pool configuration such as `max_connections`, `min_connections`, and `connect_timeout` is not exposed by Ferro's current Python API. See [Coming Soon](../coming-soon.md#connection-pool-configuration).
+### Use Long-Lived Pools
 
-For web applications, connect once at startup and reuse that engine:
+For web applications, connect once at startup and reuse those pools:
 
 ```python
-# Basic connection for production
-await ferro.connect("postgresql://localhost/proddb")
+await ferro.connect("postgresql://localhost/proddb", name="app", default=True)
 ```
 
 ### Separate Dev/Prod Configs

{ferro_orm-0.5.0 → ferro_orm-0.6.0}/docs/guide/queries.md

@@ -251,8 +251,16 @@ smith_users = await User.where(User.name.like("%Smith%")).all()
 
 ## Raw SQL
 
-!!! warning "Feature Not Implemented"
-    Raw SQL query execution is not yet available. Use the query builder API for all queries. See [Coming Soon](../coming-soon.md#raw-sql-queries) for more information.
+Ferro exposes `execute`, `fetch_all`, and `fetch_one` for raw SQL escape hatches. Raw SQL uses backend-native placeholders and can route to named connections:
+
+```python
+from ferro import execute, fetch_all
+
+await execute("select run_pipeline_job($1)", job_id, using="service")
+rows = await fetch_all("select id, name from users where org_id = $1", org_id)
+```
+
+Inside `transaction(using="service")`, raw SQL inherits the transaction connection. See [Raw SQL](../api/raw-sql.md) for bind-type details and caveats.
 
 ## Performance Tips