faker-pg

faker-pg

A terminal UI for anonymizing sensitive data in PostgreSQL databases. Connect to a Postgres database, map columns to realistic gofakeit generators, then let faker-pg rewrite matching rows in place. An optional LLM (OpenAI-compatible) can auto-suggest mappings based on column names and types.

faker-pg -- PostgreSQL Fake Data Anonymizer
  Status: Done! Updated 84,312 rows across 7 tables.

  ┌─ Column ──────────────────────────────────────┬── Type ────────────────┬── Faker Function ──────────────────┐
  │ public.users.email                            │ character varying      │ Email                              │
  │ public.users.full_name                        │ character varying      │ Name                               │
  │ public.users.phone                            │ character varying      │ PhoneFormatted                     │
  │ public.orders.shipping_address                │ text                   │ Street                             │
  └───────────────────────────────────────────────┴────────────────────────┴────────────────────────────────────┘

Features

• Interactive TUI — navigate with keyboard; no config files required
• Schema discovery — reads tables, columns, primary keys, and foreign keys from information_schema
• Column filtering — include/exclude schemas or tables by name
• 600+ fake generators — every gofakeit function, searchable by name or category
• Type-aware picker — shows only generators whose output type is compatible with the target column
• Parameterised functions — pass arguments to generators (e.g. numerify format strings)
• Regex selectors — map a single rule to multiple columns via a pattern
• Constraint safeguards — key columns, generated columns, and unsupported types are excluded to preserve integrity
• Batched parallel execution — update rows in bounded batches and process independent tables concurrently
• LLM auto-select — uses any OpenAI-compatible model to suggest mappings for sensitive columns
• Persistent cache — mappings are saved to ~/.faker-pg/fake-data-mapping.yml and restored on next run
• Remote host guard — confirms before touching a non-localhost database

Requirements

• Go 1.27.1+
• PostgreSQL 12+ (accessed over TCP; unix sockets are not tested)
• (Optional) Docker — for the task dev:db:* helpers
• (Optional) An OpenAI-compatible API key — for LLM auto-select

Installation

Pre-built binaries

Download the latest release for your platform from the Releases page. Pre-built binaries are available for Linux, macOS, and Windows (amd64, arm64).

go install

go install github.com/ralscha/faker-pg/cmd/faker-pg@latest

Build from source

git clone https://github.com/ralscha/faker-pg
cd faker-pg
go build -o faker-pg ./cmd/faker-pg

Quick start

# Launch the TUI — fill in connection details interactively
faker-pg

# Pre-fill the DSN from the command line
faker-pg --dsn "postgres://user:pass@localhost:5432/mydb?sslmode=disable"

# Supply reusable rules from the command line (the flag is repeatable)
faker-pg \
  --dsn "postgres://user:pass@localhost:5432/mydb?sslmode=disable" \
  --fake-data "email=email" \
  --fake-data 'public\..*\.phone=phonenumber'

# Pre-fill the DSN and configure the LLM for auto-select
faker-pg \
  --dsn "postgres://user:pass@localhost:5432/mydb?sslmode=disable" \
  --llm-model "gpt-4o-mini" \
  --llm-api-key-env OPENAI_API_KEY

Demo database

Spin up a local Postgres container with the demo schema:

task demo:setup
# Connection DSN: postgres://postgres:postgres@localhost:5432/devdb?sslmode=disable

Tear it down when done:

task dev:db:down

TUI walkthrough

1 — Connection form

Fill in the PostgreSQL connection details and optional LLM configuration, then choose an action:

Schema filters (comma-separated):

2 — Fake-data editor

A table listing every copyable column and its currently assigned faker function.

3 — Function picker

Type to filter the 600+ available gofakeit functions. Only functions whose output type is compatible with the selected column's data type are shown.

If the selected function accepts parameters, a parameter entry screen is shown next. Enter multiple values in the displayed order, separated by ;.

4 — Run

Press ^A from the connection form to start. faker-pg will:

1. Parse the fake-data rules
2. Connect to PostgreSQL and load the current schema
3. For each table that has at least one mapped column, replace values in transactional database batches
4. Process up to --workers tables concurrently
5. Report the total rows and tables updated

A confirmation screen is shown before touching any non-localhost host.

CLI flags

Fake-data selectors

Rules are matched from most to least specific:

Selectors are case-insensitive. Quoted identifiers ("MyTable") are normalised to lower-case. Use --fake-data to configure generic and regex selectors; rules selected in the editor are stored as exact selectors.

Function parameters

Append parameters with ; separators:

numerify;###-###-####

LLM auto-select

When a model and API key are configured, pressing A in the fake-data editor sends column names and types to the model and applies its suggestions.

Any OpenAI-compatible endpoint works (Ollama, Azure OpenAI, LiteLLM, etc.) via --llm-base-url.

Cache

Mappings are persisted to ~/.faker-pg/fake-data-mapping.yml keyed by host:port/database. On the next run against the same database, the editor is pre-populated with your previous choices and ^A can start from cached rules. Existing host/database cache entries remain readable.

Development

# Run tests
task test

# Run tests with coverage report
task test:cover

# Format code
task format

# Run linter
task lint

# Build binary
task build

# Run directly (supports DSN, LLM_MODEL, LLM_KEY_ENV variables)
task run DSN="postgres://postgres:postgres@localhost:5432/devdb?sslmode=disable"

License

MIT