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.3 like so:

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

From source

PgDog can be easily compiled from source. For production deployments, a Dockerfile is provided in GitHub. If you prefer to deploy on bare metal or you're looking to run PgDog locally, you'll 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.

Mac OSUbuntuArchWindows

Install XCode from the App Store and CMake & Clang from brew:

brew install cmake llvm

Install Clang and CMake:

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

Install Clang and CMake:

sudo pacman -Syu base-devel clang cmake git

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:

cargo build --release

Launch PgDog

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

cargo run --release

Configuration

PgDog is configured via 2 files:

Configuration file	Description
pgdog.toml	Contains general settings and info about PostgreSQL servers.
users.toml	Contains users and passwords that are allowed to connect to PgDog.

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

Both config files should be placed in the current working directory ($PWD) for PgDog to detect them. 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:

[[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 won't be able to connect:

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

Note

PgDog creates connection pools for each user/database pair. If no users are specified in users.toml, all connection pools will be disabled and connections to Postgres will not be created.

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.