db-model-router 1.0.6 → 1.0.7

package/README.md

@@ -373,21 +373,38 @@ db-model-router inspect --type mysql --json
 
 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`) |
+| Flag / Arg               | Description                                       |
+| ------------------------ | ------------------------------------------------- |
+| `--from <path>`          | Path to schema file (default: `dbmr.schema.json`) |
+| `--models=false`         | Disable model file generation                     |
+| `--routes=false`         | Disable route file generation                     |
+| `--openapi=false`        | Disable OpenAPI spec generation                   |
+| `--tests=false`          | Disable test file generation                      |
+| `--migrations=false`     | Disable migration file generation                 |
+| `--saas-structure=false` | Disable SaaS multi-tenant generation              |
 
-When no artifact flags are provided, all artifact types are generated.
+All artifact types are **enabled by default**. Use `--flag=false` to disable specific ones.
+
+##### `--saas-structure` — SaaS Multi-Tenant Architecture (default: enabled)
+
+The SaaS structure is always generated unless explicitly disabled with `--saas-structure=false`. It scaffolds a complete multi-tenant SaaS backend on top of your schema-generated code:
+
+- **Tables**: `tenants`, `users`, `roles`, `role_permissions`, `webhooks`, `webhook_logs`
+- **Middleware**: `authenticate`, `tenantIsolation`, `hasPermission`
+- **Routes**: CRUD for users/tenants/roles/permissions + auth (login/logout)
+- **Utilities**: password hashing (crypto.scrypt), modules registry, webhook delivery with retry
+- **Seeds**: Super Admin user + Tenant Admin role template
+- **Migrations**: Single consolidated migration file for all SaaS tables
+
+> **Important**: Since `--saas-structure` is on by default, the tables `users`, `tenants`, `roles`, and `role_permissions` are already generated with their models, routes, and migrations. **Do not add these tables to your `dbmr.schema.json`** — they will be duplicated. Only define your product/domain-specific tables in the schema (e.g., `products`, `orders`, `invoices`).
+
+The generated `routes/index.js` automatically combines both SaaS routes (under `/api/auth`, `/api/users`, `/api/tenants`, `/api/roles`) and your schema-generated product routes. The OpenAPI/Swagger docs include all SaaS endpoints with security annotations.
 
 ```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 --tests=false --dry-run       # skip tests
+db-model-router generate --saas-structure=false        # skip SaaS generation
+db-model-router generate --openapi=false --tests=false # skip OpenAPI and tests
 db-model-router generate --from dbmr.schema.json --json
 ```
 
@@ -429,6 +446,32 @@ db-model-router help init         # detailed help for init
 db-model-router init --help       # same as above
 ```
 
+## DB Manager
+
+A built-in database management dashboard accessible via the CLI. Connects to any supported SQL database and provides a visual interface for browsing tables, editing data, running queries, and viewing history.
+
+### Launch
+
+```bash
+db-model-router db-manager [--env .env] [--port 4000]
+```
+
+| Flag / Arg     | Description                             |
+| -------------- | --------------------------------------- |
+| `--env <path>` | Path to `.env` file with DB credentials |
+| `--port <n>`   | Server port (default: 4000)             |
+
+### Features
+
+- **Dashboard** — Overview of all tables with column count, index count, row count, and size
+- **Table Browser** — Browse, filter, sort, add, edit, and delete rows with pagination
+- **Query Editor** — Execute raw SQL queries with results table and CSV export
+- **Query History** — View previously executed queries with timestamps
+- **Theme Support** — Light, Dark, and System (auto-detect) modes with persistent preference
+- **Filter System** — Column-level filters with operators (=, !=, like, not like, <, >, <=, >=)
+- **Inline Editing** — Edit rows directly in the table without a separate form
+- **CSV Export** — Export selected rows or query results to CSV
+
 ## MySQL Example
 
 ### 1. Connect
@@ -645,6 +688,102 @@ When using `GET /` (list endpoint), query parameters are automatically parsed in
 - `IN` and `NOT IN` values are comma-separated inside parentheses.
   Operators are detected in order of specificity: `!in(...)` → `in(...)` → `!%...%` → `%...%` → `>=` → `<=` → `>` → `<` → `!value` → `=` (default).
 
+## Kafka Event Production
+
+db-model-router has built-in Kafka support. When enabled, every write operation (insert, update, upsert, delete) automatically produces a Kafka event — one event per row affected.
+
+### Setup
+
+Install the Kafka driver:
+
+```bash
+npm install kafkajs
+```
+
+Set the `KAFKA_BROKER` environment variable in your `.env`:
+
+```env
+KAFKA_BROKER=localhost:9092
+KAFKA_CLIENT_ID=my-app
+KAFKA_TOPIC_PREFIX=dbmr
+```
+
+### Initialize
+
+```js
+const { init, db, kafka } = require("db-model-router");
+
+init("postgres");
+db.connect({ host: "localhost", database: "my_app" });
+
+// Connect Kafka producer (only if KAFKA_BROKER is set)
+await kafka.init();
+```
+
+Or with explicit options:
+
+```js
+await kafka.init({
+  broker: "localhost:9092",
+  clientId: "my-app",
+  topicPrefix: "dbmr",
+});
+```
+
+### API
+
+| Method                                  | Description                                  |
+| --------------------------------------- | -------------------------------------------- |
+| `kafka.init(opts)`                      | Connect producer. Returns `true` on success. |
+| `kafka.disconnect()`                    | Graceful shutdown.                           |
+| `kafka.produce(table, operation, data)` | Manually produce an event.                   |
+| `kafka.status()`                        | Returns `true` if connected.                 |
+
+### Event Format
+
+Each affected row produces its own event to topic `{prefix}.{table_name}`:
+
+```json
+{
+  "table_name": "users",
+  "operation_type": "insert",
+  "data": { "id": 1, "name": "Alice", "email": "alice@example.com" },
+  "timestamp": "2026-05-09T12:00:00.000Z"
+}
+```
+
+- `operation_type`: `"insert"`, `"update"`, `"upsert"`, or `"delete"`
+- `data`: The affected row as an object (not an array)
+- Bulk operations (e.g. inserting 100 rows) produce 100 individual events, batched efficiently
+
+### Behavior
+
+- If `KAFKA_BROKER` is not set, Kafka is completely disabled with zero overhead
+- Events are produced after successful DB operations only
+- Read operations (`find`, `list`, `byId`) never produce events
+- Large batches are automatically chunked (500 messages per send) to stay within Kafka's message size limits
+- Failed event production logs a warning but does not throw or affect the API response
+
+### Docker
+
+The included `docker-compose.yml` provides Zookeeper, Kafka, and Kafka UI:
+
+```bash
+docker compose up -d zookeeper kafka kafka-ui
+```
+
+| Service   | Port | Description                       |
+| --------- | ---- | --------------------------------- |
+| Zookeeper | 2181 | Kafka coordination                |
+| Kafka     | 9092 | Broker (host) / 29092 (internal)  |
+| Kafka UI  | 8090 | Web dashboard for topics/messages |
+
+### Testing
+
+```bash
+npm run test:kafka   # uses env/.env.kafka (SQLite3 + Kafka broker)
+```
+
 ## Switching Adapters
 
 To use a different database, call `init()` before `db.connect()`:

package/TODO.md

@@ -1,15 +0,0 @@
-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/db-manager/README.md

@@ -0,0 +1,223 @@
+# DB Manager — Testing Guide
+
+A live database management UI launched via `npx db-model-router db-manager`. This guide covers how to test it against each supported database using Docker.
+
+## Prerequisites
+
+- Docker and Docker Compose installed
+- Node.js 18+
+- npm dependencies installed (`npm install` from the project root)
+
+## Quick Start (SQLite — no Docker needed)
+
+SQLite requires no external services. Run these commands from the project root:
+
+```bash
+# Seed the demo SQLite database
+sqlite3 ./db-manager/demo/demo.sqlite < ./db-manager/demo/seeds/sqlite3.sql
+
+# Start the DB Manager
+npx db-model-router db-manager --env ./db-manager/demo/sqlite3.env
+```
+
+Open http://localhost:4000 in your browser.
+
+## Testing with Docker Databases
+
+### 1. Start Docker Services
+
+From the project root, start all database containers:
+
+```bash
+# Start all services
+docker compose up -d
+
+# Or start a specific service
+docker compose up -d mysql
+docker compose up -d postgres
+docker compose up -d mssql
+docker compose up -d mongodb
+docker compose up -d redis
+docker compose up -d cockroachdb
+docker compose up -d oracle
+docker compose up -d dynamodb
+```
+
+Wait for the containers to be healthy:
+
+```bash
+docker compose ps
+```
+
+### 2. Seed the Databases
+
+Run the seed scripts to create sample tables (`users`, `products`) with test data.
+
+#### MySQL
+
+```bash
+docker exec -i db-model-router-mysql mysql -uroot -ppassword test_db < ./db-manager/demo/seeds/mysql.sql
+```
+
+#### PostgreSQL
+
+```bash
+docker exec -i db-model-router-postgres psql -U postgres -d test_db < ./db-manager/demo/seeds/postgres.sql
+```
+
+#### MSSQL
+
+```bash
+docker exec -i db-model-router-mssql /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "Password123!" -d master -C -i /dev/stdin < ./db-manager/demo/seeds/mssql.sql
+```
+
+#### CockroachDB
+
+```bash
+docker exec -i db-model-router-cockroachdb cockroach sql --insecure --database=defaultdb < ./db-manager/demo/seeds/cockroachdb.sql
+```
+
+#### Oracle
+
+```bash
+docker exec -i db-model-router-oracle sqlplus system/oracle@//localhost:1521/FREEPDB1 < ./db-manager/demo/seeds/oracle.sql
+```
+
+#### SQLite (no Docker)
+
+```bash
+sqlite3 ./db-manager/demo/demo.sqlite < ./db-manager/demo/seeds/sqlite3.sql
+```
+
+> **Note:** MongoDB, Redis, and DynamoDB do not use SQL seeds. They will work with the DB Manager once data is inserted through the UI.
+
+### 3. Launch the DB Manager
+
+Run from the project root. Use the `--env` flag to point to the appropriate demo env file.
+
+#### MySQL
+
+```bash
+npx db-model-router db-manager --env ./db-manager/demo/mysql.env
+```
+
+#### PostgreSQL
+
+```bash
+npx db-model-router db-manager --env ./db-manager/demo/postgres.env
+```
+
+#### MSSQL
+
+```bash
+npx db-model-router db-manager --env ./db-manager/demo/mssql.env
+```
+
+#### CockroachDB
+
+```bash
+npx db-model-router db-manager --env ./db-manager/demo/cockroachdb.env
+```
+
+#### Oracle
+
+```bash
+npx db-model-router db-manager --env ./db-manager/demo/oracle.env
+```
+
+#### MongoDB
+
+```bash
+npx db-model-router db-manager --env ./db-manager/demo/mongodb.env
+```
+
+#### Redis
+
+```bash
+npx db-model-router db-manager --env ./db-manager/demo/redis.env
+```
+
+#### DynamoDB
+
+```bash
+npx db-model-router db-manager --env ./db-manager/demo/dynamodb.env
+```
+
+#### SQLite
+
+```bash
+npx db-model-router db-manager --env ./db-manager/demo/sqlite3.env
+```
+
+### 4. Custom Port
+
+Use the `--port` flag to run on a different port:
+
+```bash
+npx db-model-router db-manager --env ./db-manager/demo/postgres.env --port 5000
+```
+
+## CLI Flags
+
+| Flag              | Default | Description                                      |
+| ----------------- | ------- | ------------------------------------------------ |
+| `--env <path>`    | `.env`  | Path to the environment file with DB credentials |
+| `--port <number>` | `4000`  | Port for the web UI                              |
+
+## Running Tests
+
+From the project root:
+
+```bash
+# Run all tests (unit + integration + property tests)
+npm test
+
+# Run only the DB Manager property tests
+npx mocha test/properties/db-manager.property.test.js --timeout 15000 --exit
+
+# Run only the DB Manager integration tests
+npx mocha test/integration/db-manager-app.test.js --timeout 15000 --exit
+
+# Run only the DB Manager CLI unit tests
+npx mocha test/commands/db-manager.test.js --timeout 15000 --exit
+```
+
+## Stopping Docker Services
+
+```bash
+# Stop all services
+docker compose down
+
+# Stop and remove volumes (clean slate)
+docker compose down -v
+```
+
+## Demo Environment Files
+
+Located in `db-manager/demo/`:
+
+| File              | Database       | Host      | Port  |
+| ----------------- | -------------- | --------- | ----- |
+| `sqlite3.env`     | SQLite3        | —         | —     |
+| `mysql.env`       | MySQL 8.0      | localhost | 3306  |
+| `postgres.env`    | PostgreSQL 16  | localhost | 5432  |
+| `mssql.env`       | SQL Server     | localhost | 1433  |
+| `cockroachdb.env` | CockroachDB    | localhost | 26257 |
+| `oracle.env`      | Oracle Free    | localhost | 1521  |
+| `mongodb.env`     | MongoDB 7      | localhost | 27017 |
+| `redis.env`       | Redis 7        | localhost | 6379  |
+| `dynamodb.env`    | DynamoDB Local | localhost | 8000  |
+
+## Seed Data
+
+SQL seed files are in `db-manager/demo/seeds/`. Each creates two tables:
+
+- **users** — id, name, email, created_at (5 sample rows)
+- **products** — id, name, price, stock, created_at (5 sample rows)
+
+## Troubleshooting
+
+- **Port already in use**: Use `--port` to pick a different port
+- **Connection refused**: Make sure the Docker container is running and healthy (`docker compose ps`)
+- **Oracle slow to start**: Oracle can take 60–90 seconds to initialize. Wait for the healthcheck to pass
+- **MSSQL tools path**: If the seed command fails, try `/opt/mssql-tools/bin/sqlcmd` instead of `/opt/mssql-tools18/bin/sqlcmd`