160 lines
4.2 KiB
Markdown
160 lines
4.2 KiB
Markdown
```text
|
|
▄▄▄▄ ▐▌
|
|
█ █ ▐▌
|
|
█▄▄▄▀ ▗▞▀▜▌
|
|
█ ▗▄▖▝▚▄▟▌
|
|
▀ ▐▌ ▐▌
|
|
▝▀▜▌
|
|
▐▙▄▞▘
|
|
```
|
|
|
|
---
|
|
|
|
> Inspired by the great [Gel](https://github.com/geldata/gel-cli) CLI. We will miss it.
|
|
|
|
Project-scoped PostgreSQL instance manager for local development.
|
|
|
|
## Overview
|
|
|
|
Tired of juggling PostgreSQL versions across projects? Wrestling with port conflicts? Spending half your morning helping new teammates get their local database running? Well, say no more!
|
|
|
|
`pgd` gives each of your projects its own containerized PostgreSQL instance with zero configuration headaches.
|
|
Isolate, upgrade and nuke -- everything safely.
|
|
|
|
## Why Use pgd?
|
|
|
|
**Stop playing around database -- play with it.** Your legacy project needs Postgres 14, your new microservice wants 16, and that experimental side project is testing 19-beta. With `pgd`, they all run simultaneously without stepping on each other's toes.
|
|
|
|
**Onboard developers in seconds, not hours.** No more wiki pages with 47 steps to set up the local database. New teammate clones the repo, runs `pgd init`, and they're ready to code. The database config lives right there in version control where it belongs.
|
|
|
|
**Isolate your data like you isolate your code (or your life).** Each project gets its own database instance.
|
|
|
|
**Let the tool handle the boring stuff.** `pgd` manages ports, volumes and versions for you
|
|
|
|
## Requirements
|
|
|
|
- Docker daemon running locally
|
|
- Rust toolchain (for installation from source)
|
|
|
|
## Installation
|
|
|
|
Install via cargo:
|
|
|
|
```bash
|
|
cargo install pgd
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
Navigate to your project directory and initialize a new PostgreSQL instance:
|
|
|
|
```bash
|
|
cd my-project
|
|
pgd init
|
|
```
|
|
|
|
This creates a `pgd.toml` configuration file with auto-generated credentials and latests postgres version available.
|
|
Note: upgrades are currently unsupported at the moment.
|
|
Downgrades wouldn't ever be supported, because postgres is not future-compatible.
|
|
|
|
## Commands
|
|
|
|
### Project Initialization
|
|
|
|
```bash
|
|
pgd init
|
|
```
|
|
|
|
Creates a `pgd.toml` file in the current directory with auto-populated configuration. If the file already exists, initializes the Docker container for the existing configuration.
|
|
|
|
### Instance Control
|
|
|
|
All instance commands follow the pattern `pgd instance <command>`:
|
|
|
|
```bash
|
|
# Start the PostgreSQL instance
|
|
pgd instance start
|
|
|
|
# Stop the PostgreSQL instance
|
|
pgd instance stop
|
|
|
|
# Restart the PostgreSQL instance
|
|
pgd instance restart
|
|
|
|
# Check instance status and configuration drift
|
|
pgd instance status
|
|
|
|
# View PostgreSQL logs
|
|
pgd instance logs
|
|
|
|
# Follow logs in real-time
|
|
pgd instance logs --follow
|
|
|
|
# Get connection details
|
|
pgd instance conn
|
|
|
|
# Get connection as DSN URL
|
|
pgd instance conn --format dsn
|
|
|
|
# Get human-readable connection details
|
|
pgd instance conn --format human
|
|
```
|
|
|
|
### Destructive Operations
|
|
|
|
```bash
|
|
# Stop and remove the container
|
|
pgd instance destroy
|
|
|
|
# Wipe all database data
|
|
pgd instance wipe
|
|
```
|
|
|
|
These commands require confirmation to prevent accidental data loss. You can bypass confirmation with the `force` flag, but use with caution:
|
|
|
|
```bash
|
|
# Force destroy without confirmation
|
|
pgd instance destroy --force
|
|
|
|
# Force wipe without confirmation
|
|
pgd instance wipe --force
|
|
```
|
|
|
|
### Global Options
|
|
|
|
```bash
|
|
# Enable verbose logging
|
|
pgd --verbose <command>
|
|
|
|
# Show version
|
|
pgd --version
|
|
|
|
# Show help
|
|
pgd --help
|
|
```
|
|
|
|
## How It Works
|
|
|
|
`pgd` manages Docker containers with PostgreSQL images. Each project's container is named deterministically based on the project directory name, ensuring no duplicates.
|
|
|
|
The tool tracks state separately for each instance to detect configuration drift, such as:
|
|
|
|
- Version mismatches between `pgd.toml` and the running container
|
|
- Port conflicts or changes
|
|
- Container state inconsistencies
|
|
|
|
When drift is detected, `pgd instance status` will show warnings and you can use `pgd instance start` to reconcile the state.
|
|
|
|
## Project Structure
|
|
|
|
Your project tree after initialization:
|
|
|
|
```text
|
|
my-project/
|
|
├── pgd.toml # Database configuration
|
|
├── src/ # Your application code
|
|
└── ...
|
|
```
|
|
|
|
The `pgd.toml` file should be committed to version control so team members can reproduce the exact database setup.
|