db-model-router 1.0.2 → 1.0.4

package/README.md

@@ -2,11 +2,26 @@
 
 A database-agnostic REST API generator for Node.js. Works with Express or ultimate-express (a high-performance drop-in replacement). Define a model, get a full CRUD API with filtering, pagination, and bulk operations — backed by any of 9 supported databases.
 
+## Build a REST API with AI
+
+This library is designed to be driven by an AI assistant. Give it a prompt like this:
+
+```
+Use db-model-router to build a REST API for a task management app with postgres.
+I need: users (name, email, password_hash), projects (name, description, owner_id → users),
+and tasks (title, status, priority, project_id → projects, assignee_id → users).
+Scaffold the project, write the migrations, generate models and routes with parent-child
+relationships for projects.tasks, and make sure everything runs.
+```
+
+For the LLM skill reference, see [SKILL.md](./docs/SKILL.md).
+
 ## Supported Adapters
 
 | Adapter                                       | Module Key    | Driver                   | Install                                                                |
 | --------------------------------------------- | ------------- | ------------------------ | ---------------------------------------------------------------------- |
 | [MySQL](#mysql-example)                       | `mysql`       | mysql2                   | `npm i db-model-router mysql2`                                         |
+| MariaDB                                       | `mariadb`     | mysql2                   | `npm i db-model-router mysql2`                                         |
 | [PostgreSQL](./docs/adapters/postgres.md)     | `postgres`    | pg                       | `npm i db-model-router pg`                                             |
 | [SQLite3](./docs/adapters/sqlite3.md)         | `sqlite3`     | better-sqlite3           | `npm i db-model-router better-sqlite3`                                 |
 | [MongoDB](./docs/adapters/mongodb.md)         | `mongodb`     | mongodb                  | `npm i db-model-router mongodb`                                        |
@@ -55,6 +70,306 @@ npm install db-model-router @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
 
 Both `express` and `ultimate-express` are optional peer dependencies. The library auto-detects which one is installed (preferring `ultimate-express` when both are present). All database drivers are also optional peer dependencies, so your `node_modules` stays lean.
 
+## Quick Start
+
+The fastest way to start a new project:
+
+```bash
+# Scaffold a project interactively
+npx db-model-router init
+
+# Or fully non-interactive from a schema file
+db-model-router init --from dbmr.schema.json --yes --no-install
+db-model-router generate --from dbmr.schema.json
+```
+
+After scaffolding:
+
+```bash
+# 1. Edit .env with your database credentials
+# 2. Start developing
+npm run dev
+```
+
+## Schema-Driven Workflow
+
+Instead of running multiple CLI commands manually, you can define your entire project in a single `dbmr.schema.json` file and let the CLI generate everything from it.
+
+### The Schema File
+
+`dbmr.schema.json` is a declarative JSON file that describes your adapter, framework, tables, columns, relationships, and options — all in one place:
+
+```json
+{
+  "adapter": "postgres",
+  "framework": "express",
+  "options": {
+    "session": "redis",
+    "rateLimiting": true,
+    "helmet": true,
+    "logger": true,
+    "loki": false
+  },
+  "tables": {
+    "users": {
+      "columns": {
+        "user_id": "auto_increment",
+        "name": "required|string",
+        "email": "required|string",
+        "age": "integer",
+        "is_deleted": "boolean",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "user_id",
+      "unique": ["email"],
+      "softDelete": "is_deleted",
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      }
+    },
+    "posts": {
+      "columns": {
+        "post_id": "auto_increment",
+        "title": "required|string",
+        "body": "string",
+        "user_id": "required|integer",
+        "created_at": "datetime",
+        "modified_at": "datetime"
+      },
+      "pk": "post_id",
+      "unique": ["post_id"]
+    }
+  },
+  "relationships": [
+    { "parent": "users", "child": "posts", "foreignKey": "user_id" }
+  ]
+}
+```
+
+Table entries support these fields:
+
+| Field        | Required | Description                                                              |
+| ------------ | -------- | ------------------------------------------------------------------------ |
+| `columns`    | Yes      | Object mapping column names to Column_Rule strings (include ALL columns) |
+| `pk`         | Yes      | Primary key column name (convention: `<table>_id`)                       |
+| `unique`     | No       | Array of unique constraint columns (defaults to `[pk]`)                  |
+| `softDelete` | No       | Column name used for soft-delete                                         |
+| `timestamps` | No       | Object with `created_at` and `modified_at` column name mapping           |
+
+Column rules use the format `(required|)?(string|integer|numeric|boolean|object|datetime|auto_increment)`.
+
+- `auto_increment` — auto-incrementing PK (SERIAL in Postgres, AUTO_INCREMENT in MySQL/MariaDB)
+- `datetime` — date/time columns (TIMESTAMP, DATETIME, DATE)
+- `required|<type>` — NOT NULL constraint on insert/update
+
+### Unified CLI: `db-model-router`
+
+The `db-model-router` command is the unified entry point with five subcommands:
+
+```bash
+db-model-router <subcommand> [flags]
+```
+
+| Subcommand | Description                                                         |
+| ---------- | ------------------------------------------------------------------- |
+| `init`     | Scaffold a new project (optionally from a schema file)              |
+| `inspect`  | Introspect a live database and produce a `dbmr.schema.json`         |
+| `generate` | Generate models, routes, tests, and OpenAPI spec from the schema    |
+| `doctor`   | Validate schema, check dependencies, verify generated files in sync |
+| `diff`     | Preview what changes regeneration would make (read-only)            |
+
+#### Universal Flags
+
+All subcommands accept these flags:
+
+| Flag           | Description                                                 |
+| -------------- | ----------------------------------------------------------- |
+| `--yes`        | Accept all defaults, suppress interactive prompts           |
+| `--json`       | Output machine-readable JSON instead of human-readable text |
+| `--dry-run`    | Preview actions without writing files or running commands   |
+| `--no-install` | Skip `npm install` (applies to commands that would run it)  |
+| `--help`       | Show usage information for the subcommand                   |
+
+#### Quick Workflow Example
+
+```bash
+# 1. Introspect an existing database into a schema file
+db-model-router inspect --type postgres --env .env
+
+# 2. (Optional) Edit dbmr.schema.json to add relationships, tweak columns, etc.
+
+# 3. Generate all artifacts from the schema
+db-model-router generate --from dbmr.schema.json
+
+# 4. Check everything is in sync
+db-model-router doctor --from dbmr.schema.json
+
+# 5. Preview what a regeneration would change
+db-model-router diff --from dbmr.schema.json
+```
+
+Or start a brand-new project from a schema file:
+
+```bash
+# Scaffold project + generate everything in one go
+db-model-router init --from dbmr.schema.json --yes --no-install
+db-model-router generate --from dbmr.schema.json
+```
+
+### Command Reference
+
+#### `init`
+
+Scaffold a new project from a schema file or interactively. Generates an ESM-based project (`"type": "module"` in package.json) with Docker support.
+
+| Flag / Arg           | Description                                                                                                                                                               |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--from <path>`      | Read adapter, framework, and options from a `dbmr.schema.json` file                                                                                                       |
+| `--framework <name>` | Express framework: `express` or `ultimate-express`                                                                                                                        |
+| `--database <name>`  | Database adapter: `mysql`, `mariadb`, `postgres`, `sqlite3`, `mongodb`, `mssql`, `cockroachdb`, `oracle`, `redis`, `dynamodb`                                             |
+| `--db <name>`        | Alias for `--database`                                                                                                                                                    |
+| `--session <type>`   | Session store: `memory`, `redis`, `database`                                                                                                                              |
+| `--output <dir>`     | Directory for backend source files (relative to cwd). `package.json` and `app.js` stay in root; `commons/`, `route/`, `middleware/`, `migrations/` go inside this folder. |
+| `--rateLimiting`     | Enable rate limiting via `express-rate-limit` (default: yes)                                                                                                              |
+| `--helmet`           | Enable Helmet security headers (default: yes)                                                                                                                             |
+| `--logger`           | Enable Winston request logger (default: yes)                                                                                                                              |
+| `--loki`             | Enable Grafana Loki log transport + Loki/Grafana in docker-compose (default: no, only asked when `--logger` is enabled)                                                   |
+
+```bash
+# Non-interactive with output directory
+db-model-router init --framework express --database postgres --output backend --yes
+
+# With Loki logging
+db-model-router init --database postgres --logger --loki --yes
+
+# From schema, skip install
+db-model-router init --from dbmr.schema.json --yes --no-install
+
+# Dry run to preview files
+db-model-router init --from dbmr.schema.json --dry-run
+```
+
+Generated project structure (with `--output backend`):
+
+```
+├── package.json              # root (type: "module")
+├── app.js                    # ESM entry point
+├── .env / .env.example
+├── .gitignore
+├── Dockerfile                # node:alpine production image
+├── .dockerignore
+├── docker-compose.yml        # database + CloudBeaver + optional Loki/Grafana
+├── .cloudbeaver/
+│   └── data-sources.json     # auto-connects CloudBeaver to your DB
+├── .grafana/                 # (only when --loki)
+│   └── datasources.yml       # auto-connects Grafana to Loki
+└── backend/
+    ├── commons/
+    │   ├── db.js             # database init, connect, global.db
+    │   ├── session.js        # session configuration
+    │   ├── security.js       # helmet, rate limiting, custom headers
+    │   ├── migrate.js        # migration runner (importable + standalone script)
+    │   └── add_migration.js  # migration creator (importable + standalone script)
+    ├── middleware/
+    │   └── logger.js         # Winston logger (+ Loki transport when LOKI_HOST is set)
+    ├── route/
+    │   ├── index.js          # central route mounting
+    │   └── health.js         # GET /health with DB connectivity check
+    └── migrations/
+        └── <timestamp>_create_migrations_table.sql
+```
+
+Docker services included automatically:
+
+| Service     | When                                  | Port   | Description                            |
+| ----------- | ------------------------------------- | ------ | -------------------------------------- |
+| Database    | Always (except sqlite3)               | Varies | Selected database with random password |
+| Redis       | `--session redis` (if DB isn't redis) | 6379   | Session store                          |
+| CloudBeaver | SQL/MongoDB databases                 | 8978   | Web-based DB admin, auto-connected     |
+| Loki        | `--loki`                              | 3100   | Log aggregation                        |
+| Grafana     | `--loki`                              | 3001   | Log visualization, Loki pre-configured |
+
+npm scripts added: `start`, `dev`, `test`, `migrate`, `add_migration`, `docker:build`, `docker:up`, `docker:down`.
+
+#### `inspect`
+
+Introspect a live database and produce a `dbmr.schema.json` file.
+
+| Flag / Arg         | Description                                                                                                            |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `--type <adapter>` | Database adapter to introspect (required): `mysql`, `mariadb`, `postgres`, `sqlite3`, `mssql`, `oracle`, `cockroachdb` |
+| `--env <path>`     | Path to `.env` file for database connection parameters                                                                 |
+| `--out <path>`     | Output file path (default: `dbmr.schema.json`)                                                                         |
+| `--tables <list>`  | Comma-separated list of tables to include (omit for all)                                                               |
+
+```bash
+db-model-router inspect --type postgres --env .env
+db-model-router inspect --type sqlite3 --out schema.json --tables users,posts
+db-model-router inspect --type mysql --json
+```
+
+#### `generate`
+
+Generate models, routes, tests, OpenAPI spec, and LLM docs from a schema file. All generated code is ESM (`import`/`export`).
+
+| Flag / Arg      | Description                                                  |
+| --------------- | ------------------------------------------------------------ |
+| `--from <path>` | Path to schema file (default: `dbmr.schema.json`)            |
+| `--models`      | Generate only model files                                    |
+| `--routes`      | Generate only route files (including child routes and index) |
+| `--openapi`     | Generate only OpenAPI spec                                   |
+| `--tests`       | Generate only test files                                     |
+| `--llm-docs`    | Generate only LLM documentation (`llms.txt` + `docs/llm.md`) |
+
+When no artifact flags are provided, all artifact types are generated.
+
+```bash
+db-model-router generate --from dbmr.schema.json
+db-model-router generate --models --dry-run
+db-model-router generate --routes --tests
+db-model-router generate --from dbmr.schema.json --json
+```
+
+#### `doctor`
+
+Validate schema, check adapter driver dependencies, and verify generated files are in sync.
+
+| Flag / Arg      | Description                                       |
+| --------------- | ------------------------------------------------- |
+| `--from <path>` | Path to schema file (default: `dbmr.schema.json`) |
+
+```bash
+db-model-router doctor --from dbmr.schema.json
+db-model-router doctor --json
+```
+
+Reports three checks: schema validation, dependency check, sync check.
+
+#### `diff`
+
+Preview changes between the current generated files and what the schema would produce. Read-only.
+
+| Flag / Arg      | Description                                       |
+| --------------- | ------------------------------------------------- |
+| `--from <path>` | Path to schema file (default: `dbmr.schema.json`) |
+
+```bash
+db-model-router diff --from dbmr.schema.json
+db-model-router diff --json
+```
+
+#### `help`
+
+Show help for any command.
+
+```bash
+db-model-router help              # general overview with per-command flags
+db-model-router help init         # detailed help for init
+db-model-router init --help       # same as above
+```
+
 ## MySQL Example
 
 ### 1. Connect
@@ -109,13 +424,14 @@ app.use("/users", route(users));
 app.listen(3000);
 ```
 
-This creates 8 endpoints:
+This creates 9 endpoints:
 
 | Method | Path         | Description                     |
 | ------ | ------------ | ------------------------------- |
 | GET    | `/users/:id` | Get one record by PK            |
 | POST   | `/users/add` | Insert a single record          |
 | PUT    | `/users/:id` | Update a single record          |
+| PATCH  | `/users/:id` | Partial update a single record  |
 | DELETE | `/users/:id` | Delete a single record          |
 | GET    | `/users/`    | List with pagination            |
 | POST   | `/users/`    | Bulk insert (`{ data: [...] }`) |
@@ -274,207 +590,6 @@ The model and route APIs remain identical across all adapters. See the individua
 - [Redis](./docs/adapters/redis.md)
 - [DynamoDB](./docs/adapters/dynamodb.md)
 
-## CLI Tools
-
-Three CLI commands are included to scaffold models, routes, and full apps from an existing database.
-
-### generate-app
-
-The fastest way to go from database to running API. Scaffolds a complete Express REST API project in a single command — introspects your database, generates models and routes (including parent-child relationships), and creates the app entry point, middleware, environment config, and project structure.
-
-```bash
-# Full app from MySQL
-db-model-router-generate-app --type mysql --env .env
-
-# SQLite3 into a specific directory
-db-model-router-generate-app --type sqlite3 --database ./myapp.db --output ./my-api
-
-# Postgres with specific tables and relationships
-db-model-router-generate-app --type postgres --env .env --tables users,posts,posts.comments
-```
-
-Options:
-
-| Option       | Description                                                                     |
-| ------------ | ------------------------------------------------------------------------------- |
-| `--type`     | Database type (mysql, postgres, sqlite3, mssql, oracle, cockroachdb) [required] |
-| `--output`   | Output directory (default: current directory)                                   |
-| `--host`     | Database host                                                                   |
-| `--port`     | Database port                                                                   |
-| `--database` | Database name or file path                                                      |
-| `--user`     | Database user                                                                   |
-| `--password` | Database password                                                               |
-| `--schema`   | Schema name (postgres only)                                                     |
-| `--tables`   | Comma-separated tables, supports `parent.child` notation for relationships      |
-| `--env`      | Path to .env file for DB connection                                             |
-
-Generated project structure:
-
-```
-my-api/
-  app.js              # Express app with init(), db.connect(), middleware, error handler, health check
-  .env.example         # Pre-filled environment template for your DB type
-  .gitignore           # node_modules, .env, *.db
-  middleware/
-    logger.js          # Request logger (method, URL, status, response time)
-  models/
-    users.js           # Auto-generated from DB introspection
-    posts.js
-    index.js
-  routes/
-    users.js           # Auto-generated route files
-    posts.js
-    index.js
-    openapi.json       # OpenAPI 3.0 spec
-  migrations/
-    README.md          # Placeholder for migration scripts
-  sessions/
-    README.md          # Placeholder for session config
-```
-
-When `--tables` includes parent-child notation (e.g., `posts.comments`), the routes directory also includes scoped child route files and nested route mounting — see [Parent-Child Relationships](#parent-child-relationships-foreign-keys) below.
-
-To start the generated app:
-
-```bash
-cp .env.example .env   # edit with your DB credentials
-npm install
-node app.js
-```
-
-### generate-model
-
-Connects to your database, introspects all tables, and generates model files with validation rules, primary keys, unique constraints, and auto-detected options (safeDelete, timestamps). This is called automatically by `generate-app`, but can be used standalone.
-
-```bash
-# Basic usage
-db-model-router-generate-model --type mysql --host localhost --database mydb --user root --password secret
-
-# Using an .env file
-db-model-router-generate-model --type postgres --env .env --output ./src/models
-
-# SQLite3
-db-model-router-generate-model --type sqlite3 --database ./myapp.db --output ./models
-
-# Only specific tables
-db-model-router-generate-model --type mysql --env .env --tables users,posts,comments
-```
-
-Options:
-
-| Option       | Description                                                                   |
-| ------------ | ----------------------------------------------------------------------------- |
-| `--type`     | Database type (mysql, postgres, sqlite3, mssql, oracle, cockroachdb)          |
-| `--host`     | Database host (default: localhost)                                            |
-| `--port`     | Database port                                                                 |
-| `--database` | Database name (or file path for sqlite3)                                      |
-| `--user`     | Database user                                                                 |
-| `--password` | Database password                                                             |
-| `--schema`   | Schema name (postgres only, default: public)                                  |
-| `--output`   | Output directory (default: ./models)                                          |
-| `--tables`   | Comma-separated list of tables to generate (supports `parent.child` notation) |
-| `--env`      | Path to .env file to load                                                     |
-
-Auto-detection:
-
-- Columns with `DEFAULT` values are marked as optional (not `required`)
-- Timestamp columns (`created_at`, `updated_at`, `modified_at`, `createdAt`, etc.) are excluded from the model structure and added to the option object
-- Soft-delete columns (`is_deleted`, `deleted`, `is_active`, `archived`, etc.) are excluded from the structure and set as `safeDelete` in the option
-- Multi-column unique indexes are correctly grouped for the unique constraint parameter
-
-Generated output:
-
-```
-models/
-  users.js          # model(db, "users", {...}, "user_id", ["email"], { safeDelete: "is_deleted", ... })
-  posts.js          # model(db, "posts", {...}, "post_id", ["post_id"])
-  index.js          # exports { users, posts }
-```
-
-### generate-route
-
-Generates Express route files for each model. If models don't exist yet, it auto-generates them first. Also generates an OpenAPI 3.0 spec (`openapi.json`) from the model metadata. This is called automatically by `generate-app`, but can be used standalone.
-
-```bash
-# From existing models
-db-model-router-generate-route --models ./models --output ./routes
-
-# Auto-generate models + routes in one step
-db-model-router-generate-route --type mysql --env .env --models ./models --output ./routes
-
-# SQLite3 one-liner
-db-model-router-generate-route --type sqlite3 --database ./myapp.db
-```
-
-Options:
-
-| Option       | Description                                                                |
-| ------------ | -------------------------------------------------------------------------- |
-| `--models`   | Path to models directory (default: ./models)                               |
-| `--output`   | Output directory for routes (default: ./routes)                            |
-| `--type`     | Database type — triggers model generation if models are missing            |
-| `--host`     | Database host (passed to model generation)                                 |
-| `--port`     | Database port (passed to model generation)                                 |
-| `--database` | Database name or file path (passed to model generation)                    |
-| `--user`     | Database user (passed to model generation)                                 |
-| `--password` | Database password (passed to model generation)                             |
-| `--schema`   | Schema name (passed to model generation)                                   |
-| `--tables`   | Comma-separated tables, supports `parent.child` notation for relationships |
-| `--env`      | Path to .env file (passed to model generation)                             |
-
-#### Parent-Child Relationships (Foreign Keys)
-
-Use dot notation in `--tables` to declare parent-child relationships. This works in `generate-route`, `generate-app`, and `generate-model`. The generator creates nested routes that automatically scope child queries by the parent's foreign key.
-
-```bash
-# Declare that comments belong to posts
-db-model-router-generate-route --type mysql --env .env --tables users,posts,posts.comments
-
-# Same via generate-app
-db-model-router-generate-app --type mysql --env .env --tables users,posts,posts.comments
-```
-
-The FK column is derived by convention: `<parent_singular>_id` (e.g., `posts.comments` → `post_id`).
-
-This generates:
-
-```
-routes/
-  users.js                        # route(users)
-  posts.js                        # route(posts)
-  comments.js                     # route(comments)  — direct access
-  comments_child_of_posts.js      # route(comments, { post_id: "params.post_id" })  — scoped
-  index.js                        # mounts all routes
-  openapi.json                    # OpenAPI 3.0 spec
-```
-
-The generated `index.js` mounts both nested and top-level routes:
-
-```js
-// Nested: GET /api/posts/:post_id/comments — returns only comments for that post
-router.use("/posts/:post_id/comments", commentsChildRoute);
-
-// Direct: GET /api/comments — returns all comments
-router.use("/comments", commentsRoute);
-```
-
-The child route file uses payload override to scope every query:
-
-```js
-// comments_child_of_posts.js
-module.exports = route(comments, { post_id: "params.post_id" });
-```
-
-#### Generated output (without relationships)
-
-```
-routes/
-  users.js          # route(users)
-  posts.js          # route(posts)
-  index.js          # express.Router() mounting all routes at /users, /posts, etc.
-  openapi.json      # OpenAPI 3.0 spec
-```
-
 ## Environment Setup (Docker)
 
 A `docker-compose.yml` is included for running all supported databases locally: