agent-db

The agent-db skill provides a robust, isolated PostgreSQL execution environment specifically engineered for integration testing within the Prebid Sales Agent repository. By leveraging Docker and deterministic container naming, this tool allows developers to maintain clean, conflict-free database states across multiple git worktrees simultaneously without the overhead of manual environment management or port contention. It is designed for developers actively writing or running integration tests who need a stable, lightweight database instance that reflects production-like conditions without requiring the full deployment stack.

• Deterministic container management using postgres:17-alpine, ensuring reliable up, down, and status transitions for every worktree.

• Seamless environment variable injection (DATABASE_URL, ADCP_TESTING, and security keys) to simplify testing configurations.

• Idempotent execution patterns allowing developers to re-run startup commands safely without breaking existing test sessions or duplicating resources.

• Native support for complex test suites, including integration with pytest fixtures that handle database schema initialization and cleanup between test cases.

• Automatic orphaned container mitigation to prevent long-term resource leakage during worktree maintenance or manual cleanup processes.

• Use this skill during active integration testing cycles to bypass the full docker-compose stack and improve test iteration velocity.

• It requires Docker to be running on the host machine to manage the ephemeral PostgreSQL instances effectively.

• The skill is intended to be invoked via eval $(.claude/skills/agent-db/agent-db.sh up) in your terminal to export current session variables.

• It is highly compatible with standard testing frameworks, enabling smooth transitions between unit tests that require no database and integration tests that demand a fresh, transactional environment.

• If a workspace is deleted without calling the down command, developers can manually reclaim system resources using docker rm -f agent-pg-<worktree-name>.