agent-db

agent-db 工具提供了一个强大且隔离的 PostgreSQL 执行环境，专为 Prebid Sales Agent 存储库中的集成测试所设计。通过利用 Docker 和确定性的容器命名机制，此工具允许开发人员在多个 git 工作树（worktree）中同时维护干净、无冲突的数据库状态，无需手动管理环境或担心端口冲突。它专为那些需要稳定、轻量级数据库实例（且反映类生产环境条件）但又不希望启动完整部署堆栈的开发人员而设计。

• 使用 postgres:17-alpine 进行确定性的容器管理，确保每个工作树都能稳定执行启动、关闭与状态查询。

• 无缝的环境变量注入（如 DATABASE_URL、ADCP_TESTING 及安全性密钥），简化测试配置流程。

• 支持幂等性执行，开发人员可以多次安全地调用启动指令，而不会中断现有的测试会话或造成资源重复。

• 原生支持复杂的测试套件，包括与 pytest 的集成，自动处理每个测试用例之间的数据库模式初始化与清理作业。

• 自动处理孤立容器，防止在工作树维护或手动删除过程中产生资源泄漏。

• 在进行集成测试周期时使用此工具，以绕过完整的 docker-compose 堆栈，显著提升测试迭代速度。

• 使用前提是宿主机必须正在运行 Docker 以有效管理短暂的 PostgreSQL 实例。

• 建议通过 eval $(.claude/skills/agent-db/agent-db.sh up) 指令在终端调用，以导出当前会话所需的环境变量。

• 与标准测试框架高度兼容，能够在不需要数据库的单元测试与需要全新事务环境的集成测试之间流畅切换。

• 若在未执行 down 指令的情况下删除工作空间，开发人员可随时使用 docker rm -f agent-pg-<worktree-name> 手动回收系统资源。