@mariiodegen/seed-db 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,262 @@
1
- # Temporary Holding Version
1
+ <p align="center">
2
+ <img src="./assets/wordmark.svg" alt="seed-db logo" width="320" />
3
+ </p>
2
4
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
5
+ <p align="center">
6
+ <b>Deterministic, relationally consistent mock data generator for PostgreSQL.</b><br>
7
+ Built with Bun, TypeScript, and postgres.js.
8
+ </p>
9
+
10
+ ---
11
+
12
+ `seed-db` connects to any live PostgreSQL database, analyzes table relationships into a Directed Acyclic Graph (DAG), and fills your tables with realistic fake data in the correct dependency order—all wrapped in a safe, all-or-nothing transaction.
13
+
14
+ ---
15
+
16
+ ## 🚀 30-Second Quickstart
17
+
18
+ ```bash
19
+ # 1. Scaffold a starter configuration and .env file
20
+ bun run src/index.ts init
21
+
22
+ # 2. Inspect your schema to see the calculated insertion order and patch pass
23
+ bun run src/index.ts inspect
24
+
25
+ # 3. Seed your database with 25 rows per table using a repeatable seed
26
+ bun run src/index.ts run --rows 25 --seed 42
27
+ ```
28
+
29
+ ---
30
+
31
+ ## Key Features
32
+
33
+ - **Zero Configuration:** Reads constraints, foreign keys, and column types directly from PostgreSQL's live system catalogs (`information_schema` + `pg_catalog`).
34
+ - **Graph-Aware Ordering:** Uses Kahn's topological sort algorithm to insert parents before children, automatically deferring self-references (`employees.manager_id`) and breaking circular loops.
35
+ - **6-Tier Waterfall Resolution:** Strict priority ladder ensures database-generated columns and relational integrity always take precedence over text guessing (`Skip > Config > Foreign Key > Semantic Match > Type Mapping > Null Roll`).
36
+ - **Smart Semantic Matching:** Intelligently recognizes column names to generate realistic emails, full names, phone numbers, addresses, avatar URLs, and dummy password hashes.
37
+ - **Referential Integrity via Key Pools:** Automatically captures database-assigned primary keys (`RETURNING id`) into an in-memory `KeyPool`, guaranteeing child foreign keys always point to real rows.
38
+ - **All-or-Nothing Safety:** Everything executes inside a single transaction (`BEGIN ... COMMIT`). Any error triggers an immediate `ROLLBACK`, leaving your database clean.
39
+ - **100% Deterministic:** Running with the same `--seed` produces the exact same fake data and exact same row order every time.
40
+ - **Single-File Binary:** Compiles into a standalone executable (`bun build --compile`) that runs with zero dependencies on user machines.
41
+
42
+ ---
43
+
44
+ ## 💡 Core Concept: `--rows` vs `--seed`
45
+
46
+ It is common to confuse these two flags, but they control completely different things:
47
+
48
+ | Flag | Question it Answers | What it Controls | Example |
49
+ | :--- | :--- | :--- | :--- |
50
+ | **`--rows <number>`** | *"How much data do you want?"* | **Quantity / Volume** | `--rows 50` creates 50 users, 50 orders, 50 products. |
51
+ | **`--seed <number>`** | *"Which specific fake data do you want?"* | **Reproducibility** | `--seed 42` generates the *exact same* names, emails, and dates every time. |
52
+
53
+ ### Why `--seed` is a Superpower for Testing
54
+ Computers use Pseudo-Random Number Generators (PRNG). If you don't supply `--seed`, the generator uses the current computer clock time, generating completely different names and emails on every run.
55
+
56
+ When you specify `--seed 42`:
57
+ - **Run 1:** User #1 is `"Sarah Connor"`, email `"sarah@example.com"`.
58
+ - **Run 2 (Tomorrow):** User #1 is **still** `"Sarah Connor"`, email `"sarah@example.com"`.
59
+ - **Run 3 (On your colleague's laptop in another country):** User #1 is **still** `"Sarah Connor"`.
60
+
61
+ > [!TIP]
62
+ > **Use them together for automated tests:**
63
+ > `seed-db run --rows 50 --seed 42`
64
+ > *"Generate 50 rows per table, and make sure they are the exact same 50 records every time my test suite runs."*
65
+
66
+ ---
67
+
68
+ ## CLI Reference & Examples
69
+
70
+ ### Global Flags
71
+
72
+ These flags work across all subcommands:
73
+
74
+ ```bash
75
+ Options:
76
+ -c, --config <path> Path to seed.config.ts (default: "./seed.config.ts")
77
+ --database-url <url> PostgreSQL connection string (or via DATABASE_URL env var)
78
+ --schema <name> PostgreSQL schema name (default: "public")
79
+ --format <type> Output format: text | json (default: "text")
80
+ --json Shorthand for --format json
81
+ --verbose Show detailed execution and configuration logs
82
+ -h, --help Display help for command
83
+ ```
84
+
85
+ ---
86
+
87
+ ### Commands
88
+
89
+ #### 1. `seed-db init`
90
+ Creates a starter `seed.config.ts` and `.env.example` file in the current directory.
91
+
92
+ ```bash
93
+ # Create starter config files
94
+ seed-db init
95
+
96
+ # Force overwrite if files already exist
97
+ seed-db init --force
98
+ ```
99
+
100
+ #### 2. `seed-db inspect`
101
+ Examines your database, resolves dependencies, and prints the plan without writing any data.
102
+
103
+ ```bash
104
+ # Inspect your live database (reads connection from DATABASE_URL)
105
+ seed-db inspect
106
+
107
+ # Inspect a specific remote database URL
108
+ seed-db inspect --database-url postgres://user:pass@localhost:5433/mydb
109
+
110
+ # Export an offline schema snapshot (safe to share: zero passwords, zero row data)
111
+ seed-db inspect --json > schema.json
112
+
113
+ # Inspect an offline snapshot file without connecting to any database
114
+ seed-db inspect --snapshot schema.json
115
+ ```
116
+
117
+ **Example Output:**
118
+ ```text
119
+ Insert order:
120
+ 1 organizations
121
+ 2 users (org_id -> organizations.id)
122
+ 3 orders (user_id -> users.id)
123
+ 4 employees (manager_id deferred (self-reference))
124
+
125
+ Patch pass:
126
+ employees.manager_id (self-reference)
127
+
128
+ Schema "public" (4 tables):
129
+ table users (4 columns)
130
+ id integer | PK | NOT NULL | default | identity (always)
131
+ email varchar | unique | NOT NULL
132
+ org_id integer | NOT NULL | -> organizations.id
133
+ created_at timestamptz | NOT NULL | default
134
+ ```
135
+
136
+ #### 3. `seed-db run`
137
+ Generates and inserts relationally consistent mock data into your tables.
138
+
139
+ ```bash
140
+ # Seed all tables with default 10 rows
141
+ seed-db run
142
+
143
+ # Seed a custom row count (e.g. 100 rows per table)
144
+ seed-db run --rows 100
145
+
146
+ # Seed with a fixed random seed for reproducible test suites
147
+ seed-db run --seed 42
148
+
149
+ # Seed only specific tables (skipping unrelated tables)
150
+ seed-db run --tables users,orders
151
+
152
+ # Dry-run: view generated SQL statements in your terminal without executing
153
+ seed-db run --dry-run
154
+
155
+ # Safety check: execute inserts inside a transaction and rollback
156
+ # (Verifies all foreign keys and constraints pass without keeping data)
157
+ seed-db run --check
158
+
159
+ # Export as a standalone SQL script file instead of connecting to a live database
160
+ seed-db run --out seed.sql --snapshot schema.json
161
+
162
+ # Skip the production prompt when targeting non-localhost databases
163
+ seed-db run --yes
164
+ ```
165
+
166
+ ---
167
+
168
+ ## Configuration (`seed.config.ts`)
169
+
170
+ An optional TypeScript configuration file for custom business rules, fixed IDs, and test passwords:
171
+
172
+ ```ts
173
+ import type { SeedConfig } from "seed-db"; // Type-only import (erased at runtime)
174
+
175
+ export default {
176
+ defaultRows: 25,
177
+ seed: 42,
178
+ nullRate: 0.1, // 10% chance a nullable column becomes NULL
179
+
180
+ tables: {
181
+ // 1. Skip internal migration tables
182
+ _prisma_migrations: { ignore: true },
183
+
184
+ // 2. Custom rules for the users table
185
+ users: {
186
+ rows: 100, // Custom row count for this specific table
187
+ columns: {
188
+ // Constant value
189
+ role: "customer",
190
+
191
+ // Pre-computed bcrypt hash for "password123" (instant logins, zero CPU lag)
192
+ password_hash: "$2b$10$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW",
193
+
194
+ // Categorical distribution with custom weights
195
+ status: { oneOf: ["active", "pending", "suspended"], weights: [70, 20, 10] },
196
+
197
+ // Integer range
198
+ age: { int: { min: 18, max: 75 } },
199
+
200
+ // Dynamic custom generator function
201
+ member_code: ({ index, faker }) => `MEMBER-${index + 1}-${faker.string.alphanumeric(4).toUpperCase()}`,
202
+ },
203
+ },
204
+ },
205
+ } satisfies SeedConfig;
206
+ ```
207
+
208
+ ---
209
+
210
+ ## Architecture: "Thin Edges, Pure Core"
211
+
212
+ `seed-db` isolates database interactions to the edges of the pipeline:
213
+
214
+ ```mermaid
215
+ flowchart LR
216
+ A["1. Config\n(Flags, File, Env)"] --> B["2. Introspect\n(Reads DB / Snapshot)"]
217
+ B --> C["3. Order\n(Kahn's Sort DAG)"]
218
+ C --> D["4. Generate\n(Waterfall Rules)"]
219
+ D --> E["5. Execute\n(1 Transaction)"]
220
+
221
+ style A fill:#e9ecef,stroke:#495057
222
+ style B fill:#d8f3dc,stroke:#2d6a4f
223
+ style C fill:#d8f3dc,stroke:#2d6a4f
224
+ style D fill:#d8f3dc,stroke:#2d6a4f
225
+ style E fill:#cfe2ff,stroke:#084298
226
+ ```
227
+
228
+ - **Pure Core:** Stages 1, 3, and 4 are pure functions. They execute in-memory with zero network or filesystem dependencies, allowing unit tests to run in milliseconds.
229
+ - **Thin Edges:** Only Stage 2 (Introspect) and Stage 5 (Execute) touch PostgreSQL.
230
+
231
+ ### Parameter Math: Safe Dynamic Batching
232
+ PostgreSQL protocol binds query parameters using an unsigned 16-bit integer ($2^{16} - 1 = 65,535$). Passing more parameters in a single statement causes a query crash.
233
+
234
+ `seed-db` dynamically calculates batch sizes to maximize speed while guaranteeing safety:
235
+ $$\text{batchSize} = \min\left(1000, \left\lfloor \frac{65000}{\text{columnCount}} \right\rfloor\right)$$
236
+
237
+ - Table with 10 columns: $\min(1000, 6500) = 1,000\text{ rows/batch}$ ($10,000\text{ parameters}$).
238
+ - Table with 100 columns: $\min(1000, 650) = 650\text{ rows/batch}$ ($65,000\text{ parameters}$).
239
+
240
+ ---
241
+
242
+ ## Development & Testing
243
+
244
+ ```bash
245
+ # Install dependencies
246
+ bun install
247
+
248
+ # Run the complete test suite (46 tests across 8 suites)
249
+ bun test
250
+
251
+ # Run tests in watch mode
252
+ bun test --watch
253
+
254
+ # Compile standalone single binary
255
+ bun build --compile ./src/index.ts --outfile dist/seed-db
256
+ ```
257
+
258
+ ---
259
+
260
+ ## License
261
+
262
+ MIT
package/dist/bin.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
package/dist/cli.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ import { Command } from "commander";
2
+ export declare function isJsonRequested(argv: string[]): boolean;
3
+ export declare function createProgram(): Command;