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

pgsqlasync2fast_fastapi-0.4.1/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.1}/PKG-INFO

@@ -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/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.1}/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.1/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.1/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.1/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.1/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.1}/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.1}/src/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-0.4.1/src/pgsqlasync2fast_fastapi/__version__.py

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