schematic-pg 0.1.12 → 0.1.14

package/README.md

@@ -182,7 +182,7 @@ models {
 
   model User {
     id:        UUID        @id @default(gen_random_uuid())
-    email:     VARCHAR(255) @unique
+    email:     VARCHAR(255) @unique @regex(pattern: "^[\\w.-]+@[\\w.-]+\\.\\w+$", message: "Invalid email address")
     name:      VARCHAR(150)
     role:      UserRole    @default(USER)
     age:       SMALLINT?
@@ -449,14 +449,14 @@ npm run start      # schematic-pg start
 
 ```bash
 schematic-pg db:ping [schema]              # Test DATABASE_URL connection (SELECT 1)
-schematic-pg db:bootstrap [schema]         # Apply DDL from schema + write .schema-state snapshot
+schematic-pg db:bootstrap [schema]         # Reset public schema, apply DDL, write .schema-state snapshot
 schematic-pg db:diff [schema]              # Print pending schema changes (snapshot vs app.schema)
 schematic-pg db:diff --name add_users      # Write a migration file under migrations/
 schematic-pg db:migrate [schema]           # Apply pending migration files
 schematic-pg db:migrate:status [schema]    # Show snapshot + migration file status
 ```
 
-`db:bootstrap` is the recommended first-time setup. Use `db:diff` / `db:migrate` when evolving an existing database.
+`db:bootstrap` resets the `public` schema then applies full DDL — safe to re-run locally (including via `dev` watch). Use `db:diff` / `db:migrate` when evolving a database you need to keep.
 
 For a full walkthrough (mental model, local loop, and automating staging/production with GitHub Actions), see [Migrations tutorial](docs/migrations.md).
 

package/dist/api-generator/openapi-generator.js

@@ -3,14 +3,20 @@ import { fieldHasAttribute, getModelNames, getPrimaryKey, getStoredFields, } fro
 import { getFilterableFields, getIncludableRelationFields, getOmittedFields, getSortableFieldNames, isStoredScalarField, } from './utils/api-fields.js';
 import { buildFilterFieldMeta, queryParamKey } from './utils/filter-operators.js';
 const ERROR_REF = { $ref: '#/components/schemas/Error' };
-const ERROR_CONTENT = {
-    'application/json': {
-        schema: ERROR_REF,
-    },
-};
+const ERROR_EXAMPLE_VALIDATION = 'Validation failed';
+const ERROR_EXAMPLE_FORBIDDEN = 'Role "USER" is not allowed to list this resource';
+const ERROR_EXAMPLE_CONFLICT = 'Unique constraint violation on email';
 const OPTIONAL_BEARER_SECURITY = [{}, { bearerAuth: [] }];
-function errorResponse(description) {
-    return { description, content: ERROR_CONTENT };
+function errorResponse(description, exampleMessage = description) {
+    return {
+        description,
+        content: {
+            'application/json': {
+                schema: ERROR_REF,
+                example: { error: exampleMessage },
+            },
+        },
+    };
 }
 function jsonContent(schema) {
     return {
@@ -32,7 +38,10 @@ export class OpenApiGenerator {
                 type: 'object',
                 required: ['error'],
                 properties: {
-                    error: { type: 'string' },
+                    error: {
+                        type: 'string',
+                        description: 'Human-readable error message',
+                    },
                 },
             },
         };
@@ -161,9 +170,9 @@ export class OpenApiGenerator {
                             description: `List of ${model.name}`,
                             content: jsonContent({ type: 'array', items: responseRef }),
                         },
-                        '400': errorResponse('Validation error'),
+                        '400': errorResponse('Validation error', ERROR_EXAMPLE_VALIDATION),
                         '401': errorResponse('Unauthorized'),
-                        '403': errorResponse('Forbidden'),
+                        '403': errorResponse('Forbidden', ERROR_EXAMPLE_FORBIDDEN),
                         '500': errorResponse('Internal server error'),
                     },
                 },
@@ -181,10 +190,10 @@ export class OpenApiGenerator {
                             description: `Created ${model.name}`,
                             content: jsonContent(responseRef),
                         },
-                        '400': errorResponse('Validation error'),
+                        '400': errorResponse('Validation error', ERROR_EXAMPLE_VALIDATION),
                         '401': errorResponse('Unauthorized'),
-                        '403': errorResponse('Forbidden'),
-                        '409': errorResponse('Conflict'),
+                        '403': errorResponse('Forbidden', ERROR_EXAMPLE_FORBIDDEN),
+                        '409': errorResponse('Conflict', ERROR_EXAMPLE_CONFLICT),
                         '500': errorResponse('Internal server error'),
                     },
                 },
@@ -204,9 +213,9 @@ export class OpenApiGenerator {
                             description: `${model.name} record`,
                             content: jsonContent(responseRef),
                         },
-                        '400': errorResponse('Validation error'),
+                        '400': errorResponse('Validation error', ERROR_EXAMPLE_VALIDATION),
                         '401': errorResponse('Unauthorized'),
-                        '403': errorResponse('Forbidden'),
+                        '403': errorResponse('Forbidden', ERROR_EXAMPLE_FORBIDDEN),
                         '404': errorResponse('Not found'),
                         '500': errorResponse('Internal server error'),
                     },
@@ -226,11 +235,11 @@ export class OpenApiGenerator {
                             description: `Updated ${model.name}`,
                             content: jsonContent(responseRef),
                         },
-                        '400': errorResponse('Validation error'),
+                        '400': errorResponse('Validation error', ERROR_EXAMPLE_VALIDATION),
                         '401': errorResponse('Unauthorized'),
-                        '403': errorResponse('Forbidden'),
+                        '403': errorResponse('Forbidden', ERROR_EXAMPLE_FORBIDDEN),
                         '404': errorResponse('Not found'),
-                        '409': errorResponse('Conflict'),
+                        '409': errorResponse('Conflict', ERROR_EXAMPLE_CONFLICT),
                         '500': errorResponse('Internal server error'),
                     },
                 },
@@ -245,9 +254,9 @@ export class OpenApiGenerator {
                             description: `Deleted ${model.name}`,
                             content: jsonContent(responseRef),
                         },
-                        '400': errorResponse('Validation error'),
+                        '400': errorResponse('Validation error', ERROR_EXAMPLE_VALIDATION),
                         '401': errorResponse('Unauthorized'),
-                        '403': errorResponse('Forbidden'),
+                        '403': errorResponse('Forbidden', ERROR_EXAMPLE_FORBIDDEN),
                         '404': errorResponse('Not found'),
                         '500': errorResponse('Internal server error'),
                     },
@@ -445,8 +454,8 @@ export class OpenApiGenerator {
                             description: 'Registered user with access token',
                             content: jsonContent({ $ref: '#/components/schemas/AuthTokenResponse' }),
                         },
-                        '400': errorResponse('Validation error'),
-                        '409': errorResponse('Conflict'),
+                        '400': errorResponse('Validation error', ERROR_EXAMPLE_VALIDATION),
+                        '409': errorResponse('Conflict', ERROR_EXAMPLE_CONFLICT),
                         '500': errorResponse('Internal server error'),
                     },
                 },
@@ -465,7 +474,7 @@ export class OpenApiGenerator {
                             description: 'Access token and user',
                             content: jsonContent({ $ref: '#/components/schemas/AuthTokenResponse' }),
                         },
-                        '400': errorResponse('Validation error'),
+                        '400': errorResponse('Validation error', ERROR_EXAMPLE_VALIDATION),
                         '401': errorResponse('Invalid email or password'),
                         '500': errorResponse('Internal server error'),
                     },

package/dist/cli/templates/agents.md

@@ -264,7 +264,7 @@ Flow: `validate → assertPolicy → beforeHooks → db op → afterHooks → re
 schematic-pg generate              # schema.sql + db client + API
 schematic-pg dev [--no-watch]      # generate + bootstrap + server + watch
 schematic-pg start [--no-migrate]  # production: migrate + run server
-schematic-pg db:bootstrap            # first-time DDL apply
+schematic-pg db:bootstrap            # reset public schema + apply DDL
 schematic-pg db:diff [--name label]  # print or write migration
 schematic-pg db:migrate              # apply pending migrations
 schematic-pg hooks:add [--model X]   # scaffold src/hooks/{Model}.ts

package/dist/cli/templates.d.ts

@@ -1,5 +1,5 @@
 export declare const AGENTS_TEMPLATE: string;
-export declare const APP_SCHEMA_TEMPLATE = "extensions {\n\n}\n\nenums {\n  UserRole { ADMIN, USER }\n}\n\nmodels {\n  model User {\n    id:           UUID         @id @default(gen_random_uuid())\n    email:        VARCHAR(255) @unique\n    name:         VARCHAR(150)?\n    role:         UserRole     @default(USER)\n    passwordHash: VARCHAR(255)? @omit @unfilterable\n    createdAt:    TIMESTAMP    @default(now())\n\n    @policy(role: USER, allow: [select, update], where: \"id = {{auth.user.id}}\")\n    @policy(role: ADMIN, allow: all)\n  }\n}\n";
+export declare const APP_SCHEMA_TEMPLATE = "extensions {\n\n}\n\nenums {\n  UserRole { ADMIN, USER }\n}\n\nmodels {\n  model User {\n    id:           UUID         @id @default(gen_random_uuid())\n    email:        VARCHAR(255) @unique @regex(pattern: \"^[\\w.-]+@[\\w.-]+\\.\\w+$\", message: \"Invalid email address\")\n    name:         VARCHAR(150)?\n    role:         UserRole     @default(USER)\n    passwordHash: VARCHAR(255)? @omit @unfilterable\n    createdAt:    TIMESTAMP    @default(now())\n\n    @policy(role: USER, allow: [select, update], where: \"id = {{auth.user.id}}\")\n    @policy(role: ADMIN, allow: all)\n  }\n}\n";
 export declare const ENV_TEMPLATE = "DATABASE_URL=postgresql://postgrest:postgrest@localhost:5432/postgrest\nJWT_SECRET=\nAUTH_PEPPER=\nAUTH_ACCESS_TOKEN_TTL=1h\nJWT_ROLE_CLAIM=role\nJWT_USER_ID_CLAIM=sub\n";
 export declare const GITIGNORE_TEMPLATE = "node_modules/\ndist/\n.env\ndocker_data/\n.DS_Store\n*.log\nnpm-debug.log*\n";
 export declare const DOCKER_COMPOSE_TEMPLATE = "services:\n  postgres:\n    image: postgres:18.4-bookworm\n    container_name: schematic-pg\n    restart: unless-stopped\n    ports:\n      - \"5432:5432\"\n    environment:\n      POSTGRES_USER: postgrest\n      POSTGRES_PASSWORD: postgrest\n      POSTGRES_DB: postgrest\n    volumes:\n      - ./docker_data/postgres:/var/lib/postgresql\n    healthcheck:\n      test: [\"CMD-SHELL\", \"pg_isready -U postgrest -d postgrest\"]\n      interval: 5s\n      timeout: 5s\n      retries: 5\n";

package/dist/cli/templates.js

@@ -15,7 +15,7 @@ enums {
 models {
   model User {
     id:           UUID         @id @default(gen_random_uuid())
-    email:        VARCHAR(255) @unique
+    email:        VARCHAR(255) @unique @regex(pattern: "^[\\w.-]+@[\\w.-]+\\.\\w+$", message: "Invalid email address")
     name:         VARCHAR(150)?
     role:         UserRole     @default(USER)
     passwordHash: VARCHAR(255)? @omit @unfilterable

package/dist/cli.js

@@ -18,7 +18,7 @@ Commands:
   dev [schema] [--no-watch]  Generate, bootstrap DB, start server, watch schema
   start [schema] [--no-migrate]  Run production server (migrate DB, no generate/watch)
   db:ping                    Test database connection
-  db:bootstrap [schema]      Apply DDL and snapshot schema state
+  db:bootstrap [schema]      Reset public schema, apply DDL, snapshot state
   db:diff [schema]           Show schema diff (--name <name> to write migration)
   db:migrate [schema]        Apply pending migrations
   db:migrate:status [schema] Show migration status

package/dist/db/bootstrap.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { SqlGenerator } from '../sql-generator/sql-generator.js';
 import { DatabaseClient } from './client.js';
+import { resetPublicSchema } from './reset-database.js';
 import { writeSnapshot } from './schema-state.js';
 export function generateBootstrapSql(schemaPath) {
     const source = readFileSync(schemaPath, 'utf8');
@@ -10,6 +11,8 @@ export function generateBootstrapSql(schemaPath) {
 export async function bootstrapDatabase(schemaPath = join(process.cwd(), 'app.schema'), client = new DatabaseClient()) {
     const sql = generateBootstrapSql(schemaPath);
     await client.withClient(async (pgClient) => {
+        // Bootstrap is greenfield: wipe existing objects so re-runs (e.g. `dev` watch) are idempotent.
+        await resetPublicSchema(pgClient);
         await pgClient.query(sql);
     });
     writeSnapshot(schemaPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schematic-pg",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Single-file backend framework for PostgreSQL and Node.js",
   "type": "module",
   "license": "MIT",