{"id":30308700,"url":"https://github.com/matija2209/pgdock","last_synced_at":"2026-01-20T16:42:59.829Z","repository":{"id":285604956,"uuid":"928352910","full_name":"matija2209/pgdock","owner":"matija2209","description":"pgdock - PostgreSQL Docker Instance Manager CLI. Create, manage, and backup PostgreSQL instances with automatic credential generation, health monitoring, and cross-platform support.","archived":false,"fork":false,"pushed_at":"2025-08-12T10:10:15.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-12T12:10:47.905Z","etag":null,"topics":["backup","cli","database","docker","docker-compose","instance-manager","postgres","postgresql","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matija2209.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-06T13:52:53.000Z","updated_at":"2025-08-12T10:10:18.000Z","dependencies_parsed_at":"2025-04-01T17:51:28.470Z","dependency_job_id":"d0486223-bdb9-4c41-9fc3-77683eb694f9","html_url":"https://github.com/matija2209/pgdock","commit_stats":null,"previous_names":["matija2209/postgres-docker-db"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/matija2209/pgdock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matija2209%2Fpgdock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matija2209%2Fpgdock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matija2209%2Fpgdock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matija2209%2Fpgdock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matija2209","download_url":"https://codeload.github.com/matija2209/pgdock/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matija2209%2Fpgdock/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270850079,"owners_count":24656448,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backup","cli","database","docker","docker-compose","instance-manager","postgres","postgresql","python"],"created_at":"2025-08-17T12:44:44.113Z","updated_at":"2025-10-20T04:20:12.344Z","avatar_url":"https://github.com/matija2209.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PgDock - PostgreSQL Docker Instance Manager\n\n[![PyPI version](https://badge.fury.io/py/pgdock.svg)](https://badge.fury.io/py/pgdock)\n[![Test](https://github.com/matija2209/pgdock/actions/workflows/test.yml/badge.svg)](https://github.com/matija2209/pgdock/actions/workflows/test.yml)\n[![Publish to PyPI](https://github.com/matija2209/pgdock/actions/workflows/publish.yml/badge.svg)](https://github.com/matija2209/pgdock/actions/workflows/publish.yml)\n\nA CLI tool for managing PostgreSQL Docker instances with automatic credential generation, health checking, and backup capabilities.\n\n## Features\n\n- **Easy Instance Management**: Create, start, stop, and destroy PostgreSQL instances with simple commands\n- **Automatic Setup**: Generates secure credentials, picks free ports, and handles Docker Compose configuration\n- **Health Monitoring**: Built-in health checks with timeout handling\n- **Backup \u0026 Restore**: Built-in backup functionality with retention policies\n- **Multiple Formats**: Human-readable output and JSON support\n- **Cross-Platform**: Works on macOS and Ubuntu with Docker Desktop or Docker Engine\n\n## Installation\n\n### Via pip (recommended)\n\n```bash\npip install pgdock\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/matija2209/pgdock.git\ncd pgdock\npip install -e .\n```\n\n#### WSL/Linux PATH Setup\n\nIf `pgdock` command is not found after installation, add the user bin directory to your PATH:\n\n```bash\n# Add to PATH temporarily\nexport PATH=\"$HOME/.local/bin:$PATH\"\n\n# Make it permanent (choose your shell)\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.bashrc  # for bash\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.zshrc   # for zsh\n\n# Reload your shell configuration\nsource ~/.bashrc  # or source ~/.zshrc\n```\n\n### Requirements\n\n- Python 3.10+\n- Docker Engine (Ubuntu) or Docker Desktop (macOS)\n- Docker Compose v2 (or legacy docker-compose)\n\n## Quick Start\n\n### Create a New Instance\n\n```bash\n# Create with auto-generated name and credentials\npgdock create\n\n# Create with custom name\npgdock create --name mydb\n\n# Create with specific version and port\npgdock create --name mydb --version 16 --port 5433\n```\n\n### Connect to Your Database\n\n```bash\n# Get connection details\npgdock creds mydb\n\n# Get connection string in JSON format\npgdock creds mydb --json\n\n# Copy connection string to clipboard\npgdock creds mydb --copy\n\n# Connect with psql using the connection string\npsql \"$(pgdock creds mydb --json | jq -r .connectionString)\"\n```\n\n### List All Instances\n\n```bash\npgdock list\n```\n\n### Check Instance Status\n\n```bash\npgdock status mydb\n```\n\n## Command Reference\n\n### `pgdock create`\n\nCreate and start a new PostgreSQL instance.\n\n```bash\npgdock create [OPTIONS]\n```\n\n**Options:**\n- `--name TEXT`: Instance name (auto-generated if not provided)\n- `--version TEXT`: PostgreSQL version (default: \"latest\")\n- `--db-name TEXT`: Database name (defaults to instance name)\n- `--user TEXT`: Database user (auto-generated if not provided)\n- `--password TEXT`: Database password (auto-generated if not provided)\n- `--port INTEGER`: Host port (auto-picked if not provided)\n- `--wait/--no-wait`: Wait for container to be healthy (default: --wait)\n- `--json-out PATH`: Save credentials to JSON file\n- `--no-pgpass`: Skip updating ~/.pgpass\n- `--timeout INTEGER`: Health check timeout in seconds (default: 90)\n- `--copy`: Copy connection string to clipboard\n\n**Example:**\n```bash\npgdock create --name myapp --version 15 --port 5433 --copy\n```\n\n### `pgdock list`\n\nList all PostgreSQL instances with their status.\n\n```bash\npgdock list\n```\n\n### `pgdock status`\n\nShow detailed status of a PostgreSQL instance.\n\n```bash\npgdock status INSTANCE_NAME\n```\n\n### `pgdock creds`\n\nShow credentials for a PostgreSQL instance.\n\n```bash\npgdock creds INSTANCE_NAME [OPTIONS]\n```\n\n**Options:**\n- `--json`: Output in JSON format\n- `--copy`: Copy connection string to clipboard\n\n### `pgdock start/stop`\n\nStart or stop a PostgreSQL instance.\n\n```bash\npgdock start INSTANCE_NAME\npgdock stop INSTANCE_NAME\n```\n\n### `pgdock destroy`\n\nDestroy a PostgreSQL instance.\n\n```bash\npgdock destroy INSTANCE_NAME [OPTIONS]\n```\n\n**Options:**\n- `--purge-volume`: Also remove the data volume\n- `--remove-config`: Also remove instance configuration files\n- `--force`: Skip confirmation prompts\n\n### `pgdock backup`\n\nCreate a backup of a PostgreSQL instance.\n\n```bash\npgdock backup INSTANCE_NAME DEST_DIR [OPTIONS]\n```\n\n**Options:**\n- `--format TEXT`: Backup format: \"sql\" or \"custom\" (default: \"sql\")\n- `--retention-days INTEGER`: Delete backups older than N days\n- `--json`: Output result in JSON format\n\n**Example:**\n```bash\npgdock backup mydb ./backups --format custom --retention-days 30\n```\n\n### `pgdock logs`\n\nShow logs for a PostgreSQL instance.\n\n```bash\npgdock logs INSTANCE_NAME [OPTIONS]\n```\n\n**Options:**\n- `--follow, -f`: Follow log output\n- `--lines, -n INTEGER`: Number of lines to show\n\n## Configuration\n\n### Environment Variables\n\n- `PGDOCK_HOME`: Override default home directory (`~/.pgdock`)\n\n### Instance Storage\n\npgdock stores instance configurations in `~/.pgdock/instances/`. Each instance has:\n\n- `compose.yml`: Docker Compose configuration\n- `metadata.json`: Instance metadata and credentials\n\n### PostgreSQL Credentials\n\n- **Automatic ~/.pgpass Updates**: pgdock automatically updates your `~/.pgpass` file\n- **Secure Generation**: Passwords are 20 characters with URL-safe characters\n- **Username Pattern**: `u_\u003c8_random_chars\u003e`\n\n## Backup and Retention\n\npgdock includes built-in backup functionality:\n\n```bash\n# Create SQL backup\npgdock backup mydb /path/to/backups\n\n# Create custom format backup with retention\npgdock backup mydb /path/to/backups --format custom --retention-days 7\n\n# JSON output for scripting\npgdock backup mydb /path/to/backups --json\n```\n\n**Backup Filename Format**: `{instance_name}_{YYYYMMDD_HHMMSS}.{ext}`\n\n**Retention Policy**: Automatically deletes backups older than specified days, only affecting files matching the instance name pattern.\n\n## Troubleshooting\n\n### Command Not Found (WSL/Linux)\n\nIf `pgdock` command is not found after installation:\n\n```bash\n# Check if ~/.local/bin is in your PATH\necho $PATH | grep -q \"$HOME/.local/bin\" \u0026\u0026 echo \"✓ In PATH\" || echo \"✗ Not in PATH\"\n\n# Add to PATH temporarily\nexport PATH=\"$HOME/.local/bin:$PATH\"\n\n# Make it permanent\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.bashrc  # bash\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.zshrc   # zsh\n\n# Reload shell\nsource ~/.bashrc  # or source ~/.zshrc\n```\n\n### Docker Permission Issues (Linux)\n\nIf you get \"Docker daemon not running or not accessible\" error on Linux:\n\n```bash\n# Add your user to the docker group\nsudo usermod -aG docker $USER\n\n# Apply the group change (requires re-login or newgrp)\nnewgrp docker\n\n# Verify Docker access\ndocker info\n\n# Now pgdock should work\npgdock create --name test\n```\n\n**Note**: You may need to log out and back in for group changes to take effect.\n\n### Docker Compose Version Issues\n\npgdock requires Docker Compose v2. If you get compose-related errors:\n\n```bash\n# Check your Docker Compose version\ndocker compose version\n\n# If you only have legacy docker-compose, upgrade Docker Desktop or install Compose v2:\n# For Ubuntu/Debian:\nsudo apt-get update\nsudo apt-get install docker-compose-plugin\n\n# For other systems, follow: https://docs.docker.com/compose/install/\n```\n\npgdock supports both `docker compose` (v2, recommended) and `docker-compose` (legacy, with warning).\n\n### WSL Networking\n\nIf you need to access pgdock instances from outside WSL:\n\n```powershell\n# In Windows PowerShell (as Administrator)\n# Replace 172.27.16.146 with your WSL IP (get it with: wsl hostname -I)\nnetsh interface portproxy add v4tov4 listenport=5400 listenaddress=0.0.0.0 connectport=5400 connectaddress=172.27.16.146\n\n# List current port forwards\nnetsh interface portproxy show v4tov4\n\n# Remove port forward when no longer needed\nnetsh interface portproxy delete v4tov4 listenport=5400 listenaddress=0.0.0.0\n```\n\n### Port Conflicts\n\npgdock automatically finds free ports starting from 5400. To use a specific port:\n\n```bash\npgdock create --port 5433\n```\n\n### Health Check Timeouts\n\nIf instances fail to start:\n\n1. Check Docker container logs: `pgdock logs instance_name`\n2. Verify port availability\n3. Check Docker daemon status\n4. Increase timeout: `pgdock create --timeout 120`\n\n### Docker Compose Version\n\npgdock supports both:\n- `docker compose` (v2, recommended)\n- `docker-compose` (legacy, with warning)\n\n## Migration from Manual Docker Setup\n\nIf you're migrating from a manual Docker Compose setup to pgdock:\n\n1. **Stop existing containers**:\n   ```bash\n   docker compose down\n   ```\n\n2. **Install pgdock**:\n   ```bash\n   pip install pgdock\n   ```\n\n3. **Create new managed instance**:\n   ```bash\n   pgdock create --name mydb --port 5432\n   ```\n\n4. **Migrate data** (if needed):\n   ```bash\n   # Export from old container\n   docker exec old_container pg_dump -U user dbname \u003e backup.sql\n   \n   # Import to new instance  \n   psql \"$(pgdock creds mydb --json | jq -r .connectionString)\" \u003c backup.sql\n   ```\n\n## Testing Your Instance\n\nAfter creating a pgdock instance, verify it's working correctly:\n\n### Quick Connection Test\n\n```bash\n# Get connection details\npgdock creds mydb\n\n# Test connection with psql (remove ?schema=public if you get URI errors)\npsql \"postgresql://user:password@localhost:port/database\" -c \"SELECT version();\"\n\n# Or use the JSON output to get connection string\nCONNECTION_STRING=$(pgdock creds mydb --json | jq -r .connectionString | sed 's/?schema=public//')\npsql \"$CONNECTION_STRING\" -c \"SELECT version();\"\n```\n\n### Comprehensive Instance Test\n\n```bash\n# 1. Check instance status\npgdock status mydb\n\n# 2. Test database connection\npgdock creds mydb --json | jq -r .connectionString | sed 's/?schema=public//' | xargs -I {} psql {} -c \"SELECT current_database(), current_user, version();\"\n\n# 3. Create a test table and insert data\nCONNECTION_STRING=$(pgdock creds mydb --json | jq -r .connectionString | sed 's/?schema=public//')\npsql \"$CONNECTION_STRING\" \u003c\u003c EOF\nCREATE TABLE test_table (id SERIAL PRIMARY KEY, name TEXT, created_at TIMESTAMP DEFAULT NOW());\nINSERT INTO test_table (name) VALUES ('pgdock test'), ('connection verified');\nSELECT * FROM test_table;\nDROP TABLE test_table;\nEOF\n\n# 4. Test backup functionality\nmkdir -p ./test-backups\npgdock backup mydb ./test-backups --format sql\nls -la ./test-backups/\n\n# 5. Check container logs\npgdock logs mydb --lines 20\n```\n\n### External Access Testing\n\nIf you need external access (VPS, cloud instance):\n\n```bash\n# Test from another machine (replace with your server IP)\npsql \"postgresql://user:password@YOUR_SERVER_IP:5400/database\" -c \"SELECT version();\"\n\n# Example with actual values:\npsql \"postgresql://u_56ocdyl4:TbCnRR9UiI0SBROW7O1C@23.88.102.236:5400/pg_smart_wolf\" -c \"SELECT version();\"\n```\n\n**Expected Output:**\n```\n                                   version                                    \n-----------------------------------------------------------------------------\nPostgreSQL 17.5 (Debian 17.5-1.pgdg120+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 12.2.0-14) 12.2.0, 64-bit\n(1 row)\n```\n\n### Testing Network Connectivity\n\n```bash\n# Test port connectivity\ntelnet localhost 5400  # or your server IP\n\n# Check if port is open\nnmap -p 5400 localhost  # or your server IP\n\n# For Docker containers, check port mapping\ndocker port pgdock-mydb\n```\n\n## Examples\n\n### Development Workflow\n\n```bash\n# Create a development database\npgdock create --name devdb --version 15\n\n# Get connection details for your app\npgdock creds devdb --json\n\n# Check if it's running\npgdock status devdb\n\n# Create a backup before making changes\npgdock backup devdb ./backups\n\n# View recent logs\npgdock logs devdb --lines 50\n\n# Stop when done\npgdock stop devdb\n```\n\n### Production-like Setup\n\n```bash\n# Create production-like instance\npgdock create --name proddb --version 16 --port 5432\n\n# Create daily backups with retention\npgdock backup proddb /var/backups/postgres --retention-days 30\n\n# Monitor health\npgdock status proddb\n```\n\n### Multiple Instances\n\n```bash\n# Create multiple versions for testing\npgdock create --name test-pg14 --version 14\npgdock create --name test-pg15 --version 15\npgdock create --name test-pg16 --version 16\n\n# List all instances\npgdock list\n\n# Connect to specific version\npsql \"$(pgdock creds test-pg15 --json | jq -r .connectionString)\"\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\n[License Type] - see LICENSE file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatija2209%2Fpgdock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatija2209%2Fpgdock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatija2209%2Fpgdock/lists"}