@pgpm/faker

create fake data in PostgreSQL

Overview

@pgpm/faker provides a comprehensive set of fake data generation functions directly in PostgreSQL. Perfect for seeding test databases, creating demo data, and development environments. All functions are implemented in pure plpgsql and return realistic-looking data without external dependencies.

Features

• Geographic Data: Latitude/longitude coordinates, addresses by state
• Text Generation: Sentences, paragraphs, tags, names
• Temporal Data: Random timestamps, dates, intervals
• Numeric Data: Random integers and floats
• Contact Information: Email, phone, IP addresses
• File & Media: URLs, images, profile pictures, attachments
• Business Data: Company names, usernames, tokens
• State-Aware: Filter data by US state codes
• Pure plpgsql: No external dependencies required

Installation

If you have pgpm installed:

pgpm install @pgpm/faker
pgpm deploy

This is a quick way to get started. The sections below provide more detailed installation options.

Prerequisites

# Install pgpm CLI 
npm install -g pgpm

# Start local Postgres (via Docker) and export env vars
pgpm docker start
eval "$(pgpm env)"

Tip: Already running Postgres? Skip the Docker step and just export your PG* environment variables.

Add to an Existing Package

# 1. Install the package
pgpm install @pgpm/faker

# 2. Deploy locally
pgpm deploy 

Add to a New Project

# 1. Create a workspace
pgpm init workspace

# 2. Create your first module
cd my-workspace
pgpm init

# 3. Install a package
cd packages/my-module
pgpm install @pgpm/faker

# 4. Deploy everything
pgpm deploy --createdb --database mydb1

Usage

state, city, zip

select faker.state();
-- CA

select faker.city();
-- Belle Haven

select faker.city('MI');
-- Livonia

select faker.zip();
-- 48105

select faker.zip('Los Angeles');
-- 90272

address, street

select faker.address();
-- 762 MESA ST         
-- Fort Mohave, AZ 86427

select faker.address('MI');
-- 2316 LAPHAM WAY           
-- Sterling Heights, MI 48312

select faker.street();
-- CLAY ST

tags

Tags can be seeded in faker.dictionary table, here's an example with sustainability

select faker.tags();
-- {"causes of global warming","electronic waste","solar powered cars"}

words

select faker.word();
-- woodpecker

Specify word types

select faker.word(ARRAY['adjectives']);
-- decisive

paragraphs

select faker.paragraph();
-- Ligula. Aliquet torquent consequat egestas dui. Nullam sed tincidunt mauris porttitor ad taciti rutrum eleifend. Phasellus.

email

select faker.email();
-- crimson79@hotmail.com

uuid

select faker.uuid();
-- 327cb21d-1680-47ee-9979-3689e1bcb9ab

tokens, passwords

select faker.token();
-- 9e23040a7825529beb1528c957eac73f

select faker.token(20);
-- 7504ef4eafbba04a9645198b10ebc9616afce13a

select faker.password();
-- d8f1cca306e4d7^15bb(62618c1e

hostname

select faker.hostname();
-- fine.net

time unit

select faker.time_unit();
-- hour

float

select faker.float();
-- 64.6970694223782

select faker.float(2.3,10.5);
-- 10.233102884792025

integer

select faker.integer();
-- 8

select faker.integer(2,10);
-- 7

date

select faker.date();
-- 2020-10-02

Date 1-3 days ago

select faker.date(1,3);
-- 2020-12-02

Date in the future between 1-3 days

select faker.date(1,3, true);
-- 2020-12-06

birthdate

select faker.birthdate();
-- 2007-02-24

Generate birthdate for somebody who is between age of 37 and 64

select faker.birthdate(37, 64);
-- 1972-08-10

interval

select faker.interval();
-- 00:01:34.959831

Generate an interval between 2 and 300 seconds

select faker.interval(2,300);
-- 00:01:04

gender

select faker.gender();
-- F

select faker.gender();
-- M

boolean

select faker.boolean();
-- TRUE

timestamptz

select faker.timestamptz();
-- 2019-12-20 15:57:29.520365+00

Future timestamptz

select faker.timestamptz(TRUE);
-- 2020-12-03 23:00:10.013301+00
-- 

mime types

select faker.mime();
-- text/x-scss

file extensions

select faker.ext();
-- html

Specify a mimetype

select faker.ext('image/png');
-- png

Image mimetypes

select faker.image_mime();
-- image/gif

image

select faker.image();
-- {"url": "https://picsum.photos/843/874", "mime": "image/gif"}

profilepic

credit: thank you https://randomuser.me

select faker.profilepic();
-- {"url": "https://randomuser.me/api/portraits/women/53.jpg", "mime": "image/jpeg"}

Specify a gender

select faker.profilepic('M');
-- {"url": "https://randomuser.me/api/portraits/men/4.jpg", "mime": "image/jpeg"}

file

select faker.file();
-- scarlet.jpg

Specify a mimetype

select faker.file('image/png');
-- anaconda.png

url

select faker.url();
-- https://australian.io/copper.gzip

upload

select faker.upload();
-- https://magenta.co/moccasin.yaml

attachment

select faker.attachment();
--  {"url": "https://silver.io/sapphire.jsx", "mime": "text/jsx"}

phone

select faker.phone();
-- +1 (121) 617-3329

ip

select faker.ip();
-- 42.122.9.119

username

select faker.username();
-- amaranth28

name

select faker.name();
-- Lindsay

Specify a gender

select faker.name('M');
-- Stuart

select faker.name('F');
-- Shelly

surname

select faker.surname();
-- Smith

fullname

select faker.fullname();
-- Ross Silva

select faker.fullname('M');
-- George Spencer

business

select faker.business();
-- Seed Partners, Co.

longitude / latitude coordinates

select faker.lnglat( -118.561721, 33.59, -117.646374, 34.23302 );
-- (-118.33162189532844,34.15614699957491)

select faker.lnglat();
-- (-74.0205,40.316)

Use Cases

Seeding Test Databases

Generate realistic test data for development:

-- Create test users with fake data
INSERT INTO users (name, email, created_at)
SELECT 
  faker.fullname(),
  faker.email(),
  faker.timestamptz()
FROM generate_series(1, 100);

Geographic Testing

Test location-based features:

-- Create test locations with coordinates
INSERT INTO locations (lat, lng, address)
SELECT 
  (faker.lnglat()).lat,
  (faker.lnglat()).lng,
  faker.address()
FROM generate_series(1, 50);

Content Generation

Generate fake content for testing:

-- Create blog posts
INSERT INTO posts (title, content, tags, published_at)
SELECT 
  faker.word() || ' ' || faker.word(),
  faker.paragraph(),
  faker.tags(),
  faker.timestamptz()
FROM generate_series(1, 100);

Demo Data

Create realistic demo data for presentations:

-- E-commerce orders
INSERT INTO orders (customer_name, phone, total, order_date)
SELECT 
  faker.fullname(),
  faker.phone(),
  faker.float(10, 1000),
  faker.date()
FROM generate_series(1, 1000);

Testing

pnpm test

Dependencies

None - this is a pure plpgsql implementation.

Related Tooling

• pgpm: 🖥️ PostgreSQL Package Manager for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
• pgsql-test: 📊 Isolated testing environments with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
• supabase-test: 🧪 Supabase-native test harness preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
• graphile-test: 🔐 Authentication mocking for Graphile-focused test helpers and emulating row-level security contexts.
• pgsql-parser: 🔄 SQL conversion engine that interprets and converts PostgreSQL syntax.
• libpg-query-node: 🌉 Node.js bindings for libpg_query, converting SQL into parse trees.
• pg-proto-parser: 📦 Protobuf parser for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.

Disclaimer

AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.

No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.