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> 手動回收系統資源。