# PgDock - PostgreSQL Docker Instance Manager
[](https://badge.fury.io/py/pgdock)
[](https://github.com/matija2209/pgdock/actions/workflows/test.yml)
[](https://github.com/matija2209/pgdock/actions/workflows/publish.yml)
A CLI tool for managing PostgreSQL Docker instances with automatic credential generation, health checking, and backup capabilities.
## Features
- **Easy Instance Management**: Create, start, stop, and destroy PostgreSQL instances with simple commands
- **Automatic Setup**: Generates secure credentials, picks free ports, and handles Docker Compose configuration
- **Health Monitoring**: Built-in health checks with timeout handling
- **Backup & Restore**: Built-in backup functionality with retention policies
- **Multiple Formats**: Human-readable output and JSON support
- **Cross-Platform**: Works on macOS and Ubuntu with Docker Desktop or Docker Engine
## Installation
### Via pip (recommended)
```bash
pip install pgdock
```
### Development Installation
```bash
git clone https://github.com/matija2209/pgdock.git
cd pgdock
pip install -e .
```
#### WSL/Linux PATH Setup
If `pgdock` command is not found after installation, add the user bin directory to your PATH:
```bash
# Add to PATH temporarily
export PATH="$HOME/.local/bin:$PATH"
# Make it permanent (choose your shell)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # for bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # for zsh
# Reload your shell configuration
source ~/.bashrc # or source ~/.zshrc
```
### Requirements
- Python 3.10+
- Docker Engine (Ubuntu) or Docker Desktop (macOS)
- Docker Compose v2 (or legacy docker-compose)
## Quick Start
### Create a New Instance
```bash
# Create with auto-generated name and credentials
pgdock create
# Create with custom name
pgdock create --name mydb
# Create with specific version and port
pgdock create --name mydb --version 16 --port 5433
```
### Connect to Your Database
```bash
# Get connection details
pgdock creds mydb
# Get connection string in JSON format
pgdock creds mydb --json
# Copy connection string to clipboard
pgdock creds mydb --copy
# Connect with psql using the connection string
psql "$(pgdock creds mydb --json | jq -r .connectionString)"
```
### List All Instances
```bash
pgdock list
```
### Check Instance Status
```bash
pgdock status mydb
```
## Command Reference
### `pgdock create`
Create and start a new PostgreSQL instance.
```bash
pgdock create [OPTIONS]
```
**Options:**
- `--name TEXT`: Instance name (auto-generated if not provided)
- `--version TEXT`: PostgreSQL version (default: "latest")
- `--db-name TEXT`: Database name (defaults to instance name)
- `--user TEXT`: Database user (auto-generated if not provided)
- `--password TEXT`: Database password (auto-generated if not provided)
- `--port INTEGER`: Host port (auto-picked if not provided)
- `--wait/--no-wait`: Wait for container to be healthy (default: --wait)
- `--json-out PATH`: Save credentials to JSON file
- `--no-pgpass`: Skip updating ~/.pgpass
- `--timeout INTEGER`: Health check timeout in seconds (default: 90)
- `--copy`: Copy connection string to clipboard
**Example:**
```bash
pgdock create --name myapp --version 15 --port 5433 --copy
```
### `pgdock list`
List all PostgreSQL instances with their status.
```bash
pgdock list
```
### `pgdock status`
Show detailed status of a PostgreSQL instance.
```bash
pgdock status INSTANCE_NAME
```
### `pgdock creds`
Show credentials for a PostgreSQL instance.
```bash
pgdock creds INSTANCE_NAME [OPTIONS]
```
**Options:**
- `--json`: Output in JSON format
- `--copy`: Copy connection string to clipboard
### `pgdock start/stop`
Start or stop a PostgreSQL instance.
```bash
pgdock start INSTANCE_NAME
pgdock stop INSTANCE_NAME
```
### `pgdock destroy`
Destroy a PostgreSQL instance.
```bash
pgdock destroy INSTANCE_NAME [OPTIONS]
```
**Options:**
- `--purge-volume`: Also remove the data volume
- `--remove-config`: Also remove instance configuration files
- `--force`: Skip confirmation prompts
### `pgdock backup`
Create a backup of a PostgreSQL instance.
```bash
pgdock backup INSTANCE_NAME DEST_DIR [OPTIONS]
```
**Options:**
- `--format TEXT`: Backup format: "sql" or "custom" (default: "sql")
- `--retention-days INTEGER`: Delete backups older than N days
- `--json`: Output result in JSON format
**Example:**
```bash
pgdock backup mydb ./backups --format custom --retention-days 30
```
### `pgdock logs`
Show logs for a PostgreSQL instance.
```bash
pgdock logs INSTANCE_NAME [OPTIONS]
```
**Options:**
- `--follow, -f`: Follow log output
- `--lines, -n INTEGER`: Number of lines to show
## Configuration
### Environment Variables
- `PGDOCK_HOME`: Override default home directory (`~/.pgdock`)
### Instance Storage
pgdock stores instance configurations in `~/.pgdock/instances/`. Each instance has:
- `compose.yml`: Docker Compose configuration
- `metadata.json`: Instance metadata and credentials
### PostgreSQL Credentials
- **Automatic ~/.pgpass Updates**: pgdock automatically updates your `~/.pgpass` file
- **Secure Generation**: Passwords are 20 characters with URL-safe characters
- **Username Pattern**: `u_<8_random_chars>`
## Backup and Retention
pgdock includes built-in backup functionality:
```bash
# Create SQL backup
pgdock backup mydb /path/to/backups
# Create custom format backup with retention
pgdock backup mydb /path/to/backups --format custom --retention-days 7
# JSON output for scripting
pgdock backup mydb /path/to/backups --json
```
**Backup Filename Format**: `{instance_name}_{YYYYMMDD_HHMMSS}.{ext}`
**Retention Policy**: Automatically deletes backups older than specified days, only affecting files matching the instance name pattern.
## Troubleshooting
### Command Not Found (WSL/Linux)
If `pgdock` command is not found after installation:
```bash
# Check if ~/.local/bin is in your PATH
echo $PATH | grep -q "$HOME/.local/bin" && echo "✓ In PATH" || echo "✗ Not in PATH"
# Add to PATH temporarily
export PATH="$HOME/.local/bin:$PATH"
# Make it permanent
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # zsh
# Reload shell
source ~/.bashrc # or source ~/.zshrc
```
### Docker Permission Issues (Linux)
If you get "Docker daemon not running or not accessible" error on Linux:
```bash
# Add your user to the docker group
sudo usermod -aG docker $USER
# Apply the group change (requires re-login or newgrp)
newgrp docker
# Verify Docker access
docker info
# Now pgdock should work
pgdock create --name test
```
**Note**: You may need to log out and back in for group changes to take effect.
### Docker Compose Version Issues
pgdock requires Docker Compose v2. If you get compose-related errors:
```bash
# Check your Docker Compose version
docker compose version
# If you only have legacy docker-compose, upgrade Docker Desktop or install Compose v2:
# For Ubuntu/Debian:
sudo apt-get update
sudo apt-get install docker-compose-plugin
# For other systems, follow: https://docs.docker.com/compose/install/
```
pgdock supports both `docker compose` (v2, recommended) and `docker-compose` (legacy, with warning).
### WSL Networking
If you need to access pgdock instances from outside WSL:
```powershell
# In Windows PowerShell (as Administrator)
# Replace 172.27.16.146 with your WSL IP (get it with: wsl hostname -I)
netsh interface portproxy add v4tov4 listenport=5400 listenaddress=0.0.0.0 connectport=5400 connectaddress=172.27.16.146
# List current port forwards
netsh interface portproxy show v4tov4
# Remove port forward when no longer needed
netsh interface portproxy delete v4tov4 listenport=5400 listenaddress=0.0.0.0
```
### Port Conflicts
pgdock automatically finds free ports starting from 5400. To use a specific port:
```bash
pgdock create --port 5433
```
### Health Check Timeouts
If instances fail to start:
1. Check Docker container logs: `pgdock logs instance_name`
2. Verify port availability
3. Check Docker daemon status
4. Increase timeout: `pgdock create --timeout 120`
### Docker Compose Version
pgdock supports both:
- `docker compose` (v2, recommended)
- `docker-compose` (legacy, with warning)
## Migration from Manual Docker Setup
If you're migrating from a manual Docker Compose setup to pgdock:
1. **Stop existing containers**:
```bash
docker compose down
```
2. **Install pgdock**:
```bash
pip install pgdock
```
3. **Create new managed instance**:
```bash
pgdock create --name mydb --port 5432
```
4. **Migrate data** (if needed):
```bash
# Export from old container
docker exec old_container pg_dump -U user dbname > backup.sql
# Import to new instance
psql "$(pgdock creds mydb --json | jq -r .connectionString)" < backup.sql
```
## Testing Your Instance
After creating a pgdock instance, verify it's working correctly:
### Quick Connection Test
```bash
# Get connection details
pgdock creds mydb
# Test connection with psql (remove ?schema=public if you get URI errors)
psql "postgresql://user:password@localhost:port/database" -c "SELECT version();"
# Or use the JSON output to get connection string
CONNECTION_STRING=$(pgdock creds mydb --json | jq -r .connectionString | sed 's/?schema=public//')
psql "$CONNECTION_STRING" -c "SELECT version();"
```
### Comprehensive Instance Test
```bash
# 1. Check instance status
pgdock status mydb
# 2. Test database connection
pgdock creds mydb --json | jq -r .connectionString | sed 's/?schema=public//' | xargs -I {} psql {} -c "SELECT current_database(), current_user, version();"
# 3. Create a test table and insert data
CONNECTION_STRING=$(pgdock creds mydb --json | jq -r .connectionString | sed 's/?schema=public//')
psql "$CONNECTION_STRING" << EOF
CREATE TABLE test_table (id SERIAL PRIMARY KEY, name TEXT, created_at TIMESTAMP DEFAULT NOW());
INSERT INTO test_table (name) VALUES ('pgdock test'), ('connection verified');
SELECT * FROM test_table;
DROP TABLE test_table;
EOF
# 4. Test backup functionality
mkdir -p ./test-backups
pgdock backup mydb ./test-backups --format sql
ls -la ./test-backups/
# 5. Check container logs
pgdock logs mydb --lines 20
```
### External Access Testing
If you need external access (VPS, cloud instance):
```bash
# Test from another machine (replace with your server IP)
psql "postgresql://user:password@YOUR_SERVER_IP:5400/database" -c "SELECT version();"
# Example with actual values:
psql "postgresql://u_56ocdyl4:TbCnRR9UiI0SBROW7O1C@23.88.102.236:5400/pg_smart_wolf" -c "SELECT version();"
```
**Expected Output:**
```
version
-----------------------------------------------------------------------------
PostgreSQL 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
(1 row)
```
### Testing Network Connectivity
```bash
# Test port connectivity
telnet localhost 5400 # or your server IP
# Check if port is open
nmap -p 5400 localhost # or your server IP
# For Docker containers, check port mapping
docker port pgdock-mydb
```
## Examples
### Development Workflow
```bash
# Create a development database
pgdock create --name devdb --version 15
# Get connection details for your app
pgdock creds devdb --json
# Check if it's running
pgdock status devdb
# Create a backup before making changes
pgdock backup devdb ./backups
# View recent logs
pgdock logs devdb --lines 50
# Stop when done
pgdock stop devdb
```
### Production-like Setup
```bash
# Create production-like instance
pgdock create --name proddb --version 16 --port 5432
# Create daily backups with retention
pgdock backup proddb /var/backups/postgres --retention-days 30
# Monitor health
pgdock status proddb
```
### Multiple Instances
```bash
# Create multiple versions for testing
pgdock create --name test-pg14 --version 14
pgdock create --name test-pg15 --version 15
pgdock create --name test-pg16 --version 16
# List all instances
pgdock list
# Connect to specific version
psql "$(pgdock creds test-pg15 --json | jq -r .connectionString)"
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
[License Type] - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "pgdock",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "postgresql, docker, cli, database, postgres, docker-compose, backup, instance-manager",
"author": "pgdock",
"author_email": "Matija <your-email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/94/50/cecfb5d241aaf3542eed629643c3b7c75412bd4024b4b1828628f4599ef9/pgdock-1.0.0.tar.gz",
"platform": null,
"description": "# PgDock - PostgreSQL Docker Instance Manager\n\n[](https://badge.fury.io/py/pgdock)\n[](https://github.com/matija2209/pgdock/actions/workflows/test.yml)\n[](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 & 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\"' >> ~/.bashrc # for bash\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.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_<8_random_chars>`\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\" && echo \"\u2713 In PATH\" || echo \"\u2717 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\"' >> ~/.bashrc # bash\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.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 > backup.sql\n \n # Import to new instance \n psql \"$(pgdock creds mydb --json | jq -r .connectionString)\" < 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\" << 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.\n",
"bugtrack_url": null,
"license": null,
"summary": "PostgreSQL Docker Instance Manager CLI. Create, manage, and backup PostgreSQL instances with automatic credential generation, health monitoring, and cross-platform support.",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/matija2209/pgdock#readme",
"Homepage": "https://github.com/matija2209/pgdock",
"Issues": "https://github.com/matija2209/pgdock/issues",
"Repository": "https://github.com/matija2209/pgdock"
},
"split_keywords": [
"postgresql",
" docker",
" cli",
" database",
" postgres",
" docker-compose",
" backup",
" instance-manager"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b712dcdb21d390e5a54059c5c3b3afeb8473ce2ddb073e2916bfd53c1efc1fff",
"md5": "2c6c9f474e488716d3d8aafd3d6a63af",
"sha256": "32866e4de6201b71c777408f68560af8a058a3d4acab4182623922b88c9fbd80"
},
"downloads": -1,
"filename": "pgdock-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c6c9f474e488716d3d8aafd3d6a63af",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 15566,
"upload_time": "2025-08-12T14:28:18",
"upload_time_iso_8601": "2025-08-12T14:28:18.441647Z",
"url": "https://files.pythonhosted.org/packages/b7/12/dcdb21d390e5a54059c5c3b3afeb8473ce2ddb073e2916bfd53c1efc1fff/pgdock-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9450cecfb5d241aaf3542eed629643c3b7c75412bd4024b4b1828628f4599ef9",
"md5": "6e5a0c0564f833d83fcbda222f74a847",
"sha256": "cee5ca350e7e2e9ce9b454256dbbc8a0b724e94ba0613c2de5a697800513638a"
},
"downloads": -1,
"filename": "pgdock-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "6e5a0c0564f833d83fcbda222f74a847",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19675,
"upload_time": "2025-08-12T14:28:22",
"upload_time_iso_8601": "2025-08-12T14:28:22.292430Z",
"url": "https://files.pythonhosted.org/packages/94/50/cecfb5d241aaf3542eed629643c3b7c75412bd4024b4b1828628f4599ef9/pgdock-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 14:28:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "matija2209",
"github_project": "pgdock#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "typer",
"specs": [
[
">=",
"0.12.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "jinja2",
"specs": [
[
">=",
"3.1.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
}
],
"lcname": "pgdock"
}
JSON
