@constructive-io/cli 0.0.3 → 5.1.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.
- package/LICENSE +1 -1
- package/README.md +346 -153
- package/commands/{analyze.d.ts → codegen.d.ts} +2 -2
- package/commands/codegen.js +131 -0
- package/commands/explorer.js +94 -0
- package/commands/get-graphql-schema.js +73 -0
- package/commands/server.js +187 -0
- package/commands.d.ts +0 -1
- package/commands.js +42 -61
- package/esm/commands/codegen.js +126 -0
- package/esm/commands/explorer.js +92 -0
- package/esm/commands/get-graphql-schema.js +71 -0
- package/esm/commands/server.js +185 -0
- package/esm/commands.js +41 -59
- package/esm/index.js +16 -36
- package/esm/utils/display.js +26 -23
- package/esm/utils/index.js +3 -6
- package/index.d.ts +0 -22
- package/index.js +16 -72
- package/package.json +50 -25
- package/utils/display.d.ts +1 -1
- package/utils/display.js +26 -23
- package/utils/index.d.ts +3 -6
- package/utils/index.js +7 -20
- package/commands/add.d.ts +0 -7
- package/commands/add.js +0 -86
- package/commands/admin-users/add.d.ts +0 -4
- package/commands/admin-users/add.js +0 -89
- package/commands/admin-users/bootstrap.d.ts +0 -4
- package/commands/admin-users/bootstrap.js +0 -50
- package/commands/admin-users/remove.d.ts +0 -4
- package/commands/admin-users/remove.js +0 -82
- package/commands/admin-users.d.ts +0 -4
- package/commands/admin-users.js +0 -68
- package/commands/analyze.js +0 -21
- package/commands/clear.d.ts +0 -3
- package/commands/clear.js +0 -59
- package/commands/deploy.d.ts +0 -4
- package/commands/deploy.js +0 -146
- package/commands/docker.d.ts +0 -3
- package/commands/docker.js +0 -194
- package/commands/env.d.ts +0 -4
- package/commands/env.js +0 -124
- package/commands/export.js +0 -129
- package/commands/extension.js +0 -48
- package/commands/init/index.d.ts +0 -7
- package/commands/init/index.js +0 -47
- package/commands/init/module.d.ts +0 -4
- package/commands/init/module.js +0 -71
- package/commands/init/workspace.d.ts +0 -4
- package/commands/init/workspace.js +0 -52
- package/commands/install.d.ts +0 -4
- package/commands/install.js +0 -37
- package/commands/kill.js +0 -107
- package/commands/migrate/deps.d.ts +0 -4
- package/commands/migrate/deps.js +0 -186
- package/commands/migrate/init.d.ts +0 -4
- package/commands/migrate/init.js +0 -65
- package/commands/migrate/list.d.ts +0 -4
- package/commands/migrate/list.js +0 -85
- package/commands/migrate/status.d.ts +0 -4
- package/commands/migrate/status.js +0 -94
- package/commands/migrate.d.ts +0 -4
- package/commands/migrate.js +0 -69
- package/commands/package.d.ts +0 -3
- package/commands/package.js +0 -65
- package/commands/plan.d.ts +0 -3
- package/commands/plan.js +0 -62
- package/commands/remove.d.ts +0 -3
- package/commands/remove.js +0 -42
- package/commands/rename.d.ts +0 -4
- package/commands/rename.js +0 -35
- package/commands/revert.d.ts +0 -3
- package/commands/revert.js +0 -107
- package/commands/tag.d.ts +0 -6
- package/commands/tag.js +0 -168
- package/commands/verify.d.ts +0 -3
- package/commands/verify.js +0 -85
- package/dist/README.md +0 -412
- package/dist/package.json +0 -64
- package/esm/commands/add.js +0 -51
- package/esm/commands/admin-users/add.js +0 -87
- package/esm/commands/admin-users/bootstrap.js +0 -48
- package/esm/commands/admin-users/remove.js +0 -80
- package/esm/commands/admin-users.js +0 -63
- package/esm/commands/analyze.js +0 -16
- package/esm/commands/clear.js +0 -54
- package/esm/commands/deploy.js +0 -144
- package/esm/commands/docker.js +0 -192
- package/esm/commands/env.js +0 -122
- package/esm/commands/export.js +0 -127
- package/esm/commands/extension.js +0 -46
- package/esm/commands/init/index.js +0 -42
- package/esm/commands/init/module.js +0 -68
- package/esm/commands/init/workspace.js +0 -46
- package/esm/commands/install.js +0 -35
- package/esm/commands/kill.js +0 -105
- package/esm/commands/migrate/deps.js +0 -184
- package/esm/commands/migrate/init.js +0 -63
- package/esm/commands/migrate/list.js +0 -83
- package/esm/commands/migrate/status.js +0 -92
- package/esm/commands/migrate.js +0 -64
- package/esm/commands/package.js +0 -63
- package/esm/commands/plan.js +0 -60
- package/esm/commands/remove.js +0 -40
- package/esm/commands/rename.js +0 -30
- package/esm/commands/revert.js +0 -105
- package/esm/commands/tag.js +0 -133
- package/esm/commands/verify.js +0 -83
- package/esm/package.js +0 -26
- package/esm/utils/argv.js +0 -92
- package/esm/utils/cli-error.js +0 -48
- package/esm/utils/database.js +0 -78
- package/esm/utils/deployed-changes.js +0 -68
- package/esm/utils/module-utils.js +0 -51
- package/package.d.ts +0 -1
- package/package.js +0 -29
- package/utils/argv.d.ts +0 -46
- package/utils/argv.js +0 -100
- package/utils/cli-error.d.ts +0 -8
- package/utils/cli-error.js +0 -52
- package/utils/database.d.ts +0 -21
- package/utils/database.js +0 -83
- package/utils/deployed-changes.d.ts +0 -4
- package/utils/deployed-changes.js +0 -72
- package/utils/module-utils.d.ts +0 -8
- package/utils/module-utils.js +0 -54
- /package/commands/{export.d.ts → explorer.d.ts} +0 -0
- /package/commands/{extension.d.ts → get-graphql-schema.d.ts} +0 -0
- /package/commands/{kill.d.ts → server.d.ts} +0 -0
package/README.md
CHANGED
|
@@ -1,310 +1,383 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Constructive CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> Build secure, role-aware GraphQL backends powered by PostgreSQL with database-first development
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Constructive CLI is a comprehensive command-line tool that transforms your PostgreSQL database into a powerful GraphQL API. With automated schema generation, sophisticated migration management, and robust deployment capabilities, you can focus on building great applications instead of boilerplate code.
|
|
6
6
|
|
|
7
7
|
## ✨ Features
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
* 🌐 **Portable by Design** — Built on open standards and SQL-first workflows, your app runs anywhere—from the constructive cloud to your own infra.
|
|
15
|
-
* 🚀 **Optimized Developer Experience** — Type-safe SDKs, hot reloading for data and APIs, local-first dev, and zero boilerplate to get from idea → production fast.
|
|
9
|
+
- 🚀 **Database-First Development** - Design your database, get your GraphQL API automatically
|
|
10
|
+
- 🔐 **Built-in Security** - Role-based access control and security policies
|
|
11
|
+
- 📦 **Module System** - Reusable database modules with dependency management
|
|
12
|
+
- 🛠️ **Developer Experience** - Hot-reload development server with GraphiQL explorer
|
|
13
|
+
- 🏗️ **Production Ready** - Deployment plans, versioning, and rollback support
|
|
16
14
|
|
|
17
15
|
## 🚀 Quick Start
|
|
18
16
|
|
|
19
|
-
###
|
|
17
|
+
### Installation
|
|
20
18
|
|
|
21
19
|
```bash
|
|
22
|
-
# Install constructive globally
|
|
23
20
|
npm install -g @constructive-io/cli
|
|
24
|
-
|
|
25
|
-
# Start local Postgres (via Docker) and export env vars
|
|
26
|
-
constructive docker start
|
|
27
|
-
eval "$(constructive env)"
|
|
28
21
|
```
|
|
29
22
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
---
|
|
33
|
-
|
|
34
|
-
### Create a Workspace and Install a Package
|
|
23
|
+
### Create Your First Project
|
|
35
24
|
|
|
36
25
|
```bash
|
|
37
|
-
#
|
|
38
|
-
|
|
39
|
-
cd my-
|
|
26
|
+
# Initialize a new workspace
|
|
27
|
+
cnc init workspace
|
|
28
|
+
cd my-project
|
|
40
29
|
|
|
41
|
-
#
|
|
42
|
-
|
|
43
|
-
cd packages/your-module
|
|
30
|
+
# Create your first module
|
|
31
|
+
cnc init
|
|
44
32
|
|
|
45
|
-
#
|
|
46
|
-
|
|
33
|
+
# Deploy to your database
|
|
34
|
+
cnc deploy --createdb
|
|
47
35
|
|
|
48
|
-
#
|
|
49
|
-
|
|
50
|
-
psql -d mydb1 -c "SELECT faker.city('MI');"
|
|
51
|
-
> Ann Arbor
|
|
36
|
+
# Start the development server
|
|
37
|
+
cnc server
|
|
52
38
|
```
|
|
53
39
|
|
|
54
|
-
|
|
40
|
+
Visit `http://localhost:5555` to explore your GraphQL API!
|
|
55
41
|
|
|
56
|
-
|
|
42
|
+
## 📖 Core Concepts
|
|
57
43
|
|
|
58
|
-
|
|
59
|
-
- `constructive init --workspace` - Initialize a new workspace
|
|
44
|
+
### Workspaces and Modules
|
|
60
45
|
|
|
61
|
-
|
|
46
|
+
- **Workspace**: A collection of related database modules
|
|
47
|
+
- **Module**: A self-contained database package with migrations, functions, and types
|
|
48
|
+
- **Dependencies**: Modules can depend on other modules, creating reusable building blocks
|
|
62
49
|
|
|
63
|
-
|
|
64
|
-
- `constructive docker stop` - Stop PostgreSQL container
|
|
65
|
-
- `constructive env` - Print PostgreSQL environment variables for shell export
|
|
50
|
+
### Database-First Workflow
|
|
66
51
|
|
|
67
|
-
|
|
52
|
+
1. **Design** your database schema using SQL migrations
|
|
53
|
+
2. **Deploy** changes with `cnc deploy`
|
|
54
|
+
3. **Develop** against the auto-generated GraphQL API
|
|
55
|
+
4. **Version** and **package** your modules for distribution
|
|
68
56
|
|
|
69
|
-
|
|
70
|
-
- `constructive verify` - Verify database state matches expected migrations
|
|
71
|
-
- `constructive revert` - Safely revert database changes
|
|
72
|
-
|
|
73
|
-
### Migration Management
|
|
74
|
-
|
|
75
|
-
- `constructive migrate` - Comprehensive migration management
|
|
76
|
-
- `constructive migrate init` - Initialize migration tracking
|
|
77
|
-
- `constructive migrate status` - Check migration status
|
|
78
|
-
- `constructive migrate list` - List all changes
|
|
79
|
-
- `constructive migrate deps` - Show change dependencies
|
|
57
|
+
## 🛠️ Commands
|
|
80
58
|
|
|
81
|
-
###
|
|
59
|
+
### Getting Started
|
|
82
60
|
|
|
83
|
-
|
|
84
|
-
- `constructive extension` - Interactively manage module dependencies
|
|
85
|
-
- `constructive tag` - Version your changes with tags
|
|
61
|
+
#### `cnc init`
|
|
86
62
|
|
|
87
|
-
|
|
63
|
+
Initialize a new Constructive workspace or module.
|
|
88
64
|
|
|
89
|
-
|
|
90
|
-
|
|
65
|
+
```bash
|
|
66
|
+
# Create a new workspace
|
|
67
|
+
cnc init workspace
|
|
91
68
|
|
|
92
|
-
|
|
69
|
+
# Create a new module (run inside workspace)
|
|
70
|
+
cnc init
|
|
93
71
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
- `constructive clear` - Clear database state
|
|
98
|
-
- `constructive kill` - Clean up database connections
|
|
99
|
-
- `constructive analyze` - Analyze database structure
|
|
100
|
-
- `constructive rename` - Rename database changes
|
|
101
|
-
- `constructive admin-users` - Manage admin users
|
|
72
|
+
# Use templates from GitHub repository (defaults to constructive-io/pgpm-boilerplates.git)
|
|
73
|
+
cnc init workspace --repo owner/repo
|
|
74
|
+
cnc init --repo owner/repo --from-branch develop
|
|
102
75
|
|
|
103
|
-
|
|
76
|
+
# Use templates from custom paths
|
|
77
|
+
cnc init workspace --template-path ./custom-templates
|
|
78
|
+
cnc init --template-path ./custom-templates/module
|
|
79
|
+
```
|
|
104
80
|
|
|
105
|
-
|
|
81
|
+
**Options:**
|
|
106
82
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
cd my-app
|
|
83
|
+
- `--repo <repo>` - Template repo (default: `https://github.com/constructive-io/pgpm-boilerplates.git`)
|
|
84
|
+
- `--template-path <path>` - Template sub-path (defaults to `workspace`/`module`) or local path override
|
|
85
|
+
- `--from-branch <branch>` - Branch/tag when cloning the template repo
|
|
111
86
|
|
|
112
|
-
|
|
113
|
-
constructive init
|
|
114
|
-
cd packages/new-module
|
|
87
|
+
Templates are cached for one week under the `pgpm` tool namespace. Run `cnc cache clean` if you need to refresh the boilerplates.
|
|
115
88
|
|
|
116
|
-
|
|
117
|
-
constructive add some_change
|
|
89
|
+
### Development
|
|
118
90
|
|
|
119
|
-
|
|
120
|
-
constructive deploy --createdb
|
|
121
|
-
```
|
|
91
|
+
#### `cnc server`
|
|
122
92
|
|
|
123
|
-
|
|
93
|
+
Start the GraphQL development server with hot-reload.
|
|
124
94
|
|
|
125
95
|
```bash
|
|
126
|
-
#
|
|
127
|
-
|
|
96
|
+
# Start with defaults (port 5555)
|
|
97
|
+
cnc server
|
|
128
98
|
|
|
129
|
-
#
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
# 3. Deploy all installed modules
|
|
133
|
-
constructive deploy --createdb --database mydb1
|
|
134
|
-
psql -d mydb1 -c "SELECT faker.city('MI');"
|
|
135
|
-
> Ann Arbor
|
|
99
|
+
# Custom port and options
|
|
100
|
+
cnc server --port 8080 --no-postgis
|
|
136
101
|
```
|
|
137
102
|
|
|
138
|
-
|
|
103
|
+
#### `cnc explorer`
|
|
139
104
|
|
|
140
|
-
|
|
141
|
-
# 1. Install workspace dependencies
|
|
142
|
-
pnpm install
|
|
105
|
+
Launch GraphiQL explorer for your API.
|
|
143
106
|
|
|
144
|
-
|
|
145
|
-
|
|
107
|
+
```bash
|
|
108
|
+
# Launch explorer
|
|
109
|
+
cnc explorer
|
|
146
110
|
|
|
147
|
-
#
|
|
148
|
-
|
|
111
|
+
# With custom CORS origin
|
|
112
|
+
cnc explorer --origin http://localhost:3000
|
|
149
113
|
```
|
|
150
114
|
|
|
115
|
+
## 🔄 Updates
|
|
116
|
+
|
|
117
|
+
The CLI performs a lightweight npm version check at most once per week (skipped in CI or when `PGPM_SKIP_UPDATE_CHECK` is set). Use `cnc update` to install the latest release (installs `pgpm` by default; pass `--package @constructive-io/cli` to target the CLI package).
|
|
118
|
+
|
|
151
119
|
### Database Operations
|
|
152
120
|
|
|
153
|
-
#### `
|
|
121
|
+
#### `cnc deploy`
|
|
154
122
|
|
|
155
123
|
Deploy your database changes and migrations.
|
|
156
124
|
|
|
157
125
|
```bash
|
|
158
126
|
# Deploy to selected database
|
|
159
|
-
|
|
127
|
+
cnc deploy
|
|
160
128
|
|
|
161
129
|
# Create database if it doesn't exist
|
|
162
|
-
|
|
130
|
+
cnc deploy --createdb
|
|
163
131
|
|
|
164
132
|
# Deploy specific package to a tag
|
|
165
|
-
|
|
133
|
+
cnc deploy --package mypackage --to @v1.0.0
|
|
166
134
|
|
|
167
135
|
# Fast deployment without transactions
|
|
168
|
-
|
|
136
|
+
cnc deploy --fast --no-tx
|
|
169
137
|
```
|
|
170
138
|
|
|
171
|
-
#### `
|
|
139
|
+
#### `cnc verify`
|
|
172
140
|
|
|
173
141
|
Verify your database state matches expected migrations.
|
|
174
142
|
|
|
175
143
|
```bash
|
|
176
144
|
# Verify current state
|
|
177
|
-
|
|
145
|
+
cnc verify
|
|
178
146
|
|
|
179
147
|
# Verify specific package
|
|
180
|
-
|
|
148
|
+
cnc verify --package mypackage
|
|
181
149
|
```
|
|
182
150
|
|
|
183
|
-
#### `
|
|
151
|
+
#### `cnc revert`
|
|
184
152
|
|
|
185
153
|
Safely revert database changes.
|
|
186
154
|
|
|
187
155
|
```bash
|
|
188
156
|
# Revert latest changes
|
|
189
|
-
|
|
157
|
+
cnc revert
|
|
190
158
|
|
|
191
159
|
# Revert to specific tag
|
|
192
|
-
|
|
160
|
+
cnc revert --to @v1.0.0
|
|
193
161
|
```
|
|
194
162
|
|
|
195
163
|
### Migration Management
|
|
196
164
|
|
|
197
|
-
#### `
|
|
165
|
+
#### `cnc migrate`
|
|
198
166
|
|
|
199
167
|
Comprehensive migration management.
|
|
200
168
|
|
|
201
169
|
```bash
|
|
202
170
|
# Initialize migration tracking
|
|
203
|
-
|
|
171
|
+
cnc migrate init
|
|
204
172
|
|
|
205
173
|
# Check migration status
|
|
206
|
-
|
|
174
|
+
cnc migrate status
|
|
207
175
|
|
|
208
176
|
# List all changes
|
|
209
|
-
|
|
177
|
+
cnc migrate list
|
|
210
178
|
|
|
211
179
|
# Show change dependencies
|
|
212
|
-
|
|
180
|
+
cnc migrate deps
|
|
213
181
|
```
|
|
214
182
|
|
|
215
183
|
### Module Management
|
|
216
184
|
|
|
217
|
-
#### `
|
|
185
|
+
#### `cnc install`
|
|
218
186
|
|
|
219
|
-
Install
|
|
187
|
+
Install PGPM modules as dependencies.
|
|
220
188
|
|
|
221
189
|
```bash
|
|
222
190
|
# Install single package
|
|
223
|
-
|
|
191
|
+
cnc install @constructive-io/auth
|
|
224
192
|
|
|
225
193
|
# Install multiple packages
|
|
226
|
-
|
|
194
|
+
cnc install @constructive-io/auth @constructive-io/utils
|
|
227
195
|
```
|
|
228
196
|
|
|
229
|
-
#### `
|
|
197
|
+
#### `cnc extension`
|
|
230
198
|
|
|
231
199
|
Interactively manage module dependencies.
|
|
232
200
|
|
|
233
201
|
```bash
|
|
234
|
-
|
|
202
|
+
cnc extension
|
|
235
203
|
```
|
|
236
204
|
|
|
237
|
-
#### `
|
|
205
|
+
#### `cnc tag`
|
|
238
206
|
|
|
239
207
|
Version your changes with tags.
|
|
240
208
|
|
|
241
209
|
```bash
|
|
242
210
|
# Tag latest change
|
|
243
|
-
|
|
211
|
+
cnc tag v1.0.0
|
|
244
212
|
|
|
245
213
|
# Tag with comment
|
|
246
|
-
|
|
214
|
+
cnc tag v1.0.0 --comment "Initial release"
|
|
247
215
|
|
|
248
216
|
# Tag specific change
|
|
249
|
-
|
|
217
|
+
cnc tag v1.1.0 --package mypackage --changeName my-change
|
|
250
218
|
```
|
|
251
219
|
|
|
252
220
|
### Packaging and Distribution
|
|
253
221
|
|
|
254
|
-
#### `
|
|
222
|
+
#### `cnc plan`
|
|
255
223
|
|
|
256
224
|
Generate deployment plans for your modules.
|
|
257
225
|
|
|
258
226
|
```bash
|
|
259
|
-
|
|
227
|
+
cnc plan
|
|
260
228
|
```
|
|
261
229
|
|
|
262
|
-
#### `
|
|
230
|
+
#### `cnc package`
|
|
263
231
|
|
|
264
232
|
Package your module for distribution.
|
|
265
233
|
|
|
266
234
|
```bash
|
|
267
235
|
# Package with defaults
|
|
268
|
-
|
|
236
|
+
cnc package
|
|
269
237
|
|
|
270
238
|
# Package without deployment plan
|
|
271
|
-
|
|
239
|
+
cnc package --no-plan
|
|
272
240
|
```
|
|
273
241
|
|
|
274
242
|
### Utilities
|
|
275
243
|
|
|
276
|
-
#### `
|
|
244
|
+
#### `cnc export`
|
|
277
245
|
|
|
278
246
|
Export migrations from existing databases.
|
|
279
247
|
|
|
280
248
|
```bash
|
|
281
|
-
|
|
249
|
+
cnc export
|
|
282
250
|
```
|
|
283
251
|
|
|
284
|
-
#### `
|
|
252
|
+
#### `cnc kill`
|
|
285
253
|
|
|
286
254
|
Clean up database connections and optionally drop databases.
|
|
287
255
|
|
|
288
256
|
```bash
|
|
289
257
|
# Kill connections and drop databases
|
|
290
|
-
|
|
258
|
+
cnc kill
|
|
291
259
|
|
|
292
260
|
# Only kill connections
|
|
293
|
-
|
|
261
|
+
cnc kill --no-drop
|
|
294
262
|
```
|
|
295
263
|
|
|
296
|
-
##
|
|
264
|
+
## 💡 Common Workflows
|
|
297
265
|
|
|
298
|
-
###
|
|
266
|
+
### Starting a New Project
|
|
267
|
+
|
|
268
|
+
```bash
|
|
269
|
+
# 1. Create workspace
|
|
270
|
+
mkdir my-app && cd my-app
|
|
271
|
+
cnc init workspace
|
|
272
|
+
|
|
273
|
+
# 2. Create your first module
|
|
274
|
+
cnc init
|
|
275
|
+
|
|
276
|
+
# 3. Add some SQL migrations to sql/ directory
|
|
277
|
+
# 4. Deploy to database
|
|
278
|
+
cnc deploy --createdb
|
|
279
|
+
|
|
280
|
+
# 5. Start developing
|
|
281
|
+
cnc server
|
|
282
|
+
```
|
|
299
283
|
|
|
300
|
-
|
|
284
|
+
### Using Custom Templates
|
|
285
|
+
|
|
286
|
+
You can use custom templates from GitHub repositories or local paths:
|
|
301
287
|
|
|
302
|
-
**Quick setup** (recommended):
|
|
303
288
|
```bash
|
|
304
|
-
|
|
289
|
+
# Initialize workspace with templates from GitHub
|
|
290
|
+
cnc init workspace --repo owner/repo
|
|
291
|
+
|
|
292
|
+
# Initialize workspace with templates from local path
|
|
293
|
+
cnc init workspace --template-path ./my-custom-templates
|
|
294
|
+
|
|
295
|
+
# Initialize module with custom templates
|
|
296
|
+
cnc init --template-path ./my-custom-templates
|
|
297
|
+
|
|
298
|
+
# Use specific branch from GitHub repository
|
|
299
|
+
cnc init workspace --repo owner/repo --from-branch develop
|
|
305
300
|
```
|
|
306
301
|
|
|
307
|
-
**
|
|
302
|
+
**Template Structure:**
|
|
303
|
+
Custom templates should follow the same structure as the default templates:
|
|
304
|
+
|
|
305
|
+
- For workspace: `boilerplates/workspace/` directory
|
|
306
|
+
- For module: `boilerplates/module/` directory
|
|
307
|
+
- Or provide direct path to `workspace/` or `module/` directory
|
|
308
|
+
|
|
309
|
+
### Working with Existing Projects
|
|
310
|
+
|
|
311
|
+
```bash
|
|
312
|
+
# 1. Clone and enter project
|
|
313
|
+
git clone <repo> && cd <project>
|
|
314
|
+
|
|
315
|
+
# 2. Install dependencies
|
|
316
|
+
cnc install
|
|
317
|
+
|
|
318
|
+
# 3. Deploy to local database
|
|
319
|
+
cnc deploy --createdb
|
|
320
|
+
|
|
321
|
+
# 4. Start development server
|
|
322
|
+
cnc server
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
### Production Deployment
|
|
326
|
+
|
|
327
|
+
```bash
|
|
328
|
+
# 1. Create deployment plan
|
|
329
|
+
cnc plan
|
|
330
|
+
|
|
331
|
+
# 2. Package module
|
|
332
|
+
cnc package
|
|
333
|
+
|
|
334
|
+
# 3. Deploy to production
|
|
335
|
+
cnc deploy --package myapp --to @production
|
|
336
|
+
|
|
337
|
+
# 4. Verify deployment
|
|
338
|
+
cnc verify --package myapp
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
### Get Graphql Schema
|
|
342
|
+
|
|
343
|
+
Fetch and output your GraphQL schema in SDL.
|
|
344
|
+
|
|
345
|
+
- Option 1 – Programmatic builder (from database schemas):
|
|
346
|
+
- Write to file:
|
|
347
|
+
- `cnc get-graphql-schema --database constructive --schemas myapp,public --out ./schema.graphql`
|
|
348
|
+
- Print to stdout:
|
|
349
|
+
- `cnc get-graphql-schema --database constructive --schemas myapp,public`
|
|
350
|
+
|
|
351
|
+
- Option 2 – Fetch from running server (via endpoint introspection):
|
|
352
|
+
- Write to file:
|
|
353
|
+
- `cnc get-graphql-schema --endpoint http://localhost:3000/graphql --headerHost meta8.localhost --out ./schema.graphql`
|
|
354
|
+
- Print to stdout:
|
|
355
|
+
- `cnc get-graphql-schema --endpoint http://localhost:3000/graphql --headerHost meta8.localhost`
|
|
356
|
+
|
|
357
|
+
Options:
|
|
358
|
+
- `--database <name>` (Option 1)
|
|
359
|
+
- `--schemas <list>` (Option 1; comma-separated)
|
|
360
|
+
- `--endpoint <url>` (Option 2)
|
|
361
|
+
- `--headerHost <hostname>` (Option 2; optional custom HTTP Host header for vhost-based local setups)
|
|
362
|
+
- `--auth <token>` (Option 2; optional; sets Authorization header)
|
|
363
|
+
- `--header <name: value>` (Option 2; optional; repeatable; adds request headers, last value wins on duplicates)
|
|
364
|
+
- `--out <path>` (optional; if omitted, prints to stdout)
|
|
365
|
+
|
|
366
|
+
Notes:
|
|
367
|
+
- If your local dev server routes by hostname (e.g., `meta8.localhost`), but is reachable at `http://localhost:<port>`, use:
|
|
368
|
+
- `cnc get-graphql-schema --endpoint http://localhost:3000/graphql --headerHost meta8.localhost`
|
|
369
|
+
- You can repeat `--header` to add multiple headers, e.g.: `--header 'X-Mode: fast' --header 'Authorization: Bearer abc123'`
|
|
370
|
+
|
|
371
|
+
Tip:
|
|
372
|
+
- For Option 1, include only the schemas you need (e.g., `myapp,public`) to avoid type naming conflicts when multiple schemas contain similarly named tables.
|
|
373
|
+
|
|
374
|
+
|
|
375
|
+
## ⚙️ Configuration
|
|
376
|
+
|
|
377
|
+
### Environment Variables
|
|
378
|
+
|
|
379
|
+
Constructive respects standard PostgreSQL environment variables:
|
|
380
|
+
|
|
308
381
|
```bash
|
|
309
382
|
export PGHOST=localhost
|
|
310
383
|
export PGPORT=5432
|
|
@@ -313,22 +386,17 @@ export PGUSER=postgres
|
|
|
313
386
|
export PGPASSWORD=password
|
|
314
387
|
```
|
|
315
388
|
|
|
316
|
-
|
|
317
|
-
```bash
|
|
318
|
-
eval "$(constructive env --supabase)"
|
|
319
|
-
```
|
|
320
|
-
|
|
321
|
-
## Getting Help
|
|
389
|
+
## 🆘 Getting Help
|
|
322
390
|
|
|
323
391
|
### Command Help
|
|
324
392
|
|
|
325
393
|
```bash
|
|
326
394
|
# Global help
|
|
327
|
-
|
|
395
|
+
cnc --help
|
|
328
396
|
|
|
329
397
|
# Command-specific help
|
|
330
|
-
|
|
331
|
-
|
|
398
|
+
cnc deploy --help
|
|
399
|
+
cnc server -h
|
|
332
400
|
```
|
|
333
401
|
|
|
334
402
|
### Common Options
|
|
@@ -338,10 +406,135 @@ Most commands support these global options:
|
|
|
338
406
|
- `--help, -h` - Show help information
|
|
339
407
|
- `--version, -v` - Show version information
|
|
340
408
|
- `--cwd <dir>` - Set working directory
|
|
409
|
+
### Codegen
|
|
410
|
+
|
|
411
|
+
Generate types, operations, and SDK from a schema or endpoint.
|
|
412
|
+
|
|
413
|
+
```bash
|
|
414
|
+
# From SDL file
|
|
415
|
+
cnc codegen --schema ./schema.graphql --out ./codegen
|
|
416
|
+
|
|
417
|
+
# From endpoint with Host override
|
|
418
|
+
cnc codegen --endpoint http://localhost:3000/graphql --headerHost meta8.localhost --out ./codegen
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
Options:
|
|
422
|
+
- `--schema <path>` or `--endpoint <url>`
|
|
423
|
+
- `--out <dir>` output root (default: `graphql/codegen/dist`)
|
|
424
|
+
- `--format <gql|ts>` documents format
|
|
425
|
+
- `--convention <dashed|underscore|camelcase|camelUpper>` filenames
|
|
426
|
+
- `--headerHost <host>` optional HTTP Host header for endpoint requests
|
|
427
|
+
- `--auth <token>` Authorization header value (e.g., `Bearer 123`)
|
|
428
|
+
- `--header "Name: Value"` repeatable headers
|
|
429
|
+
- `--emitTypes <bool>` `--emitOperations <bool>` `--emitSdk <bool>` `--emitReactQuery <bool>`
|
|
430
|
+
- `--config ./config.json` Use customized config file
|
|
431
|
+
|
|
432
|
+
|
|
433
|
+
Config file (JSON/YAML):
|
|
434
|
+
|
|
435
|
+
```bash
|
|
436
|
+
# Use a JSON config to override defaults
|
|
437
|
+
cnc codegen --config ./my-options.json
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
Example `my-options.json`:
|
|
441
|
+
|
|
442
|
+
```json
|
|
443
|
+
{
|
|
444
|
+
"input": {
|
|
445
|
+
"schema": "./schema.graphql",
|
|
446
|
+
"headers": { "Host": "meta8.localhost" }
|
|
447
|
+
},
|
|
448
|
+
"output": {
|
|
449
|
+
"root": "graphql/codegen/dist/codegen-config",
|
|
450
|
+
"reactQueryFile": "react-query.ts"
|
|
451
|
+
},
|
|
452
|
+
"documents": {
|
|
453
|
+
"format": "gql",
|
|
454
|
+
"convention": "dashed",
|
|
455
|
+
"excludePatterns": [".*Module$", ".*By.+And.+$"]
|
|
456
|
+
},
|
|
457
|
+
"features": {
|
|
458
|
+
"emitTypes": true,
|
|
459
|
+
"emitOperations": true,
|
|
460
|
+
"emitSdk": true,
|
|
461
|
+
"emitReactQuery": true
|
|
462
|
+
},
|
|
463
|
+
"reactQuery": {
|
|
464
|
+
"fetcher": "graphql-request"
|
|
465
|
+
}
|
|
466
|
+
}
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
---
|
|
470
|
+
|
|
471
|
+
## Education and Tutorials
|
|
472
|
+
|
|
473
|
+
1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
|
|
474
|
+
Get started with modular databases in minutes. Install prerequisites and deploy your first module.
|
|
475
|
+
|
|
476
|
+
2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
|
|
477
|
+
Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
|
|
478
|
+
|
|
479
|
+
3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
|
|
480
|
+
Master the workflow for adding, organizing, and managing database changes with pgpm.
|
|
481
|
+
|
|
482
|
+
4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
|
|
483
|
+
Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
|
|
484
|
+
|
|
485
|
+
5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
|
|
486
|
+
Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
|
|
487
|
+
|
|
488
|
+
6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
|
|
489
|
+
Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
|
|
490
|
+
|
|
491
|
+
7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
|
|
492
|
+
Common issues and solutions for pgpm, PostgreSQL, and testing.
|
|
493
|
+
|
|
494
|
+
## Related Constructive Tooling
|
|
495
|
+
|
|
496
|
+
### 🧪 Testing
|
|
497
|
+
|
|
498
|
+
* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
|
|
499
|
+
* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
|
|
500
|
+
* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
|
|
501
|
+
* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
|
|
502
|
+
|
|
503
|
+
### 🧠 Parsing & AST
|
|
504
|
+
|
|
505
|
+
* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
|
|
506
|
+
* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
|
|
507
|
+
* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
|
|
508
|
+
* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
|
|
509
|
+
* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
|
|
510
|
+
* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
|
|
511
|
+
* [pg-ast](https://www.npmjs.com/package/pg-ast): **🔍 Low-level AST tools** and transformations for Postgres query structures.
|
|
512
|
+
|
|
513
|
+
### 🚀 API & Dev Tools
|
|
514
|
+
|
|
515
|
+
* [@constructive-io/graphql-server](https://github.com/constructive-io/constructive/tree/main/graphql/server): **⚡ Express-based API server** powered by PostGraphile to expose a secure, scalable GraphQL API over your Postgres database.
|
|
516
|
+
* [@constructive-io/graphql-explorer](https://github.com/constructive-io/constructive/tree/main/graphql/explorer): **🔎 Visual API explorer** with GraphiQL for browsing across all databases and schemas—useful for debugging, documentation, and API prototyping.
|
|
517
|
+
|
|
518
|
+
### 🔁 Streaming & Uploads
|
|
519
|
+
|
|
520
|
+
* [etag-hash](https://github.com/constructive-io/constructive/tree/main/streaming/etag-hash): **🏷️ S3-compatible ETags** created by streaming and hashing file uploads in chunks.
|
|
521
|
+
* [etag-stream](https://github.com/constructive-io/constructive/tree/main/streaming/etag-stream): **🔄 ETag computation** via Node stream transformer during upload or transfer.
|
|
522
|
+
* [uuid-hash](https://github.com/constructive-io/constructive/tree/main/streaming/uuid-hash): **🆔 Deterministic UUIDs** generated from hashed content, great for deduplication and asset referencing.
|
|
523
|
+
* [uuid-stream](https://github.com/constructive-io/constructive/tree/main/streaming/uuid-stream): **🌊 Streaming UUID generation** based on piped file content—ideal for upload pipelines.
|
|
524
|
+
* [@constructive-io/s3-streamer](https://github.com/constructive-io/constructive/tree/main/streaming/s3-streamer): **📤 Direct S3 streaming** for large files with support for metadata injection and content validation.
|
|
525
|
+
* [@constructive-io/upload-names](https://github.com/constructive-io/constructive/tree/main/streaming/upload-names): **📂 Collision-resistant filenames** utility for structured and unique file names for uploads.
|
|
526
|
+
|
|
527
|
+
### 🧰 CLI & Codegen
|
|
528
|
+
|
|
529
|
+
* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
|
|
530
|
+
* [@constructive-io/cli](https://github.com/constructive-io/constructive/tree/main/packages/cli): **🖥️ Command-line toolkit** for managing Constructive projects—supports database scaffolding, migrations, seeding, code generation, and automation.
|
|
531
|
+
* [@constructive-io/graphql-codegen](https://github.com/constructive-io/constructive/tree/main/graphql/codegen): **✨ GraphQL code generation** (types, operations, SDK) from schema/endpoint introspection.
|
|
532
|
+
* [@constructive-io/query-builder](https://github.com/constructive-io/constructive/tree/main/packages/query-builder): **🏗️ SQL constructor** providing a robust TypeScript-based query builder for dynamic generation of `SELECT`, `INSERT`, `UPDATE`, `DELETE`, and stored procedure calls—supports advanced SQL features like `JOIN`, `GROUP BY`, and schema-qualified queries.
|
|
533
|
+
* [@constructive-io/graphql-query](https://github.com/constructive-io/constructive/tree/main/graphql/query): **🧩 Fluent GraphQL builder** for PostGraphile schemas. ⚡ Schema-aware via introspection, 🧩 composable and ergonomic for building deeply nested queries.
|
|
341
534
|
|
|
342
535
|
## Credits
|
|
343
536
|
|
|
344
|
-
|
|
537
|
+
**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
|
|
345
538
|
|
|
346
539
|
## Disclaimer
|
|
347
540
|
|