Getting started

Install

You can use our install script to pull everything. Under the hood, this verifies you have the Rust toolchain, builds from source, and adds puffgres to your PATH.

curl -fsSL https://raw.githubusercontent.com/a24films/puffgres/main/install.sh | sh

Use with coding agents

The docs are published as one file at https://a24films.github.io/puffgres/AGENTS.md, and you can install it as a skill using one of the scripts below.

# Claude Code
mkdir -p ~/.claude/skills/puffgres && curl -fsSL https://a24films.github.io/puffgres/AGENTS.md -o ~/.claude/skills/puffgres/SKILL.md

# Codex
mkdir -p ~/.codex/skills/puffgres && curl -fsSL https://a24films.github.io/puffgres/AGENTS.md -o ~/.codex/skills/puffgres/SKILL.md

Setting Up a Project

Navigate to the root level of your repo and run puffgres init. This will generate a puffgres/ folder, complete with a Dockerfile and initial setup. It will also ask you to navigate to where your environment variables are; to start, you only need a TURBOPUFFER_API_KEY and DATABASE_URL. You'll need to enable logical replication on the database, but the setup wizard will also run you through this proces. There's many more knobs you can turn; see the advanced options section for further configurations.

The generated puffgres.toml is the main configuration file for your project. It controls both runtime behavior and environment variable loading. See the Advanced options section for a full reference.

Creating your first config

Run puffgres new to run through the config wizard. It should let you select a Postgres table, pick an embedding provider and what fields you want, and set the destination turbopuffer namespace.

This will generate a bunch of files, but they are effectively "staged". You are welcome to change the config or the transform (schema is autogenerated) to write arbitrary logic, use other packages, etc. In effect, these files are "staged". In order to "apply" them and actually get puffgres to listen to changes, run puffgres apply.

You can then see the run loop by using puffgres run.

Debugging

Before you apply a config, you may watn to test that a transform works with some sample data. If you run puffgres check --name it will give you sample output. If you've run database migrations on a Postgres table you are listening to, you will also need to run puffgres generate to regenerate the TS schema.

You can also run puffgres debug, which spins up a small service to look at the contents of a turbopuffer namespace, or to view the live progress of the WAL.