@avytrix/nestjs-drizzle-crud 3.6.0 → 3.7.0

package/AGENT.md

@@ -60,11 +60,16 @@ pnpm add @avytrix/nestjs-drizzle-crud
 pnpm add @nestjs/common @nestjs/core drizzle-orm reflect-metadata   # peers, always
 pnpm add postgres                                                   # PostgreSQL
 pnpm add mysql2                                                     # MySQL
+pnpm add @libsql/client                                             # SQLite / libSQL
 ```
 
-`postgres` is an optional peer. You only need it when you let the module build
-the connection from a `connectionString` on PostgreSQL. If you pass your own
-`db`, no driver peer is required.
+`postgres` and `mysql2` are optional peers. You only need them when you let the
+module build the connection from a `connectionString` (PostgreSQL or MySQL;
+`connection: { poolSize, idleTimeout, ssl }` tunes it). If you pass your own
+`db`, no driver peer is required. SQLite (`dialect: 'sqlite'`, also libSQL and
+Cloudflare D1) always takes your own `db`. On D1 and synchronous SQLite drivers
+the mass writes, nested creates and attach / detach / sync throw a
+`TransactionException`; use libSQL when you need them.
 
 Requires Node >= 20 and `emitDecoratorMetadata` / `experimentalDecorators` in
 `tsconfig.json`, which the Nest CLI already sets.
@@ -87,7 +92,8 @@ DrizzleCrudModule.forRootAsync({
 ```
 
 Use `forRoot` for a static config and `forRootAsync` when the value comes from
-`ConfigService` or the environment. Provide exactly one of `connectionString`
+`ConfigService` or the environment (`useFactory`, or `useClass` / `useExisting`
+with a class that implements `DrizzleCrudOptionsFactory`). Provide exactly one of `connectionString`
 or `db`. The module is global, so feature modules do not import it again for
 the connection.
 
@@ -138,7 +144,7 @@ Those are legacy manual patterns and they break registration.
 | OpenAPI | `@ApiCrudList(source)`, `@ApiCrudQuery(source)` (needs `@nestjs/swagger`) |
 | Bulk | `massCreate`, `massUpdate`, `massUpsert`, `massSoftDelete`, `massRestore`, `massDelete`, `massForceDelete` |
 | Query string | `parseQuery(query, options)`, or the standalone `parseCrudQuery(query, table, options)` |
-| Search | `fullTextSearch(term, columns, pagination)`, PostgreSQL only |
+| Search | `fullTextSearch(term, columns, pagination, { filters, relations, select, language, queryMode })`, PostgreSQL only |
 | Transaction | `executeSqlTransaction(cb)` |
 
 `findAll` returns `{ data, total, page, limit }`, not a bare array; with
@@ -427,7 +433,8 @@ Driver error codes are translated at the service boundary, so bad client input
 never reaches the caller as a 500: a unique violation is a 409, a value that is
 too long, fails a check, has the wrong type or is not a valid date is a 400 (on
 reads too), a foreign key pointing at a row that does not exist is a 400, and a
-delete blocked by dependent rows is a 409.
+delete blocked by dependent rows is a 409. The same holds on MySQL (strict mode
+errors included) and SQLite (constraint errors).
 
 ---
 
@@ -452,9 +459,10 @@ To insert or update by a unique key, use
 than a find followed by a create.
 
 Take a row lock with `options.lock: 'update' | 'share'` only inside a
-transaction, and prefer `forNoKeyUpdate` when the key is not changing. The lock
-covers the service's own table only (`FOR UPDATE OF <table>`), so it works with
-an eager belongs-to.
+transaction, and prefer `forNoKeyUpdate` when the key is not changing. On
+PostgreSQL the lock covers the service's own table only (`FOR UPDATE OF
+<table>`), so it works with an eager belongs-to. MySQL gets `FOR UPDATE` or
+`FOR SHARE`; on SQLite a lock is a 400.
 
 ---
 

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-All notable changes to `@avytrix/nestjs-drizzle-crud` (published as `nestjs-drizzle-crud` up to 3.5.0) are documented here.
+All notable changes to `@avytrix/nestjs-drizzle-crud` (published as `nestjs-drizzle-crud` up to 3.3.0) are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
@@ -8,6 +8,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Scope note: the 3.0.x line is PostgreSQL-first. MySQL-specific paths (non-`RETURNING`
 restore, `ER_DUP_ENTRY` mapping, dialect locking) are tracked separately and unchanged here.
 
+3.3.1, 3.4.0, 3.5.0 and 3.5.2 were tagged but never published to npm. Their changes reached npm
+in 3.5.1 (3.3.1 to 3.5.0) and 3.6.0 (3.5.2). The unscoped `nestjs-drizzle-crud` stops at 3.3.0.
+
+## [3.7.0] - 2026-11-02
+
+SQLite support, MySQL connections built for you, and full-text search that works like `findAll`.
+
+### Added
+
+- `dialect: "sqlite"` for SQLite, libSQL (Turso) and Cloudflare D1. Pass the Drizzle instance as
+  `db`. Writes use `RETURNING`, `upsert` uses `ON CONFLICT DO UPDATE` with the tenant guard, and
+  keyset pages follow SQLite's NULL order. `LIKE` gets `ESCAPE '\'`, so `%`, `_` and `\` in a
+  search term match literally. Constraint errors map like the other dialects: `UNIQUE` 409,
+  `FOREIGN KEY` 400 on a write and 409 on a delete, `NOT NULL` and `CHECK` 400. Full-text search,
+  row locks and the array and JSON operators are a 400.
+- On Cloudflare D1 and synchronous SQLite drivers (better-sqlite3, bun:sqlite, sql.js), the calls
+  that need an interactive transaction (mass writes, nested creates, `attach`, `detach`, `sync`)
+  throw a `TransactionException` that says why, before any statement runs. `TransactionException`
+  is no longer deprecated.
+- `connectionString` works with `dialect: "mysql"`: the module builds a `mysql2` pool, wraps it
+  with `drizzle-orm/mysql2` and ends it on shutdown. `mysql2` is a new optional peer, loaded only
+  on that path.
+- `connection: { poolSize, idleTimeout, ssl }` for the connection the module builds from
+  `connectionString`, on PostgreSQL (postgres-js) and MySQL (mysql2).
+- `forRootAsync` takes `useClass` and `useExisting`, with a class that implements
+  `DrizzleCrudOptionsFactory` (`createDrizzleCrudOptions()`), next to `useFactory`.
+- `fullTextSearch()` takes `options.filters`, and honours `options.relations`, `options.select`
+  and `options.counts`, the same as `findAll`. Before, they were ignored.
+- `language` (the text search configuration, default `"english"`) and `queryMode` (`"plain"`, the
+  default, or `"websearch"` for `websearch_to_tsquery`) on `fullTextSearch()` options and on
+  `search` with `mode: "fullText"`. A language that is not a plain identifier is a 400.
+- New types: `DrizzleConnectionOptions`, `DrizzleCrudAsyncOptions`, `DrizzleCrudOptionsFactory`,
+  `FullTextOptions`, `FullTextQueryMode` and `FullTextSearchOptions`.
+
+### Fixed
+
+- MySQL: `lock` and `forNoKeyUpdate` add `FOR UPDATE` or `FOR SHARE` (`forNoKeyUpdate` becomes
+  `FOR UPDATE`). They used to be accepted and silently ignored.
+- MySQL strict mode data errors (a missing required value, a value too long, out of range, of
+  the wrong type, a bad date, a failed check) are a 400 that names the column, instead of a 500.
+
+### Changed
+
+- The default `sql.useReturning` is `true` for every dialect except MySQL, so SQLite gets it.
+  PostgreSQL and MySQL keep the values they had.
+
 ## [3.6.0] - 2026-11-02
 
 Fixes from the second audit. The first one is a security fix: upgrade if you use `scope`.

package/README.md

@@ -5,7 +5,7 @@
 [![license](https://img.shields.io/npm/l/@avytrix/nestjs-drizzle-crud)](./LICENSE)
 [![Sponsor @avytrix](https://img.shields.io/badge/Sponsor-%40avytrix-db61a2?style=for-the-badge&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/avytrix)
 
-**nestjs-drizzle-crud is a NestJS + Drizzle ORM CRUD library: extend one base class and every table gets type-safe find, create, update, delete, filtering, pagination, relations and soft delete, on PostgreSQL or MySQL.**
+**nestjs-drizzle-crud is a NestJS + Drizzle ORM CRUD library: extend one base class and every table gets type-safe find, create, update, delete, filtering, pagination, relations and soft delete, on PostgreSQL, MySQL or SQLite.**
 
 ```bash
 pnpm add @avytrix/nestjs-drizzle-crud drizzle-orm
@@ -94,7 +94,7 @@ sponsors are what make keeping it free sustainable.
 - 🚀 **CRUD**: `find`, `findOne`, `findAll`, `create`, `update`, `delete`, and more
 - 🧩 **Configure once**: `forRoot()` owns the connection; services only declare a table
 - ⚡ **Type-safe**: generics over your entity, create/update DTOs and filter types
-- 🗃️ **PostgreSQL & MySQL**: dialect-aware (`RETURNING` vs `insertId`)
+- 🗃️ **PostgreSQL, MySQL & SQLite**: dialect-aware (`RETURNING` vs `insertId`), libSQL and Cloudflare D1 included
 - 🔄 **Soft delete**: opt-in, with `restore`, a trash view (`onlyDeleted`) and `forceDelete`
 - 📦 **Bulk operations**: one statement per mass create/update/delete, inside a transaction, plus `upsert`
 - 🔍 **Filtering**: comparison, `in`/`notIn`, `between`, escaped `contains`/`startsWith`, array and JSON operators, `or`/`not` groups
@@ -136,23 +136,23 @@ pnpm add @nestjs/common @nestjs/core drizzle-orm reflect-metadata
 # PostgreSQL (also required if you use `connectionString` with dialect 'postgresql')
 pnpm add postgres
 
-# MySQL
+# MySQL (also required if you use `connectionString` with dialect 'mysql')
 pnpm add mysql2
 
+# SQLite / libSQL (you build the Drizzle instance and pass it as `db`)
+pnpm add @libsql/client
+
 # Only for ApiCrudQuery / ApiCrudList (OpenAPI docs)
 pnpm add @nestjs/swagger
 ```
 
 > Using npm or yarn? Swap `pnpm add` for `npm install` / `yarn add`.
 
-> **pnpm note:** `postgres` is an optional peer dependency and `mysql2` is not a peer
-> at all. pnpm enforces peer deps strictly, so if you build the connection from a
-> `connectionString` make sure `postgres` is installed in your app; for MySQL you
-> install `mysql2` yourself and pass the `db` you build with it.
-
-> `postgres` is an **optional** peer dependency. It's only needed when you let the
-> module build the connection from a `connectionString` for the `postgresql` dialect.
-> If you pass a pre-built `db` instead, you don't need it.
+> **pnpm note:** `postgres` and `mysql2` are optional peer dependencies. pnpm
+> enforces peer deps strictly, so if you build the connection from a
+> `connectionString` make sure the driver for your dialect is installed in your app.
+> If you pass a pre-built `db` instead, you don't need either. SQLite always takes a
+> `db` you build.
 
 ---
 
@@ -285,15 +285,16 @@ export class UsersController {
 
 | Field | Type | Description |
 |---|---|---|
-| `dialect` | `'postgresql' \| 'mysql'` | **Required.** Database dialect. |
-| `connectionString` | `string` | Connection string. The module builds the connection (PostgreSQL only). |
+| `dialect` | `'postgresql' \| 'mysql' \| 'sqlite'` | **Required.** Database dialect. `'sqlite'` covers SQLite, libSQL and Cloudflare D1. |
+| `connectionString` | `string` | Connection string. The module builds the connection (PostgreSQL with `postgres`, MySQL with `mysql2`). |
+| `connection` | `{ poolSize?, idleTimeout?, ssl? }` | Pool size, idle timeout (seconds) and TLS for the connection built from `connectionString`. |
 | `db` | `Drizzle instance` | Alternatively, pass a Drizzle instance you built yourself (any dialect). |
 | `schema` | `Record<string, unknown>` | Drizzle schema, used when building from `connectionString`. |
 | `defaults.softDelete` | `boolean` | Enable soft delete for all entities (default `true`). |
 | `defaults.timestamps` | `boolean` | Auto-manage `created_at`/`updated_at` for all entities (default `true`). |
 | `defaults.pagination` | `{ defaultLimit?, maxLimit? }` | Pagination defaults (default `{ 20, 100 }`). Either key alone keeps the other's default. |
 | `defaults.sortOrder` | `'asc' \| 'desc'` | Opt-in default sort: entities **without** an explicit `defaultSort` fall back to ordering by their `created_at` column in this direction. Omit it and `findAll` orders by the primary key only. |
-| `sql` | `{ caseSensitive?, useReturning? }` | Dialect tuning. `useReturning` defaults to `true` for PostgreSQL, `false` for MySQL. `jsonSupport` and `enableFullTextSearch` are deprecated and do nothing. |
+| `sql` | `{ caseSensitive?, useReturning? }` | Dialect tuning. `useReturning` defaults to `true` for PostgreSQL and SQLite, `false` for MySQL. `jsonSupport` and `enableFullTextSearch` are deprecated and do nothing. |
 | `hooks` | `{ enableGlobalHooks?, subscribers? }` | Module-level write events on the `CrudEventBus`. See [Events](#events-and-global-hooks). |
 
 > **Provide exactly one of `connectionString` or `db`.** If your tables have no
@@ -306,7 +307,7 @@ export class UsersController {
 > table does not have stops the app at startup, and the message names the key
 > to use.
 
-**Build the connection yourself (any dialect, recommended for MySQL):**
+**Build the connection yourself (any dialect, required for SQLite):**
 
 ```typescript
 import { drizzle } from 'drizzle-orm/postgres-js';
@@ -332,6 +333,27 @@ DrizzleCrudModule.forRootAsync({
 });
 ```
 
+`forRootAsync` also takes `useClass` or `useExisting` with a class that
+implements `DrizzleCrudOptionsFactory`:
+
+```typescript
+@Injectable()
+class CrudConfig implements DrizzleCrudOptionsFactory {
+  constructor(private readonly cfg: ConfigService) {}
+  createDrizzleCrudOptions(): DrizzleCrudConfig {
+    return { dialect: 'mysql', connectionString: this.cfg.get('DATABASE_URL') };
+  }
+}
+
+DrizzleCrudModule.forRootAsync({ useClass: CrudConfig });
+```
+
+On SQLite (`dialect: 'sqlite'`), mass writes, nested creates and attach / detach
+/ sync need an async transaction: they work on libSQL and throw a
+`TransactionException` on Cloudflare D1 and synchronous drivers such as
+better-sqlite3. Full-text search, row locks and the array and JSON operators
+are a 400 there.
+
 ### `DrizzleCrudModule.forFeature(entities)`
 
 Registers one or more services and binds each to its table. Per-entity overrides
@@ -1111,7 +1133,19 @@ const { data, total } = await service.fullTextSearch(
 ```
 
 Builds `to_tsvector(...) @@ plainto_tsquery(...)` across the given columns and
-orders by `ts_rank`. Throws if the dialect is not `postgresql`.
+orders by `ts_rank`. Throws a 400 if the dialect is not `postgresql`. The options
+take `filters`, `relations`, `select` and `counts` as on `findAll`, plus
+`language` (default `'english'`) and `queryMode: 'websearch'` for
+`websearch_to_tsquery`:
+
+```typescript
+await service.fullTextSearch('"zero downtime" -kubernetes', ['title', 'body'], {}, {
+  filters: { status: 'published' },
+  relations: ['author'],
+  language: 'english',
+  queryMode: 'websearch',
+});
+```
 
 For paginated list endpoints, prefer `findAll(..., ..., { search })` so search is
 combined with filters and the count query. Use `fullTextSearch` directly when
@@ -1211,7 +1245,7 @@ read-only and never touches your database. Full setup:
 
 Use these facts instead of guessing.
 
-**Package:** `nestjs-drizzle-crud` · **Peers:** `@nestjs/common`, `@nestjs/core`, `drizzle-orm`, `reflect-metadata`; optional `postgres` (PG) / `@nestjs/swagger` (for `ApiCrudList`); `mysql2` is installed by you for MySQL, not a peer.
+**Package:** `nestjs-drizzle-crud` · **Peers:** `@nestjs/common`, `@nestjs/core`, `drizzle-orm`, `reflect-metadata`; optional `postgres` (PG `connectionString`) / `mysql2` (MySQL `connectionString`) / `@nestjs/swagger` (for `ApiCrudList`). SQLite drivers are yours, passed as `db`.
 
 **Setup is two steps and no per-service connection wiring:**
 1. `DrizzleCrudModule.forRoot({ dialect, connectionString | db, schema, defaults })` once in `AppModule`.
@@ -1242,15 +1276,17 @@ export class XService extends SqlBaseCrudService<X, CreateXDto, UpdateXDto, XFil
 - Relations: declare in forFeature `config.relations` and eager-load via `options.relations: ['relName']`, where a dotted path nests (`['states', 'states.cities']`, `['state.country']`; the parent path is pulled in automatically). Belongs-to is `{ table, localKey, references? }`, LEFT JOINed into the main query, resolving to an object or `null`. Has-many is `{ table, type: 'hasMany', foreignKey, parentKey?, orderBy? }`. Many-to-many is `{ table, type: 'manyToMany', through, throughLocalKey, throughForeignKey, references?, parentKey?, orderBy? }`. Nested relations live in a `relations` map on the relation. Every collection and every nested level costs exactly one extra query for the whole result set, never one per row. Filter via `findAll({ relName: { col: value } })` with the same operators; collection filters compile to `parentKey IN (SELECT ... WHERE ...)`, so `total` stays correct. Filters go through relation paths at any depth (`{ state: { country: { code: 'IN' } } }`), and collections take `some` / `none` / `every` (`{ posts: { none: { status: 'draft' } } }`), compiled to subqueries.
 - `options.select` narrows the projection and takes dotted relation paths at any depth: `['id', 'name', 'region.code', 'states.cities.name']`. Unknown names are ignored; an all-dotted list leaves the base row complete; the parent key, the child foreign key and any nested key are re-added automatically.
 - Primary keys: `primaryKey` (default `'id'`) per entity in forFeature config (`primaryKeyType` is deprecated and does nothing). UUID works on Postgres via RETURNING; with uuid keys, route params are strings, so don't use `ParseIntPipe`.
-- Full-text search is PostgreSQL-only.
+- Full-text search is PostgreSQL-only; it takes `filters`, `relations`, `select`, `language` and `queryMode` in its options.
+- SQLite (`dialect: 'sqlite'`): pass `db`. Bulk writes need libSQL; D1 and sync drivers throw `TransactionException`. Locks, full-text and array/JSON operators are a 400.
+- Exports (3.7): `DrizzleConnectionOptions`, `DrizzleCrudAsyncOptions`, `DrizzleCrudOptionsFactory`, `FullTextOptions`, `FullTextQueryMode`, `FullTextSearchOptions`.
 - Exports (3.5): `createCrudController`, `CrudContext`, `CrudEventBus`, `ApiCrudQuery`, `ApiCrudList`, `MissingScopeException`, `StaleVersionException`, and the types `CrudControllerOptions`, `CrudEvent`, `CrudSubscriber`, `CrudScope`, `CollectionFilter`, `CountByRow`, `CrudPage`, `UncountedCrudPage`, `RelationCounts`.
-- Exports: `SqlBaseCrudService`, `DrizzleCrudModule`, `DRIZZLE_DB`, `DRIZZLE_CRUD_CONFIG`, `TestCrudFactory`, exceptions (`EntityNotFoundException`, `DuplicateEntityException`, `ForeignKeyViolationException`, `EntityInUseException`, `ValidationFailedException`, `BulkOperationException`, plus the deprecated `DatabaseConnectionException` and `TransactionException`), and types (`SqlCrudConfig`, `SqlOperationOptions`, `DrizzleCrudConfig`, `CrudFeature`, `CrudFeatureConfig`, `PaginationOptions`, `OperationOptions`, `SqlSearchOptions`, `SqlSearchMode`, `BulkOperationResult`, `BulkOperationItemError`, `SqlDialect`, `PrimaryKeyType`, `CrudFilter`, `FilterOperators`, `SortInput`, `CursorPaginationOptions`, `CursorPage`, `CrudAllowlists`, `UpsertOptions`, `BulkMode`, `ParsedCrudQuery`), and `parseCrudQuery`.
+- Exports: `SqlBaseCrudService`, `DrizzleCrudModule`, `DRIZZLE_DB`, `DRIZZLE_CRUD_CONFIG`, `TestCrudFactory`, exceptions (`EntityNotFoundException`, `DuplicateEntityException`, `ForeignKeyViolationException`, `EntityInUseException`, `ValidationFailedException`, `BulkOperationException`, `TransactionException`, plus the deprecated `DatabaseConnectionException`), and types (`SqlCrudConfig`, `SqlOperationOptions`, `DrizzleCrudConfig`, `CrudFeature`, `CrudFeatureConfig`, `PaginationOptions`, `OperationOptions`, `SqlSearchOptions`, `SqlSearchMode`, `BulkOperationResult`, `BulkOperationItemError`, `SqlDialect`, `PrimaryKeyType`, `CrudFilter`, `FilterOperators`, `SortInput`, `CursorPaginationOptions`, `CursorPage`, `CrudAllowlists`, `UpsertOptions`, `BulkMode`, `ParsedCrudQuery`), and `parseCrudQuery`.
 
 ### `SqlCrudConfig`
 
 ```typescript
 interface SqlCrudConfig {
-  dialect: 'postgresql' | 'mysql';
+  dialect: 'postgresql' | 'mysql' | 'sqlite';
   db: any;                         // Drizzle instance (injected by forFeature)
   table: any;                      // Drizzle table (set by forFeature)
   primaryKey: string;              // default 'id'

package/dist/core/abstract/sql-base-crud.service.d.ts

@@ -3,7 +3,7 @@ import type { ICrudService, PaginationOptions } from "../interfaces/crud-service
 import type { CrudWriteOperation } from "../interfaces/events.interface";
 import type { CountByRow, CrudAllowlists, CrudPage, CursorPage, CursorPaginationOptions, ParseCrudQueryOptions, ParsedCrudQuery, RelationCounts, SortInput, UncountedCrudPage, UpsertOptions } from "../interfaces/query.interface";
 import type { CrudScopeValues } from "../interfaces/scope.interface";
-import type { RelationConfig, RelationNode, RelationsConfig, RelationType, SelectTree, SqlCrudConfig, SqlOperationOptions } from "../interfaces/sql-crud-config.interface";
+import type { FullTextOptions, FullTextSearchOptions, RelationConfig, RelationNode, RelationsConfig, RelationType, SelectTree, SqlCrudConfig, SqlOperationOptions } from "../interfaces/sql-crud-config.interface";
 import type { SortOrder } from "../types/sql.types";
 interface SortSpec {
     key: string;
@@ -85,8 +85,12 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
         offset: number;
     };
     protected isUniqueViolation(error: any): boolean;
+    protected sqliteConstraint(error: any): string | undefined;
     protected toDuplicateException(error: any): DuplicateEntityException;
     private static readonly DATA_ERRORS;
+    private static readonly MYSQL_DATA_ERRORS;
+    private static readonly SQLITE_DATA_ERRORS;
+    private dataErrorMessage;
     protected isDataException(error: any): boolean;
     protected toDataException(error: any): ValidationFailedException;
     protected toClientError(error: any, operation?: "read" | "write" | "delete"): unknown;
@@ -94,8 +98,14 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
     protected isForeignKeyViolation(error: any): boolean;
     protected toForeignKeyException(error: any): ForeignKeyViolationException;
     protected applyLock(query: any, options?: SqlOperationOptions): any;
+    protected textSearchConfig(language?: unknown): any;
+    protected fullTextParts(columns: any[], term: string, options?: FullTextOptions): {
+        vector: any;
+        query: any;
+    };
     protected buildSearchCondition(search?: SqlOperationOptions["search"]): any;
     protected caseInsensitiveLike(column: any, pattern: string): any;
+    protected likePattern(column: any, pattern: string): any;
     parseQuery(query: Record<string, unknown> | null | undefined, options?: ParseCrudQueryOptions): ParsedCrudQuery;
     idKind(): "int" | "bigint" | "uuid" | "string";
     parseId(raw: unknown): Promise<unknown>;
@@ -219,8 +229,9 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
     private patternCondition;
     protected applyComplexFilter(conditions: any[], column: any, filterObj: any): void;
     protected executeSqlTransaction<R>(operation: (tx: any) => Promise<R>, existingTransaction?: any): Promise<R>;
+    protected assertTransactions(db: any): void;
     protected getEntityName(): string;
-    fullTextSearch(searchTerm: string, searchColumns: string[], pagination?: PaginationOptions, options?: SqlOperationOptions): Promise<{
+    fullTextSearch(searchTerm: string, searchColumns: string[], pagination?: PaginationOptions, options?: FullTextSearchOptions<FilterDto>): Promise<{
         data: T[];
         total: number;
         page: number;

package/dist/core/abstract/sql-base-crud.service.js

@@ -66,6 +66,10 @@ class SqlBaseCrudService {
             return result.rowsAffected > 0;
         if (typeof result.affectedRows === "number")
             return result.affectedRows > 0;
+        if (typeof result.changes === "number")
+            return result.changes > 0;
+        if (typeof result.meta?.changes === "number")
+            return result.meta.changes > 0;
         return false;
     }
     buildWhereConditionsFromPartial(where) {
@@ -806,13 +810,32 @@ class SqlBaseCrudService {
     isUniqueViolation(error) {
         const code = error?.code ?? error?.cause?.code;
         const errno = error?.errno ?? error?.cause?.errno;
-        return code === "23505" || code === "ER_DUP_ENTRY" || errno === 1062;
+        const sqlite = this.sqliteConstraint(error);
+        return (code === "23505" ||
+            code === "ER_DUP_ENTRY" ||
+            errno === 1062 ||
+            sqlite === "UNIQUE" ||
+            sqlite === "PRIMARYKEY");
+    }
+    sqliteConstraint(error) {
+        if (this.config.dialect !== "sqlite")
+            return undefined;
+        for (const e of [error, error?.cause]) {
+            const code = e?.extendedCode ?? e?.code;
+            if (typeof code === "string" && code.startsWith("SQLITE_CONSTRAINT_")) {
+                return code.slice("SQLITE_CONSTRAINT_".length);
+            }
+        }
+        const message = `${error?.cause?.message ?? ""} ${error?.message ?? ""}`;
+        const m = message.match(/(UNIQUE|PRIMARY KEY|FOREIGN KEY|NOT NULL|CHECK) constraint failed/);
+        return m?.[1]?.replace(" ", "");
     }
     toDuplicateException(error) {
         const detail = error?.detail ?? error?.cause?.detail ?? "";
         const message = error?.cause?.message ?? error?.message ?? "";
         const m = detail.match(/Key \((?<field>.+?)\)=\((?<value>.+?)\)/) ??
-            message.match(/Duplicate entry '(?<value>.*)' for key '(?:[^']*\.)?(?<field>[^']+)'/);
+            message.match(/Duplicate entry '(?<value>.*)' for key '(?:[^']*\.)?(?<field>[^']+)'/) ??
+            message.match(/UNIQUE constraint failed: (?:[^.,\s]+\.)?(?<field>[^,\s]+)/);
         return new crud_exceptions_1.DuplicateEntityException(this.getEntityName(), m?.groups?.field ?? "unique field", m?.groups?.value ?? "");
     }
     static DATA_ERRORS = {
@@ -825,18 +848,53 @@ class SqlBaseCrudService {
         "22008": "a date or time value is out of range",
         "21000": "the same key appears more than once in one upsert",
     };
-    isDataException(error) {
+    static MYSQL_DATA_ERRORS = {
+        1048: "a required value is missing",
+        1364: "a required value is missing",
+        1406: "a value is too long for its column",
+        3819: "a value violates a column check constraint",
+        1264: "a numeric value is out of range",
+        1265: "a value does not match its column type",
+        1366: "a value does not match its column type",
+        1292: "a date or time value has an invalid format",
+    };
+    static SQLITE_DATA_ERRORS = {
+        NOTNULL: "a required value is missing",
+        CHECK: "a value violates a column check constraint",
+    };
+    dataErrorMessage(error) {
         const code = error?.code ?? error?.cause?.code;
-        return Object.hasOwn(SqlBaseCrudService.DATA_ERRORS, code ?? "");
+        if (Object.hasOwn(SqlBaseCrudService.DATA_ERRORS, code ?? "")) {
+            return SqlBaseCrudService.DATA_ERRORS[code];
+        }
+        if (this.config.dialect === "mysql") {
+            const errno = error?.errno ?? error?.cause?.errno;
+            return Object.hasOwn(SqlBaseCrudService.MYSQL_DATA_ERRORS, errno ?? "")
+                ? SqlBaseCrudService.MYSQL_DATA_ERRORS[errno]
+                : undefined;
+        }
+        const sqlite = this.sqliteConstraint(error) ?? "";
+        return Object.hasOwn(SqlBaseCrudService.SQLITE_DATA_ERRORS, sqlite)
+            ? SqlBaseCrudService.SQLITE_DATA_ERRORS[sqlite]
+            : undefined;
+    }
+    isDataException(error) {
+        return this.dataErrorMessage(error) !== undefined;
     }
     toDataException(error) {
-        const code = error?.code ?? error?.cause?.code;
-        const message = SqlBaseCrudService.DATA_ERRORS[code] ?? "invalid value";
+        const message = this.dataErrorMessage(error) ?? "invalid value";
         const cause = error?.cause ?? error;
+        const text = String(cause?.message ?? "");
         const column = error?.column ??
             cause?.column ??
             error?.column_name ??
-            cause?.column_name;
+            cause?.column_name ??
+            (this.config.dialect === "mysql"
+                ? text.match(/column '([^']+)'/i)?.[1]
+                : undefined) ??
+            (this.config.dialect === "sqlite"
+                ? text.match(/NOT NULL constraint failed: (?:[^.\s]+\.)?(\S+)/)?.[1]
+                : undefined);
         return new crud_exceptions_1.ValidationFailedException(column ? `${message}: ${column}` : message);
     }
     toClientError(error, operation = "write") {
@@ -862,7 +920,10 @@ class SqlBaseCrudService {
     isForeignKeyViolation(error) {
         const code = error?.code ?? error?.cause?.code;
         const errno = error?.errno ?? error?.cause?.errno;
-        return code === "23503" || errno === 1451 || errno === 1452;
+        return (code === "23503" ||
+            errno === 1451 ||
+            errno === 1452 ||
+            this.sqliteConstraint(error) === "FOREIGNKEY");
     }
     toForeignKeyException(error) {
         const detail = error?.detail ?? error?.cause?.detail ?? "";
@@ -870,14 +931,37 @@ class SqlBaseCrudService {
         return new crud_exceptions_1.ForeignKeyViolationException(this.getEntityName(), m?.groups?.field ?? "reference");
     }
     applyLock(query, options) {
-        if (this.config.dialect !== "postgresql")
+        const strength = options?.forNoKeyUpdate
+            ? "no key update"
+            : options?.lock && options.lock !== "none"
+                ? options.lock
+                : undefined;
+        if (!strength)
             return query;
-        const of = { of: this.config.table };
-        if (options?.forNoKeyUpdate)
-            return query.for("no key update", of);
-        if (options?.lock && options.lock !== "none")
-            return query.for(options.lock, of);
-        return query;
+        if (this.config.dialect === "postgresql") {
+            return query.for(strength, { of: this.config.table });
+        }
+        if (this.config.dialect === "mysql") {
+            return query.for(strength === "share" ? "share" : "update");
+        }
+        throw new common_1.BadRequestException(`Row locks (lock, forNoKeyUpdate) are not supported on ${this.config.dialect}`);
+    }
+    textSearchConfig(language = "english") {
+        if (typeof language !== "string" ||
+            !/^[A-Za-z_][A-Za-z0-9_]{0,62}(\.[A-Za-z_][A-Za-z0-9_]{0,62})?$/.test(language)) {
+            throw new common_1.BadRequestException(`Invalid full-text search language: ${String(language)}`);
+        }
+        return drizzle_orm_1.sql.raw(`'${language}'`);
+    }
+    fullTextParts(columns, term, options = {}) {
+        const config = this.textSearchConfig(options.language);
+        const mode = options.queryMode ?? "plain";
+        if (mode !== "plain" && mode !== "websearch") {
+            throw new common_1.BadRequestException(`Invalid full-text query mode: ${String(mode)} (expected 'plain' or 'websearch')`);
+        }
+        const parse = drizzle_orm_1.sql.raw(mode === "websearch" ? "websearch_to_tsquery" : "plainto_tsquery");
+        const vector = drizzle_orm_1.sql.join(columns.map((column) => (0, drizzle_orm_1.sql) `to_tsvector(${config}, ${column})`), (0, drizzle_orm_1.sql) ` || `);
+        return { vector, query: (0, drizzle_orm_1.sql) `${parse}(${config}, ${term})` };
     }
     buildSearchCondition(search) {
         if (!search?.term || !search.columns?.length)
@@ -894,18 +978,22 @@ class SqlBaseCrudService {
             if (this.config.dialect !== "postgresql") {
                 throw new common_1.BadRequestException("Full-text search only supported in PostgreSQL");
             }
-            const tsVector = drizzle_orm_1.sql.join(columns.map((column) => (0, drizzle_orm_1.sql) `to_tsvector('english', ${column})`), (0, drizzle_orm_1.sql) ` || `);
-            const tsQuery = (0, drizzle_orm_1.sql) `plainto_tsquery('english', ${term})`;
-            return (0, drizzle_orm_1.sql) `${tsVector} @@ ${tsQuery}`;
+            const { vector, query } = this.fullTextParts(columns, term, search);
+            return (0, drizzle_orm_1.sql) `${vector} @@ ${query}`;
         }
         const pattern = `%${term.replace(/[\\%_]/g, "\\$&")}%`;
         const conditions = columns.map((column) => this.caseInsensitiveLike(column, pattern));
         return conditions.length === 1 ? conditions[0] : (0, drizzle_orm_1.or)(...conditions);
     }
     caseInsensitiveLike(column, pattern) {
-        return this.config.dialect === "mysql"
-            ? (0, drizzle_orm_1.like)(column, pattern)
-            : (0, drizzle_orm_1.ilike)(column, pattern);
+        if (this.config.dialect === "postgresql")
+            return (0, drizzle_orm_1.ilike)(column, pattern);
+        return this.likePattern(column, pattern);
+    }
+    likePattern(column, pattern) {
+        return this.config.dialect === "sqlite"
+            ? (0, drizzle_orm_1.sql) `${column} like ${pattern} escape '\\'`
+            : (0, drizzle_orm_1.like)(column, pattern);
     }
     parseQuery(query, options = {}) {
         const config = this.config;
@@ -1211,7 +1299,7 @@ class SqlBaseCrudService {
         return branches.length > 0 ? (0, drizzle_orm_1.or)(...branches) : (0, drizzle_orm_1.sql) `false`;
     }
     afterCursor(spec, value) {
-        const postgres = this.config.dialect !== "mysql";
+        const postgres = this.config.dialect === "postgresql";
         const nullsFirst = postgres ? spec.order === "desc" : spec.order === "asc";
         if (value === null) {
             return nullsFirst ? (0, drizzle_orm_1.isNotNull)(spec.column) : undefined;
@@ -2751,7 +2839,7 @@ class SqlBaseCrudService {
                 : `%${escaped}%`;
         return insensitive || this.config.sql?.caseSensitive === false
             ? this.caseInsensitiveLike(column, pattern)
-            : (0, drizzle_orm_1.like)(column, pattern);
+            : this.likePattern(column, pattern);
     }
     applyComplexFilter(conditions, column, filterObj) {
         const coerce = (value) => this.coerceFilterValue(column, value);
@@ -2783,7 +2871,7 @@ class SqlBaseCrudService {
                     conditions.push((0, drizzle_orm_1.ne)(column, coerce(raw)));
                     break;
                 case "like":
-                    conditions.push((0, drizzle_orm_1.like)(column, raw));
+                    conditions.push(this.likePattern(column, raw));
                     break;
                 case "ilike":
                     conditions.push(this.caseInsensitiveLike(column, raw));
@@ -2841,10 +2929,22 @@ class SqlBaseCrudService {
         }
     }
     async executeSqlTransaction(operation, existingTransaction) {
+        this.assertTransactions(existingTransaction ?? this.config.db);
         if (existingTransaction)
             return operation(existingTransaction);
         return this.config.db.transaction(operation);
     }
+    assertTransactions(db) {
+        if (this.config.dialect !== "sqlite")
+            return;
+        const kind = db?.constructor?.[drizzle_orm_1.entityKind];
+        if (kind === "D1Database" || kind === "D1Transaction") {
+            throw new crud_exceptions_1.TransactionException("Cloudflare D1 has no interactive transactions, so mass writes, nested writes and attach/detach/sync are not available on it. Use the single-row methods, or db.batch() yourself.");
+        }
+        if (db?.resultKind === "sync") {
+            throw new crud_exceptions_1.TransactionException("This SQLite driver is synchronous (better-sqlite3, bun:sqlite, sql.js), and its transactions cannot wait for async work, so mass writes, nested writes and attach/detach/sync are not available on it. Use an async driver such as libSQL (@libsql/client).");
+        }
+    }
     getEntityName() {
         try {
             return (0, drizzle_orm_1.getTableName)(this.config.table) || "Entity";
@@ -2868,31 +2968,37 @@ class SqlBaseCrudService {
             this.assertAllowed("searchableColumns", name, options);
             return column;
         });
-        const { transaction } = options || {};
-        const db = transaction || this.config.db;
-        const tsVector = drizzle_orm_1.sql.join(columns.map((column) => (0, drizzle_orm_1.sql) `to_tsvector('english', ${column})`), (0, drizzle_orm_1.sql) ` || `);
-        const tsQuery = (0, drizzle_orm_1.sql) `plainto_tsquery('english', ${searchTerm})`;
-        const matchExpr = (0, drizzle_orm_1.sql) `${tsVector} @@ ${tsQuery}`;
-        const whereExpr = (0, drizzle_orm_1.and)(matchExpr, ...this.rowScope(options));
+        const { filters, language, queryMode, ...readOptions } = options ?? {};
+        const { vector, query } = this.fullTextParts(columns, searchTerm, {
+            language,
+            queryMode,
+        });
         const { page, limit, offset } = this.resolvePagination(pagination?.page, pagination?.limit);
+        const plan = this.planList(filters, undefined, "asc", readOptions);
+        const conditions = [(0, drizzle_orm_1.sql) `${vector} @@ ${query}`, ...plan.conditions];
+        const joins = Array.from(new Set([
+            ...plan.joined.map((node) => node.name),
+            ...plan.filterRelations,
+        ]));
         const pk = this.columnOf(this.config.table, this.config.primaryKey);
-        const orderBy = [(0, drizzle_orm_1.sql) `ts_rank(${tsVector}, ${tsQuery}) DESC`];
+        const orderBy = [(0, drizzle_orm_1.sql) `ts_rank(${vector}, ${query}) DESC`];
         if (pk)
             orderBy.push((0, drizzle_orm_1.asc)(pk));
-        const dataQuery = db
-            .select()
-            .from(this.config.table)
-            .where(whereExpr)
+        let dataQuery = this.startSelect(plan.db, plan.baseSelect, plan.joined, joins.length > 0, plan.selection);
+        dataQuery = this.applyJoins(dataQuery, joins, readOptions)
+            .where((0, drizzle_orm_1.and)(...conditions))
             .orderBy(...orderBy)
             .limit(limit)
             .offset(offset);
-        const countQuery = db
-            .select({ count: (0, drizzle_orm_1.sql) `count(*)` })
-            .from(this.config.table)
-            .where(whereExpr);
-        const [data, totalResult] = await this.runRead(Promise.all([dataQuery, countQuery]));
+        const countQuery = this.buildCountQuery(plan.db, conditions, plan.filterRelations, readOptions);
+        const [fetched, totalResult] = await this.runRead(Promise.all([dataQuery, countQuery]));
         const total = parseInt(totalResult[0]?.count?.toString() || "0", 10);
-        return { data, total, page, limit };
+        const rows = this.normalizeRelations(fetched, plan.joined.map((node) => node.name));
+        await Promise.all([
+            this.loadRelations(plan.db, rows, plan.nodes, plan.selection, undefined, readOptions),
+            this.loadCounts(plan.db, rows, readOptions.counts, readOptions),
+        ]);
+        return { data: rows, total, page, limit };
     }
 }
 exports.SqlBaseCrudService = SqlBaseCrudService;