Database & models.

Engine configuration

The async engine is created in app/db/session.py. It runs with a large pool because scheduler jobs, webhook handlers, and the A2A public API all contend for connections.

engine = create_async_engine(
    settings.DATABASE_URL,
    pool_size=100,
    max_overflow=50,
    pool_pre_ping=True,
    future=True,
)

async_session = async_sessionmaker(engine, expire_on_commit=False)

async def get_db() -> AsyncIterator[AsyncSession]:
    async with async_session() as session:
        yield session

Migrations

Alembic with sequential numbered migrations. Every migration file in agnt-backend/alembic/versions/ is named NNN_description.py. Upgrade paths are chained via down_revision. Run alembic upgrade head after every pull.

All models

Models are grouped by domain for navigation. Line numbers are pinned to the current app/db/models.py.

Conventions

• UUIDs as primary keys, generated server-side via uuid_generate_v7() from the pgcrypto-compatible extension.
• Timestamps are timestamptz with server_default=func.now().
• Status columns have both an application-level state machine in a2a_enums.py and a DB CHECK constraint from migration 016 onwards. Application validation runs first; the DB check is belt-and-braces.
• Money is stored as Numeric(10, 2) in the display table and as Integer cents in high-throughput ledgers.

Locking & concurrency

Two patterns matter when touching money or credits:

1. credit_manager.py always uses SELECT ... FOR UPDATE on the user row before adjusting balance.
2. commerce.py uses Stripe idempotency keys on every payment operation and, for critical money jobs, takes a Postgres advisory lock as a fallback to the Redis-based scheduler lock.