Installation

Kubernetes

PgDog comes with its own Helm chart. You can install it directly from our chart repository:

helm repo add pgdogdev https://helm.pgdog.dev
helm install pgdog pgdogdev/pgdog

Docker

Docker images are built automatically for each commit to the main branch in GitHub:

docker run ghcr.io/pgdogdev/pgdog:main

SemVer

PgDog follows SemVer, and for each tagged release, a corresponding tag will be available in the Docker repository. For example, you can run v0.1.44 like so:

docker run ghcr.io/pgdogdev/pgdog:v0.1.44

AWS ECS

New feature

The ECS Terraform module is a new project. Please report any issues you may encounter. Community contributions are welcome.

We recently added a Terraform module to deploy PgDog on AWS ECS. It works with the same Docker image as our Helm chart, so the experience should be familiar.

Pre-built binaries

Each PgDog release (every week, on Thursday) contains pre-built binaries for Linux (arm64, amd64), Mac (aarch64, i.e. Apple Silicon), and Debian packages (.deb) for convenient installation on Debian/Ubuntu.

You can download all binaries from the releases page in GitHub.

Linux binaries and glibc

The Linux binaries are built on Ubuntu 24.04 and are linked against glibc version 2.39. To run them, your system needs glibc 2.39 or later.

Mac OS security

The Mac OS binary is not signed. To run it locally, make sure to de-quarantine it first, e.g.:

xattr -d com.apple.quarantine ./pgdog

From source

PgDog can be easily compiled from source. For production deployments, a Dockerfile is provided in our code repository. If you prefer to deploy on bare-metal or you are looking to run PgDog locally, you will need to install a few dependencies.

Dependencies

Parts of PgDog depend on C/C++ libraries, which are compiled from source. Make sure to have a working version of a C/C++ compiler installed before building from source:

macOSUbuntuArchWindows

Install Xcode from the App Store and CMake & Clang from Homebrew:

brew install cmake llvm

Install Clang and CMake:

sudo apt update && \
sudo apt install -y cmake clang curl pkg-config libssl-dev git build-essential mold

Install Clang and CMake:

sudo pacman -Syu base-devel clang cmake git mold

Install Visual Studio Community Edition. Make sure to include CMake in the installation.

Rust compiler

PgDog is written in Rust and uses the latest stable features of the language. Make sure to install the newest version of the toolchain from rust-lang.org.

Compile PgDog

Clone the code from our GitHub repository:

git clone https://github.com/pgdogdev/pgdog && \
cd pgdog

To make sure you get all performance benefits, PgDog should be compiled in release mode with all optimizations:

cargo build --release

Launch PgDog

You can start PgDog by running the binary directly, which is located in target/release/pgdog, or by running it with Cargo:

cargo run --release

Configuration

PgDog is configured via two files:

Configuration file	Description
pgdog.toml	General settings and information about PostgreSQL servers.
users.toml	Usernames and passwords that are allowed to connect to PgDog.

Users are configured separately, which allows them to be encrypted at rest in environments that support it, like in Kubernetes or with the AWS Secrets Manager.

If the configuration files are placed in the current working directory ($PWD), PgDog will detect them automatically. Alternatively, you can pass their paths at startup as arguments:

pgdog \
    --config /path/to/pgdog.toml \
    --users /path/to/users.toml

pgdog.toml

Most configuration options have sensible defaults. This makes single-database configuration pretty short:

pgdog.tomlHelm chart

[[databases]]
name = "postgres"
host = "127.0.0.1"

databases:
  - name: postgres
    host: 127.0.0.1

users.toml

This config file contains a mapping between databases, users, and passwords. Unless you configured passthrough authentication, users not specified in this file will not be able to connect:

users.tomlHelm chart

[[users]]
name = "alice"
database = "postgres"
password = "hunter2"

users:
  - name: alice
    database: postgres
    password: hunter2

Configuring users

PgDog creates connection pools for each user/database pair. If no users are configured in users.toml, all connection pools will be disabled and PgDog won't connect to the database(s).

Next steps

Features

Read more about PgDog features like load balancing, supported authentication mechanisms, TLS, health checks, and more.

Administration

Learn how to operate PgDog in production, like fetching real-time statistics from the admin database or updating configuration.

Architecture

Read about PgDog internals and how it works under the hood.

Configuration

Reference for PgDog configuration like maximum server connections, number of shards, and more.