@mariiodegen/seed-db 0.0.1 → 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 +262 -0
- package/dist/bin.d.ts +2 -0
- package/dist/cli.d.ts +3 -0
- package/dist/cli.js +11918 -0
- package/dist/commands/init.d.ts +7 -0
- package/dist/commands/inspect.d.ts +4 -0
- package/dist/commands/run.d.ts +3 -0
- package/dist/config/define.d.ts +15 -0
- package/dist/config/index.d.ts +4 -0
- package/dist/config/load.d.ts +5 -0
- package/dist/config/merge.d.ts +15 -0
- package/dist/config/types.d.ts +45 -0
- package/dist/config/validate.d.ts +2 -0
- package/dist/errors.d.ts +17 -0
- package/dist/execute/batch.d.ts +12 -0
- package/dist/execute/dry-run.d.ts +15 -0
- package/dist/execute/file-mode.d.ts +18 -0
- package/dist/execute/format.d.ts +2 -0
- package/dist/execute/guard.d.ts +16 -0
- package/dist/execute/live.d.ts +18 -0
- package/dist/execute/sql-format.d.ts +31 -0
- package/dist/execute/types.d.ts +18 -0
- package/dist/generate/generate.d.ts +17 -0
- package/dist/generate/semantic.d.ts +13 -0
- package/dist/generate/types-map.d.ts +10 -0
- package/dist/generate/types.d.ts +42 -0
- package/dist/graph/cycles.d.ts +9 -0
- package/dist/graph/order.d.ts +17 -0
- package/dist/graph/types.d.ts +10 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +11922 -0
- package/dist/introspect/assemble.d.ts +2 -0
- package/dist/introspect/index.d.ts +4 -0
- package/dist/introspect/introspect.d.ts +7 -0
- package/dist/introspect/queries.d.ts +5 -0
- package/dist/introspect/types.d.ts +60 -0
- package/dist/main.d.ts +1 -0
- package/dist/types.d.ts +26 -0
- package/package.json +64 -7
package/README.md
ADDED
|
@@ -0,0 +1,262 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="./assets/wordmark.svg" alt="seed-db logo" width="320" />
|
|
3
|
+
</p>
|
|
4
|
+
|
|
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
package/dist/cli.d.ts
ADDED