@realitydb/cli 2.0.1

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.
Files changed (4) hide show
  1. package/LICENSE +80 -0
  2. package/README.md +140 -0
  3. package/dist/index.js +36312 -0
  4. package/package.json +62 -0
package/LICENSE ADDED
@@ -0,0 +1,80 @@
1
+ Business Source License 1.1
2
+
3
+ Parameters
4
+
5
+ Licensor: Mpingo Systems Ltd (Eddy Mkwambe)
6
+ Licensed Work: RealityDB Sandbox
7
+ The Licensed Work is (c) 2026 Mpingo Systems Ltd
8
+ Additional Use Grant: You may make use of the Licensed Work, provided that
9
+ you do not use the Licensed Work for a Synthetic Data
10
+ Service, SQL Learning Service, or Database Simulation
11
+ Service.
12
+
13
+ A "Synthetic Data Service" is a commercial offering
14
+ that allows third parties to access the functionality
15
+ of the Licensed Work by generating synthetic database
16
+ records, test data, or simulation environments.
17
+
18
+ A "SQL Learning Service" is a commercial offering that
19
+ allows third parties to practice SQL queries against
20
+ auto-graded challenges using functionality substantially
21
+ derived from the Licensed Work.
22
+
23
+ A "Database Simulation Service" is a commercial offering
24
+ that allows third parties to create or access simulated
25
+ database environments with lifecycle-coherent data using
26
+ functionality substantially derived from the Licensed Work.
27
+
28
+ You may use the Licensed Work for internal testing,
29
+ development, education, research, and any non-competing
30
+ commercial purpose without restriction.
31
+
32
+ Change Date: March 31, 2030
33
+ Change License: Apache License, Version 2.0
34
+
35
+ For information about alternative licensing arrangements for the Licensed Work,
36
+ please contact: licensing@realitydb.dev
37
+
38
+ Notice
39
+
40
+ Business Source License 1.1 (the "License")
41
+
42
+ The Licensor hereby grants you the right to copy, modify, create derivative
43
+ works, redistribute, and make non-production use of the Licensed Work. The
44
+ Licensor may make an Additional Use Grant, above, permitting limited production
45
+ use.
46
+
47
+ Effective on the Change Date, or the fourth anniversary of the first publicly
48
+ available distribution of a specific version of the Licensed Work under this
49
+ License, whichever comes first, the Licensor hereby grants you rights under
50
+ the terms of the Change License, and the rights granted in the paragraph
51
+ above terminate.
52
+
53
+ If your use of the Licensed Work does not comply with the requirements
54
+ currently in effect as described in this License, you must purchase a
55
+ commercial license from the Licensor, its affiliated entities, or authorized
56
+ resellers, or you must refrain from using the Licensed Work.
57
+
58
+ All copies of the original and modified Licensed Work, and derivative works
59
+ of the Licensed Work, are subject to this License. This License applies
60
+ separately for each version of the Licensed Work and the Change Date may vary
61
+ for each version of the Licensed Work released by Licensor.
62
+
63
+ You must conspicuously display this License on each original or modified copy
64
+ of the Licensed Work. If you receive the Licensed Work in original or
65
+ modified form from a third party, the terms and conditions set forth in this
66
+ License apply to your use of that work.
67
+
68
+ Any use of the Licensed Work in violation of this License will automatically
69
+ terminate your rights under this License for the current and all other
70
+ versions of the Licensed Work.
71
+
72
+ This License does not grant you any right in any trademark or logo of
73
+ Licensor or its affiliates (provided that you may use a trademark or logo of
74
+ Licensor as expressly required by this License).
75
+
76
+ TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
77
+ AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
78
+ EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
79
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
80
+ TITLE.
package/README.md ADDED
@@ -0,0 +1,140 @@
1
+ # RealityDB
2
+
3
+ > Production-like data before production exists.
4
+
5
+ RealityDB populates your PostgreSQL database with realistic, schema-aware data. Point it at your schema, pick a domain template, and get thousands of rows that look like they came from a real application. Deterministic seeds mean the same command always produces the same data.
6
+
7
+ ## Quick Start
8
+
9
+ ```bash
10
+ npm install -g realitydb
11
+
12
+ realitydb scan # Inspect your schema
13
+ realitydb seed --template saas --seed 42 # Populate with realistic data
14
+ realitydb reset --confirm # Clear and start fresh
15
+ ```
16
+
17
+ ## Domain Templates
18
+
19
+ | Template | Description | Tables |
20
+ |----------|-------------|--------|
21
+ | `saas` | Subscription business | users, plans, subscriptions, payments |
22
+ | `ecommerce` | Online store | customers, products, orders, order_items |
23
+ | `education` | School system | teachers, classes, students, enrollments, grades, attendance |
24
+ | `fintech` | Financial services | accounts, transactions, fraud_alerts, settlements, chargebacks |
25
+ | `healthcare` | Medical system | patients, providers, encounters, diagnoses, billing |
26
+
27
+ ```bash
28
+ realitydb seed --template fintech --records 200 --seed 42
29
+ ```
30
+
31
+ Each template includes weighted distributions matching real-world data.
32
+
33
+ ## Key Features
34
+
35
+ ```bash
36
+ # Timeline generation -- data spanning months
37
+ realitydb seed --template saas --timeline 12-months --seed 42
38
+
39
+ # Scenario injection -- controlled anomalies
40
+ realitydb seed --template saas --scenario payment-failures --scenario-intensity high
41
+
42
+ # Environment reproduction -- capture and share
43
+ realitydb capture --name bug-4821
44
+ realitydb load bug-4821.realitydb-pack.json --confirm
45
+
46
+ # CI mode -- JSON output, proper exit codes
47
+ npx realitydb seed --ci --template saas --records 500 --seed 42
48
+ ```
49
+
50
+ ## Data Science Mode
51
+
52
+ Generate large-scale datasets for ML training, analytics testing, and data pipelines — no database required.
53
+
54
+ ```bash
55
+ # Generate 1M rows with default demo schema
56
+ realitydb generate --records 1000000 --format csv
57
+
58
+ # Generate from your SQL schema
59
+ realitydb generate --schema schema.sql --records 100000 --format parquet
60
+
61
+ # Generate from JSON schema with distribution controls
62
+ realitydb generate --schema custom.json --records 500000 --correlations --seed 42
63
+ ```
64
+
65
+ ### Statistical Distributions
66
+
67
+ Define per-column distributions in your JSON schema:
68
+
69
+ ```json
70
+ {
71
+ "tables": [{
72
+ "name": "users",
73
+ "columns": [
74
+ { "name": "age", "type": "integer", "distribution": { "type": "normal", "mean": 35, "stddev": 12, "min": 18, "max": 85 } },
75
+ { "name": "income", "type": "numeric", "distribution": { "type": "log-normal", "mu": 10.5, "sigma": 0.8, "min": 15000, "max": 500000 } },
76
+ { "name": "login_count", "type": "integer", "distribution": { "type": "zipf", "exponent": 1.2, "min": 1, "max": 1000 } }
77
+ ]
78
+ }],
79
+ "correlations": [
80
+ { "source": "age", "target": "income", "coefficient": 0.6 }
81
+ ]
82
+ }
83
+ ```
84
+
85
+ Supported distributions: `normal`, `uniform`, `zipf`, `exponential`, `log-normal`.
86
+
87
+ ### Output Formats
88
+
89
+ | Format | Flag | Description |
90
+ |--------|------|-------------|
91
+ | JSON | `--format json` | NDJSON (newline-delimited JSON), one object per line |
92
+ | CSV | `--format csv` | Standard CSV with headers |
93
+ | Parquet | `--format parquet` | NDJSON with `.parquet.ndjson` extension (convert via DuckDB/pyarrow) |
94
+
95
+ ## Commands
96
+
97
+ | Command | Description |
98
+ |---------|-------------|
99
+ | `realitydb scan` | Inspect database schema |
100
+ | `realitydb seed` | Generate and insert realistic data |
101
+ | `realitydb reset` | Clear seeded data |
102
+ | `realitydb export` | Export data to JSON/CSV/SQL files |
103
+ | `realitydb generate` | Generate large-scale datasets (no DB required) |
104
+ | `realitydb capture` | Snapshot live database into a Reality Pack |
105
+ | `realitydb load` | Load a Reality Pack into the database |
106
+ | `realitydb share` | Display Reality Pack info for sharing |
107
+ | `realitydb pack export` | Generate and export as Reality Pack |
108
+ | `realitydb pack import` | Import a Reality Pack |
109
+ | `realitydb templates` | List available domain templates |
110
+ | `realitydb scenarios` | List available scenarios |
111
+
112
+ ## Configuration
113
+
114
+ Create `realitydb.config.json`:
115
+
116
+ ```json
117
+ {
118
+ "database": {
119
+ "client": "postgres",
120
+ "connectionString": "postgres://user:pass@localhost:5432/mydb"
121
+ },
122
+ "seed": {
123
+ "defaultRecords": 1000,
124
+ "batchSize": 1000,
125
+ "randomSeed": 42
126
+ },
127
+ "template": "saas"
128
+ }
129
+ ```
130
+
131
+ ## Requirements
132
+
133
+ - Node.js 20+
134
+ - PostgreSQL
135
+
136
+ Full documentation: [github.com/emkwambe/databox](https://github.com/emkwambe/databox)
137
+
138
+ ## License
139
+
140
+ MIT