pgsqlasync2fast-fastapi 0.3.1__py3-none-any.whl → 0.4.1__py3-none-any.whl

pgsqlasync2fast_fastapi/__init__.py

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

pgsqlasync2fast_fastapi/__version__.py

@@ -1 +1 @@
-__version__ = "0.3.1"
+__version__ = "0.4.1"

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
 
 
 # ============================================================================
@@ -510,6 +593,60 @@ def _resolve_load_order(manifest: dict[str, Any]) -> list[str]:
 # ============================================================================
 
 
+async def sync_table_sequence(
+    session: Any,
+    model_class: type,
+) -> None:
+    """
+    Re-sync a PostgreSQL table identity sequence to its current MAX(id).
+
+    The seeder inserts rows with explicit ``id`` values straight from the
+    manifest JSON. PostgreSQL's plain ``serial``/``sequence``-backed columns do
+    NOT advance the sequence when a row is inserted with an explicit id, so a
+    later sequence-backed insert (e.g. ``insert_if_missing``) can generate an
+    id that collides with an existing explicit-id row (UniqueViolation).
+
+    This issues one ``setval`` to ``MAX(id)`` after the explicit-id inserts so
+    the next auto-generated id continues past the seeded rows. It only runs
+    against PostgreSQL — SQLite assigns ``INTEGER PRIMARY KEY`` as max+1
+    automatically and has no incompatible sequence catalog, so it is a no-op
+    there.
+
+    Args:
+        session: SQLModel AsyncSession bound to the target DB.
+        model_class: The SQLModel/SQLAlchemy table class to re-sync.
+    """
+    from sqlalchemy import text
+
+    try:
+        bind = getattr(session, "bind", None)
+        if bind is None:
+            return
+        dialect = getattr(bind.dialect, "name", None)
+        if dialect != "postgresql":
+            return
+
+        table = model_class.__tablename__
+        seq = f"{table}_id_seq"
+        async with bind.begin() as conn:
+            max_id = await conn.scalar(
+                text(f'SELECT COALESCE(MAX(id), 0) FROM "{table}"')
+            )
+            if max_id:
+                await conn.execute(
+                    text("SELECT setval(:seq, :val)"),
+                    {"seq": seq, "val": max_id},
+                )
+                logger.info(
+                    f"Synced sequence '{seq}' to MAX(id)={max_id} "
+                    f"(table '{table}')"
+                )
+    except Exception as exc:  # pragma: no cover - defensive, non-fatal
+        logger.warning(
+            f"Could not re-sync sequence for '{model_class.__name__}': {exc}"
+        )
+
+
 async def _seed_table_idempotent(
     session: Any,
     table_name: str,
@@ -575,6 +712,9 @@ async def _seed_table_idempotent(
             logger.error(f"Failed to insert row in table '{table_name}': {e}")
             raise
 
+    if model_class is not None:
+        await sync_table_sequence(session, model_class)
+
     return rows_inserted, rows_skipped
 
 
@@ -644,6 +784,8 @@ async def _seed_table_idempotent_generic(
             logger.error(f"Failed to insert row in table '{table_name}': {e}")
             raise
 
+    await sync_table_sequence(session, model_class)
+
     return rows_inserted, rows_skipped
 
 
@@ -683,8 +825,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 +940,6 @@ __all__ = [
     "clear_registry",
     # Main orchestrator
     "seed_all",
+    # Shared idempotent insert-if-missing primitive
+    "insert_if_missing",
 ]

pgsqlasync2fast_fastapi/skills/SKILL.md

@@ -4,7 +4,7 @@ description: "Trigger: working on or with pgsqlasync2fast-fastapi. Multi-databas
 license: MIT
 metadata:
   author: AngelDanielSanchezCastillo
-  version: "1.0"
+  version: "2.1"
 ---
 
 ## Purpose
@@ -26,6 +26,13 @@ engines/session factories keyed by connection name (`default`, `auth`,
 - `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
 
@@ -51,8 +58,13 @@ Downstream imports (stable contracts): oauth2fast `get_db_session`→`partial(..
 
 ## Seeder orchestrator
 
-- `register_seeder` does registration-time **table-conflict detection** per connection (`SeederConflictError` if two seeders on the same connection share a manifest `tables` key).
-- `seed_all(profile, package_filter=None)` sorts 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).
+- 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

{pgsqlasync2fast_fastapi-0.3.1.dist-info → pgsqlasync2fast_fastapi-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgsqlasync2fast-fastapi
-Version: 0.3.1
+Version: 0.4.1
 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

pgsqlasync2fast_fastapi-0.4.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+pgsqlasync2fast_fastapi/__init__.py,sha256=jc45a0ClPL76d2BTkBIM6DvRzJj3O9mv1sgGEn17dmA,2474
+pgsqlasync2fast_fastapi/__version__.py,sha256=pMtTmSUht-XtbR_7Doz6bsQqopJJd8rZ8I8zy2HwwoA,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=b_7fKP19Qh08NaTyY4kA7HL48dqZIE-Re5I-ki3M5a4,33284
+pgsqlasync2fast_fastapi/settings.py,sha256=9SAmEVtotKJYlbTjI4qkKBjEOghTTtaICAFBBrR-eHk,6678
+pgsqlasync2fast_fastapi/skills/SKILL.md,sha256=Yqge3ydNnZXO5hN5Ac4aynCG0hn-WYPCy_nkzToUDsM,6787
+pgsqlasync2fast_fastapi-0.4.1.dist-info/licenses/LICENSE,sha256=CkISX1hNEwxxrPTOXet3IYMEH28Bn7SoUyKniRjg68I,1086
+pgsqlasync2fast_fastapi-0.4.1.dist-info/METADATA,sha256=_giXkOTGxUOtf__J-zPoRXtzyznR0WedKi-42Bgi4Ws,10105
+pgsqlasync2fast_fastapi-0.4.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pgsqlasync2fast_fastapi-0.4.1.dist-info/top_level.txt,sha256=7pllDm9nlFGWKJDtG5zukxqdADqjZddU-GzaQJPLMVc,24
+pgsqlasync2fast_fastapi-0.4.1.dist-info/RECORD,,

pgsqlasync2fast_fastapi-0.3.1.dist-info/RECORD

@@ -1,13 +0,0 @@
-pgsqlasync2fast_fastapi/__init__.py,sha256=zGV8J18n9bis4KiqEuMZyG31w_lSnVenuxhk355IZIA,2168
-pgsqlasync2fast_fastapi/__version__.py,sha256=r4xAFihOf72W9TD-lpMi6ntWSTKTP2SlzKP1ytkjRbI,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/skills/SKILL.md,sha256=csaMzyhXqu573EbqbUJtKJfSsVVofMdvfyUz8sm1FuU,5558
-pgsqlasync2fast_fastapi-0.3.1.dist-info/licenses/LICENSE,sha256=CkISX1hNEwxxrPTOXet3IYMEH28Bn7SoUyKniRjg68I,1086
-pgsqlasync2fast_fastapi-0.3.1.dist-info/METADATA,sha256=-1y2MEla31uhqbpLg786EMu4DOdDMg_nTPQi5_t8DVE,10105
-pgsqlasync2fast_fastapi-0.3.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-pgsqlasync2fast_fastapi-0.3.1.dist-info/top_level.txt,sha256=7pllDm9nlFGWKJDtG5zukxqdADqjZddU-GzaQJPLMVc,24
-pgsqlasync2fast_fastapi-0.3.1.dist-info/RECORD,,