pgsqlasync2fast-fastapi 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

pgsqlasync2fast_fastapi/__init__.py

@@ -50,6 +50,8 @@ from pgsqlasync2fast_fastapi.seeder import (
     clear_registry,
     # Main orchestrator
     seed_all,
+    # Shared idempotent insert-if-missing primitive
+    insert_if_missing,
 )
 
 __all__ = [
@@ -86,4 +88,6 @@ __all__ = [
     "clear_registry",
     # Main orchestrator (seeder)
     "seed_all",
+    # Shared idempotent insert-if-missing primitive
+    "insert_if_missing",
 ]

pgsqlasync2fast_fastapi/__version__.py

@@ -1 +1 @@
-__version__ = "0.3.0"
+__version__ = "0.4.0"

pgsqlasync2fast_fastapi/seeder.py

@@ -32,7 +32,7 @@ import logging
 from collections import defaultdict
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 if TYPE_CHECKING:
     from sqlalchemy.ext.asyncio import AsyncEngine
@@ -133,25 +133,38 @@ class SeederResult:
 # ============================================================================
 
 
-_SEEDER_REGISTRY: list[SeederConfig] = []
+_SEEDER_REGISTRY: dict[tuple[str, str], SeederConfig] = {}
 
 
-def register_seeder(config: SeederConfig) -> None:
+def register_seeder(
+    config: SeederConfig,
+    mode: Literal["retain_base", "replace"] = "retain_base",
+) -> None:
     """
-    Register a package's seeder configuration.
+    Register a package's seeder configuration, keyed by (connection, package).
 
-    Validates that there are no table conflicts between packages using
-    the same connection name. Two packages cannot seed the same table
-    in the same connection.
+    The registry is a dict keyed by ``(connection_name, package_name)``, so a
+    repeated registration of the same key updates that single entry in place
+    (idempotent - no duplicate registry entries).
 
-    The validation happens at registration time (not execution time) to fail
-    fast and provide clear error messages.
+    Conflict detection only applies to *distinct* packages on the same
+    connection: if two different ``(connection, package)`` keys overlap on
+    shared manifest tables, ``SeederConflictError`` is raised. Re-registering
+    the same key NEVER raises - it is an override/update, not a conflict.
 
     Args:
-        config: SeederConfig with connection_name, manifest_path, and priority
+        config: SeederConfig with connection_name, manifest_path, and priority.
+        mode: Override behavior when the same key is already registered:
+            - ``"retain_base"`` (default, backward-compatible): replace the
+              entry's config fields but MERGE the prior entry's manifest
+              ``model_classes`` into the new config's set (base tables are
+              preserved when an app extends rather than replaces).
+            - ``"replace"``: replace the prior entry wholesale.
 
     Raises:
-        SeederConflictError: If tables overlap with an already-registered seeder
+        ValueError: If ``mode`` is not one of the supported values.
+        SeederConflictError: If a *distinct* package on the same connection
+            shares overlapping tables with an already-registered seeder.
 
     Example:
         register_seeder(SeederConfig(
@@ -161,12 +174,21 @@ def register_seeder(config: SeederConfig) -> None:
             priority=60
         ))
     """
-    # Load manifests to check for conflicts
-    for existing in _SEEDER_REGISTRY:
-        if existing.connection_name != config.connection_name:
+    if mode not in ("retain_base", "replace"):
+        raise ValueError(f"Unsupported register_seeder mode: {mode!r}")
+
+    key = (config.connection_name, config.package_name)
+
+    # True conflict: a DIFFERENT package on the same connection overlapping
+    # on manifest tables. Same key is an override, never a conflict.
+    # The new config's manifest is only loaded when a candidate exists, so a
+    # lone registration with a missing manifest still succeeds (as before).
+    for (conn, pkg), existing in _SEEDER_REGISTRY.items():
+        if conn != config.connection_name:
+            continue
+        if (conn, pkg) == key:
             continue
 
-        # Same connection - check for table overlap
         tables_a = set(_load_manifest(existing.manifest_path)["tables"].keys())
         tables_b = set(_load_manifest(config.manifest_path)["tables"].keys())
         overlap = tables_a & tables_b
@@ -180,9 +202,20 @@ def register_seeder(config: SeederConfig) -> None:
                 f"on connection '{config.connection_name}'"
             )
 
-    _SEEDER_REGISTRY.append(config)
+    prior = _SEEDER_REGISTRY.get(key)
+
+    if prior is None or mode == "replace":
+        # No prior entry, or wholesale replace: take the new config as-is.
+        _SEEDER_REGISTRY[key] = config
+    else:  # mode == "retain_base": merge prior base model_classes into the new
+        # Preserve prior base tables that the new config does not override.
+        merged = {**prior.model_classes, **config.model_classes}
+        config.model_classes = merged
+        _SEEDER_REGISTRY[key] = config
+
     logger.debug(f"Registered seeder: {config.package_name or config.connection_name} "
-                 f"(priority={config.priority}, is_tenant={config.is_tenant_seeder})")
+                 f"(priority={config.priority}, is_tenant={config.is_tenant_seeder}, "
+                 f"mode={mode})")
 
 
 def get_registered_seeders() -> list[SeederConfig]:
@@ -192,13 +225,63 @@ def get_registered_seeders() -> list[SeederConfig]:
     Returns:
         List of all registered SeederConfig objects
     """
-    return list(_SEEDER_REGISTRY)
+    return list(_SEEDER_REGISTRY.values())
 
 
 def clear_registry() -> None:
     """Clear all registered seeders. Useful for testing."""
     global _SEEDER_REGISTRY
-    _SEEDER_REGISTRY = []
+    _SEEDER_REGISTRY = {}
+
+
+# ============================================================================
+# Idempotent insert-if-missing primitive (shared across consumer packages)
+# ============================================================================
+
+
+async def insert_if_missing(
+    session: Any,
+    model: type,
+    lookup: dict[str, Any],
+    defaults: dict[str, Any] | None = None,
+):
+    """
+    Insert a row if no row matches the natural-key ``lookup`` fields.
+
+    This is the shared, reusable idempotent **insert-if-missing** primitive.
+    Consumer packages (permissions2fast GLOBAL route seeding, tenants2fast
+    TENANT route seeding) reuse it instead of hand-rolling per package.
+
+    A ``SELECT`` by the ``lookup`` fields decides whether the row already
+    exists: if it does, the existing row is returned untouched (idempotent);
+    otherwise a new row is built from ``lookup`` merged with ``defaults``,
+    added to the session and flushed (no commit — the caller decides the
+    transaction boundary).
+
+    Args:
+        session: SQLModel AsyncSession (supports both ``exec`` and ``execute``).
+        model: SQLModel table class to query/insert.
+        lookup: Mapping of column name -> value that forms the row's natural key.
+        defaults: Optional extra column values applied only on insert.
+
+    Returns:
+        The existing (found) or newly created row instance.
+    """
+    from sqlmodel import select
+
+    stmt = select(model)
+    for col, val in lookup.items():
+        stmt = stmt.where(getattr(model, col) == val)
+    result = await session.exec(stmt)
+    existing = result.first()
+    if existing is not None:
+        return existing
+
+    merged = {**lookup, **(defaults or {})}
+    row = model(**merged)
+    session.add(row)
+    await session.flush()
+    return row
 
 
 # ============================================================================
@@ -683,8 +766,8 @@ async def seed_all(
     """
     result = SeederResult()
 
-    # Sort by priority (lower = first)
-    sorted_seeders = sorted(get_registered_seeders(), key=lambda s: s.priority)
+    # Iterate registry values, sorted by priority (lower = first)
+    sorted_seeders = sorted(_SEEDER_REGISTRY.values(), key=lambda s: s.priority)
 
     for seeder in sorted_seeders:
         # Apply package filter if specified
@@ -798,4 +881,6 @@ __all__ = [
     "clear_registry",
     # Main orchestrator
     "seed_all",
+    # Shared idempotent insert-if-missing primitive
+    "insert_if_missing",
 ]

pgsqlasync2fast_fastapi/skills/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: pgsqlasync2fast-fastapi
+description: "Trigger: working on or with pgsqlasync2fast-fastapi. Multi-database async engine manager for FastAPI: DB_CONNECTIONS config, get_db_session deps, seeder orchestrator, tenant engines. Prevails over the 2fast-handbook base skill for this package."
+license: MIT
+metadata:
+  author: AngelDanielSanchezCastillo
+  version: "2.1"
+---
+
+## Purpose
+
+Connection-management foundation of the 2fast stack: multiple PostgreSQL
+engines/session factories keyed by connection name (`default`, `auth`,
+`business`, `tenant_{id}`), lifecycle, and the generic seeder orchestrator.
+
+## Import quirk
+
+- Dist `pgsqlasync2fast-fastapi` → import `pgsqlasync2fast_fastapi` (dash→underscore only).
+- Two "default connection" paths DISAGREE: `get_db_session`/`get_db_engine` default `connection_name="default"` (literal string), while `DatabaseManager.get_engine`/`get_connection` fall back `None → config.default_connection`. Never rely on `"default"`: name your primary `default` or always pass an explicit name via `functools.partial` (oauth2fast pattern: `get_auth_session = partial(get_db_session, connection_name="auth")`).
+
+## Public API
+
+- `get_manager(config=None)` — **global singleton**; honors a custom config only on its FIRST call. `get_db_manager` (FastAPI dep) always injects the module `settings`, so per-app config via the dep path is impossible.
+- `get_db_engine(connection_name="default")`, `get_db_session(connection_name="default")` (yields session; commits on success, rolls back on exception, closes in finally).
+- `startup_database()` — **NOT lazy**: eagerly creates and health-checks EVERY configured connection. README's "lazy loading" is wrong.
+- `shutdown_database()` → `manager.close_all()` (disposes all engines).
+- DB ops `database_exists/create_database/drop_database/list_databases` — ALL require a superuser connection (`is_superuser=True`; first configured one wins); use AUTOCOMMIT isolation.
+- Seeder: `SeederConfig`, `register_seeder`, `seed_all`, `get_registered_seeders`, `SeederConflictError`.
+- `insert_if_missing(session, model, lookup, defaults=None)` — **shared idempotent
+  insert-if-missing** primitive: SELECT by natural-key `lookup` fields, return the
+  existing row if present or insert (merge `lookup`+`defaults`) and flush if absent.
+  Consumer packages (permissions2fast GLOBAL routes, tenants2fast TENANT routes)
+  reuse this instead of hand-rolling per package (RBAC standardization D2). No
+  commit — caller owns the transaction boundary. Also re-exported from the top-level
+  `pgsqlasync2fast_fastapi` package.
+
+## Architecture
+
+- `DatabaseSettings.connections: dict[str, DatabaseConnectionSettings]` — any lowercase name is a legal key (env `DB_CONNECTIONS__{NAME}__*`).
+- Engine: `create_async_engine(url, echo, pool_size=5, max_overflow=10, pool_timeout=30, pool_recycle=3600, pool_pre_ping=True)` (pre_ping hard-coded). URL: `postgresql+asyncpg://user:pass@host:port/db`.
+- Each engine has a parallel `async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)` (SQLModel session — supports BOTH `session.execute` and `session.exec`).
+- `echo` resolution QUIRK: `conn.echo if conn.echo else global echo` — a connection-level `echo=False` cannot override a global `echo=True`.
+
+## Dynamic/tenant engines (private contract)
+
+- There is **no public API to register an engine at runtime**. tenants2fast writes the manager's PRIVATE (`manager._engines`, `manager._session_makers`, `manager.config.connections`) directly. No LRU, no cap — dynamic engines accumulate unboundedly (N tenants × up to 15 connections each). Dispose idle tenant engines explicitly.
+- `get_manager(config)` honors custom config only once; the FastAPI dep always passes module settings.
+
+## Wiring
+
+```python
+from pgsqlasync2fast_fastapi import get_db_session, startup_database, shutdown_database
+# startup(shutdown) events: await startup_database() / await shutdown_database()
+session: AsyncSession = Depends(get_db_session)  # or partial with connection_name
+```
+
+Downstream imports (stable contracts): oauth2fast `get_db_session`→`partial(..., connection_name="auth")`; permissions2fast `SeederConfig, register_seeder`; tenants2fast `create_database, drop_database`, `connection.get_manager`, `settings.settings, DatabaseConnectionSettings`.
+
+## Seeder orchestrator
+
+- The seeder registry is **keyed by `(connection_name, package_name)`** — re-registering the same key updates that single entry in place (idempotent, no duplicates).
+- `register_seeder(config, mode="retain_base")` is the **override primitive**:
+  - `mode="retain_base"` (default, backward-compatible): an existing same-key entry's config fields are replaced but its prior manifest `model_classes` are **merged** into the new config's set — base tables are preserved when an app extends a package seeder.
+  - `mode="replace"`: the prior same-key entry is replaced wholesale.
+  - Re-registering the same key NEVER raises `SeederConflictError`.
+- Registration-time **table-conflict detection** applies only to *distinct* `(connection, package)` keys: `SeederConflictError` if two different packages on the same connection share a manifest `tables` key.
+- `seed_all(profile, package_filter=None)` sorts registered values by `priority` (LOWER first). **Skips** registered seeders with `is_tenant_seeder=True` and no `seed_fn` (warns — tenant seeding must be driven by `seed_all_tenants`/the tenant package itself).
+- Generic path: topological sort of `depends_on` (cycle → `SeedValidationError`), FK resolution `fk_field_mapping`/`fk_fields`/`rstrip('s')+'_id'`, insert **per row** with explicit `id` → idempotent (SELECT by id, skip if exists, commit per row).
+
+## Settings
+
+`DatabaseSettings`, prefix `DB_`, nested `__`, `.env` from **process CWD**. Top: `DB_DEFAULT_CONNECTION` (default "default"), `DB_ECHO` (False). Per connection: `HOST, USERNAME, PASSWORD, DATABASE` (**all required** — import crashes otherwise), `PORT` (5432), `IS_SUPERUSER` (False), `POOL_SIZE` (5), `MAX_OVERFLOW` (10), `POOL_TIMEOUT` (30), `POOL_RECYCLE` (3600), `ECHO` (False). Missing `.env` does NOT crash at import — it yields an empty manager that fails on first `get_engine` (plus a Spanish warning).
+
+## Gotchas
+
+- `create_database`/`drop_database` require a configured superuser connection.
+- Engines are disposed only by `shutdown_database`/`close_all` — or by tenants2fast's `dispose_tenant_engine` for individual tenant engines; dropping a tenant DB without disposing first leaks connections.
+
+## Golden rule (inherited)
+
+Follow the 2fast-handbook base skill for layout/versioning/naming/README/commits/release.
+Local edits are fine; NEVER bump/publish on your own — prepare the exact command and hand it to the developer.

{pgsqlasync2fast_fastapi-0.3.0.dist-info → pgsqlasync2fast_fastapi-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgsqlasync2fast-fastapi
-Version: 0.3.0
+Version: 0.4.0
 Summary: Simple and fast PostgreSQL async module for FastAPI with multi-database support
 Author-email: Angel Daniel Sanchez Castillo <angeldaniel.sanchezcastillo@gmail.com>
 License: MIT License
@@ -56,6 +56,8 @@ Dynamic: license-file
 
 Simple and fast PostgreSQL async module for FastAPI with multi-database support and automatic database creation.
 
+> 📖 **Conventions reference**: this package follows the [2fast-handbook](https://github.com/AngelDanielSanchezCastillo/2fast-handbook) for ecosystem conventions (structure, versioning, README, commits, release).
+
 ## Features
 
 - ✅ **Multiple Database Connections**: Configure and manage multiple PostgreSQL databases

pgsqlasync2fast_fastapi-0.4.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pgsqlasync2fast_fastapi/__init__.py,sha256=rfPB2UJsmImEeCR-FfZ3Gg0cfuVLc4bymp-A1gi5Do4,2320
+pgsqlasync2fast_fastapi/__version__.py,sha256=42STGor_9nKYXumfeV5tiyD_M8VdcddX7CEexmibPBk,22
+pgsqlasync2fast_fastapi/connection.py,sha256=vyR3SLpLTENYGKWkEoou0ud5IwUOJ9ksfkysUW5tz-I,6168
+pgsqlasync2fast_fastapi/database.py,sha256=t6i8V4Bbec0sPoWYsBPScSqQpde1tVkqGx0CBRnAupk,8856
+pgsqlasync2fast_fastapi/dependencies.py,sha256=jgX14S6h6i4Uk6edMDGh-wiDpxTlB16qvYMlIm1QofQ,4444
+pgsqlasync2fast_fastapi/seeder.py,sha256=Pl9xEkgqOcOlZgFAHuTGgPUSCZ-Mt-M7wvYJZ6VLM98,31122
+pgsqlasync2fast_fastapi/settings.py,sha256=9SAmEVtotKJYlbTjI4qkKBjEOghTTtaICAFBBrR-eHk,6678
+pgsqlasync2fast_fastapi/skills/SKILL.md,sha256=Yqge3ydNnZXO5hN5Ac4aynCG0hn-WYPCy_nkzToUDsM,6787
+pgsqlasync2fast_fastapi-0.4.0.dist-info/licenses/LICENSE,sha256=CkISX1hNEwxxrPTOXet3IYMEH28Bn7SoUyKniRjg68I,1086
+pgsqlasync2fast_fastapi-0.4.0.dist-info/METADATA,sha256=rA3ZltgZR83lOfPOidK2yKxpOZxX1KbGL50cP5LqMys,10105
+pgsqlasync2fast_fastapi-0.4.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pgsqlasync2fast_fastapi-0.4.0.dist-info/top_level.txt,sha256=7pllDm9nlFGWKJDtG5zukxqdADqjZddU-GzaQJPLMVc,24
+pgsqlasync2fast_fastapi-0.4.0.dist-info/RECORD,,

{pgsqlasync2fast_fastapi-0.3.0.dist-info → pgsqlasync2fast_fastapi-0.4.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (84.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

pgsqlasync2fast_fastapi-0.3.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-pgsqlasync2fast_fastapi/__init__.py,sha256=zGV8J18n9bis4KiqEuMZyG31w_lSnVenuxhk355IZIA,2168
-pgsqlasync2fast_fastapi/__version__.py,sha256=VrXpHDu3erkzwl_WXrqINBm9xWkcyUy53IQOj042dOs,22
-pgsqlasync2fast_fastapi/connection.py,sha256=vyR3SLpLTENYGKWkEoou0ud5IwUOJ9ksfkysUW5tz-I,6168
-pgsqlasync2fast_fastapi/database.py,sha256=t6i8V4Bbec0sPoWYsBPScSqQpde1tVkqGx0CBRnAupk,8856
-pgsqlasync2fast_fastapi/dependencies.py,sha256=jgX14S6h6i4Uk6edMDGh-wiDpxTlB16qvYMlIm1QofQ,4444
-pgsqlasync2fast_fastapi/seeder.py,sha256=wRBAhiUsIn6pDlMq63q1HilgV8JHo8FuYUJ3xL0FPwo,27388
-pgsqlasync2fast_fastapi/settings.py,sha256=9SAmEVtotKJYlbTjI4qkKBjEOghTTtaICAFBBrR-eHk,6678
-pgsqlasync2fast_fastapi-0.3.0.dist-info/licenses/LICENSE,sha256=CkISX1hNEwxxrPTOXet3IYMEH28Bn7SoUyKniRjg68I,1086
-pgsqlasync2fast_fastapi-0.3.0.dist-info/METADATA,sha256=6jRDeCgNZmaQT0j5bbPJjKb4rOb-HCrIBvIiUnqaEy8,9889
-pgsqlasync2fast_fastapi-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-pgsqlasync2fast_fastapi-0.3.0.dist-info/top_level.txt,sha256=7pllDm9nlFGWKJDtG5zukxqdADqjZddU-GzaQJPLMVc,24
-pgsqlasync2fast_fastapi-0.3.0.dist-info/RECORD,,