fastify-auto-sqlapi 0.0.3 → 0.0.5

package/AGENTS.md

@@ -8,9 +8,9 @@ The plugin generates REST endpoints (search, get, insert, update, delete, bulk u
 
 ## Documentation
 
-- **[AGENTS_BACKEND.md](./AGENTS_BACKEND.md)** — Setup workflow, CLI, schema/table generation, `defineTable()` complete reference, `buildRelation`, `extraFilters` + `extendedCondition`, **SqlApi** (programmatic high-level API for custom routes), ConditionBuilder API, QueryClient API, Swagger, multi-tenant configuration, hooks, key conventions, common backend patterns, FAQ/gotchas, dialect differences.
+- **[AGENTS_BACKEND.md](./AGENTS_BACKEND.md)** — Setup workflow, CLI, schema/table generation, `defineTable()` complete reference, `buildRelation`, `extraFilters` + `extendedCondition`, **SqlApi** (programmatic high-level API for custom routes), ConditionBuilder API, QueryClient API, Swagger, multi-tenant configuration, **validation** (`validate` + `validateBulk`), hooks, key conventions, common backend patterns, FAQ/gotchas, dialect differences.
 
-- **[AGENTS_FRONTEND.md](./AGENTS_FRONTEND.md)** — Generated endpoints overview, search (POST with body filters, conditions/advanced filters using ConditionBuilder methods, query params for ordering/pagination/aggregation), joinFilters (EXISTS-based filtering by related tables), GET, INSERT (with secondaries), UPDATE (with secondaries + deletions), DELETE, bulk upsert, bulk delete, response shapes (PK-only), joins usage, joinGroups/aggregations, pagination, computed values.
+- **[AGENTS_FRONTEND.md](./AGENTS_FRONTEND.md)** — Generated endpoints overview, search (POST with body filters, conditions/advanced filters using ConditionBuilder methods, query params for ordering/pagination/aggregation), joinFilters (EXISTS-based filtering by related tables), GET, INSERT (with secondaries), UPDATE (with secondaries + deletions), DELETE, bulk upsert, bulk delete, response shapes (PK-only), **validation errors** (structured field-level 400 responses), joins usage, joinGroups/aggregations, pagination, computed values.
 
 ## Quick Reference
 

package/AGENTS_BACKEND.md

@@ -21,15 +21,16 @@ npm install @fastify/swagger @fastify/swagger-ui
 Create `sqlapi.config.ts` (or `.js`) in the project root. This config is used **only by the CLI** (`sqlapi-generate-schema` / `sqlapi-generate-tables`), NOT at runtime by the Fastify plugin.
 
 ```typescript
-// sqlapi.config.ts — interface: { outputDir: string; schema?: string; dialect?: DialectName }
+// sqlapi.config.ts — interface: { outputDir: string; schema?: string; dialect?: DialectName; envFile?: string }
 export default {
   outputDir: './src/db',       // base directory for generated files (default: './src/db')
   schema: 'public',            // DB schema to introspect (default: 'public', PostgreSQL only)
   dialect: 'postgres',         // 'postgres' | 'mysql' | 'mariadb' (default: 'postgres')
+  // envFile: '../../.env',    // path to .env file, relative to cwd (default: '.env')
 };
 ```
 
-That's it — only these three fields exist. **No connection string, no migration path.** If the file is missing, defaults are used. The `dialect` can also be passed via CLI flag `--dialect mysql`.
+That's it — only these four fields exist. **No connection string, no migration path.** If the file is missing, defaults are used. The `dialect` can also be passed via CLI flag `--dialect mysql`. The `envFile` is useful in monorepo setups where the `.env` lives at the repo root.
 
 ### 3. Configure database connection (env vars)
 
@@ -256,17 +257,43 @@ export const TableCustomer = defineTable({
   //   through: { schema: SchemaCustomer, localField: 'customerId', foreignField: 'id' },
   // },
 
-  // HOOKS
+  // SCHEMA OVERRIDES — tighten auto-generated schema validation without editing Schema files
+  schemaOverrides: {
+    email: Type.String({ format: 'email' }),
+    name: Type.String({ minLength: 1, maxLength: 100 }),
+  },
+
+  // VALIDATION — structured field-level validation (runs after schema, before hooks)
+  validate: async (db, req, main, secondaries) => {
+    // Return ValidationError[] — tuple: [field, code] or [field, code, message]
+    // message defaults to code if omitted
+    const errors = [];
+    if (main.name === '') {
+      errors.push(['name', 'required', 'cannot be empty']);
+    }
+    // Cross-entity: validate secondaries (e.g. date overlap in periods)
+    if (secondaries?.customer_order) {
+      // ... check overlaps, business rules across related records
+    }
+    return errors;
+  },
+  validateBulk: async (db, req, items) => {
+    // Called once with ALL items in bulk-upsert. Use for cross-item validation.
+    // items: Array<{ main, secondaries? }>
+    return []; // ValidationError[]
+  },
+
+  // HOOKS — side effects (runs after validation). All receive camelCase (schema field names).
   beforeInsert: async (db, req, record) => {
-    // Mutate record before INSERT. record is snake_case.
-    record.created_by = req.user.id;
+    // Mutate record before INSERT. Use camelCase (schema) field names — conversion is automatic.
+    record.createdBy = req.user.id;
   },
   afterInsert: async (db, req, record, secondaryRecords) => {
-    // Called after INSERT + secondaries. record is camelCase.
+    // Called after INSERT + secondaries. record is camelCase (input merged with generated PK).
   },
   beforeUpdate: async (db, req, fields) => {
-    // Mutate fields before UPDATE. fields is snake_case.
-    fields.updated_by = req.user.id;
+    // Mutate fields before UPDATE. camelCase. PK is present for reference but excluded from UPDATE SET.
+    fields.updatedBy = req.user.id;
   },
 
   // AUTH — per-table request hooks
@@ -404,6 +431,8 @@ const sqlApi = createSqlApi(db, dbTables, { dialect: 'mysql' });
 
 ```typescript
 // Search — full filter, join, pagination, aggregation support
+// orderBy supports dot notation for joinGroup aggregations: "session.sum.duration DESC"
+// (requires the joinGroup to be declared in the same request, see AGENTS_FRONTEND.md)
 sqlApi.search(tableName, {
   filters?, joinFilters?, joins?, joinGroups?,
   orderBy?, paginator?, computeMin?, computeMax?, computeSum?, computeAvg?,
@@ -564,11 +593,14 @@ Tables without `tenantScope` are unaffected — no filtering regardless of `getT
 
 ## Key Conventions
 
-- **camelCase in API, snake_case in DB**: all request/response fields are camelCase. The plugin converts automatically via `col()`.
+- **camelCase in API, any case in DB**: all request/response fields are camelCase. The plugin converts via `col()` and `colMap`. For snake_case DB columns (default), conversion is automatic. For camelCase DB columns (e.g. betterauth), the CLI generates a `colMap` that preserves the original column names — no conversion needed. Manual schemas without `colMap` fall back to `toUnderscore()`.
 - **All fields Optional in response**: `RETURNING *` may return any subset. Response schemas use `Type.Partial`.
 - **`excludeFromCreation`**: **IMPORTANT** — auto-increment PKs (e.g. `id` serial/auto_increment) MUST be listed here, otherwise INSERT will try to send them and fail. The CLI auto-detects this and adds it by default. Also useful for `createdAt`/`updatedAt` columns managed by DB defaults or hooks.
 - **`upsertMap`**: when present for a schema, INSERT becomes upsert. PostgreSQL: `ON CONFLICT (...) DO UPDATE`. MySQL/MariaDB: `ON DUPLICATE KEY UPDATE`. Applies to both main and secondary tables.
-- **Hooks receive snake_case**: `beforeInsert` and `beforeUpdate` receive snake_case records (pre-DB). `afterInsert` receives camelCase (post-DB).
+- **`schemaOverrides`**: override auto-generated schema fields with stricter TypeBox types (e.g. `{ email: Type.String({ format: 'email' }) }`). Overrides are merged into the body schema for insert, update, and bulk-upsert. The original Schema file is never modified. In updates, overridden fields are still wrapped in Optional (validates only when present). Overrides appear in Swagger.
+- **Validation receives camelCase**: `validate` receives the original camelCase record (as sent by the client) and secondaries. Field names match the schema definition, with full TypeScript inference (`main.startDate`, not `main.start_date`). It returns `ValidationError[]` — tuples of `[field, code]` or `[field, code, message]`. If any errors are returned, the request is rejected with 400 before hooks or SQL execute.
+- **`validateBulk` replaces `validate` in bulk**: when `validateBulk` is defined, it is called once with all items and per-item `validate` is skipped. This allows optimized batch queries instead of N individual checks. When only `validate` is defined, it runs per-item as fallback.
+- **All hooks and validators receive camelCase records**: `validate`, `beforeInsert`, `beforeUpdate`, and `afterInsert` all get records keyed by schema field names (camelCase). Mutations propagate to the SQL (plugin converts to DB column format via `colMap` after the hook). The engine internally uses `snakecaseRecord(..., schema)` after user mutations to map field names to actual DB columns.
 - **Filters validation**: TypeBox schemas use `additionalProperties: false`. By default Fastify strips unknown fields silently. For 400 errors on unknown filters: `Fastify({ ajv: { customOptions: { removeAdditional: false } } })`.
 - **Tenant filtering**: when `tenantScope` is set on a table and `getTenantId` is provided in plugin options, all CRUD operations are automatically scoped to the tenant. `getTenantId` returning `null`/`undefined` = admin (no filter). Returning an array = multi-tenant user (IN clause).
 
@@ -599,6 +631,70 @@ const TableAdmin = defineTable({
 });
 ```
 
+### Custom validation (field-level, cross-entity)
+
+```typescript
+import type { ValidationError } from 'fastify-auto-sqlapi';
+
+const TableSession = defineTable({
+  primary: 'id',
+  ...exportTableInfo(SchemaSession),
+  allowedWriteJoins: [
+    buildRelation(SchemaSession, 'id', SchemaPeriod, 'sessionId'),
+  ],
+  validate: async (db, req, main, secondaries) => {
+    // ValidationError is a tuple: [field, code] or [field, code, message]
+    // message defaults to code if omitted
+    const errors: ValidationError[] = [];
+
+    // Simple field validation
+    if (!main.name) {
+      errors.push(['name', 'required']);  // message defaults to 'required'
+    }
+
+    // Async validation (uniqueness check)
+    if (main.code) {
+      const existing = await db.query('SELECT 1 FROM session WHERE code = $1 AND id != $2', [main.code, main.id ?? 0]);
+      if (existing.rows.length) {
+        errors.push(['code', 'unique', 'already exists']);
+      }
+    }
+
+    // Cross-entity: validate periods don't overlap
+    const periods = secondaries?.session_period;
+    if (periods?.length) {
+      for (let i = 0; i < periods.length; i++) {
+        for (let j = i + 1; j < periods.length; j++) {
+          if (periods[i].startDate < periods[j].endDate && periods[j].startDate < periods[i].endDate) {
+            errors.push([`session_period[${j}].startDate`, 'overlap', 'overlaps with another period']);
+          }
+        }
+      }
+    }
+
+    return errors;
+  },
+});
+```
+
+`validate` runs on insert, update, and each item in bulk-upsert (when `validateBulk` is not defined). When `validateBulk` is defined, it **replaces** per-item `validate` in bulk operations — use it for optimized batch queries and cross-item validation:
+
+```typescript
+const TableSession = defineTable({
+  // ...
+  validateBulk: async (db, req, items) => {
+    // items: Array<{ main, secondaries? }>
+    // Check for duplicate codes across all items in the batch
+    const codes = items.map(i => i.main.code).filter(Boolean);
+    const unique = new Set(codes);
+    if (unique.size !== codes.length) {
+      return [['code', 'batch_unique', 'duplicate codes in batch']];
+    }
+    return [];
+  },
+});
+```
+
 ### Auto-fill audit fields
 
 ```typescript
@@ -606,12 +702,13 @@ const TableCustomer = defineTable({
   primary: 'id',
   ...exportTableInfo(SchemaCustomer),
   beforeInsert: async (db, req, record) => {
-    record.created_by = req.user.id;
-    record.created_at = db.expression('NOW()');
+    // camelCase — schema field names. The plugin converts to the actual DB column names.
+    record.createdBy = req.user.id;
+    record.createdAt = db.expression('NOW()');
   },
   beforeUpdate: async (db, req, fields) => {
-    fields.updated_by = req.user.id;
-    fields.updated_at = db.expression('NOW()');
+    fields.updatedBy = req.user.id;
+    fields.updatedAt = db.expression('NOW()');
   },
 });
 ```
@@ -738,4 +835,3 @@ The plugin internally strips `prefix` before passing options to sub-route plugin
 | **CLI env vars** | `POSTGRES_*` | `MYSQL_*` | `MYSQL_*` |
 | **CLI introspection** | `pg` | `mysql2` | `mysql2` |
 
-MySQL does not support `RETURNING`, so insert/upsert responses return only the PK (from record or `insertId`), not the full row.

package/AGENTS_FRONTEND.md

@@ -107,6 +107,40 @@ Also available: `isNotGreater`, `isNotGreaterOrEqual`, `isNotLess`, `isNotLessOr
 - **Field validation** — field names are validated against the table schema (400 if unknown)
 - **Method validation** — only whitelisted methods are allowed (`raw`, `append` etc. are blocked)
 
+#### Conditions on joinGroup aggregations (HAVING-style)
+
+You can filter main rows based on the value of a joinGroup aggregation using the same dot notation as `orderBy`: `<joinTable>.<fn>.<field>`.
+
+Example: "users with at least 4 sessions":
+
+```json
+{
+  "conditions": [
+    { "field": "session.count.id", "method": "isGreaterOrEqual", "params": [4] }
+  ],
+  "joinGroups": {
+    "session": { "aggregations": { "count": ["id"] } }
+  }
+}
+```
+
+Generated SQL:
+```sql
+SELECT * FROM "user"
+WHERE COALESCE((
+  SELECT COUNT("session"."id")
+  FROM "session"
+  WHERE "session"."user_id" = "user"."id"
+), 0) >= $1
+```
+
+**Rules:**
+- Same declaration requirement as orderBy: the joinGroup must be declared in `joinGroups.<table>.aggregations.<fn>` with the referenced field.
+- The joinGroup's own `filters` are applied inside the correlated subquery (consistent with the breakdown). Example: filter customers whose SUM of *completed* orders > 1000 by declaring `joinGroups.order.filters: { status: 'completed' }`.
+- All ConditionBuilder methods work: `isEqual`, `isGreater`, `isLess`, `isBetween`, `isIn`, `isNull`, `isNotNull`, etc.
+- Can be combined with plain-field conditions and with aggregation `orderBy` in the same request.
+- Respects `aggregations.by` rules: allowed when `by` equals the correlation FK, otherwise 400.
+
 ### Join Filters (filter main by related table)
 
 `joinFilters` restrict **main table results** based on conditions on a related table. Only tables listed in `allowedReadJoins` are available. Uses `EXISTS` subquery — no duplicate rows, works correctly with pagination.
@@ -151,6 +185,8 @@ The join executes as a separate query: `SELECT ... FROM {joinTable} WHERE {fk} I
         "sum": ["total"],
         "min": ["total"],
         "max": ["total"],
+        "avg": ["total"],
+        "count": ["id"],
         "distinctCount": ["status"]
       },
       "filters": { "status": "active" }
@@ -160,7 +196,8 @@ The join executes as a separate query: `SELECT ... FROM {joinTable} WHERE {fk} I
 ```
 
 - `by` — GROUP BY field
-- `sum`, `min`, `max` — aggregate functions on specified columns
+- `sum`, `min`, `max`, `avg` — aggregate functions on specified columns
+- `count` — COUNT(col)
 - `distinctCount` — COUNT(DISTINCT col)
 - `filters` — optional, narrow rows before aggregation
 
@@ -176,6 +213,46 @@ Use the `orderBy` query parameter:
 
 If not specified, the table's `defaultOrder` is used.
 
+#### Ordering by joinGroup aggregations
+
+You can order the main results by an aggregation computed on a joined table using dot notation: `<joinTable>.<fn>.<field>`.
+
+Supported functions: `sum`, `min`, `max`, `avg`, `count`, `distinctCount`.
+
+Example: get users ordered by total session duration DESC.
+
+```
+POST /auto/search/user?orderBy=session.sum.duration%20DESC
+```
+```json
+{
+  "joinGroups": {
+    "session": {
+      "aggregations": { "sum": ["duration"] }
+    }
+  }
+}
+```
+
+Generated SQL (simplified):
+```sql
+SELECT * FROM "user"
+ORDER BY (
+  SELECT SUM("session"."duration")
+  FROM "session"
+  WHERE "session"."user_id" = "user"."id"
+) DESC
+```
+
+**Rules:**
+- The joinGroup **must be declared in the request body** (`joinGroups.<table>.aggregations.<fn>` must include the field). The engine refuses undeclared references with 400.
+- If the joinGroup declares `aggregations.filters`, those filters are applied inside the correlated subquery — consistent with the breakdown.
+- **`aggregations.by`**: allowed **only** when `by` is the same field used for the join correlation (e.g. `by: "userId"` when joining user→session via userId). In that case each main row maps to exactly one group, so the ordering is well-defined *and* the response contains the per-row breakdown you can render next to each row. Using `by` on any other column is rejected with 400 (the result would be bucketed per group, not per row).
+- **Not allowed** when the main table has `distinctResults: true`. 400 error.
+- Can be combined with plain field ordering: `?orderBy=session.sum.duration DESC, name ASC`.
+- The joinGroup breakdown is still returned in the response (`joinGroups.session.sum.duration` etc.) as before — you get both ordered main results and the aggregated summary.
+- **No-data rows**: rows with no matching joined records are coalesced to `0` via `COALESCE(..., 0)`. Practically: on DESC they appear last, on ASC they appear first. This is universal across PostgreSQL, MySQL, and MariaDB.
+
 ### Pagination
 
 Add `page` or `itemsPerPage` to the query string to enable pagination:
@@ -359,6 +436,54 @@ Each object must contain the PK field. All deletions execute as a single `DELETE
 
 ---
 
+## Validation Errors
+
+Insert, update, and bulk-upsert endpoints may return **structured field-level validation errors** (400). Two sources:
+
+1. **Schema validation** (TypeBox/Ajv) — type mismatches, missing required fields
+2. **Custom validation** (`validate` / `validateBulk` on the table) — business rules, cross-entity checks
+
+Both return the same response format:
+
+```json
+{
+  "statusCode": 400,
+  "error": "Bad Request",
+  "message": "Validation failed",
+  "fields": [
+    { "path": "body.main.name", "code": "required", "message": "must have required property 'name'" },
+    { "path": "session_period[1].startDate", "code": "overlap", "message": "overlaps with another period" }
+  ]
+}
+```
+
+Each entry in `fields`:
+- `path` — the field path (e.g. `body.main.name` for schema errors, `name` or `session_period[1].startDate` for custom validation)
+- `code` — machine-readable error code (e.g. `required`, `type`, `overlap`, `unique`)
+- `message` — human-readable description
+
+### Handling validation errors in the frontend
+
+```typescript
+const response = await fetch('/api/rest/session', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ main: { name: '' }, secondaries: { session_period: periods } }),
+});
+
+if (!response.ok) {
+  const error = await response.json();
+  if (error.fields) {
+    // Field-level errors — display inline on the form
+    for (const { path, message } of error.fields) {
+      setFieldError(path, message);
+    }
+  }
+}
+```
+
+---
+
 ## Response Conventions
 
 - **PK-only responses**: Insert, update, delete, bulk operations return only the primary key fields, not the full record. This is by design for performance and consistency.

package/README.md

@@ -1,8 +1,8 @@
 # fastify-auto-sqlapi
 
-Automatic CRUD API generation from PostgreSQL tables for [Fastify](https://fastify.dev/). No ORM, no magic — just raw SQL via `pg`, with TypeBox validation and Swagger docs out of the box.
+Automatic CRUD API generation from PostgreSQL, MySQL, and MariaDB tables for [Fastify](https://fastify.dev/). No ORM, no magic — just raw SQL, with TypeBox validation and Swagger docs out of the box.
 
-Point it at your database, and get a full REST API with search, pagination, joins, bulk operations, multi-tenant isolation, and hooks.
+Point it at your database, and get a full REST API with search, advanced conditions, pagination, joins, aggregations, bulk operations, multi-tenant isolation, validation, and hooks.
 
 ## Features
 
@@ -12,6 +12,7 @@ Point it at your database, and get a full REST API with search, pagination, join
 - **Virtual joins** — fetch related records without complex SQL
 - **Bulk operations** — batch insert/upsert/delete in single queries
 - **Multi-tenant** — automatic row-level isolation, zero code in handlers
+- **Validation** — structured field-level validation with cross-entity support
 - **Hooks** — `beforeInsert`, `beforeUpdate`, `afterInsert` for custom logic
 - **Swagger UI** — optional, auto-configured from your schemas
 - **Composable** — register all routes or pick only what you need
@@ -155,13 +156,30 @@ const TableCustomer = defineTable({
     buildUpsertRule(SchemaCustomer, ['id']),
   ),
 
+  // Schema overrides (tighten generated schema without editing Schema files)
+  schemaOverrides: {
+    email: Type.String({ format: 'email' }),
+  },
+
   // Multi-tenant isolation
   tenantScope: { column: 'organization_id' },
 
-  // Hooks
-  beforeInsert: async (db, req, record) => { /* record is snake_case */ },
-  beforeUpdate: async (db, req, fields) => { /* fields is snake_case */ },
-  afterInsert: async (db, req, record, secondaryRecords) => { /* record is camelCase */ },
+  // Validation (runs after schema validation, before hooks)
+  validate: async (db, req, main, secondaries) => {
+    // Return ValidationError[] — tuple: [field, code] or [field, code, message]
+    // message defaults to code if omitted
+    if (!main.name) return [['name', 'required']];
+    return [];
+  },
+  validateBulk: async (db, req, items) => {
+    // Bulk-upsert only. Called once with all items for cross-item validation.
+    return [];
+  },
+
+  // Hooks (runs after validation) — all receive camelCase records (schema field names)
+  beforeInsert: async (db, req, record) => { /* camelCase; mutations propagate to INSERT */ },
+  beforeUpdate: async (db, req, fields) => { /* camelCase; PK included for reference, excluded from UPDATE SET */ },
+  afterInsert: async (db, req, record, secondaryRecords) => { /* camelCase; input merged with generated PK */ },
 
   // Auth (per-table)
   onRequests: [
@@ -201,37 +219,80 @@ const TableCustomer = defineTable({
 ```typescript
 await app.register(fastifyAutoSqlApi, {
   DbTables: dbTables,           // Required — your table definitions
+  dialect: 'postgres',          // Optional — 'postgres' | 'mysql' | 'mariadb' (default: 'postgres')
   prefix: '/api',               // Optional — URL prefix for all routes
   swagger: true,                // Optional — enable Swagger UI (or pass SwaggerOptions)
   onRequests: [authMiddleware],  // Optional — global hooks applied to every route
   getTenantId: (req) => id,     // Optional — multi-tenant function
+  debug: true,                  // Optional — log all SQL queries and params
 });
 ```
 
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `DbTables` | `Record<string, ITable>` | Yes | Table configurations |
+| `dialect` | `'postgres' \| 'mysql' \| 'mariadb'` | No | DB dialect (default: `'postgres'`) |
 | `prefix` | `string` | No | URL prefix (e.g. `/api`) |
 | `swagger` | `boolean \| SwaggerOptions` | No | Enable Swagger UI |
 | `onRequests` | `Function[]` | No | Global auth/middleware hooks |
 | `getTenantId` | `(req) => id \| null` | No | Tenant resolver for multi-tenant |
+| `debug` | `boolean` | No | Log all SQL queries to console |
+
+For MySQL/MariaDB, register `mysql2/promise` pool instead of `@fastify/postgres` and pass `dialect: 'mysql'` or `'mariadb'`.
 
 ## API Reference
 
 ### POST /search/{table}
 
-Search with filters, pagination, ordering, joins, and aggregations.
+Search with filters, advanced conditions, pagination, ordering, joins, and aggregations.
 
 **Request body** (all fields optional):
 
 ```json
 {
   "filters": { "name": "Mario" },
-  "joins": { "order": {} },
-  "paginator": { "page": 1, "itemsPerPage": 20 }
+  "conditions": [
+    { "field": "total", "method": "isGreater", "params": [100] },
+    { "field": "createdAt", "method": "isBetween", "params": ["2024-01-01", "2024-12-31"] }
+  ],
+  "joinFilters": {
+    "order": {
+      "filters": { "status": "completed" },
+      "conditions": [{ "field": "total", "method": "isGreater", "params": [50] }]
+    }
+  },
+  "joins": {
+    "order": {
+      "filters": { "status": "completed" },
+      "conditions": [{ "field": "total", "method": "isGreater", "params": [50] }]
+    }
+  },
+  "joinGroups": {
+    "order": {
+      "aggregations": {
+        "by": "status",
+        "sum": ["total"],
+        "min": ["total"],
+        "max": ["total"],
+        "avg": ["total"],
+        "count": ["id"],
+        "distinctCount": ["status"]
+      },
+      "filters": { "status": "completed" },
+      "conditions": [{ "field": "total", "method": "isGreater", "params": [0] }]
+    }
+  }
 }
 ```
 
+- **`filters`** — equality-based, flat key/value. Supports schema fields + `extraFilters`.
+- **`conditions`** — array of `{ field, method, params }`. Methods: `isEqual`, `isNotEqual`, `isGreater`, `isGreaterOrEqual`, `isLess`, `isLessOrEqual`, `isLike`, `isILike`, `isIn`, `isNotIn`, `isBetween`, `isNotBetween`, `isNull`, `isNotNull`.
+- **`joinFilters`** — EXISTS-based filtering: "main rows where at least one related row matches". Accepts `{ filters, conditions }` (both optional). Only tables in `allowedReadJoins`.
+- **`joins`** — fetch related records (virtual join via separate query). Accepts `{ filters, conditions }`.
+- **`joinGroups`** — aggregations on related tables. Supports `sum`, `min`, `max`, `avg`, `count`, `distinctCount`, and optional `by` for GROUP BY. Accepts `{ filters, conditions }` inside the subquery.
+
+**Dot-notation in `conditions` and `orderBy`** — use `<joinTable>.<fn>.<field>` to filter/order the main rows by an aggregation value (HAVING-style). Example: `orderBy=order.sum.total DESC` or `conditions: [{ field: 'order.count.id', method: 'isGreaterOrEqual', params: [4] }]`. The joinGroup must be declared in the body.
+
 **Querystring** (optional): `orderBy`, `page`, `itemsPerPage`, `computeMin`, `computeMax`, `computeSum`, `computeAvg`
 
 **Response:**
@@ -241,11 +302,23 @@ Search with filters, pagination, ordering, joins, and aggregations.
   "table": "customer",
   "main": [{ "id": 1, "name": "Mario", "email": "m@test.it" }],
   "joins": { "order": [{ "id": 10, "customerId": 1, "total": 50 }] },
-  "pagination": { "total": 25, "pages": 3, "paginator": { "page": 1, "itemsPerPage": 20 } }
+  "joinGroups": {
+    "order": {
+      "sum": { "total": 300 },
+      "count": { "id": 2 },
+      "rows": [{ "by": "completed", "sum_total": 300, "count_id": 2 }]
+    }
+  },
+  "pagination": {
+    "total": 25,
+    "pages": 3,
+    "computed": { "min": { "id": 1 }, "max": { "id": 100 } },
+    "paginator": { "page": 1, "itemsPerPage": 20 }
+  }
 }
 ```
 
-`joins`, `joinGroups`, and `pagination` only appear when requested. A simple `{}` body returns `{ table, main }`.
+`joins`, `joinGroups`, and `pagination` only appear when requested. A simple `{}` body returns `{ table, main }`. `pagination.computed` appears only if `computeMin`/`computeMax`/`computeSum`/`computeAvg` are used.
 
 ### GET /rest/{table}/:id
 
@@ -294,6 +367,24 @@ Returns the deleted record or 404.
 
 **Body:** Array of objects with the PK field, e.g. `[{ "id": 1 }, { "id": 2 }]`. Executes as a single `DELETE WHERE pk IN (...)`.
 
+### Validation errors (400)
+
+Both schema-level (TypeBox/Ajv) and custom (`validate` / `validateBulk`) errors use the same response shape:
+
+```json
+{
+  "statusCode": 400,
+  "error": "Bad Request",
+  "message": "Validation failed",
+  "fields": [
+    { "path": "main.email", "code": "format", "message": "must match format \"email\"" },
+    { "path": "name", "code": "required", "message": "is required" }
+  ]
+}
+```
+
+Custom validators return tuples `[field, code]` or `[field, code, message]` — `message` defaults to `code` if omitted. `validateBulk` replaces per-item `validate` in bulk-upsert requests.
+
 ## Multi-Tenant
 
 Automatic row-level isolation on all CRUD operations. Configure once, no code in handlers.
@@ -387,9 +478,9 @@ await app.register(async (instance) => {
 
 ## Conventions
 
-- **camelCase in API, snake_case in DB** — the plugin converts automatically
-- **Joins are virtual** — they execute separate `SELECT ... WHERE fk IN (...)` queries, not SQL JOINs
-- **Hooks receive snake_case** — `beforeInsert` and `beforeUpdate` get snake_case records; `afterInsert` gets camelCase
+- **camelCase everywhere in the API** — requests, responses, `validate`, and all hooks (`beforeInsert`, `beforeUpdate`, `afterInsert`) use schema field names
+- **Conversion to DB column format is automatic** via `colMap` — supports both snake_case and camelCase DB columns (e.g. betterauth-style)
+- **Joins are virtual** — separate `SELECT ... WHERE fk IN (...)` queries, not SQL JOINs
 - **All response fields are Optional** — response schemas use `Type.Partial` since `RETURNING *` may return any subset
 
 ## Re-exports
@@ -399,23 +490,49 @@ The package re-exports commonly needed utilities so you don't need to install th
 ```typescript
 import {
   Type,                   // from @sinclair/typebox
+  type Static,            // from @sinclair/typebox
   ConditionBuilder,       // from node-condition-builder
   Expression,             // from node-condition-builder
-  QueryClient,            // raw SQL query helper
+
+  // Table configuration
   defineTable,
   exportTableInfo,
   buildRelation,
   buildUpsertRule,
   buildUpsertRules,
+
+  // DB layer
+  QueryClient,            // raw SQL query helper
+  createQueryClient,      // factory with dialect string
+  pgQueryable,            // pg pool adapter
+  mysqlQueryable,         // mysql2 pool adapter
+
+  // Programmatic high-level API
+  createSqlApi,           // standalone SqlApi (for scripts/tests)
+  setupSwagger,           // manual Swagger registration
+} from 'fastify-auto-sqlapi';
+
+import type {
+  ValidationError,        // [field, code] | [field, code, message]
+  ValidatorFn,
+  BulkValidatorFn,
+  JoinRefFilter,
+  JoinGroupRequest,
+  SearchCondition,
+  ConditionMethod,
 } from 'fastify-auto-sqlapi';
 ```
 
+After registering the plugin, `app.sqlApi` is decorated on the Fastify instance and exposes `search`, `get`, `insert`, `update`, `delete`, `bulkUpsert`, `bulkDelete` for custom routes — same code path as the auto-generated endpoints.
+
 ## Requirements
 
 - Node.js >= 18
-- PostgreSQL
-- Fastify >= 4
-- `@fastify/postgres` >= 5
+- Fastify >= 4 (peer dependency)
+- One of:
+  - **PostgreSQL** + `pg` + `@fastify/postgres`
+  - **MySQL** / **MariaDB** + `mysql2`
+- Optional: `@fastify/swagger` + `@fastify/swagger-ui` for Swagger UI
 
 ## License
 

package/dist/bin/generate-schema.js

@@ -6,7 +6,6 @@ import { buildConnectionString, introspectTables } from '../lib/cli/pg-introspec
 import { buildMysqlConnectionConfig, introspectMysqlTables } from '../lib/cli/mysql-introspect.js';
 import { buildTableMap, generateSchemaFile } from '../lib/cli/schema-codegen.js';
 import { loadEnvFile, CONSOLE_COLORS, display, displayAsTableRow, error } from './utils.js';
-loadEnvFile();
 function parseCliArgs() {
     const args = process.argv.slice(2);
     const result = {};
@@ -27,6 +26,7 @@ async function main() {
     display('++++++ fastify-auto-sqlapi: generating schemas ++++++', CONSOLE_COLORS.yellow);
     const cliArgs = parseCliArgs();
     const config = await loadConfig();
+    loadEnvFile(config.envFile);
     const dialect = (cliArgs.dialect || config.dialect || 'postgres');
     const schema = config.schema || (dialect === 'postgres' ? 'public' : config.schema || 'public');
     const outputDir = path.resolve(process.cwd(), cliArgs.output || config.outputDir);
@@ -67,10 +67,10 @@ async function main() {
     let untouched = 0;
     const generatedFiles = new Set();
     for (const schemaName of Object.keys(tableMap)) {
-        const { name: tableName, fields } = tableMap[schemaName];
+        const { name: tableName, fields, colMap } = tableMap[schemaName];
         const filename = path.join(schemasDir, `${schemaName}.ts`);
         generatedFiles.add(`${schemaName}.ts`);
-        const content = generateSchemaFile(schemaName, tableName, fields);
+        const content = generateSchemaFile(schemaName, tableName, fields, colMap);
         let status = 'created';
         let color = CONSOLE_COLORS.green;
         if (fs.existsSync(filename)) {