db-model-router 1.0.14 → 1.0.16

package/.codegraph/.gitignore

@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore

package/.serena/project.yml

@@ -0,0 +1,133 @@
+# the name by which the project can be referenced within Serena
+project_name: "db-model-router"
+
+
+# list of languages for which language servers are started; choose from:
+#   al                  angular             ansible             bash                clojure
+#   cpp                 cpp_ccls            crystal             csharp              csharp_omnisharp
+#   dart                elixir              elm                 erlang              fortran
+#   fsharp              go                  groovy              haskell             haxe
+#   hlsl                html                java                json                julia
+#   kotlin              lean4               lua                 luau                markdown
+#   matlab              msl                 nix                 ocaml               pascal
+#   perl                php                 php_phpactor        powershell          python
+#   python_jedi         python_ty           r                   rego                ruby
+#   ruby_solargraph     rust                scala               scss                solidity
+#   svelte              swift               systemverilog       terraform           toml
+#   typescript          typescript_vts      vue                 yaml                zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root)
+#   - For Svelte projects, use svelte (subsumes typescript/javascript for .svelte projects; requires npm)
+#   - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three)
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some languages require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- typescript
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# The language backend to use for this project.
+# If not set, the global setting from serena_config.yml is used.
+# Valid values: LSP, JetBrains
+# Note: the backend is fixed at startup. If a project with a different backend
+# is activated post-init, an error will be returned.
+language_backend:
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
+# No documentation on options means no options are available.
+ls_specific_settings: {}
+
+# list of additional workspace folder paths for cross-package reference support (e.g. in monorepos).
+# Paths can be absolute or relative to the project root.
+# Each folder is registered as an LSP workspace folder, enabling language servers to discover
+# symbols and references across package boundaries.
+# Currently supported for: TypeScript.
+# Example:
+#   additional_workspace_folders:
+#     - ../sibling-package
+#     - ../shared-lib
+additional_workspace_folders: []
+
+# list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Note: global ignored_paths from serena_config.yml are also applied additively.
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+excluded_tools: []
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+fixed_tools: []
+
+# list of mode names that are to be activated by default, overriding the setting in the global configuration.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
+# for this project.
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+default_modes:
+
+# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+added_modes:
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+# time budget (seconds) per tool call for the retrieval of additional symbol information
+# such as docstrings or parameter information.
+# This overrides the corresponding setting in the global configuration; see the documentation there.
+# If null or missing, use the setting from the global configuration.
+symbol_info_budget:
+
+# list of regex patterns which, when matched, mark a memory entry as read‑only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []

package/README.md

@@ -205,6 +205,7 @@ Note: `comments` has `user_id` as a foreign key column but `users` is NOT its pa
 | `unique`     | No       | Unique constraint columns. Flat array = one composite group; array-of-arrays = multiple independent constraints. Defaults to `[[pk]]`. |
 | `softDelete` | No       | Column name used for soft-delete                                         |
 | `timestamps` | No       | Object with `created_at` and `modified_at` column name mapping           |
+| `search_columns` | No  | Array of column names targeted by the `search=` query param (multi-column OR `LIKE`). Each entry must reference an existing column. |
 | `parent`     | No       | Parent table name for route nesting, or `null` for top-level             |
 
 #### Column Rules
@@ -528,7 +529,10 @@ const users = model(
   },
   "id", // primary key column
   ["id"], // unique key columns
-  { safeDelete: "is_deleted" }, // optional: soft-delete column
+  {
+    safeDelete: "is_deleted", // optional: soft-delete column
+    search_columns: ["name", "email"], // optional: columns searched by ?search=
+  },
 );
 ```
 
@@ -632,6 +636,10 @@ const user = await users.byId(1);
 ```js
 const result = await users.find({ name: "Alice" });
 // => { data: [{ id: 1, name: "Alice", ... }], count: 1 }
+
+// Free-text search across the model's search_columns (OR between columns)
+const found = await users.find({ search: "alice", status: "active" });
+// => rows where (name LIKE %alice% OR email LIKE %alice%) AND status = 'active'
 ```
 
 ### findOne(filter)
@@ -639,6 +647,9 @@ const result = await users.find({ name: "Alice" });
 ```js
 const user = await users.findOne({ email: "alice@example.com" });
 // => { id: 1, ... } or false
+
+// findOne also accepts `search` (returns the first matching row)
+const user = await users.findOne({ search: "alice" });
 ```
 
 ### list(options)
@@ -649,6 +660,9 @@ const page = await users.list({ page: 0, size: 10 });
 
 // With filter
 const filtered = await users.list({ name: "Ali", page: 0 });
+
+// With multi-column search (requires search_columns on the model)
+const searched = await users.list({ search: "alice", page: 0 });
 ```
 
 ### remove(idOrFilter)
@@ -705,6 +719,36 @@ When using `GET /` (list endpoint), query parameters are automatically parsed in
 - `%` 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".
+
+### Multi-Column Search (`?search=`)
+
+`search` is a reserved query parameter for free-text matching across multiple columns at once. It is enabled per-model via the `search_columns` option (an array of column names). When present, the term is matched as a substring (`LIKE %term%`) against **any** of the configured columns, OR-joined, and **AND-combined** with any other filters in the same request.
+
+```js
+// Enable search on the model (programmatic or via dbmr.schema.json)
+const users = model(db, "users", structure, "id", ["id"], {
+  search_columns: ["name", "description", "email"],
+});
+```
+
+```bash
+# Match rows where (name OR description OR email) contains "alice" AND status = 'active'
+GET /users/?search=alice&status=active
+
+# Pure search across columns
+GET /users/?search=alice
+```
+
+**Semantics:**
+
+- `search` is OR-joined across `search_columns`: `(col0 LIKE %term% OR col1 LIKE %term% OR ...)`.
+- `search` is AND-combined with other query filters: the above matches rows that satisfy the search **and** `status = 'active'`.
+- Works on `find`, `findOne`, and `list` (and their `GET /:id` and `GET /` routes). `findOne` returns the first matching row.
+- Matching is **contains** (substring) in every adapter. Case sensitivity is adapter-native: PostgreSQL (`ILIKE`), MongoDB (`$regex i`), and Redis (`String.includes`) are case-insensitive; MySQL depends on column collation; DynamoDB `contains()` is case-sensitive; SQLite3 `LIKE` is case-insensitive for ASCII.
+- Empty/whitespace `search` is ignored (normal filter behavior). If `search` is sent but `search_columns` is not configured, `search` is silently dropped (never treated as a column filter, never causes a 422).
+- `search_columns` is **config-only** — it is set on the model option / in `dbmr.schema.json` and cannot be overridden per request (clients cannot target arbitrary columns).
+- Multi-term search (`search=alice bob`) matches the literal substring `alice bob` per column. Tokenized/word-boundary search is not supported.
+- In SQL adapters, `%` and `_` in the search term act as `LIKE` wildcards; MongoDB/Redis/DynamoDB match the term literally (MongoDB also escapes regex metacharacters).
 - `IN` and `NOT IN` values are comma-separated inside parentheses.
   Operators are detected in order of specificity: `!in(...)` → `in(...)` → `!%...%` → `%...%` → `>=` → `<=` → `>` → `<` → `!value` → `=` (default).
 

package/docs/adapters/postgres.md

@@ -35,6 +35,7 @@ PG_DB=test_db
 - `SERIAL` / `BIGSERIAL` primary keys are auto-detected via `pg_index`
 - `ON CONFLICT` is used for upsert operations
 - Includes a SQL translator layer that converts common MySQL DDL/DML to PostgreSQL syntax
+- `like` / `not like` filter operators (and the `?search=` parameter) compile to **`ILIKE` / `NOT ILIKE`** — case-insensitive substring matching. The value is wrapped as `%term%`.
 
 ## Table Creation
 

package/docs/dbmr-schema-spec.md

@@ -40,6 +40,7 @@ Each entry in `tables` is a Table Definition object:
   "pk": "product_id",
   "unique": ["sku"],
   "softDelete": "is_deleted",
+  "search_columns": ["name", "description"],
   "timestamps": {
     "created_at": "created_at",
     "modified_at": "modified_at"
@@ -54,6 +55,7 @@ Each entry in `tables` is a Table Definition object:
 | `pk`         | Yes      | Primary key column name. Convention: `<table>_id` (e.g. `user_id`, `order_id`).                 |
 | `unique`     | No       | Unique constraint columns. A flat array creates one composite unique group; an array-of-arrays creates multiple independent constraints. Defaults to `[[pk]]`. |
 | `softDelete` | No       | Column name used for soft-delete. When set, `remove()` updates this column to `1`/`true` instead of hard-deleting. |
+| `search_columns` | No  | Array of column names targeted by the `search=` query parameter (multi-column OR `LIKE`). Each entry must reference an existing column. Empty/absent disables search. |
 | `timestamps` | No       | Object mapping `{ created_at: "col_name", modified_at: "col_name" }`. These columns are auto-excluded from insert/update payloads. |
 | `parent`     | No       | Parent table name for route nesting, or `null` for a top-level route.                           |
 
@@ -444,12 +446,14 @@ const products = model(
   },
   "product_id",
   ["sku", "slug"],
-  { safeDelete: "is_deleted" },
+  { safeDelete: "is_deleted", search_columns: ["name", "description"] },
 );
 ```
 
 The model passes these rules to `node-input-validator` on every insert/update/patch operation. Sub-types are stripped — only the base type and validators are kept in the runtime structure.
 
+`search_columns` is passed through to the model `option` and enables the `search=` query parameter (see [Multi-Column Search](#multi-column-search-search) below). It is not a column rule and is not part of `structure`.
+
 ### OpenAPI Generation
 
 Validators map to OpenAPI schema properties:
@@ -471,6 +475,38 @@ Validators map to OpenAPI schema properties:
 | `alphaNumeric`  | `pattern: "^[a-zA-Z0-9]+$"`           |
 | `alphaDash`     | `pattern: "^[a-zA-Z0-9_-]+$"`         |
 
+When a table defines `search_columns`, the OpenAPI generator adds a `search` query parameter (type `string`) to that table's `GET /` list path, with a description listing the targeted columns. Tables without `search_columns` get no `search` parameter.
+
+---
+
+## Multi-Column Search (`search_columns` / `?search=`)
+
+`search_columns` enables free-text search across multiple columns via the reserved `search` query parameter. The term is matched as a substring against any configured column (OR-joined), and AND-combined with any other filters in the same request.
+
+```json
+{
+  "products": {
+    "columns": { "product_id": "auto_increment", "name": "required|string", "description": "string", "sku": "required|string" },
+    "pk": "product_id",
+    "search_columns": ["name", "description"]
+  }
+}
+```
+
+```bash
+# (name LIKE %alice% OR description LIKE %alice%) AND sku = 'ABC'
+GET /products/?search=alice&sku=ABC
+```
+
+**Rules:**
+
+- Optional per table. If absent or empty, `search=` is ignored.
+- Each entry must be a non-empty string referencing an existing column (validated by `doctor`/`validateSchema`).
+- Applies to `find`, `findOne`, and `list` (and the `GET /:id`/`GET /` routes). `findOne` returns the first match.
+- Matching is **contains** (substring). Case sensitivity is adapter-native (PostgreSQL/MongoDB/Redis/SQLite3 case-insensitive; DynamoDB case-sensitive; MySQL depends on collation).
+- `search_columns` is config-only — set in the schema/model option, not overridable per request.
+- The `search` parameter is reserved: it is never treated as a column filter, even when `search_columns` is unset.
+
 ---
 
 ## Complete Example Schema

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "db-model-router",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "Generative API Creation using mysql2 and express libraries in node js",
   "main": "src/index.js",
   "bin": {

package/skill/SKILL.md

@@ -118,7 +118,7 @@ For adapter-specific connect options (ports, env vars, upsert behavior), read th
 | `structure` | `{col: "rule"}` | Types: `string\|integer\|numeric\|boolean\|object\|datetime\|auto_increment`. Prefix `required\|` for NOT NULL. |
 | `pk`        | string          | Primary key column. Convention: `<table>_id`                                                                    |
 | `unique`    | string[] \| string[][] | Flat array = one composite unique group; array-of-arrays = multiple independent constraints               |
-| `option`    | object          | `{ safeDelete, created_at, modified_at }` — column names or null                                                |
+| `option`    | object          | `{ safeDelete, created_at, modified_at, search_columns }` — column names or null; `search_columns` is a string[] enabling `?search=` |
 
 > PK, timestamp, soft-delete, and `auto_increment` cols are auto-excluded from insert/update payloads.
 
@@ -146,6 +146,8 @@ await m.byId(1)                                                       // → rec
 await m.find({ name: "Alice" })                                       // → {data:[], count}
 await m.findOne({ email: "a@b.com" })                                 // → record or false
 await m.list({ page: 0, size: 10, sort: ["-age"] })                   // → {data:[], count}
+// `search` works on find/findOne/list when option.search_columns is set:
+await m.list({ search: "alice", status: "active" })                   // (col0 LIKE %alice% OR ...) AND status='active'
 
 // DELETE — safeDelete: sets column=1; without: hard delete
 await m.remove(1)
@@ -197,6 +199,28 @@ When using `GET /` (list endpoint), query parameters are automatically parsed in
 
 `%` is URL-encoded as `%25`; `=` in `>=`/`<=` is URL-encoded as `%3D`. `LIKE` patterns follow SQL conventions: `%25john%25` → contains, `%25john` → ends with, `john%25` → starts with. `IN`/`NOT IN` values are comma-separated inside parentheses.
 
+### Multi-Column Search (`?search=`)
+
+`search` is a **reserved** query param for free-text matching across multiple columns. Enabled per-model via `option.search_columns` (string[]). Term is matched as **contains** (`LIKE %term%`) against any configured column, OR-joined, and AND-combined with other filters.
+
+```js
+const users = model(db, "users", structure, "id", ["id"], {
+  search_columns: ["name", "description", "email"],
+});
+```
+
+```bash
+GET /users/?search=alice&status=active
+# → (name LIKE %alice% OR description LIKE %alice% OR email LIKE %alice%) AND status='active'
+```
+
+- Works on `find`, `findOne`, `list` (and `GET /:id`, `GET /`). `findOne` returns first match.
+- Empty/whitespace `search` → ignored. `search` sent without `search_columns` → dropped (never a column filter, never 422).
+- `search_columns` is **config-only** (model option / `dbmr.schema.json`), not per-request overridable.
+- Case sensitivity is adapter-native: PostgreSQL/MongoDB/Redis/SQLite3 case-insensitive; DynamoDB case-sensitive; MySQL depends on collation.
+- Multi-term (`search=alice bob`) matches the literal substring `alice bob` per column. No tokenized search.
+- In SQL adapters `%`/`_` in the term act as `LIKE` wildcards; Mongo/Redis/DynamoDB match literally (Mongo escapes regex).
+
 ---
 
 ## route(model, override?)
@@ -217,7 +241,7 @@ Generates an Express Router with 9 endpoints:
 
 **Payload override** (multi-tenancy): `route(m, { tenant_id: "user.tenant_id" })` — maps columns to `req` paths via lodash.get.
 
-**Query params**: `select_columns=name,email`, `output_content_type=csv|xml|json`, `sort=-age,name`
+**Query params**: `select_columns=name,email`, `output_content_type=csv|xml|json`, `sort=-age,name`, `search=alice` (requires `search_columns` on the model — see Multi-Column Search above)
 
 ---
 
@@ -440,6 +464,7 @@ For the full specification, see `references/dbmr-schema-spec.md`.
 | `pk`         | Yes      | Primary key (convention: `<table>_id`)           |
 | `unique`     | No       | Unique constraint columns (default: `[pk]`)      |
 | `softDelete` | No       | Column name for soft-delete                      |
+| `search_columns` | No | String[] of columns for `?search=` (multi-col OR `LIKE`); each must exist |
 | `timestamps` | No       | `{ created_at, modified_at }` column mapping     |
 | `parent`     | No       | Parent table for route nesting, or `null`        |
 
@@ -621,3 +646,4 @@ Topic: `{KAFKA_TOPIC_PREFIX}.{table_name}` (e.g. `dbmr.users`)
 14. Use `parent` only for domain hierarchies (e.g. `posts → comments`), not system tables.
 15. When `--saas-structure` is active, do NOT define `users`, `tenants`, `roles`, or `role_permissions` in `dbmr.schema.json` — they are already generated with models, routes, middleware, and migrations. Only add your product-specific tables to the schema.
 16. Kafka is opt-in via `KAFKA_BROKER` env var. Call `kafka.init()` after `db.connect()`. Each write op produces one event per row to `{prefix}.{table}` topic.
+17. `search` is a **reserved** query param — never a column filter. It only takes effect when the model has `option.search_columns` set (config-only). It OR-joins a `LIKE %term%` across those columns and AND-combines with other filters. Works on `find`/`findOne`/`list` and the `GET /:id` + `GET /` routes.

package/skill/references/dbmr-schema-spec.md

@@ -42,6 +42,7 @@ Each entry in `tables` is a Table Definition object:
   "pk": "product_id",
   "unique": ["sku"],
   "softDelete": "is_deleted",
+  "search_columns": ["name", "description"],
   "timestamps": {
     "created_at": "created_at",
     "modified_at": "modified_at"
@@ -56,6 +57,7 @@ Each entry in `tables` is a Table Definition object:
 | `pk`         | Yes      | Primary key column name. Convention: `<table>_id` (e.g. `user_id`, `order_id`).                 |
 | `unique`     | No       | Array of column names with unique constraints. Defaults to `[pk]` if omitted.                   |
 | `softDelete` | No       | Column name used for soft-delete. When set, `remove()` updates this column to `1`/`true` instead of hard-deleting. |
+| `search_columns` | No  | Array of column names targeted by the `search=` query parameter (multi-column OR `LIKE`). Each entry must reference an existing column. Empty/absent disables search. |
 | `timestamps` | No       | Object mapping `{ created_at: "col_name", modified_at: "col_name" }`. These columns are auto-excluded from insert/update payloads. |
 | `parent`     | No       | Parent table name for route nesting, or `null` for a top-level route.                           |
 
@@ -449,12 +451,14 @@ const products = model(
   },
   "product_id",
   ["sku", "slug"],
-  { safeDelete: "is_deleted" },
+  { safeDelete: "is_deleted", search_columns: ["name", "description"] },
 );
 ```
 
 The model passes these rules to `node-input-validator` on every insert/update/patch operation. Sub-types are stripped — only the base type and validators are kept in the runtime structure.
 
+`search_columns` is passed through to the model `option` and enables the `search=` query parameter (multi-column OR `LIKE`). It is not a column rule and is not part of `structure`.
+
 ### OpenAPI Generation
 
 Validators map to OpenAPI schema properties:
@@ -476,6 +480,28 @@ Validators map to OpenAPI schema properties:
 | `alphaNumeric`  | `pattern: "^[a-zA-Z0-9]+$"`           |
 | `alphaDash`     | `pattern: "^[a-zA-Z0-9_-]+$"`         |
 
+When a table defines `search_columns`, the OpenAPI generator adds a `search` query parameter (type `string`) to that table's `GET /` list path, with a description listing the targeted columns. Tables without `search_columns` get no `search` parameter.
+
+---
+
+## Multi-Column Search (`search_columns` / `?search=`)
+
+`search_columns` enables free-text search across multiple columns via the reserved `search` query parameter. The term is matched as a substring against any configured column (OR-joined), and AND-combined with any other filters in the same request.
+
+```bash
+# (name LIKE %alice% OR description LIKE %alice%) AND sku = 'ABC'
+GET /products/?search=alice&sku=ABC
+```
+
+**Rules:**
+
+- Optional per table. If absent or empty, `search=` is ignored.
+- Each entry must be a non-empty string referencing an existing column (validated by `doctor`/`validateSchema`).
+- Applies to `find`, `findOne`, and `list` (and the `GET /:id`/`GET /` routes). `findOne` returns the first match.
+- Matching is **contains** (substring). Case sensitivity is adapter-native (PostgreSQL/MongoDB/Redis/SQLite3 case-insensitive; DynamoDB case-sensitive; MySQL depends on collation).
+- `search_columns` is config-only — set in the schema/model option, not overridable per request.
+- The `search` parameter is reserved: it is never treated as a column filter, even when `search_columns` is unset.
+
 ---
 
 ## Complete Example Schema

package/skill/references/postgres.md

@@ -35,6 +35,7 @@ PG_DB=test_db
 - `SERIAL` / `BIGSERIAL` primary keys are auto-detected via `pg_index`
 - `ON CONFLICT` is used for upsert operations
 - Includes a SQL translator layer that converts common MySQL DDL/DML to PostgreSQL syntax
+- `like` / `not like` filter operators (and the `?search=` parameter) compile to **`ILIKE` / `NOT ILIKE`** — case-insensitive substring matching. The value is wrapped as `%term%`.
 
 ## Table Creation
 

package/src/cli/generate-model.js

@@ -535,13 +535,18 @@ function generateModelFile(m) {
   const structStr = JSON.stringify(m.structure, null, 4);
   const uniqueStr = JSON.stringify(m.unique);
   const opt = m.option || {};
-  const hasOption = opt.safeDelete || opt.created_at || opt.modified_at;
+  const hasSearchColumns =
+    Array.isArray(opt.search_columns) && opt.search_columns.length > 0;
+  const hasOption =
+    opt.safeDelete || opt.created_at || opt.modified_at || hasSearchColumns;
   let optionStr = "";
   if (hasOption) {
     const parts = [];
     if (opt.safeDelete) parts.push(`safeDelete: "${opt.safeDelete}"`);
     if (opt.created_at) parts.push(`created_at: "${opt.created_at}"`);
     if (opt.modified_at) parts.push(`modified_at: "${opt.modified_at}"`);
+    if (hasSearchColumns)
+      parts.push(`search_columns: ${JSON.stringify(opt.search_columns)}`);
     optionStr = `\n  { ${parts.join(", ")} },`;
   }
   return `import dbModelRouter from "db-model-router";

package/src/cli/generate-openapi.js

@@ -68,6 +68,20 @@ function generateOpenAPISpec(models, options = {}) {
     // Helper: prepend FK path param for child routes
     const withFk = (params) => (fkParam ? [fkParam, ...params] : params);
 
+    // Optional search parameter (substring match across configured columns)
+    const searchColumns = m.option && m.option.search_columns;
+    const searchParam =
+      Array.isArray(searchColumns) && searchColumns.length > 0
+        ? [
+            {
+              name: "search",
+              in: "query",
+              schema: { type: "string" },
+              description: `Substring match (OR) across: ${searchColumns.join(", ")}`,
+            },
+          ]
+        : [];
+
     // GET / — list
     spec.paths[`${prefix}/`] = {
       get: {
@@ -96,6 +110,7 @@ function generateOpenAPISpec(models, options = {}) {
             in: "query",
             schema: { type: "string", enum: ["json", "csv", "xml"] },
           },
+          ...searchParam,
         ]),
         responses: {
           200: {

package/src/cli/init.js

@@ -239,14 +239,17 @@ function updatePackageJson(answers, outputDir) {
   const { dependencies, devDependencies } = collectDependencies(answers);
   const scripts = getScripts(outputDir);
 
+  const normalizedOutput = outputDir ? outputDir.replace(/\/+$/, "") : "";
+  const importPrefix = normalizedOutput ? `./${normalizedOutput}/` : "./";
+
   pkg.type = "module";
   pkg.imports = {
     "#root/*.js": "./*.js",
-    "#models": "./models/index.js",
-    "#models/*.js": "./models/*.js",
-    "#routes/*.js": "./routes/*.js",
-    "#commons/*.js": "./commons/*.js",
-    "#middleware/*.js": "./middleware/*.js",
+    "#models": `${importPrefix}models/index.js`,
+    "#models/*.js": `${importPrefix}models/*.js`,
+    "#routes/*.js": `${importPrefix}routes/*.js`,
+    "#commons/*.js": `${importPrefix}commons/*.js`,
+    "#middleware/*.js": `${importPrefix}middleware/*.js`,
   };
   pkg.scripts = Object.assign({}, pkg.scripts || {}, scripts);
   pkg.dependencies = Object.assign({}, pkg.dependencies || {}, dependencies);

package/src/commons/model.js

@@ -10,11 +10,16 @@ const { produce } = require("./kafka");
 
 /**
  * Extract and remove reserved params from a data/payload object.
- * Returns { select_columns: string[]|null, output_content_type: string|null, cleaned: data }
+ * Returns { select_columns: string[]|null, output_content_type: string|null, search: string|null }
+ *
+ * `search` is the free-text search term. It is stripped here so it is never
+ * treated as a column filter by dataToFilter; it is consumed by applySearch
+ * against the model's configured `search_columns` option.
  */
 function extractReservedParams(data) {
   let select_columns = null;
   let output_content_type = null;
+  let search = null;
   if (data && typeof data === "object" && !Array.isArray(data)) {
     if (data.select_columns) {
       select_columns =
@@ -27,8 +32,55 @@ function extractReservedParams(data) {
       output_content_type = data.output_content_type;
       delete data.output_content_type;
     }
+    if (data.search !== undefined && data.search !== null) {
+      search = data.search;
+      delete data.search;
+    }
+  }
+  return { select_columns, output_content_type, search };
+}
+
+/**
+ * Fan a free-text `search` term out to one OR-group per configured search
+ * column, AND-combined with the existing filter.
+ *
+ * Filter format is [[OR_groups[AND_conditions[col,op,val]]]] (top-level array
+ * = OR, within a group = AND). Each search column becomes its own OR-group
+ * containing a single `like` condition. To AND search with the existing
+ * filter, cross-product every existing OR-group with every search OR-group:
+ *
+ *   merged = for g in base, for sg in searchGroups: [...g, ...sg]
+ *
+ * Result OR-joined == (existing OR-groups) AND (col0 LIKE term OR col1 LIKE term OR ...).
+ * Empty base ([[]]) collapses to pure search OR-groups.
+ *
+ * The term is NOT pre-wrapped in `%` — adapters handle contains-wrapping:
+ * mysql/postgres add `%term%` (postgres via ILIKE, case-insensitive);
+ * mongodb/redis/dynamodb use native substring primitives (mongo regex `i`,
+ * redis String.includes ci, dynamodb contains()).
+ */
+function applySearch(filter, searchColumns, term) {
+  if (!Array.isArray(searchColumns) || searchColumns.length === 0) {
+    return filter;
+  }
+  if (term === undefined || term === null) return filter;
+  term = String(term).trim();
+  if (term === "") return filter;
+  const searchGroups = searchColumns.map((col) => [[col, "like", term]]);
+  let base = Array.isArray(filter) && filter.length > 0 ? filter : [[]];
+  const merged = [];
+  for (const g of base) {
+    // Drop malformed empty conditions (e.g. the `[]` placeholder inside the
+    // `[[[]]]` shape returned by dataToFilter for an empty object); otherwise
+    // adapter where() short-circuits the whole group to "match all".
+    const gClean = (Array.isArray(g) ? g : []).filter(
+      (c) => Array.isArray(c) && c.length === 3,
+    );
+    for (const sg of searchGroups) {
+      merged.push([...gClean, ...sg]);
+    }
   }
-  return { select_columns, output_content_type };
+  return merged;
 }
 
 /**
@@ -177,6 +229,9 @@ module.exports = function model(
     primary_key = modelStructureOrPK || "id";
     unique = primary_keyOrUnique || [];
     option = uniqueOrOption || { safeDelete: null };
+    option.search_columns = Array.isArray(option.search_columns)
+      ? option.search_columns
+      : [];
   } else {
     // model(db, "table", structure, pk, unique, option) — classic signature
     db = dbOrTable;
@@ -185,6 +240,9 @@ module.exports = function model(
     primary_key = primary_keyOrUnique || "id";
     unique = uniqueOrOption || [];
     option = optionOrUndefined || { safeDelete: null };
+    option.search_columns = Array.isArray(option.search_columns)
+      ? option.search_columns
+      : [];
   }
 
   const { createdKeys, modifiedKeys } = buildTimestampKeys(option);
@@ -341,7 +399,7 @@ module.exports = function model(
     },
     //TODO: Implement Sort Logic
     find: async (data) => {
-      const { select_columns } = extractReservedParams(data);
+      const { select_columns, search } = extractReservedParams(data);
       let sort = [];
       if (data.hasOwnProperty("sort")) {
         sort = data.sort;
@@ -349,13 +407,14 @@ module.exports = function model(
         sort = jsonSafeParse(sort);
       }
       let filter = dataToFilter(jsonSafeParse(data), primary_key);
+      filter = applySearch(filter, option.search_columns, search);
       const result = await db.get(table, filter, sort, option.safeDelete);
       if (select_columns)
         result.data = applySelect(result.data, select_columns);
       return result;
     },
     findOne: async (data) => {
-      const { select_columns } = extractReservedParams(data);
+      const { select_columns, search } = extractReservedParams(data);
       let sort = [];
       if (data.hasOwnProperty("sort")) {
         sort = data.sort;
@@ -363,6 +422,7 @@ module.exports = function model(
         sort = jsonSafeParse(sort);
       }
       let filter = dataToFilter(jsonSafeParse(data), primary_key);
+      filter = applySearch(filter, option.search_columns, search);
       let result = await db.get(table, filter, sort, option.safeDelete);
       if (result.count > 0) {
         let record = result["data"][0];
@@ -373,7 +433,7 @@ module.exports = function model(
       }
     },
     list: async (data) => {
-      const { select_columns } = extractReservedParams(data);
+      const { select_columns, search } = extractReservedParams(data);
       let page = 0;
       let size = 30;
       let sort = [];
@@ -393,6 +453,7 @@ module.exports = function model(
         delete data.sort;
       }
       let filter = dataToFilter(jsonSafeParse(data), primary_key);
+      filter = applySearch(filter, option.search_columns, search);
       sort = jsonSafeParse(sort);
       const result = await db.list(
         table,
@@ -461,3 +522,4 @@ module.exports.toCSV = toCSV;
 module.exports.toXML = toXML;
 module.exports.applySelect = applySelect;
 module.exports.extractReservedParams = extractReservedParams;
+module.exports.applySearch = applySearch;

package/src/commons/route.js

@@ -35,9 +35,12 @@ module.exports = function route(model, override = {}) {
         req,
         override,
       );
-      const { select_columns, output_content_type } =
+      const { select_columns, output_content_type, search } =
         extractReservedParams(payload);
       payload[model.pk] = req.params[model.pk];
+      // Re-attach search so the model layer can apply it against search_columns;
+      // route only needs select_columns/output_content_type for response shaping.
+      if (search !== null && search !== undefined) payload.search = search;
       model
         .find(payload)
         .then((response) => {
@@ -144,8 +147,10 @@ module.exports = function route(model, override = {}) {
         req,
         override,
       );
-      const { output_content_type } = extractReservedParams(payload);
+      const { output_content_type, search } = extractReservedParams(payload);
       // select_columns stays in payload — model.list handles it
+      // Re-attach search so the model layer can apply it against search_columns.
+      if (search !== null && search !== undefined) payload.search = search;
       model
         .list(payload)
         .then((response) => {

package/src/postgres/db.js

@@ -304,8 +304,9 @@ function where(filter, safeDelete = null) {
           ),
         );
       } else if (j[1] === "like" || j[1] === "not like") {
+        const pgOp = j[1] === "like" ? "ILIKE" : "NOT ILIKE";
         bindIdx++;
-        conditionAnd.push(`${escapeId(j[0])} ${j[1]} $${bindIdx}`);
+        conditionAnd.push(`${escapeId(j[0])} ${pgOp} $${bindIdx}`);
         value.push("%" + j[2] + "%");
       } else {
         bindIdx++;

package/src/schema/schema-parser.js

@@ -56,6 +56,10 @@ function parseSchema(input) {
     const softDelete =
       tableDef.softDelete !== undefined ? tableDef.softDelete : null;
 
+    const search_columns = Array.isArray(tableDef.search_columns)
+      ? [...tableDef.search_columns]
+      : [];
+
     const parent =
       tableDef.parent !== undefined && tableDef.parent !== null
         ? tableDef.parent
@@ -67,6 +71,7 @@ function parseSchema(input) {
       pk,
       unique,
       softDelete,
+      search_columns,
       timestamps,
       parent,
     };

package/src/schema/schema-printer.js

@@ -48,6 +48,14 @@ function printSchema(schema) {
       tableDef.softDelete = table.softDelete;
     }
 
+    // Preserve search_columns if set and non-empty
+    if (
+      Array.isArray(table.search_columns) &&
+      table.search_columns.length > 0
+    ) {
+      tableDef.search_columns = [...table.search_columns];
+    }
+
     // Preserve parent if set
     if (table.parent !== null && table.parent !== undefined) {
       tableDef.parent = table.parent;

package/src/schema/schema-to-meta.js

@@ -63,6 +63,9 @@ function schemaToModelMeta(schema) {
       modified_at: tableDef.timestamps
         ? tableDef.timestamps.modified_at || null
         : null,
+      search_columns: Array.isArray(tableDef.search_columns)
+        ? [...tableDef.search_columns]
+        : [],
     };
 
     return {

package/src/schema/schema-validator.js

@@ -214,6 +214,34 @@ function validateTables(tables, errors) {
       }
     }
 
+    // Validate search_columns (free-text search targets)
+    if (
+      tableDef.search_columns !== undefined &&
+      tableDef.search_columns !== null
+    ) {
+      if (!Array.isArray(tableDef.search_columns)) {
+        errors.push({
+          path: `${basePath}.search_columns`,
+          message: `search_columns must be an array of strings in table "${tableName}"`,
+        });
+      } else {
+        for (let i = 0; i < tableDef.search_columns.length; i++) {
+          const col = tableDef.search_columns[i];
+          if (typeof col !== "string" || col.length === 0) {
+            errors.push({
+              path: `${basePath}.search_columns[${i}]`,
+              message: `search_columns entry must be a non-empty string in table "${tableName}"`,
+            });
+          } else if (!columnNames.has(col)) {
+            errors.push({
+              path: `${basePath}.search_columns[${i}]`,
+              message: `search_columns entry "${col}" does not exist in table "${tableName}"`,
+            });
+          }
+        }
+      }
+    }
+
     // Validate parent (route nesting)
     if (tableDef.parent !== undefined && tableDef.parent !== null) {
       if (typeof tableDef.parent !== "string") {

package/.codegraph/config.json

@@ -1,143 +0,0 @@
-{
-  "version": 1,
-  "include": [
-    "**/*.ts",
-    "**/*.tsx",
-    "**/*.js",
-    "**/*.jsx",
-    "**/*.py",
-    "**/*.go",
-    "**/*.rs",
-    "**/*.java",
-    "**/*.c",
-    "**/*.h",
-    "**/*.cpp",
-    "**/*.hpp",
-    "**/*.cc",
-    "**/*.cxx",
-    "**/*.cs",
-    "**/*.php",
-    "**/*.rb",
-    "**/*.swift",
-    "**/*.kt",
-    "**/*.kts",
-    "**/*.dart",
-    "**/*.svelte",
-    "**/*.vue",
-    "**/*.liquid",
-    "**/*.pas",
-    "**/*.dpr",
-    "**/*.dpk",
-    "**/*.lpr",
-    "**/*.dfm",
-    "**/*.fmx",
-    "**/*.scala",
-    "**/*.sc"
-  ],
-  "exclude": [
-    "**/.git/**",
-    "**/node_modules/**",
-    "**/vendor/**",
-    "**/Pods/**",
-    "**/dist/**",
-    "**/build/**",
-    "**/out/**",
-    "**/bin/**",
-    "**/obj/**",
-    "**/target/**",
-    "**/*.min.js",
-    "**/*.bundle.js",
-    "**/.next/**",
-    "**/.nuxt/**",
-    "**/.svelte-kit/**",
-    "**/.output/**",
-    "**/.turbo/**",
-    "**/.cache/**",
-    "**/.parcel-cache/**",
-    "**/.vite/**",
-    "**/.astro/**",
-    "**/.docusaurus/**",
-    "**/.gatsby/**",
-    "**/.webpack/**",
-    "**/.nx/**",
-    "**/.yarn/cache/**",
-    "**/.pnpm-store/**",
-    "**/storybook-static/**",
-    "**/.expo/**",
-    "**/web-build/**",
-    "**/ios/Pods/**",
-    "**/ios/build/**",
-    "**/android/build/**",
-    "**/android/.gradle/**",
-    "**/__pycache__/**",
-    "**/.venv/**",
-    "**/venv/**",
-    "**/site-packages/**",
-    "**/dist-packages/**",
-    "**/.pytest_cache/**",
-    "**/.mypy_cache/**",
-    "**/.ruff_cache/**",
-    "**/.tox/**",
-    "**/.nox/**",
-    "**/*.egg-info/**",
-    "**/.eggs/**",
-    "**/go/pkg/mod/**",
-    "**/target/debug/**",
-    "**/target/release/**",
-    "**/.gradle/**",
-    "**/.m2/**",
-    "**/generated-sources/**",
-    "**/.kotlin/**",
-    "**/.dart_tool/**",
-    "**/.vs/**",
-    "**/.nuget/**",
-    "**/artifacts/**",
-    "**/publish/**",
-    "**/cmake-build-*/**",
-    "**/CMakeFiles/**",
-    "**/bazel-*/**",
-    "**/vcpkg_installed/**",
-    "**/.conan/**",
-    "**/Debug/**",
-    "**/Release/**",
-    "**/x64/**",
-    "**/.pio/**",
-    "**/release/**",
-    "**/*.app/**",
-    "**/*.asar",
-    "**/DerivedData/**",
-    "**/.build/**",
-    "**/.swiftpm/**",
-    "**/xcuserdata/**",
-    "**/Carthage/Build/**",
-    "**/SourcePackages/**",
-    "**/__history/**",
-    "**/__recovery/**",
-    "**/*.dcu",
-    "**/.composer/**",
-    "**/storage/framework/**",
-    "**/bootstrap/cache/**",
-    "**/.bundle/**",
-    "**/tmp/cache/**",
-    "**/public/assets/**",
-    "**/public/packs/**",
-    "**/.yardoc/**",
-    "**/coverage/**",
-    "**/htmlcov/**",
-    "**/.nyc_output/**",
-    "**/test-results/**",
-    "**/.coverage/**",
-    "**/.idea/**",
-    "**/logs/**",
-    "**/tmp/**",
-    "**/temp/**",
-    "**/_build/**",
-    "**/docs/_build/**",
-    "**/site/**"
-  ],
-  "languages": [],
-  "frameworks": [],
-  "maxFileSize": 1048576,
-  "extractDocstrings": true,
-  "trackCallSites": true
-}