db-model-router 1.0.3 → 1.0.5

package/README.md

@@ -14,13 +14,18 @@ Scaffold the project, write the migrations, generate models and routes with pare
 relationships for projects.tasks, and make sure everything runs.
 ```
 
-For the LLM skill reference, see [SKILL.md](./docs/SKILL.md).
+For the LLM skill reference, see [SKILL.md](./skill/SKILL.md). You can also add it directly to your AI assistant:
+
+```bash
+npx skills add https://github.com/AvinashSKaranth/db-model-router/skill
+```
 
 ## 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`                                        |
@@ -96,7 +101,31 @@ Instead of running multiple CLI commands manually, you can define your entire pr
 
 ### 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:
+`dbmr.schema.json` is a declarative JSON file that describes your adapter, framework, tables, columns, module hierarchy, and options — all in one place.
+
+#### Modules and the `parent` Field
+
+Each table in the schema represents a **module**. Modules are either top-level or nested under a parent module using the `parent` field:
+
+- `"parent": null` — top-level module, routes mount at `/<table>/`
+- `"parent": "posts"` — child module, routes mount at `/posts/:post_id/comments/:comment_id`
+
+When a table has `parent` set, the CLI automatically:
+
+1. Creates a child route file scoped by the parent's PK as a URL parameter
+2. Mounts the child routes under the parent path
+3. Also mounts the child as a top-level route for direct access
+
+#### Best Practice: Don't Use System Tables as Parents
+
+Tables like `users`, `tenants`, `roles`, `permissions`, `sessions`, and `role_permissions` are cross-cutting concerns — they are referenced by almost every feature module via foreign key columns (e.g. `user_id`, `tenant_id`). Making them route parents would nest every feature module under them, which is not the intent.
+
+Keep system tables as top-level modules (`"parent": null`) and reference them via FK columns in your feature tables. Only use `parent` for true domain hierarchies like `posts → comments`, `orders → order_items`, or `projects → tasks`.
+
+Examples of tables that should stay top-level (not be parents of feature modules):
+`users`, `tenants`, `roles`, `role_permissions`, `permissions`, `sessions`, `accounts`, `auth_tokens`
+
+#### Example Schema
 
 ```json
 {
@@ -106,51 +135,93 @@ Instead of running multiple CLI commands manually, you can define your entire pr
     "session": "redis",
     "rateLimiting": true,
     "helmet": true,
-    "logger": true
+    "logger": true,
+    "loki": false
   },
   "tables": {
     "users": {
       "columns": {
+        "user_id": "auto_increment",
         "name": "required|string",
         "email": "required|string",
         "age": "integer",
-        "is_deleted": "boolean"
+        "is_deleted": "boolean",
+        "created_at": "datetime",
+        "updated_at": "datetime"
       },
-      "pk": "id",
+      "pk": "user_id",
       "unique": ["email"],
       "softDelete": "is_deleted",
       "timestamps": {
         "created_at": "created_at",
         "modified_at": "updated_at"
-      }
+      },
+      "parent": null
     },
     "posts": {
       "columns": {
+        "post_id": "auto_increment",
         "title": "required|string",
         "body": "string",
-        "user_id": "required|integer"
+        "user_id": "required|integer",
+        "created_at": "datetime",
+        "modified_at": "datetime"
+      },
+      "pk": "post_id",
+      "unique": ["post_id"],
+      "parent": null
+    },
+    "comments": {
+      "columns": {
+        "comment_id": "auto_increment",
+        "post_id": "required|integer",
+        "user_id": "required|integer",
+        "body": "required|string",
+        "created_at": "datetime"
       },
-      "pk": "id",
-      "unique": ["id"]
+      "pk": "comment_id",
+      "unique": ["comment_id"],
+      "parent": "posts"
     }
-  },
-  "relationships": [
-    { "parent": "users", "child": "posts", "foreignKey": "user_id" }
-  ]
+  }
 }
 ```
 
-Table entries support these fields:
+This generates routes:
+
+- `GET /users/`, `GET /users/:user_id` — top-level
+- `GET /posts/`, `GET /posts/:post_id` — top-level
+- `GET /posts/:post_id/comments/`, `GET /posts/:post_id/comments/:comment_id` — nested under posts
+- `GET /comments/`, `GET /comments/:comment_id` — also available as top-level
+
+Note: `comments` has `user_id` as a foreign key column but `users` is NOT its parent — `posts` is. The `user_id` is just a data reference, not a route hierarchy.
+
+#### Table 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           |
+| `parent`     | No       | Parent table name for route nesting, or `null` for top-level             |
 
-| Field        | Required | Description                                                    |
-| ------------ | -------- | -------------------------------------------------------------- |
-| `columns`    | Yes      | Object mapping column names to Column_Rule strings             |
-| `pk`         | No       | Primary key column name (defaults to `"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
 
-Column rules use the format `(required|)?(string|integer|numeric|boolean|object)` — e.g. `"required|string"`, `"integer"`, `"object"`.
+Format: `(required|)?(string|integer|numeric|boolean|object|datetime|auto_increment)`
+
+| Type             | Description                                                        |
+| ---------------- | ------------------------------------------------------------------ |
+| `auto_increment` | Auto-incrementing PK (SERIAL in Postgres, AUTO_INCREMENT in MySQL) |
+| `datetime`       | Date/time columns (TIMESTAMP, DATETIME, DATE)                      |
+| `string`         | Text columns (VARCHAR, TEXT, CHAR, UUID)                           |
+| `integer`        | Integer columns (INT, BIGINT, SMALLINT)                            |
+| `numeric`        | Decimal columns (DECIMAL, FLOAT, DOUBLE, MONEY)                    |
+| `boolean`        | Boolean columns (BOOLEAN, BIT)                                     |
+| `object`         | JSON columns (JSON, JSONB)                                         |
+
+Prefix with `required|` for NOT NULL constraint (e.g. `"required|string"`).
 
 ### Unified CLI: `db-model-router`
 
@@ -206,6 +277,158 @@ 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
@@ -272,7 +495,7 @@ This creates 9 endpoints:
 | GET    | `/users/`    | List with pagination            |
 | POST   | `/users/`    | Bulk insert (`{ data: [...] }`) |
 | PUT    | `/users/`    | Bulk update (`{ data: [...] }`) |
-| DELETE | `/users/`    | Bulk delete                     |
+| DELETE | `/users/`    | Bulk delete `{ name: "Bob" }`   |
 
 ### 4. Payload Override
 
@@ -379,7 +602,7 @@ await users.remove({ name: "Bob" });
 
 Filters use a nested array structure: `[OR_groups[AND_conditions[column, operator, value]]]`
 
-Supported operators: `=`, `like`, `not like`, `in`, `not in`, `<`, `>`, `<=`, `>=`, `!=`
+Supported operators: `=`, `!=`, `<`, `>`, `<=`, `>=`, `LIKE`, `NOT LIKE`, `IN`, `NOT IN`
 
 ```js
 // Find users named Alice OR aged > 30
@@ -397,6 +620,31 @@ const result = await db.get("users", [
 ]);
 ```
 
+### Query Parameter Filter Operators
+
+When using `GET /` (list endpoint), query parameters are automatically parsed into filter conditions. Special value prefixes and patterns control the SQL operator used:
+
+| Query Param Value      | Operator   | Example URL                   | Resulting Filter                     |
+| ---------------------- | ---------- | ----------------------------- | ------------------------------------ |
+| `value`                | `=`        | `?name=john`                  | `name = 'john'`                      |
+| `!value`               | `!=`       | `?name=!john`                 | `name != 'john'`                     |
+| `>value`               | `>`        | `?age=>25`                    | `age > 25`                           |
+| `>=value` (use `>%3D`) | `>=`       | `?age=>%3D25`                 | `age >= 25`                          |
+| `<value`               | `<`        | `?age=<25`                    | `age < 25`                           |
+| `<=value` (use `<%3D`) | `<=`       | `?age=<%3D25`                 | `age <= 25`                          |
+| `%value%` (use `%25`)  | `LIKE`     | `?name=%25john%25`            | `name LIKE '%john%'`                 |
+| `!%value%`             | `NOT LIKE` | `?name=!%25john%25`           | `name NOT LIKE '%john%'`             |
+| `in(a,b,c)`            | `IN`       | `?status=in(active,pending)`  | `status IN ('active','pending')`     |
+| `!in(a,b,c)`           | `NOT IN`   | `?status=!in(active,pending)` | `status NOT IN ('active','pending')` |
+
+**Notes:**
+
+- `%` must be URL-encoded as `%25` in query strings. After URL decoding, the `%` character triggers `LIKE` detection.
+- `=` in `>=` and `<=` must be URL-encoded as `%3D` (e.g. `>%3D25` for `>=25`).
+- `LIKE` patterns follow SQL conventions: `%25john%25` → contains "john", `%25john` → ends with "john", `john%25` → starts with "john".
+- `IN` and `NOT IN` values are comma-separated inside parentheses.
+  Operators are detected in order of specificity: `!in(...)` → `in(...)` → `!%...%` → `%...%` → `>=` → `<=` → `>` → `<` → `!value` → `=` (default).
+
 ## Switching Adapters
 
 To use a different database, call `init()` before `db.connect()`:
@@ -453,4 +701,14 @@ Apache-2.0
 
 ## LLM Skill Reference
 
-For AI/LLM integration, see the [Skill Reference](./docs/SKILL.md) — a structured document covering the full API surface, patterns, constraints, and connection configs for all adapters.
+For AI/LLM integration, see the [Skill Reference](./skill/SKILL.md) — a structured document covering the full API surface, patterns, constraints, and connection configs for all adapters.
+
+### Add the Skill to Your AI Assistant
+
+You can install the db-model-router skill directly into any compatible AI assistant using:
+
+```bash
+npx skills add https://github.com/AvinashSKaranth/db-model-router/skill
+```
+
+Once installed, your AI assistant will automatically know how to scaffold projects, generate models and routes, write migrations, and work with all 10 supported database adapters.

package/TODO.md

@@ -0,0 +1,14 @@
+in generate --db-manager should generate
+DB manager using ejs db manager in the generated codebase (dark theme)
+There is login page with just password -> Needs to login status in session (req.session["db-manager"])
+the password will be in .env as DATABASE_MANAGER_PASSWORD
+Then db manager page
+Left sidebar will have list of tables with local search
+Main page will have 3 tabs
+
+1. Table Structure
+2. Data top 30 rows with filter,sort,pagenation
+3. Query page where user can type the raw query
+   This needs to added in route like /database
+
+The api that this will use is POST /database/login, GET /database/tables, GET /database/tables/:table_name?sort=1&size=30&post_name=%title%