ferro-orm 0.3.2__tar.gz → 0.3.3__tar.gz

{ferro_orm-0.3.2 → ferro_orm-0.3.3}/.github/workflows/ci.yml

@@ -171,6 +171,60 @@ jobs:
           name: python-${{ matrix.python-version }}
         continue-on-error: true
 
+  test-python-backend-matrix:
+    name: Python backend matrix (SQLite + Postgres)
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_USER: ferro
+          POSTGRES_PASSWORD: ferro
+          POSTGRES_DB: ferro
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U ferro -d ferro"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      FERRO_SUPABASE_URL: postgresql://ferro:ferro@127.0.0.1:5432/ferro?sslmode=disable
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install UV
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust build
+        uses: Swatinem/rust-cache@v2
+        with:
+          prefix-key: v1
+          cache-on-failure: true
+
+      - name: Install dependencies
+        run: |
+          uv sync --only-group ci-test --no-install-project --python 3.13
+
+      - name: Build Rust extension
+        run: |
+          uv run maturin develop
+
+      - name: Run backend matrix tests
+        run: |
+          uv run pytest -v -m "backend_matrix or postgres_only" --db-backends=sqlite,postgres
+
   check-conventional-commits:
     name: Check Conventional Commits
     runs-on: ubuntu-latest
@@ -220,7 +274,7 @@ jobs:
 
   all-checks:
     name: All Checks Passed
-    needs: [lint-and-format, test-python-pr, test-python-main, test-rust]
+    needs: [lint-and-format, test-python-pr, test-python-main, test-python-backend-matrix, test-rust]
     runs-on: ubuntu-latest
     if: always()
     steps:
@@ -232,6 +286,7 @@ jobs:
           if ! ok "${{ needs.lint-and-format.result }}"; then exit 1; fi
           if ! ok "${{ needs.test-python-pr.result }}"; then exit 1; fi
           if ! ok "${{ needs.test-python-main.result }}"; then exit 1; fi
+          if ! ok "${{ needs.test-python-backend-matrix.result }}"; then exit 1; fi
           if ! ok "${{ needs.test-rust.result }}"; then exit 1; fi
 
           echo "All checks passed!"

{ferro_orm-0.3.2 → ferro_orm-0.3.3}/CHANGELOG.md

@@ -1,6 +1,57 @@
 # CHANGELOG
 
 
+## v0.3.3 (2026-04-24)
+
+### Bug Fixes
+
+- Cast NULL and strings to ::uuid for Postgres using catalog
+  ([`f5cb4f0`](https://github.com/syn54x/ferro-orm/commit/f5cb4f08ceaf0763a29c3b78d4d077ca1119fc1c))
+
+- Catalog casts for date/timestamp columns on Postgres
+  ([`95ef5ca`](https://github.com/syn54x/ferro-orm/commit/95ef5cadc28eb26481c38b51dbca1b370a883d10))
+
+- Clean up rebase conflicts with main
+  ([`716511c`](https://github.com/syn54x/ferro-orm/commit/716511c829021ee6d2390bb85c877e670c1d7631))
+
+- Enum OIDs
+  ([`a9867be`](https://github.com/syn54x/ferro-orm/commit/a9867beac242a9d630aeb7e49b718a4234c541ec))
+
+- Postgres native enums on save and StrEnum schema registration
+  ([`44277e1`](https://github.com/syn54x/ferro-orm/commit/44277e1922182b020c17d9a7a2a9e99dd62061e5))
+
+- Use Postgres SQL dialect when connecting to postgres URLs
+  ([`c627ac8`](https://github.com/syn54x/ferro-orm/commit/c627ac8e4fa84555e0cc7250f73ce6f0858125a3))
+
+- **postgres**: Add dual-db ORM test matrix
+  ([`1fa657f`](https://github.com/syn54x/ferro-orm/commit/1fa657fe4335d41214fcb24b1eac5dcf3138273f))
+
+- **postgres**: Bind boolean writes as booleans
+  ([`346441a`](https://github.com/syn54x/ferro-orm/commit/346441a073a540c857a8aaa67bf4029cb4099535))
+
+- **postgres**: Cast uuid columns to text in SELECT for Any decode
+  ([`df957c0`](https://github.com/syn54x/ferro-orm/commit/df957c0202d32608843d6a24ae4c924ed5b9381d))
+
+- **postgres**: Cast UUID filter params for sqlx Any compatibility
+  ([`889cf8b`](https://github.com/syn54x/ferro-orm/commit/889cf8b61131c2d53e8414a76ca7b2dbc7868c23))
+
+- **postgres**: Decode native enum columns via text cast
+  ([`1270f9d`](https://github.com/syn54x/ferro-orm/commit/1270f9dcd1cc5aa19cf484c3d9c3bb3a82255a05))
+
+### Refactoring
+
+- Expand db matrix coverage and harden postgres paths
+  ([`b82f3ac`](https://github.com/syn54x/ferro-orm/commit/b82f3ac886459861cdfde122b99b880b85c09a61))
+
+- Multi db architecture with true sqlite and postgres support
+  ([`459a0c5`](https://github.com/syn54x/ferro-orm/commit/459a0c5f9c8a95ecacc9ba552137252d34de4824))
+
+### Testing
+
+- Expand schema constraints into db matrix
+  ([`24a7f0a`](https://github.com/syn54x/ferro-orm/commit/24a7f0ad38b90e98a41cf32fe2777d988ff7047f))
+
+
 ## v0.3.2 (2026-04-24)
 
 ### Bug Fixes

{ferro_orm-0.3.2 → ferro_orm-0.3.3}/Cargo.lock

@@ -79,9 +79,9 @@ checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
 [[package]]
 name = "cc"
-version = "1.2.60"
+version = "1.2.61"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "43c5703da9466b66a946814e1adf53ea2c90f10063b86290cc9eb67ce3478a20"
+checksum = "d16d90359e986641506914ba71350897565610e87ce0ad9e6f28569db3dd5c6d"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -128,9 +128,9 @@ dependencies = [
 
 [[package]]
 name = "crc-catalog"
-version = "2.4.0"
+version = "2.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "19d374276b40fb8bbdee95aef7c7fa6b5316ec764510eb64b8dd0e2ed0d7e7f5"
+checksum = "217698eaf96b4a3f0bc4f3662aaa55bdf913cd54d7204591faa790070c6d0853"
 
 [[package]]
 name = "crossbeam-queue"
@@ -294,7 +294,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.3.2"
+version = "0.3.3"
 dependencies = [
  "dashmap",
  "once_cell",
@@ -1191,9 +1191,9 @@ dependencies = [
 
 [[package]]
 name = "rustls-pki-types"
-version = "1.14.0"
+version = "1.14.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "be040f8b0a225e40375822a563fa9524378b9d63112f53e19ffff34df5d33fdd"
+checksum = "30a7197ae7eb376e574fe940d068c30fe0462554a3ddbe4eca7838e049c937a9"
 dependencies = [
  "zeroize",
 ]

{ferro_orm-0.3.2 → ferro_orm-0.3.3}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ferro"
-version = "0.3.2"
+version = "0.3.3"
 edition = "2024"
 readme = "README.md"
 

{ferro_orm-0.3.2 → ferro_orm-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.3.2
+Version: 0.3.3
 Requires-Dist: pydantic>=2.0
 Requires-Dist: alembic>=1.18.1 ; extra == 'alembic'
 Requires-Dist: sqlalchemy>=2.0.46 ; extra == 'alembic'
@@ -54,6 +54,8 @@ pip install ferro-orm
 pip install "ferro-orm[alembic]"
 ```
 
+Ferro currently supports SQLite and PostgreSQL as runtime backends. Named multi-database routing and custom connection-pool kwargs are planned, but not part of the current public API.
+
 ## Quick Start
 
 ```python

{ferro_orm-0.3.2 → ferro_orm-0.3.3}/README.md

@@ -41,6 +41,8 @@ pip install ferro-orm
 pip install "ferro-orm[alembic]"
 ```
 
+Ferro currently supports SQLite and PostgreSQL as runtime backends. Named multi-database routing and custom connection-pool kwargs are planned, but not part of the current public API.
+
 ## Quick Start
 
 ```python

{ferro_orm-0.3.2 → ferro_orm-0.3.3}/docs/api/utilities.md

@@ -17,24 +17,19 @@ await connect("sqlite:example.db?mode=rwc")
 # PostgreSQL
 await connect("postgresql://user:password@localhost/dbname")
 
-# With options
-await connect(
-    "postgresql://localhost/dbname",
-    max_connections=20,
-    auto_migrate=True  # Development only
-)
+# Auto-migrate during development
+await connect("postgresql://localhost/dbname", auto_migrate=True)
 ```
 
 See [Database Setup Guide](../guide/database.md) for complete connection options.
 
 ### disconnect()
 
-Close the database connection.
+This function is not implemented yet.
 
 ```python
-from ferro import disconnect
-
-await disconnect()
+# Current pattern: connect once during startup
+await connect("sqlite:example.db?mode=rwc")
 ```
 
 ### create_tables()

{ferro_orm-0.3.2 → ferro_orm-0.3.3}/docs/concepts/performance.md

@@ -137,14 +137,11 @@ for post in posts:
 posts = await Post.select().prefetch_related("author").all()
 ```
 
-### 6. Use Connection Pooling
+### 6. Reuse a Long-Lived Connection
 
 ```python
-await ferro.connect(
-    "postgresql://localhost/db",
-    max_connections=50,  # Tune for your load
-    min_connections=10
-)
+# Current API: connect once during startup and reuse it.
+await ferro.connect("postgresql://localhost/db")
 ```
 
 ### 7. Keep Transactions Short

{ferro_orm-0.3.2 → ferro_orm-0.3.3}/docs/faq.md

@@ -137,7 +137,7 @@ Check your Ferro version's API for raw SQL support. Most versions provide an esc
 
 ### Does Ferro support multiple databases?
 
-Multi-database support varies by version. Check your version's documentation for `using()` or similar APIs.
+Not yet. Ferro currently supports a single active database connection per application process.
 
 See [How-To: Multiple Databases](howto/multiple-databases.md).
 
@@ -198,14 +198,11 @@ Check the error message for details.
 ### How do I reset the database?
 
 ```python
-# Drop all tables
-await ferro.drop_all_tables()
-
-# Recreate
-await ferro.create_tables()
+# Reconnect to a fresh SQLite test database
+await ferro.connect("sqlite::memory:", auto_migrate=True)
 ```
 
-Or use Alembic migrations:
+For persistent environments, use Alembic migrations:
 
 ```bash
 alembic downgrade base

{ferro_orm-0.3.2 → ferro_orm-0.3.3}/docs/getting-started/installation.md

@@ -4,7 +4,7 @@
 
 - Python 3.10 or higher
 - Supported platforms: macOS, Linux, Windows
-- Database: SQLite, PostgreSQL, or MySQL
+- Database: SQLite or PostgreSQL
 
 ## Install Ferro
 
@@ -30,7 +30,7 @@ This installs Alembic and SQLAlchemy (used only for migration generation, not at
 
 ## Database Drivers
 
-Ferro uses SQLx under the hood, which includes drivers for all supported databases. No additional database-specific packages are required.
+Ferro uses SQLx under the hood. SQLite and PostgreSQL support are built into Ferro's published packages, so no additional database-specific packages are required for those backends.
 
 ### SQLite
 
@@ -40,10 +40,6 @@ No additional setup needed. SQLite is embedded in Ferro.
 
 No additional setup needed. PostgreSQL support is built into Ferro.
 
-### MySQL
-
-No additional setup needed. MySQL/MariaDB support is built into Ferro.
-
 
 ## Optional Dependencies
 
@@ -52,10 +48,10 @@ No additional setup needed. MySQL/MariaDB support is built into Ferro.
 For running tests and linting:
 
 ```bash
-pip install "ferro-orm[dev]"
+uv sync --group dev
 ```
 
-This includes pytest, ruff, mypy, and other development tools.
+This workspace group includes pytest, maturin, docs tooling, and other development dependencies used in this repository.
 
 ## Building from Source
 

{ferro_orm-0.3.2 → ferro_orm-0.3.3}/docs/guide/database.md

@@ -15,7 +15,7 @@ async def main():
 
 ## Connection Strings
 
-Ferro supports SQLite, PostgreSQL, and MySQL. The connection string format follows standard URL patterns:
+Ferro currently supports SQLite and PostgreSQL. The connection string format follows standard URL patterns:
 
 ### SQLite
 
@@ -45,10 +45,10 @@ await ferro.connect("postgresql://user:password@localhost:5432/dbname")
 # With SSL
 await ferro.connect("postgresql://user:password@localhost:5432/dbname?sslmode=require")
 
-# Connection pooling (custom pool size)
+# Development connection with auto-migrate
 await ferro.connect(
     "postgresql://user:password@localhost:5432/dbname",
-    max_connections=20
+    auto_migrate=True,
 )
 ```
 
@@ -83,16 +83,6 @@ Supabase’s pooler hostname often looks like `*.pooler.supabase.com`; the datab
 
 If you assemble the URI yourself, percent-encode reserved characters in the password (for example `%24` for `$`, `%5E` for `^`) per [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1) userinfo rules. Many drivers accept unencoded passwords until one character breaks parsing; encoding avoids surprises.
 
-### MySQL
-
-```python
-# Basic connection
-await ferro.connect("mysql://user:password@localhost:3306/dbname")
-
-# With charset
-await ferro.connect("mysql://user:password@localhost:3306/dbname?charset=utf8mb4")
-```
-
 ## Connection Options
 
 ### Auto-Migration (Development)
@@ -166,8 +156,7 @@ DATABASE_URL = os.getenv(
 async def init_db():
     await connect(
         DATABASE_URL,
-        max_connections=int(os.getenv("DB_POOL_SIZE", "10")),
-        connect_timeout=int(os.getenv("DB_TIMEOUT", "30"))
+        auto_migrate=os.getenv("ENV") != "production"
     )
 ```
 
@@ -207,12 +196,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 Connection Pooling
+### Use One Long-Lived Connection
 
 !!! note
-    Advanced connection pool parameters may not be fully supported. See [Coming Soon](../coming-soon.md#connection-pool-configuration).
+    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).
 
-For web applications with basic connection support:
+For web applications, connect once at startup and reuse that engine:
 
 ```python
 # Basic connection for production
@@ -225,10 +214,7 @@ await ferro.connect("postgresql://localhost/proddb")
 import os
 
 if os.getenv("ENV") == "production":
-    await ferro.connect(
-        "postgresql://prodhost/proddb",
-        max_connections=50
-    )
+    await ferro.connect("postgresql://prodhost/proddb")
 else:
     await ferro.connect(
         "sqlite:dev.db?mode=rwc",
@@ -255,7 +241,6 @@ except Exception as e:
 # Error: Connection refused at localhost:5432
 # Solution: Check database is running
 # PostgreSQL: sudo service postgresql start
-# MySQL: sudo service mysql start
 ```
 
 ### Authentication Failed
@@ -285,22 +270,15 @@ Ferro’s default build enables PostgreSQL TLS via SQLx (`tls-rustls-ring-webpki
 
 If the server requires TLS but the URL omits it, add `?sslmode=require` (or `&sslmode=require` after other query parameters) as shown in the Supabase subsection above.
 
-### Pool Exhaustion
+### Unsupported connect() kwargs
 
 ```python
-# Error: Too many connections
-# Solution: Increase max_connections or fix connection leaks
-await ferro.connect(
-    "postgresql://localhost/dbname",
-    max_connections=100  # Increase pool size
-)
-
-# Also ensure connections are released:
-# - Use context managers (async with)
-# - Close connections after use
-# - Fix stuck transactions
+# Example of kwargs Ferro does not currently accept:
+# await ferro.connect("postgresql://localhost/dbname", max_connections=100)
 ```
 
+If you need custom pool sizing or timeout controls today, Ferro does not expose them yet through `connect()`.
+
 ## See Also
 
 - [Schema Management](migrations.md) - Alembic migrations

{ferro_orm-0.3.2 → ferro_orm-0.3.3}/docs/guide/models-and-fields.md

@@ -155,7 +155,7 @@ class OrgMembership(Model):
 - You can list several groups for multiple composite uniques on one model.
 - Invalid or unknown column names raise when the model is registered.
 
-**Null semantics (SQLite):** With the default local SQLite engine, `UNIQUE` treats `NULL` as distinct from other `NULL` values for multi-column constraints unless columns are `NOT NULL`. Ferro maps nullability from your types and defaults like other fields; optional composite columns can therefore allow multiple rows that differ only by `NULL` in a nullable column. Prefer `NOT NULL` on composite members when you need strict “at most one row per pair” semantics. Other databases can differ; consult your backend’s documentation when you target PostgreSQL, MySQL, and so on.
+**Null semantics (SQLite):** With the default local SQLite engine, `UNIQUE` treats `NULL` as distinct from other `NULL` values for multi-column constraints unless columns are `NOT NULL`. Ferro maps nullability from your types and defaults like other fields; optional composite columns can therefore allow multiple rows that differ only by `NULL` in a nullable column. Prefer `NOT NULL` on composite members when you need strict “at most one row per pair” semantics. Other databases can differ; consult your backend's documentation when you target PostgreSQL or another backend with different unique/null behavior.
 
 **Wire format:** Declarations use nested tuples in Python; the schema JSON sent to the Rust engine uses nested lists (`ferro_composite_uniques`) because JSON has no tuple type.
 

{ferro_orm-0.3.2 → ferro_orm-0.3.3}/docs/howto/multiple-databases.md

@@ -3,7 +3,7 @@
 !!! warning "Feature Not Implemented"
     **Multi-database support is not currently available in Ferro.** This documentation describes planned features. See [Coming Soon](../coming-soon.md#multiple-database-support) for more information.
 
-    Ferro currently supports only a single database connection per application. The examples below show the planned API.
+    Ferro currently supports only a single active database connection per application process. The examples below show the planned API, not something you can call today.
 
 ---
 

{ferro_orm-0.3.2 → ferro_orm-0.3.3}/docs/howto/testing.md

@@ -2,6 +2,64 @@
 
 Test your Ferro applications with pytest and test database isolation strategies.
 
+## Ferro Test Matrix
+
+The repository test suite supports two database modes:
+
+- **Default SQLite run** for the full fast suite
+- **Dual-backend matrix** for ORM coverage on both SQLite and PostgreSQL/Supabase
+
+The matrix is opt-in so day-to-day test runs stay quick and deterministic.
+
+### Local Setup
+
+Install the development dependencies used by the matrix:
+
+```bash
+uv sync --group dev
+uv run maturin develop
+```
+
+Set `FERRO_SUPABASE_URL` to a PostgreSQL connection string. A root `.env` file works well for local development:
+
+```bash
+FERRO_SUPABASE_URL='postgresql://...'
+```
+
+The Postgres matrix reads `FERRO_SUPABASE_URL` from either the environment or the project `.env` file. Tests create a dedicated schema per test and use that schema as the search path so one shared Supabase database can still run isolated tests safely.
+
+### Run The Default Suite
+
+Run the normal SQLite-first suite:
+
+```bash
+uv run pytest -q
+```
+
+### Run The Dual-Backend ORM Matrix
+
+Run the backend-matrix and Postgres-specific tests on both SQLite and PostgreSQL:
+
+```bash
+uv run pytest -m "backend_matrix or postgres_only" --db-backends=sqlite,postgres -q
+```
+
+If you only want the PostgreSQL side of the matrix:
+
+```bash
+uv run pytest -m "backend_matrix or postgres_only" --db-backends=postgres -q
+```
+
+### Test Markers
+
+The repository uses three database markers:
+
+- `backend_matrix`: run this test once per selected backend
+- `sqlite_only`: keep SQLite-specific catalog, file-path, or pragma assertions on SQLite
+- `postgres_only`: run Postgres/Supabase-specific assertions only when `FERRO_SUPABASE_URL` is configured
+
+If `FERRO_SUPABASE_URL` is not set, `postgres_only` tests are skipped and `backend_matrix` tests run only on SQLite.
+
 ## Basic Setup
 
 ```python
@@ -9,25 +67,24 @@ Test your Ferro applications with pytest and test database isolation strategies.
 import pytest
 import ferro
 
-@pytest.fixture(scope="session")
+@pytest.fixture
 async def db():
-    """Connect to test database once per session."""
+    """Connect to a fresh test database for one test."""
     await ferro.connect("sqlite::memory:", auto_migrate=True)
     yield
-    await ferro.disconnect()
+    ferro.reset_engine()
 
 @pytest.fixture
 async def db_transaction(db):
-    """Wrap each test in a transaction that rolls back."""
-    from ferro import begin_transaction, rollback_transaction
+    """Wrap each test in Ferro's transaction() helper."""
+    from ferro import transaction
 
-    tx_id = await begin_transaction()
-    try:
+    async with transaction():
         yield
-    finally:
-        await rollback_transaction(tx_id)
 ```
 
+For backend-matrix tests, Ferro's own suite uses `--db-backends=sqlite,postgres` together with `backend_matrix` / `postgres_only` markers and a `FERRO_SUPABASE_URL` environment variable.
+
 ## Test Example
 
 ```python