Documentation Index Fetch the complete documentation index at: https://pgtofu.com/llms.txt
Use this file to discover all available pages before exploring further.
Docker (Recommended) Docker is the easiest way to get started with pgtofu. The official image includes both pgtofu and golang-migrate.
Pull the Image docker pull accented/pgtofu:latest
Verify Installation docker run --rm accented/pgtofu:latest --version docker run --rm accented/pgtofu:latest --help
Usage with Docker When using Docker, mount your local directories and pass environment variables:
docker run --rm \ -v "$( pwd ):/workspace" \ -w /workspace \ -e DATABASE_URL=" $DATABASE_URL " \ accented/pgtofu:latest extract --output current-schema.json
Create a shell alias to simplify Docker usage: alias pgtofu = 'docker run --rm -v "$(pwd):/workspace" -w /workspace -e DATABASE_URL="$DATABASE_URL" accented/pgtofu:latest'
Network Access To connect to a local database from Docker, use the host network mode on Linux or host.docker.internal on macOS/Windows:
docker run --rm \ --network host \ -v "$( pwd ):/workspace" \ -w /workspace \ -e DATABASE_URL="postgres://user:pass@localhost:5432/db" \ accented/pgtofu:latest extract --output schema.json
docker run --rm \ -v "$( pwd ):/workspace" \ -w /workspace \ -e DATABASE_URL="postgres://user:pass@host.docker.internal:5432/db" \ accented/pgtofu:latest extract --output schema.json
Install from Source Prerequisites Using go install go install github.com/accented-ai/pgtofu/cmd/pgtofu@latest
Ensure $GOPATH/bin (or $HOME/go/bin) is in your PATH:
export PATH = " $PATH :$( go env GOPATH)/bin"
Building from Source # Clone the repository git clone https://github.com/accented-ai/pgtofu.git cd pgtofu # Build the binary go build -o pgtofu ./cmd/pgtofu # Optionally, install to your PATH sudo mv pgtofu /usr/local/bin/
VERSION = $( git describe --tags --always ) COMMIT = $( git rev-parse --short HEAD ) BUILD_TIME = $( date -u +"%Y-%m-%dT%H:%M:%SZ" ) go build -ldflags "-X main.version= $VERSION -X main.commit= $COMMIT -X main.buildTime= $BUILD_TIME " \ -o pgtofu ./cmd/pgtofu
Build Docker Image Locally If you want to customize the Docker image or build from a specific branch:
git clone https://github.com/accented-ai/pgtofu.git cd pgtofu # Build the image docker build -t pgtofu:local . # Run your local build docker run --rm pgtofu:local --version
Multi-Architecture Build To build for multiple platforms:
docker buildx build \ --platform linux/amd64,linux/arm64 \ -t pgtofu:local \ .
Verifying Installation After installation, verify pgtofu is working:
# Check version pgtofu --version # View available commands pgtofu --help # View command-specific help pgtofu extract --help pgtofu diff --help pgtofu generate --help pgtofu partition --help
Installing golang-migrate pgtofu generates migration files compatible with golang-migrate. Install it to apply migrations:
macOS
Linux
Go Install
Docker
brew install golang-migrate
# Download the binary curl -L https://github.com/golang-migrate/migrate/releases/download/v4.17.0/migrate.linux-amd64.tar.gz | tar xvz sudo mv migrate /usr/local/bin/
go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
golang-migrate is included in the pgtofu Docker image: docker run --rm accented/pgtofu:latest migrate --help
System Requirements Component Requirement PostgreSQL 12 or later TimescaleDB 2.0 or later (optional) Go 1.25 or later (for building from source) Docker 20.10 or later (for Docker installation)
Next Steps
Quickstart Follow the quickstart guide to start using pgtofu
CLI Reference Learn about all available commands and options
