Installation

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:

Linux
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

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:

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)

Getting Started

Core Concepts

Features

Workflows

Development

Docker (Recommended)

Pull the Image

Verify Installation

Usage with Docker

Network Access

Install from Source

Prerequisites

Using go install

Building from Source

Build with Version Information

Build Docker Image Locally

Multi-Architecture Build

Verifying Installation

Installing golang-migrate

System Requirements

Next Steps

Quickstart

CLI Reference

​Docker (Recommended)

​Pull the Image

​Verify Installation

​Usage with Docker

​Network Access

​Install from Source

​Prerequisites

​Using go install

​Building from Source

​Build with Version Information

​Build Docker Image Locally

​Multi-Architecture Build

​Verifying Installation

​Installing golang-migrate

​System Requirements

​Next Steps

Quickstart

CLI Reference

Docker (Recommended)

Pull the Image

Verify Installation

Usage with Docker

Network Access

Install from Source

Prerequisites

Using go install

Building from Source

Build with Version Information

Build Docker Image Locally

Multi-Architecture Build

Verifying Installation

Installing golang-migrate

System Requirements

Next Steps