{"skill":{"slug":"postgres-manager","displayName":"Postgres Manager","summary":"Manage a shared PostgreSQL Docker container for local dev environments. Handles container lifecycle, database creation/removal, and cross-instance dumps via...","description":"---\nname: PostgreSQL Manager\nslug: postgres-manager\nversion: 1.1.0\ndescription: \"Manage a shared PostgreSQL Docker container for local dev environments. Handles container lifecycle, database creation/removal, and cross-instance dumps via pg_dump. Joins the shared Docker network created by proxy-manager.\"\nchangelog: \"v1.1.0: Fix dump to avoid sh -c shell injection (now uses two docker exec with -d flag), validate all DB names against strict regex, warn on default password, bind host port to 127.0.0.1, pin image to postgres:16.4-alpine.\"\ntriggers:\n  - \"start postgres\"\n  - \"stop postgres\"\n  - \"postgres status\"\n  - \"create postgres database\"\n  - \"criar banco postgres\"\n  - \"dump postgres\"\n  - \"postgres-manager\"\nmetadata: {\"clawdbot\":{\"emoji\":\"🐘\",\"requires\":{\"bins\":[\"docker\"]},\"os\":[\"linux\",\"darwin\"]}}\n---\n\n# PostgreSQL Manager\n\nManages the shared PostgreSQL Docker container for local dev environments.\n\n## Architecture\n\n```\npostgres-manager/\n├── docker-compose.yml   # PostgreSQL 16 Alpine container\n└── run.sh               # lifecycle + db admin CLI\n```\n\nJoins the shared `nginx-proxy_net` network (created by proxy-manager) so app containers connect via hostname `codai_postgres`. Data is persisted in a named volume.\n\n## Commands\n\n```bash\n./run.sh start                    # start PostgreSQL container\n./run.sh stop                     # stop container (data persists in volume)\n./run.sh status                   # status + list databases\n./run.sh wait                     # block until PostgreSQL is ready\n./run.sh create-db <name>         # CREATE DATABASE (idempotent)\n./run.sh drop-db <name>           # DROP DATABASE (interactive confirm)\n./run.sh dump <src> <dest>        # pg_dump src | psql dest\n./run.sh list-dbs                 # list all non-template databases\n./run.sh psql [<db>]              # open psql interactive session\n```\n\n## How to Execute Tasks\n\n### Start PostgreSQL for the first time\n```bash\ncd postgres-manager && ./run.sh start\n```\nOn first run, Docker creates the volume and initializes `codai_main`.\n\n### Create a database for a new instance\n```bash\n./run.sh create-db codai_feature\n```\n\n### Snapshot main database into a new instance\n```bash\n./run.sh dump codai_main codai_feature\n```\n\n### Remove a worktree database\n```bash\n./run.sh drop-db codai_feature   # prompts for confirmation\n```\n\n### Open interactive psql\n```bash\n./run.sh psql                    # connects to codai_main\n./run.sh psql codai_feature      # connects to specific db\n```\n\n## Startup Order\n\n1. `proxy-manager start` — creates the shared Docker network\n2. `postgres-manager start` — joins the shared network\n3. `worktree-manager start <instance>`\n\n## Configuration\n\n| Variable              | Default          | Purpose                        |\n|-----------------------|------------------|--------------------------------|\n| `POSTGRES_CONTAINER`  | `codai_postgres` | Container name                 |\n| `POSTGRES_USER`       | `codai`          | Database user                  |\n| `POSTGRES_PASSWORD`   | `pgpass`         | Database password              |\n| `POSTGRES_MAIN_DB`    | `codai_main`     | Primary database name          |\n| `POSTGRES_PORT`       | `5433`           | Host port (maps to 5432)       |\n| `CODAI_NETWORK`       | `nginx-proxy_net`| Shared Docker network name     |\n\n## App Connection\n\nBackend containers connect to PostgreSQL at:\n- **Host**: `codai_postgres` (container name on shared network)\n- **Port**: `5432`\n- **User**: `codai` / **Password**: `pgpass`\n- **DB**: `codai_main` (or instance-specific db)\n\n## Rules\n\n- Never drop `POSTGRES_MAIN_DB` — it is the source of truth for snapshots.\n- `drop-db` always prompts for confirmation.\n- Database names are validated against `^[a-z][a-z0-9_]{0,62}$` before any SQL or shell operation.\n- `stop` preserves data in the Docker volume. Use `docker compose down -v` only when you intentionally want to delete persisted data.\n- The container uses `restart: unless-stopped` — it will resume after a Docker daemon restart. Run `./run.sh stop` when done.\n- The host port (`POSTGRES_PORT`) is bound to `127.0.0.1` only. Set a non-default `POSTGRES_PASSWORD` on shared machines.\n- Network is `external: true` — proxy-manager must start first.\n\n## Related Plugins\n\n- `proxy-manager` — creates the shared Docker network (start first)\n- `mysql-manager` — MySQL alternative\n- `redis-manager` — in-memory cache companion\n- `worktree-manager` — app instances that consume PostgreSQL\n","topics":["Database","Docker","PostgreSQL"],"tags":{"latest":"1.0.2"},"stats":{"comments":0,"downloads":416,"installsAllTime":15,"installsCurrent":2,"stars":0,"versions":3},"createdAt":1778325510632,"updatedAt":1778492885325},"latestVersion":{"version":"1.0.2","createdAt":1778421436529,"changelog":"- Updated internal version to 1.0.2 in metadata.\n- No functional or user-facing changes.","license":"MIT-0"},"metadata":{"setup":[],"os":["linux","darwin"],"systems":null},"owner":{"handle":"pereirajair","userId":"s17ayja6zg12t1dv98gn9tsg3986dtdv","displayName":"Jair Pereira","image":"https://avatars.githubusercontent.com/u/1306512?v=4"},"moderation":null}