DEV Community: Hamza Mansoor

Seed a PostgreSQL database with realistic, connected fake data in one command

Hamza Mansoor — Tue, 28 Jul 2026 09:41:56 +0000

Every time I start or test a project, I hit the same wall: the app works, but the database is empty. No customers, no orders, nothing to click through. So I write a seed script. Then a slightly different one on the next project. And the one after that.

Faker solves half of it — it gives you names and emails. The annoying half is keeping the data consistent: an order has to reference a customer that actually exists, a unique column has to stay unique, an enum can only hold its allowed values. Get that wrong and your app breaks on its own fake data.

So I built fauxdata and open-sourced it. Point it at a PostgreSQL database and it fills every table with realistic data in one command:

npx fauxdata --dsn postgres://localhost/mydb

No config. It reads your existing schema and figures out the rest.

Try it in two minutes

Spin up a throwaway Postgres:

docker run -d --name shop -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:16

Give it a schema with the tricky bits — a foreign key, a unique column, and an enum:

CREATE TYPE order_status AS ENUM ('pending', 'paid', 'shipped', 'cancelled');

CREATE TABLE customers (
  id         serial PRIMARY KEY,
  email      varchar(255) NOT NULL UNIQUE,
  full_name  text NOT NULL
);

CREATE TABLE orders (
  id           serial PRIMARY KEY,
  customer_id  integer NOT NULL REFERENCES customers (id),
  status       order_status NOT NULL,
  total        numeric(10, 2) NOT NULL
);

Seed it:

npx fauxdata --dsn postgres://postgres:postgres@localhost:5432/postgres --rows 20
# fauxdata: inserted 40 rows across 2 tables.

Now the data actually joins:

select c.full_name, o.total, o.status
from orders o
join customers c on c.id = o.customer_id
limit 3;

   full_name    |  total  |  status
----------------+---------+----------
 Andrea Gerlach | 7891.93 | shipped
 Pauline Larkin | 5868.83 | paid
 Leonard Rempel | 2210.50 | pending

Every customer_id points to a real customer. Every status is a valid enum. Every email is unique.

What it handles

Referential integrity — it reads your foreign keys and inserts parents before children, so references always resolve.
The awkward cases — self-referencing tables (an employee whose manager is another employee) and circular references between tables, handled with a two-pass insert.
Constraints — NOT NULL, unique columns, enums, and composite primary keys.
Reproducibility — pass --seed 42 and you get byte-identical data every run, which makes it reliable in CI and shareable across a team.
Insert or inspect — write straight to the database, or emit a SQL file you can review first:

npx fauxdata --dsn postgres://localhost/mydb --output seed.sql

How it works

Under the hood it's TypeScript on Node, and the pipeline is small on purpose:

Introspect — read tables, columns, types, keys, uniques, foreign keys, and enums straight from information_schema / pg_catalog.
Order — build a dependency graph from the foreign keys and topologically sort it, deferring the minimum set of edges needed to break cycles and self-references.
Generate — pick a value per column: a config override if you gave one, then a column-name heuristic (email, *_at, price…), then a fallback by SQL type. Uniqueness and enums are enforced as it goes.
Resolve & write — fill foreign keys from already-inserted parent rows, then insert in one transaction (or write the SQL file).

node-postgres does the talking; Faker provides the values.

Why PostgreSQL first

Because I'd rather do one database really well than five halfway. Postgres is where most of us start, so it's where fauxdata starts. MySQL and SQLite are the next targets — and since the generator works on an abstract schema model, adding them is mostly a new reader, not a rewrite.

Try it / break it

It's MIT-licensed, needs no account, and installs with npx.

npm: https://www.npmjs.com/package/fauxdata
GitHub: https://github.com/hamzamansoorch/fauxdata

If you run it against a real-world schema, I'd like to know what breaks — odd types, exotic constraints, anything. Issues and PRs welcome.

I built an offline, no-AI tool that turns your terminal history into runbooks

Hamza Mansoor — Sat, 11 Jul 2026 11:09:07 +0000

Every team has that one deploy only a single person really knows how to run. The steps live in their head, and the doc that's supposed to explain it is three commands out of date.

I got tired of that, so I built runscribe: you record a terminal session the way you'd normally work, and it turns what you did into a clean, re-runnable runbook. No screen recording, no wiki page that rots, and — deliberately — no AI.

🔒 100% local. No account, no network, no telemetry. Nothing is uploaded, ever.
🤖 No AI. The runbook is produced deterministically from what actually ran. Same session in, same runbook out.
📝 Plain Markdown or HTML out. Hand-editable, diff-able, readable without runscribe installed.
▶️ It re-runs. The runbook isn't just text — hand it back and step through it later.

The loop

1. Record — run your commands as normal. # adds a note, ## starts a section.

$ runscribe record
* recording - commands run for real; # note, ## section, exit to finish
runscribe:api$ ## Deploy the API
runscribe:api$ # bump the release tag first
runscribe:api$ git tag v2.3.0
runscribe:api$ export DEPLOY_TOKEN=ghp_R2d9nQx7b4Kp...A1
runscribe:api$ ./deploy.sh production
runscribe:api$ exit
recorded 3 commands -> .runscribe/sessions/20260710.jsonl

2. Build — turn the session into a runbook, with secrets scrubbed automatically.

$ runscribe build --last -o deploy.md
done 3 commands (1 redacted) -> deploy.md

You get clean Markdown: sections become headings, notes become prose, and each command is a fenced block tagged with a marker so it can be replayed later. That DEPLOY_TOKEN shows up as <REDACTED>.

3. Run — replay the runbook step by step, later or on another machine.

$ runscribe run deploy.md
running 2 step(s) from deploy.md
value for {{ENV}}: production
## Deploy the API
$ git tag v2.3.0
  run this step? [Y]es / [s]kip / [q]uit: y
$ ./deploy.sh production
  run this step? [Y]es / [s]kip / [q]uit: y
done  ran 2, skipped 0, failed 0

Every command is shown before it runs, {{PLACEHOLDER}} tokens get filled in (prompted, or via --set NAME=value), and a failing step halts the run unless you pass --keep-going.

Export to HTML if you'd rather share a page than a Markdown file:

runscribe build --last --format html -o deploy.html

A single self-contained file, styles inlined, everything HTML-escaped.

A few things under the hood

Deterministic redaction. A regex ruleset scrubs common tokens, keys, and credentials, and you can extend it with a .runscribe/redact.toml (extra patterns and literal strings). No ML, no guessing.
State that persists. On POSIX, recording drives a single long-lived shell via a sentinel technique, so cd, export, and shell variables carry across steps just like a real session. There's an opt-in --pty mode for colored output and simple TUIs.
No INTERNET anywhere. There's no networking code in the project. That's the point — your shell history never leaves the machine.
Ships as a binary too. PyInstaller builds a one-file executable for Linux, macOS, and Windows, so a teammate without Python can still use it.

Why no AI?

Plenty of tools will "write your docs" now, but they do it by shipping your shell activity off to a model. If you've ever hesitated before pasting internal commands into a chatbot, that hesitation is the whole reason runscribe exists. A runbook is deterministic by nature: it should come out the same every time, and it should never require trusting a third party with what you typed.

Try it

pip install runscribe

PyPI: https://pypi.org/project/runscribe/
Code + demo: https://github.com/hamzamansoorch/runscribe
License: MIT

It's open source and still early. If you write runbooks (or avoid writing them), I'd genuinely love feedback — and if you try it and something feels rough, open an issue. That's the most useful thing right now.

I built envcontract: give your .env file a contract (and stop leaking secrets)

Hamza Mansoor — Thu, 02 Jul 2026 11:32:45 +0000

Every project I've worked on relies on a .env file — database URLs, ports, API keys. And every team hits the same three problems with it:

Config drift. A teammate adds a variable and forgets to mention it. Everyone else's app breaks with a cryptic error. "Works on my machine."
Silent misconfiguration. Someone writes PORT=eighty instead of 8080, and it surfaces as a confusing crash hours later.
Leaked secrets. Someone commits a real .env and exposes live credentials on GitHub — one of the most common and costly security mistakes in software.

The .env file runs our apps, but it has no validation, no documentation, and no safety net. So I built a small tool to give it one.

The idea: a contract for your .env

envcontract introduces one committed file — .env.schema — that describes what your configuration should look like: which variables are required, their types, and rules. Crucially, it never contains the secret values themselves. That file is safe to commit and share with your whole team.

version: 1
variables:
  DATABASE_URL:
    type: url
    required: true
    secret: true
  PORT:
    type: int
    default: "3000"
    min: 1
    max: 65535
  STRIPE_KEY:
    type: string
    required: true
    secret: true
    pattern: "^sk_(test|live)_[A-Za-z0-9]+$"

Four commands

pip install envcontract

envcontract init — generates the schema from your existing .env, with every value stripped out and likely secrets auto-flagged.
envcontract check — validates any .env against the schema: missing keys, wrong types, failed patterns, out-of-range values. Exits non-zero, so it works in CI.
envcontract diff — shows when your local .env has drifted from the team's contract.
envcontract guard — a pre-commit hook that blocks you from committing real secret values before they ever reach your repo.

The design choices I care about

100% local. envcontract makes zero network calls and collects zero telemetry. There's an automated test that fails the build if any socket is ever opened. A tool that handles secrets should never send them anywhere — and this one literally can't.

Framework-agnostic. It reads plain .env files, so it works with Python, Node, Go, Ruby, PHP — anything.

Focused. It is not a secrets manager (like Vault or Doppler) and not a generic secret scanner (like gitleaks). It's the small "contract + validation" layer between them.

MIT licensed. Genuinely free — personal or commercial. Fork it, ship it, build on it.

Try it

If .env headaches sound familiar, give it a spin:

pip install envcontract
cd your-project
envcontract init
envcontract check

Code and docs: https://github.com/hamzamansoorch/envcontract
On PyPI: https://pypi.org/project/envcontract/

I'd love feedback — especially on the schema format and whether the guard heuristics match how your team handles secrets. And if it's useful, a star helps others find it.