db-model-router 1.0.4 → 1.0.6

package/README.md

@@ -14,7 +14,11 @@ 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
 
@@ -97,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
 {
@@ -127,7 +155,8 @@ Instead of running multiple CLI commands manually, you can define your entire pr
       "timestamps": {
         "created_at": "created_at",
         "modified_at": "updated_at"
-      }
+      },
+      "parent": null
     },
     "posts": {
       "columns": {
@@ -139,16 +168,35 @@ Instead of running multiple CLI commands manually, you can define your entire pr
         "modified_at": "datetime"
       },
       "pk": "post_id",
-      "unique": ["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": "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                                                              |
 | ------------ | -------- | ------------------------------------------------------------------------ |
@@ -157,12 +205,23 @@ Table entries support these fields:
 | `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             |
+
+#### Column Rules
 
-Column rules use the format `(required|)?(string|integer|numeric|boolean|object|datetime|auto_increment)`.
+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
+| 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`
 
@@ -436,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
 
@@ -543,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
@@ -561,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()`:
@@ -617,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,15 @@
+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%
+the UI should be able to filter,sort and move through the pages

package/dbmr.schema.json

@@ -0,0 +1,333 @@
+{
+  "adapter": "sqlite3",
+  "framework": "express",
+  "options": {
+    "session": "memory",
+    "rateLimiting": true,
+    "helmet": true,
+    "logger": true,
+    "loki": false
+  },
+  "tables": {
+    "users": {
+      "columns": {
+        "user_id": "auto_increment",
+        "name": "required|string",
+        "email": "required|string",
+        "password_hash": "required|string",
+        "phone": "string",
+        "avatar_url": "string",
+        "role": "required|string",
+        "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"
+      },
+      "parent": null
+    },
+    "addresses": {
+      "columns": {
+        "address_id": "auto_increment",
+        "user_id": "required|integer",
+        "label": "string",
+        "line1": "required|string",
+        "line2": "string",
+        "city": "required|string",
+        "state": "required|string",
+        "postal_code": "required|string",
+        "country": "required|string",
+        "is_default": "boolean",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "address_id",
+      "unique": ["address_id"],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": null
+    },
+    "categories": {
+      "columns": {
+        "category_id": "auto_increment",
+        "name": "required|string",
+        "slug": "required|string",
+        "description": "string",
+        "parent_category_id": "integer",
+        "image_url": "string",
+        "sort_order": "integer",
+        "is_active": "boolean",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "category_id",
+      "unique": ["slug"],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": null
+    },
+    "products": {
+      "columns": {
+        "product_id": "auto_increment",
+        "category_id": "required|integer",
+        "name": "required|string",
+        "slug": "required|string",
+        "description": "string",
+        "short_description": "string",
+        "sku": "required|string",
+        "price": "required|numeric",
+        "compare_at_price": "numeric",
+        "cost_price": "numeric",
+        "currency": "required|string",
+        "stock_quantity": "required|integer",
+        "low_stock_threshold": "integer",
+        "weight": "numeric",
+        "weight_unit": "string",
+        "is_active": "boolean",
+        "is_featured": "boolean",
+        "is_deleted": "boolean",
+        "meta": "object",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "product_id",
+      "unique": ["sku", "slug"],
+      "softDelete": "is_deleted",
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": null
+    },
+    "product_images": {
+      "columns": {
+        "product_image_id": "auto_increment",
+        "product_id": "required|integer",
+        "url": "required|string",
+        "alt_text": "string",
+        "sort_order": "integer",
+        "is_primary": "boolean",
+        "created_at": "datetime"
+      },
+      "pk": "product_image_id",
+      "unique": ["product_image_id"],
+      "timestamps": {
+        "created_at": "created_at"
+      },
+      "parent": "products"
+    },
+    "product_variants": {
+      "columns": {
+        "variant_id": "auto_increment",
+        "product_id": "required|integer",
+        "name": "required|string",
+        "sku": "required|string",
+        "price": "required|numeric",
+        "stock_quantity": "required|integer",
+        "attributes": "object",
+        "is_active": "boolean",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "variant_id",
+      "unique": ["sku"],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": "products"
+    },
+    "product_reviews": {
+      "columns": {
+        "review_id": "auto_increment",
+        "product_id": "required|integer",
+        "user_id": "required|integer",
+        "rating": "required|integer",
+        "title": "string",
+        "body": "string",
+        "is_verified": "boolean",
+        "is_approved": "boolean",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "review_id",
+      "unique": ["review_id"],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": "products"
+    },
+    "carts": {
+      "columns": {
+        "cart_id": "auto_increment",
+        "user_id": "integer",
+        "session_id": "string",
+        "currency": "required|string",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "cart_id",
+      "unique": ["cart_id"],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": null
+    },
+    "cart_items": {
+      "columns": {
+        "cart_item_id": "auto_increment",
+        "cart_id": "required|integer",
+        "product_id": "required|integer",
+        "variant_id": "integer",
+        "quantity": "required|integer",
+        "unit_price": "required|numeric",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "cart_item_id",
+      "unique": ["cart_item_id"],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": "carts"
+    },
+    "orders": {
+      "columns": {
+        "order_id": "auto_increment",
+        "user_id": "required|integer",
+        "order_number": "required|string",
+        "status": "required|string",
+        "subtotal": "required|numeric",
+        "tax_amount": "required|numeric",
+        "shipping_amount": "required|numeric",
+        "discount_amount": "numeric",
+        "total": "required|numeric",
+        "currency": "required|string",
+        "shipping_address_id": "integer",
+        "billing_address_id": "integer",
+        "notes": "string",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "order_id",
+      "unique": ["order_number"],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": null
+    },
+    "order_items": {
+      "columns": {
+        "order_item_id": "auto_increment",
+        "order_id": "required|integer",
+        "product_id": "required|integer",
+        "variant_id": "integer",
+        "product_name": "required|string",
+        "sku": "required|string",
+        "quantity": "required|integer",
+        "unit_price": "required|numeric",
+        "total_price": "required|numeric",
+        "created_at": "datetime"
+      },
+      "pk": "order_item_id",
+      "unique": ["order_item_id"],
+      "timestamps": {
+        "created_at": "created_at"
+      },
+      "parent": "orders"
+    },
+    "payments": {
+      "columns": {
+        "payment_id": "auto_increment",
+        "order_id": "required|integer",
+        "method": "required|string",
+        "provider": "string",
+        "provider_transaction_id": "string",
+        "amount": "required|numeric",
+        "currency": "required|string",
+        "status": "required|string",
+        "paid_at": "datetime",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "payment_id",
+      "unique": ["payment_id"],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": "orders"
+    },
+    "shipments": {
+      "columns": {
+        "shipment_id": "auto_increment",
+        "order_id": "required|integer",
+        "carrier": "required|string",
+        "tracking_number": "string",
+        "status": "required|string",
+        "shipped_at": "datetime",
+        "delivered_at": "datetime",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "shipment_id",
+      "unique": ["shipment_id"],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": "orders"
+    },
+    "coupons": {
+      "columns": {
+        "coupon_id": "auto_increment",
+        "code": "required|string",
+        "description": "string",
+        "discount_type": "required|string",
+        "discount_value": "required|numeric",
+        "min_order_amount": "numeric",
+        "max_uses": "integer",
+        "used_count": "integer",
+        "starts_at": "datetime",
+        "expires_at": "datetime",
+        "is_active": "boolean",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "coupon_id",
+      "unique": ["code"],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": null
+    },
+    "wishlists": {
+      "columns": {
+        "wishlist_id": "auto_increment",
+        "user_id": "required|integer",
+        "product_id": "required|integer",
+        "created_at": "datetime"
+      },
+      "pk": "wishlist_id",
+      "unique": ["wishlist_id"],
+      "timestamps": {
+        "created_at": "created_at"
+      },
+      "parent": null
+    }
+  }
+}

package/docker-compose.yml

@@ -128,7 +128,7 @@ services:
       - db-network
 
   oracle:
-    image: gvenzl/oracle-xe:21-slim
+    image: gvenzl/oracle-free
     container_name: db-model-router-oracle
     restart: unless-stopped
     ports:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "db-model-router",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Generative API Creation using mysql2 and express libraries in node js",
   "main": "src/index.js",
   "bin": {
@@ -20,7 +20,8 @@
     "test:mssql": "dotenv -e env/.env.mssql -- mocha test/adapters/mssql.*.test.js --timeout 30000 --exit",
     "test:properties": "mocha test/properties/*.property.test.js --timeout 30000 --exit",
     "test:all": "mocha test/adapters/*.test.js test/properties/*.property.test.js test/function.test.js --timeout 30000 --exit",
-    "clean:demo": "rm -rf demo/* demo/.*"
+    "demo:clear": "node -e \"var fs=require('fs'),p=require('path'),d=p.join(__dirname,'demo');fs.existsSync(d)&&fs.rmSync(d,{recursive:true,force:true});fs.mkdirSync(d,{recursive:true})\"",
+    "demo:create": "node scripts/demo-create.js"
   },
   "repository": {
     "type": "git",
@@ -54,14 +55,14 @@
     "node-input-validator": "^4.5.0"
   },
   "peerDependencies": {
-    "@aws-sdk/client-dynamodb": "^3.1029.0",
-    "@aws-sdk/lib-dynamodb": "^3.1029.0",
+    "@aws-sdk/client-dynamodb": "^3.1039.0",
+    "@aws-sdk/lib-dynamodb": "^3.1039.0",
     "better-sqlite3": "^12.9.0",
     "express": "^4.17.2 || ^5.0.0",
     "ioredis": "^5.10.1",
-    "mongodb": "^7.1.1",
-    "mssql": "^12.2.1",
-    "mysql2": "^3.14.4",
+    "mongodb": "^7.2.0",
+    "mssql": "^12.5.0",
+    "mysql2": "^3.22.3",
     "oracledb": "^6.10.0",
     "pg": "^8.20.0",
     "ultimate-express": "^2.0.0"

package/scripts/demo-create.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const ROOT = path.resolve(__dirname, "..");
+const DEMO = path.join(ROOT, "demo");
+
+// 1. Clear demo folder
+if (fs.existsSync(DEMO)) {
+  fs.rmSync(DEMO, { recursive: true, force: true });
+}
+fs.mkdirSync(DEMO, { recursive: true });
+
+const run = (cmd, cwd) => {
+  console.log(`\n> ${cmd}`);
+  execSync(cmd, { cwd, stdio: "inherit" });
+};
+
+// 2. Scaffold project with sqlite3
+run("node ../src/cli/main.js init --database sqlite3 --yes --no-install", DEMO);
+
+// 3. Copy schema and patch adapter to sqlite3
+const schema = JSON.parse(
+  fs.readFileSync(path.join(ROOT, "dbmr.schema.json"), "utf8"),
+);
+schema.adapter = "sqlite3";
+if (schema.options) {
+  delete schema.options.session;
+  delete schema.options.loki;
+}
+fs.writeFileSync(
+  path.join(DEMO, "dbmr.schema.json"),
+  JSON.stringify(schema, null, 2) + "\n",
+);
+console.log("\n> Copied and patched dbmr.schema.json (adapter → sqlite3)");
+
+// 4. Generate models, routes, tests, openapi from schema
+run("node ../src/cli/main.js generate --from dbmr.schema.json", DEMO);
+
+// 5. Install dependencies
+run("npm install", DEMO);
+
+console.log("\n✔ Demo project ready in ./demo");
+console.log("  cd demo && npm run dev\n");