pgsqlasync2fast-fastapi 0.3.1__tar.gz → 0.4.0__tar.gz

pgsqlasync2fast_fastapi-0.4.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+recursive-include docs *.md *.example
+recursive-include examples *.py *.example *.json
+recursive-include src/pgsqlasync2fast_fastapi *.py *.html *.json *.md
+
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store

{pgsqlasync2fast_fastapi-0.3.1/src/pgsqlasync2fast_fastapi.egg-info → pgsqlasync2fast_fastapi-0.4.0}/PKG-INFO

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

pgsqlasync2fast_fastapi-0.4.0/docs/.env.example

@@ -0,0 +1,50 @@
+# ============================================
+# PostgreSQL Database Configuration
+# ============================================
+
+# ===== Connection DEFAULT (principal) =====
+# Esta es la conexión por defecto que se usará cuando no especifiques ninguna
+DB_CONNECTIONS__DEFAULT__HOST=localhost
+DB_CONNECTIONS__DEFAULT__PORT=5432
+DB_CONNECTIONS__DEFAULT__USERNAME=myuser
+DB_CONNECTIONS__DEFAULT__PASSWORD=mypassword
+DB_CONNECTIONS__DEFAULT__DATABASE=mydb
+DB_CONNECTIONS__DEFAULT__IS_SUPERUSER=false
+
+# Pool settings (opcional, estos son los valores por defecto)
+DB_CONNECTIONS__DEFAULT__POOL_SIZE=5
+DB_CONNECTIONS__DEFAULT__MAX_OVERFLOW=10
+DB_CONNECTIONS__DEFAULT__POOL_TIMEOUT=30
+DB_CONNECTIONS__DEFAULT__POOL_RECYCLE=3600
+
+# Echo mode para esta conexión (opcional)
+DB_CONNECTIONS__DEFAULT__ECHO=false
+
+# ===== Connection BUSINESS (ejemplo de segunda conexión) =====
+# Para usar esta conexión, especifica connection_name="business" en tus dependencias
+DB_CONNECTIONS__BUSINESS__HOST=localhost
+DB_CONNECTIONS__BUSINESS__PORT=5432
+DB_CONNECTIONS__BUSINESS__USERNAME=business_user
+DB_CONNECTIONS__BUSINESS__PASSWORD=business_password
+DB_CONNECTIONS__BUSINESS__DATABASE=business_db
+DB_CONNECTIONS__BUSINESS__IS_SUPERUSER=false
+
+# ===== Connection ADMIN (ejemplo con superusuario) =====
+# Esta conexión tiene privilegios de superusuario para crear/eliminar bases de datos
+DB_CONNECTIONS__ADMIN__HOST=localhost
+DB_CONNECTIONS__ADMIN__PORT=5432
+DB_CONNECTIONS__ADMIN__USERNAME=postgres
+DB_CONNECTIONS__ADMIN__PASSWORD=postgres_password
+DB_CONNECTIONS__ADMIN__DATABASE=postgres
+DB_CONNECTIONS__ADMIN__IS_SUPERUSER=true
+
+# ============================================
+# General Settings
+# ============================================
+
+# Conexión por defecto cuando no se especifica ninguna
+# Opciones: "default", "business", "admin", o cualquier otra que hayas configurado
+DB_DEFAULT_CONNECTION=default
+
+# Echo mode global (puede ser sobrescrito por cada conexión)
+DB_ECHO=false

{pgsqlasync2fast_fastapi-0.3.1 → pgsqlasync2fast_fastapi-0.4.0}/docs/seeder-format.md

@@ -148,25 +148,61 @@ register_seeder(SeederConfig(
 
 ## Conflict Detection
 
-When registering a seeder, the system detects table conflicts.
+When registering a seeder, the system detects table conflicts between **distinct** packages.
 
 ### Rule
 
-Two packages CANNOT seed the same table in the same connection.
+Two DIFFERENT packages (`(connection_name, package_name)` keys) CANNOT seed the same table in the same connection. Re-registering the same key is an override, never a conflict.
 
 ### Error
 
-If conflicts are detected, `SeederConflictError` is raised:
+If a distinct package's tables overlap an already-registered package on the same connection, `SeederConflictError` is raised:
 ```
 Tables {'roles'} conflict between 'pkg-a' and 'pkg-b' on connection 'auth'
 ```
 
+## Override & Idempotency (single-entry)
+
+The registry is keyed by `(connection_name, package_name)`, so registering the same package+connection repeatedly updates **one single entry** — no duplicate registry entries.
+
+`register_seeder(config, mode=...)` supports two override behaviors:
+
+| `mode` | Behavior |
+|--------|----------|
+| `"retain_base"` (default) | Replaces the entry's config fields but **merges** the prior entry's manifest `model_classes` into the new config's set. Base tables are preserved when an app extends a package seeder (e.g. keeps permissions2fast base tables while adding route tables). |
+| `"replace"` | Replaces the prior entry wholesale. |
+
+Re-registering the **same** `(connection, package)` key never raises `SeederConflictError`. Only a **distinct** package on the same connection with overlapping tables raises it.
+
+### Example
+
+```python
+# Base permissions2fast seeder auto-registered on "auth"
+register_seeder(SeederConfig(
+    connection_name="auth",
+    manifest_path="permissions2fast_fastapi/seeders/manifest.json",
+    package_name="permissions2fast-fastapi",
+    priority=60,
+))
+
+# App extends it by ADDING route tables, keeping the base manifest set
+register_seeder(SeederConfig(
+    connection_name="auth",
+    manifest_path="app/rbac_route_manifest.json",
+    package_name="permissions2fast-fastapi",   # same key -> override
+    model_classes={"routes": RouteModel},
+), mode="retain_base")
+```
+
+The result is a single `permissions2fast-fastapi` entry whose `model_classes` contain both the base `roles`/`permissions` models and the new `routes` model.
+
 ## Idempotency
 
 The seeder is idempotent - running multiple times produces the same result.
 
 - Rows with existing IDs are skipped
 - Only new rows are inserted
+- Registry registration is idempotent per key - no duplicate entries
 
 This allows safe re-runs without duplicating data.
 

pgsqlasync2fast_fastapi-0.4.0/examples/basic_usage.py

@@ -0,0 +1,58 @@
+"""
+Basic usage example for pgsqlasync2fast-fastapi
+
+This example demonstrates:
+- Basic database connection
+- Executing queries
+- Using sessions
+"""
+
+import asyncio
+from sqlalchemy import text
+from pgsqlasync2fast_fastapi import get_manager, settings
+
+
+async def main():
+    """Main function demonstrating basic usage."""
+    
+    # Get the database manager
+    manager = get_manager()
+    
+    print("📊 Basic PostgreSQL Async Usage Example")
+    print("=" * 50)
+    
+    # List configured connections
+    print(f"\n✅ Configured connections: {manager.list_connections()}")
+    
+    # Get a session for the default connection
+    print(f"\n🔌 Connecting to default database...")
+    session = await manager.get_session()
+    
+    try:
+        # Execute a simple query
+        result = await session.execute(text("SELECT version()"))
+        version = result.scalar()
+        print(f"✅ PostgreSQL version: {version}")
+        
+        # Execute another query
+        result = await session.execute(text("SELECT current_database()"))
+        db_name = result.scalar()
+        print(f"✅ Current database: {db_name}")
+        
+        # Commit the session
+        await session.commit()
+        
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        await session.rollback()
+    finally:
+        await session.close()
+    
+    # Cleanup
+    print("\n🔌 Closing connections...")
+    await manager.close_all()
+    print("✅ Done!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pgsqlasync2fast_fastapi-0.4.0/examples/database_creation.py

@@ -0,0 +1,93 @@
+"""
+Database creation example for pgsqlasync2fast-fastapi
+
+This example demonstrates:
+- Checking if a database exists
+- Creating new databases
+- Listing all databases
+- Dropping databases
+
+IMPORTANT: This requires a connection configured with is_superuser=true
+"""
+
+import asyncio
+from pgsqlasync2fast_fastapi import (
+    database_exists,
+    create_database,
+    drop_database,
+    list_databases,
+    get_manager,
+)
+
+
+async def main():
+    """Main function demonstrating database creation utilities."""
+    
+    print("📊 Database Creation Example")
+    print("=" * 50)
+    
+    # Check if we have a superuser connection
+    manager = get_manager()
+    superuser_conn = manager.config.get_superuser_connection_name()
+    
+    if not superuser_conn:
+        print("❌ No superuser connection configured!")
+        print("   Please configure a connection with IS_SUPERUSER=true")
+        print("   Example: DB_CONNECTIONS__ADMIN__IS_SUPERUSER=true")
+        return
+    
+    print(f"✅ Using superuser connection: '{superuser_conn}'")
+    
+    # List all existing databases
+    print("\n📋 Listing all databases...")
+    databases = await list_databases()
+    for db in databases:
+        print(f"  - {db}")
+    
+    # Test database name
+    test_db_name = "test_created_db"
+    
+    # Check if test database exists
+    print(f"\n🔍 Checking if '{test_db_name}' exists...")
+    exists = await database_exists(test_db_name)
+    print(f"  {'✅ Exists' if exists else '❌ Does not exist'}")
+    
+    # Create the database if it doesn't exist
+    if not exists:
+        print(f"\n🔨 Creating database '{test_db_name}'...")
+        created = await create_database(test_db_name)
+        if created:
+            print(f"  ✅ Database '{test_db_name}' created successfully!")
+        else:
+            print(f"  ❌ Failed to create database")
+    else:
+        print(f"\n⚠️  Database '{test_db_name}' already exists, skipping creation")
+    
+    # Verify it exists now
+    print(f"\n🔍 Verifying '{test_db_name}' exists...")
+    exists = await database_exists(test_db_name)
+    print(f"  {'✅ Confirmed' if exists else '❌ Not found'}")
+    
+    # List databases again to show the new one
+    print("\n📋 Listing all databases (after creation)...")
+    databases = await list_databases()
+    for db in databases:
+        marker = " ← NEW" if db == test_db_name else ""
+        print(f"  - {db}{marker}")
+    
+    # Optional: Drop the test database
+    print(f"\n🗑️  Cleaning up: dropping '{test_db_name}'...")
+    dropped = await drop_database(test_db_name, force=True)
+    if dropped:
+        print(f"  ✅ Database '{test_db_name}' dropped successfully!")
+    else:
+        print(f"  ❌ Failed to drop database")
+    
+    # Cleanup
+    print("\n🔌 Closing connections...")
+    await manager.close_all()
+    print("✅ Done!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pgsqlasync2fast_fastapi-0.4.0/examples/fastapi_integration.py

@@ -0,0 +1,151 @@
+"""
+FastAPI integration example for pgsqlasync2fast-fastapi
+
+This example demonstrates:
+- FastAPI application setup
+- Dependency injection
+- Startup/shutdown events
+- Using multiple database connections in endpoints
+"""
+
+from functools import partial
+from fastapi import FastAPI, Depends
+from sqlalchemy.ext.asyncio import AsyncSession, AsyncEngine
+from sqlalchemy import text
+
+from pgsqlasync2fast_fastapi import (
+    get_db_session,
+    get_db_engine,
+    get_db_manager,
+    startup_database,
+    shutdown_database,
+    DatabaseManager,
+)
+
+# Create FastAPI app
+app = FastAPI(
+    title="PostgreSQL Async Example",
+    description="Example FastAPI application with pgsqlasync2fast-fastapi"
+)
+
+
+@app.on_event("startup")
+async def startup():
+    """Initialize database connections on startup."""
+    await startup_database()
+
+
+@app.on_event("shutdown")
+async def shutdown():
+    """Close database connections on shutdown."""
+    await shutdown_database()
+
+
+@app.get("/")
+async def root():
+    """Root endpoint."""
+    return {
+        "message": "PostgreSQL Async FastAPI Example",
+        "endpoints": [
+            "/health",
+            "/connections",
+            "/db/info",
+            "/db/version",
+        ]
+    }
+
+
+@app.get("/health")
+async def health_check(engine: AsyncEngine = Depends(get_db_engine)):
+    """Health check endpoint using default database."""
+    try:
+        async with engine.connect() as conn:
+            await conn.execute(text("SELECT 1"))
+        return {"status": "healthy", "database": "default"}
+    except Exception as e:
+        return {"status": "unhealthy", "error": str(e)}
+
+
+@app.get("/connections")
+async def list_connections(manager: DatabaseManager = Depends(get_db_manager)):
+    """List all configured database connections."""
+    connections = manager.list_connections()
+    
+    connection_info = []
+    for conn_name in connections:
+        is_super = manager.is_superuser_connection(conn_name)
+        connection_info.append({
+            "name": conn_name,
+            "is_superuser": is_super
+        })
+    
+    return {
+        "total": len(connections),
+        "connections": connection_info
+    }
+
+
+@app.get("/db/info")
+async def get_db_info(session: AsyncSession = Depends(get_db_session)):
+    """Get database information using default connection."""
+    try:
+        # Get database name
+        result = await session.execute(text("SELECT current_database()"))
+        db_name = result.scalar()
+        
+        # Get current user
+        result = await session.execute(text("SELECT current_user"))
+        user = result.scalar()
+        
+        # Get server version
+        result = await session.execute(text("SELECT version()"))
+        version = result.scalar()
+        
+        return {
+            "database": db_name,
+            "user": user,
+            "version": version
+        }
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@app.get("/db/version")
+async def get_version(session: AsyncSession = Depends(get_db_session)):
+    """Get PostgreSQL version."""
+    result = await session.execute(text("SELECT version()"))
+    version = result.scalar()
+    return {"version": version}
+
+
+# Example: Using a specific database connection
+# Create a dependency for a specific connection (e.g., "business")
+get_business_session = partial(get_db_session, connection_name="business")
+
+
+@app.get("/business/info")
+async def get_business_info(session: AsyncSession = Depends(get_business_session)):
+    """Get database information using business connection."""
+    try:
+        result = await session.execute(text("SELECT current_database()"))
+        db_name = result.scalar()
+        
+        result = await session.execute(text("SELECT current_user"))
+        user = result.scalar()
+        
+        return {
+            "connection": "business",
+            "database": db_name,
+            "user": user
+        }
+    except Exception as e:
+        return {"error": str(e)}
+
+
+if __name__ == "__main__":
+    import uvicorn
+    
+    print("🚀 Starting FastAPI application...")
+    print("📖 API docs available at: http://localhost:8000/docs")
+    
+    uvicorn.run(app, host="0.0.0.0", port=8000)

pgsqlasync2fast_fastapi-0.4.0/examples/multi_database.py

@@ -0,0 +1,70 @@
+"""
+Multi-database example for pgsqlasync2fast-fastapi
+
+This example demonstrates:
+- Configuring multiple database connections
+- Switching between databases
+- Using different connections simultaneously
+"""
+
+import asyncio
+from sqlalchemy import text
+from pgsqlasync2fast_fastapi import get_manager
+
+
+async def main():
+    """Main function demonstrating multi-database usage."""
+    
+    manager = get_manager()
+    
+    print("📊 Multi-Database Usage Example")
+    print("=" * 50)
+    
+    # List all configured connections
+    connections = manager.list_connections()
+    print(f"\n✅ Available connections: {connections}")
+    
+    # Demonstrate using multiple connections
+    for conn_name in connections:
+        print(f"\n🔌 Connecting to '{conn_name}' database...")
+        
+        try:
+            # Health check
+            is_healthy = await manager.health_check(conn_name)
+            if not is_healthy:
+                print(f"❌ Connection '{conn_name}' is not healthy")
+                continue
+            
+            # Get a session for this connection
+            session = await manager.get_session(conn_name)
+            
+            try:
+                # Get database info
+                result = await session.execute(text("SELECT current_database()"))
+                db_name = result.scalar()
+                
+                result = await session.execute(text("SELECT current_user"))
+                user = result.scalar()
+                
+                is_super = manager.is_superuser_connection(conn_name)
+                super_flag = " (SUPERUSER)" if is_super else ""
+                
+                print(f"✅ Database: {db_name}")
+                print(f"✅ User: {user}{super_flag}")
+                
+                await session.commit()
+                
+            finally:
+                await session.close()
+                
+        except Exception as e:
+            print(f"❌ Error with connection '{conn_name}': {e}")
+    
+    # Cleanup
+    print("\n🔌 Closing all connections...")
+    await manager.close_all()
+    print("✅ Done!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{pgsqlasync2fast_fastapi-0.3.1 → pgsqlasync2fast_fastapi-0.4.0}/pyproject.toml

@@ -49,6 +49,7 @@ test = [
     "pytest-asyncio>=0.21.0",
     "pytest-cov>=4.0.0",
     "httpx>=0.24.0",
+    "aiosqlite",
 ]
 
 [project.urls]

{pgsqlasync2fast_fastapi-0.3.1 → pgsqlasync2fast_fastapi-0.4.0}/src/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-0.4.0/src/pgsqlasync2fast_fastapi/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

{pgsqlasync2fast_fastapi-0.3.1 → pgsqlasync2fast_fastapi-0.4.0}/src/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-0.3.1 → pgsqlasync2fast_fastapi-0.4.0}/src/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 → pgsqlasync2fast_fastapi-0.4.0/src/pgsqlasync2fast_fastapi.egg-info}/PKG-INFO

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

{pgsqlasync2fast_fastapi-0.3.1 → pgsqlasync2fast_fastapi-0.4.0}/src/pgsqlasync2fast_fastapi.egg-info/SOURCES.txt

@@ -2,7 +2,12 @@ LICENSE
 MANIFEST.in
 README.md
 pyproject.toml
+docs/.env.example
 docs/seeder-format.md
+examples/basic_usage.py
+examples/database_creation.py
+examples/fastapi_integration.py
+examples/multi_database.py
 examples/seeders/manifest.json
 examples/seeders/dev/categories.json
 examples/seeders/dev/permissions.json
@@ -24,4 +29,6 @@ src/pgsqlasync2fast_fastapi.egg-info/requires.txt
 src/pgsqlasync2fast_fastapi.egg-info/top_level.txt
 src/pgsqlasync2fast_fastapi/skills/SKILL.md
 tests/test_completo.py
-tests/test_seeder.py
+tests/test_insert_if_missing.py
+tests/test_seeder.py
+tests/test_seeder_override.py

pgsqlasync2fast_fastapi-0.4.0/tests/test_insert_if_missing.py

@@ -0,0 +1,92 @@
+"""
+Tests for the reusable idempotent `insert_if_missing` primitive
+(pgsqlasync2fast-fastapi).
+
+This is the shared insert-if-missing-by-natural-key helper that consumer
+packages (permissions2fast GLOBAL routes, tenants2fast TENANT routes) reuse
+instead of hand-rolling per package (RBAC standardization decision D2).
+
+Run with:
+  cd /Volumes/Desarrollo/Repos/Github/pgsqlasync2fast-fastapi \
+    && uv run pytest tests/test_insert_if_missing.py -v
+"""
+
+from __future__ import annotations
+
+import pytest
+from sqlalchemy import BigInteger
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.ext.compiler import compiles
+from sqlmodel import Field, SQLModel
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+
+@compiles(BigInteger, "sqlite")
+def _compile_bigint_sqlite(type_, compiler, **kw):
+    return "INTEGER"
+
+
+DB_URL = "sqlite+aiosqlite:///:memory:"
+
+
+class AFruit(SQLModel, table=True):
+    """Minimal SQLModel table to exercise insert_if_missing."""
+
+    __tablename__ = "afruits"
+
+    name: str = Field(primary_key=True)
+    color: str = Field(default="")
+
+
+async def _engine():
+    engine = create_async_engine(DB_URL, echo=False)
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+    return engine
+
+
+@pytest.mark.asyncio
+async def test_insert_if_missing_inserts_new_row():
+    """A row that matches no natural key is inserted."""
+    from pgsqlasync2fast_fastapi.seeder import insert_if_missing
+
+    engine = await _engine()
+    async with AsyncSession(engine) as session:
+        row = await insert_if_missing(
+            session, AFruit, lookup={"name": "apple"}, defaults={"color": "red"}
+        )
+        await session.commit()
+
+        # Re-read via a fresh query to confirm persistence
+        from sqlmodel import select
+
+        stored = (await session.exec(select(AFruit).where(AFruit.name == "apple"))).one()
+        assert stored.color == "red"
+        assert row.name == "apple"
+    await engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_insert_if_missing_is_idempotent():
+    """Calling twice with the same natural key returns the existing row."""
+    from pgsqlasync2fast_fastapi.seeder import insert_if_missing
+
+    engine = await _engine()
+    async with AsyncSession(engine) as session:
+        first = await insert_if_missing(
+            session, AFruit, lookup={"name": "pear"}, defaults={"color": "green"}
+        )
+        await session.commit()
+
+        second = await insert_if_missing(
+            session, AFruit, lookup={"name": "pear"}, defaults={"color": "green"}
+        )
+        await session.commit()
+
+        assert second is first  # same object instance returned (cached in session identity map)
+        # Only one row exists
+        from sqlmodel import select
+
+        rows = (await session.exec(select(AFruit))).all()
+        assert len(rows) == 1
+    await engine.dispose()

pgsqlasync2fast_fastapi-0.4.0/tests/test_seeder_override.py

@@ -0,0 +1,263 @@
+"""
+Tests for the seeder override primitive (pgsqlasync2fast-fastapi).
+
+Covers the keyed (connection_name, package_name) registry + register_seeder(mode=)
+override primitive:
+- H1: an override can ADD new tables to an existing (connection, package) entry
+- H2: an override can OVERWRITE an existing (connection, package) entry wholesale
+- E1: a distinct (connection, package) on the same connection STILL raises
+      SeederConflictError on table overlap
+- T1: repeated registration of the same key is idempotent (single entry)
+
+Run with: cd /Volumes/Desarrollo/Repos/Github/pgsqlasync2fast-fastapi \\
+  && uv run pytest tests/test_seeder_override.py -v
+"""
+
+import json
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from pgsqlasync2fast_fastapi.seeder import (
+    SeederConfig,
+    SeederConflictError,
+    register_seeder,
+    get_registered_seeders,
+    clear_registry,
+)
+
+
+@pytest.fixture(autouse=True)
+def clear_seeders():
+    """Clear the seeder registry before and after each test."""
+    clear_registry()
+    yield
+    clear_registry()
+
+
+@pytest.fixture
+def base_manifest():
+    """Build a temp manifest seeding base tables on the 'auth' connection."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        manifest_dir = Path(tmpdir) / "seeders"
+        dev_dir = manifest_dir / "dev"
+        manifest_dir.mkdir()
+        dev_dir.mkdir()
+
+        manifest = {
+            "tables": {
+                "roles": {"file": "roles.json"},
+                "permissions": {"file": "permissions.json"},
+            },
+            "load_order": ["roles", "permissions"],
+        }
+        manifest_path = manifest_dir / "manifest.json"
+        with open(manifest_path, "w") as f:
+            json.dump(manifest, f)
+        with open(dev_dir / "roles.json", "w") as f:
+            json.dump([{"id": 1, "name": "Admin"}], f)
+        with open(dev_dir / "permissions.json", "w") as f:
+            json.dump([{"id": 1, "name": "read:users"}], f)
+
+        yield (str(manifest_path), manifest, dev_dir)
+
+
+def make_config(manifest_path, package, **kwargs) -> SeederConfig:
+    """Build a SeederConfig for the given manifest and package."""
+    return SeederConfig(
+        connection_name="auth",
+        manifest_path=manifest_path,
+        package_name=package,
+        model_classes=kwargs.pop("model_classes", {}),
+        **kwargs,
+    )
+
+
+# ============================================================================
+# T1 — Idempotency: same key registered twice -> single entry
+# ============================================================================
+
+
+class TestOverrideIdempotency:
+    def test_same_key_twice_single_entry(self, base_manifest):
+        manifest_path, _, dev_dir = base_manifest
+
+        # New manifest that ADDS a table (extends the base manifest set)
+        extended = {
+            "tables": {
+                "roles": {"file": "roles.json"},
+                "permissions": {"file": "permissions.json"},
+                "routes": {"file": "routes.json"},
+            },
+            "load_order": ["roles", "permissions", "routes"],
+        }
+        ext_path = Path(manifest_path).parent / "manifest_override.json"
+        with open(ext_path, "w") as f:
+            json.dump(extended, f)
+        with open(Path(manifest_path).parent / "dev" / "routes.json", "w") as f:
+            json.dump([{"id": 1, "path": "/admin", "method": "GET"}], f)
+
+        base = make_config(manifest_path, "pkg-a",
+                           model_classes={"roles": object, "permissions": object})
+        override = make_config(str(ext_path), "pkg-a",
+                               model_classes={"roles": object, "routes": object})
+
+        # Register the same key twice with the default retain_base mode
+        register_seeder(base)
+        register_seeder(override)
+
+        seeders = get_registered_seeders()
+        assert len(seeders) == 1
+        assert seeders[0].package_name == "pkg-a"
+
+
+# ============================================================================
+# H1 — retain_base ADD: base tables preserved, new tables added to model set
+# ============================================================================
+
+
+class TestOverrideAdd:
+    def test_retain_base_merges_prior_model_classes(self, base_manifest):
+        manifest_path, _, _ = base_manifest
+
+        # Override manifest introduces a NEW table 'routes'
+        ext_manifest = {
+            "tables": {
+                "roles": {"file": "roles.json"},
+                "permissions": {"file": "permissions.json"},
+                "routes": {"file": "routes.json"},
+            },
+            "load_order": ["roles", "permissions", "routes"],
+        }
+        ext_path = Path(manifest_path).parent / "manifest_override.json"
+        with open(ext_path, "w") as f:
+            json.dump(ext_manifest, f)
+        with open(Path(manifest_path).parent / "dev" / "routes.json", "w") as f:
+            json.dump([{"id": 1, "path": "/admin"}], f)
+
+        class RoleModel:
+            pass
+
+        class RouteModel:
+            pass
+
+        base = make_config(manifest_path, "pkg-a",
+                           model_classes={"roles": RoleModel, "permissions": object})
+        override = make_config(str(ext_path), "pkg-a",
+                               model_classes={"roles": RoleModel, "routes": RouteModel})
+
+        register_seeder(base)
+        register_seeder(override)
+
+        seeders = get_registered_seeders()
+        assert len(seeders) == 1
+        entry = seeders[0]
+        # Extends rather than replaces: the base 'permissions' model is preserved
+        assert "permissions" in entry.model_classes
+        # And the new 'routes' model is present
+        assert entry.model_classes["routes"] is RouteModel
+
+
+# ============================================================================
+# H2 — replace: prior entry replaced wholesale
+# ============================================================================
+
+
+class TestOverrideReplace:
+    def test_replace_overwrites_wholesale(self, base_manifest):
+        manifest_path, _, _ = base_manifest
+
+        ext_manifest = {
+            "tables": {
+                "roles": {"file": "roles.json"},
+                "permissions": {"file": "permissions.json"},
+                "routes": {"file": "routes.json"},
+            },
+            "load_order": ["roles", "permissions", "routes"],
+        }
+        ext_path = Path(manifest_path).parent / "manifest_override.json"
+        with open(ext_path, "w") as f:
+            json.dump(ext_manifest, f)
+        with open(Path(manifest_path).parent / "dev" / "routes.json", "w") as f:
+            json.dump([{"id": 1, "path": "/admin"}], f)
+
+        class RouteModel:
+            pass
+
+        base = make_config(manifest_path, "pkg-a",
+                           model_classes={"roles": object, "permissions": object})
+        override = make_config(str(ext_path), "pkg-a",
+                               model_classes={"routes": RouteModel}, priority=90)
+
+        register_seeder(base)
+        # SeederConflictError must NOT be raised for same-key replace
+        register_seeder(override, mode="replace")
+
+        seeders = get_registered_seeders()
+        assert len(seeders) == 1
+        entry = seeders[0]
+        # Wholesale replace: only the new model set survives
+        assert "routes" in entry.model_classes
+        assert "permissions" not in entry.model_classes
+        assert entry.priority == 90
+
+
+# ============================================================================
+# E1 — True conflict: distinct package, same connection, overlapping tables
+# ============================================================================
+
+
+class TestOverrideConflict:
+    def test_distinct_package_same_connection_still_conflicts(self, base_manifest):
+        manifest_path, _, _ = base_manifest
+
+        # A second, DIFFERENT package on the same 'auth' connection that
+        # overlaps on the 'roles' table -> true conflict
+        conflict_manifest = {
+            "tables": {"roles": {"file": "roles.json"}},
+            "load_order": ["roles"],
+        }
+        conflict_path = Path(manifest_path).parent / "manifest_conflict.json"
+        with open(conflict_path, "w") as f:
+            json.dump(conflict_manifest, f)
+
+        register_seeder(make_config(manifest_path, "pkg-a"))
+
+        with pytest.raises(SeederConflictError) as exc_info:
+            register_seeder(make_config(str(conflict_path), "pkg-b"))
+
+        assert "roles" in str(exc_info.value)
+        assert "pkg-a" in str(exc_info.value)
+        assert "pkg-b" in str(exc_info.value)
+
+
+# ============================================================================
+# Sanity: registry remains keyed -> distinct keys stay separate entries
+# ============================================================================
+
+
+class TestOverrideKeying:
+    def test_distinct_keys_two_entries(self, base_manifest):
+        manifest_path, _, dev_dir = base_manifest
+
+        other = {
+            "tables": {"roles": {"file": "roles.json"}},
+            "load_order": ["roles"],
+        }
+        other_path = Path(manifest_path).parent / "manifest_other.json"
+        with open(other_path, "w") as f:
+            json.dump(other, f)
+        with open(dev_dir / "roles.json", "w") as f:
+            json.dump([{"id": 1, "name": "Admin"}], f)
+
+        # Distinct package on a DIFFERENT connection -> no conflict, two entries
+        register_seeder(make_config(manifest_path, "pkg-a"))
+        register_seeder(SeederConfig(
+            connection_name="business",
+            manifest_path=str(other_path),
+            package_name="pkg-b",
+        ))
+
+        seeders = get_registered_seeders()
+        assert len(seeders) == 2

pgsqlasync2fast_fastapi-0.3.1/MANIFEST.in

@@ -1,4 +0,0 @@
-include LICENSE
-include README.md
-recursive-include docs *.md
-recursive-include examples/seeders *.json

pgsqlasync2fast_fastapi-0.3.1/src/pgsqlasync2fast_fastapi/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.3.1"