Skip to main content
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

​
Install from Source

​
Prerequisites

  • Go 1.25 or later
  • Git

​
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/

​
Build with Version Information

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: 
brew install golang-migrate

​
System Requirements

ComponentRequirement
PostgreSQL12 or later
TimescaleDB2.0 or later (optional)
Go1.25 or later (for building from source)
Docker20.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