> ## Documentation Index
> Fetch the complete documentation index at: https://pgtofu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install pgtofu via Docker or from source

## Docker (Recommended)

Docker is the easiest way to get started with pgtofu. The official image includes both pgtofu and golang-migrate.

### Pull the Image

```bash theme={null}
docker pull accented/pgtofu:latest
```

### Verify Installation

```bash theme={null}
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:

```bash theme={null}
docker run --rm \
  -v "$(pwd):/workspace" \
  -w /workspace \
  -e DATABASE_URL="$DATABASE_URL" \
  accented/pgtofu:latest extract --output current-schema.json
```

<Tip>
  Create a shell alias to simplify Docker usage:

  ```bash theme={null}
  alias pgtofu='docker run --rm -v "$(pwd):/workspace" -w /workspace -e DATABASE_URL="$DATABASE_URL" accented/pgtofu:latest'
  ```
</Tip>

### Network Access

To connect to a local database from Docker, use the host network mode on Linux or `host.docker.internal` on macOS/Windows:

<Tabs>
  <Tab title="Linux">
    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="macOS / Windows">
    ```bash theme={null}
    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
    ```
  </Tab>
</Tabs>

## Install from Source

### Prerequisites

* Go 1.25 or later
* Git

### Using go install

```bash theme={null}
go install github.com/accented-ai/pgtofu/cmd/pgtofu@latest
```

Ensure `$GOPATH/bin` (or `$HOME/go/bin`) is in your `PATH`:

```bash theme={null}
export PATH="$PATH:$(go env GOPATH)/bin"
```

### Building from Source

```bash theme={null}
# 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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t pgtofu:local \
  .
```

## Verifying Installation

After installation, verify pgtofu is working:

```bash theme={null}
# 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:

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    brew install golang-migrate
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    # 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/
    ```
  </Tab>

  <Tab title="Go Install">
    ```bash theme={null}
    go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
    ```
  </Tab>

  <Tab title="Docker">
    golang-migrate is included in the pgtofu Docker image:

    ```bash theme={null}
    docker run --rm accented/pgtofu:latest migrate --help
    ```
  </Tab>
</Tabs>

## 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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Follow the quickstart guide to start using pgtofu
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Learn about all available commands and options
  </Card>
</CardGroup>