relq 1.0.69 → 1.0.71

package/dist/cjs/cli/adapters/registry.cjs

@@ -149,7 +149,12 @@ function getLoadedDialects() {
         .map(([dialect]) => dialect);
 }
 async function preloadAdapters(dialects) {
-    await Promise.all(dialects.map(dialect => getAdapter(dialect)));
+    const results = await Promise.allSettled(dialects.map(dialect => getAdapter(dialect)));
+    const failures = results.filter((r) => r.status === 'rejected');
+    if (failures.length > 0) {
+        const messages = failures.map(f => f.reason?.message || String(f.reason)).join('; ');
+        throw new Error(`Failed to load ${failures.length} adapter(s): ${messages}`);
+    }
 }
 async function preloadFamily(family) {
     registerDefaultAdapters();

package/dist/cjs/cli/utils/pool-manager.cjs

@@ -146,7 +146,11 @@ async function closeAllPools() {
         closePromises.push(entry.pool.end());
         pools.delete(key);
     }
-    await Promise.all(closePromises);
+    const results = await Promise.allSettled(closePromises);
+    const failures = results.filter((r) => r.status === 'rejected');
+    if (failures.length > 0) {
+        console.warn(`Warning: ${failures.length} pool(s) failed to close gracefully`);
+    }
 }
 function getActivePoolCount() {
     return pools.size;

package/dist/cjs/core/helpers/ConnectedSelectBuilder.cjs

@@ -52,6 +52,13 @@ class ConnectedSelectBuilder {
         this.builder.orderBy(dbColumn, direction);
         return this;
     }
+    orderByNulls(column, direction, nulls) {
+        const dbColumn = this.relq[methods_1.INTERNAL].hasColumnMapping()
+            ? Object.keys(this.relq[methods_1.INTERNAL].transformToDbColumns(this.tableName, { [column]: true }))[0]
+            : column;
+        this.builder.orderByNulls(dbColumn, direction, nulls);
+        return this;
+    }
     limit(count) {
         this.builder.limit(count);
         return this;

package/dist/cjs/select/select-builder.cjs

@@ -114,6 +114,10 @@ class SelectBuilder {
         this.orderByColumns.push({ column, direction });
         return this;
     }
+    orderByNulls(column, direction, nulls) {
+        this.orderByColumns.push({ column, direction, nulls });
+        return this;
+    }
     orderAsc(column) {
         return this.orderBy(column, 'ASC');
     }
@@ -325,7 +329,13 @@ class SelectBuilder {
         }
         if (this.orderByColumns.length > 0) {
             query += ' ORDER BY ' + this.orderByColumns
-                .map(order => (0, pg_format_1.default)('%I %s', order.column, order.direction))
+                .map(order => {
+                let sql = (0, pg_format_1.default)('%I %s', order.column, order.direction);
+                if (order.nulls) {
+                    sql += ` NULLS ${order.nulls}`;
+                }
+                return sql;
+            })
                 .join(', ');
         }
         if (this.limitValue !== undefined) {

package/dist/esm/cli/adapters/registry.js

@@ -101,7 +101,12 @@ export function getLoadedDialects() {
         .map(([dialect]) => dialect);
 }
 export async function preloadAdapters(dialects) {
-    await Promise.all(dialects.map(dialect => getAdapter(dialect)));
+    const results = await Promise.allSettled(dialects.map(dialect => getAdapter(dialect)));
+    const failures = results.filter((r) => r.status === 'rejected');
+    if (failures.length > 0) {
+        const messages = failures.map(f => f.reason?.message || String(f.reason)).join('; ');
+        throw new Error(`Failed to load ${failures.length} adapter(s): ${messages}`);
+    }
 }
 export async function preloadFamily(family) {
     registerDefaultAdapters();

package/dist/esm/cli/utils/pool-manager.js

@@ -104,7 +104,11 @@ export async function closeAllPools() {
         closePromises.push(entry.pool.end());
         pools.delete(key);
     }
-    await Promise.all(closePromises);
+    const results = await Promise.allSettled(closePromises);
+    const failures = results.filter((r) => r.status === 'rejected');
+    if (failures.length > 0) {
+        console.warn(`Warning: ${failures.length} pool(s) failed to close gracefully`);
+    }
 }
 export function getActivePoolCount() {
     return pools.size;

package/dist/esm/core/helpers/ConnectedSelectBuilder.js

@@ -49,6 +49,13 @@ export class ConnectedSelectBuilder {
         this.builder.orderBy(dbColumn, direction);
         return this;
     }
+    orderByNulls(column, direction, nulls) {
+        const dbColumn = this.relq[INTERNAL].hasColumnMapping()
+            ? Object.keys(this.relq[INTERNAL].transformToDbColumns(this.tableName, { [column]: true }))[0]
+            : column;
+        this.builder.orderByNulls(dbColumn, direction, nulls);
+        return this;
+    }
     limit(count) {
         this.builder.limit(count);
         return this;

package/dist/esm/select/select-builder.js

@@ -108,6 +108,10 @@ export class SelectBuilder {
         this.orderByColumns.push({ column, direction });
         return this;
     }
+    orderByNulls(column, direction, nulls) {
+        this.orderByColumns.push({ column, direction, nulls });
+        return this;
+    }
     orderAsc(column) {
         return this.orderBy(column, 'ASC');
     }
@@ -319,7 +323,13 @@ export class SelectBuilder {
         }
         if (this.orderByColumns.length > 0) {
             query += ' ORDER BY ' + this.orderByColumns
-                .map(order => format('%I %s', order.column, order.direction))
+                .map(order => {
+                let sql = format('%I %s', order.column, order.direction);
+                if (order.nulls) {
+                    sql += ` NULLS ${order.nulls}`;
+                }
+                return sql;
+            })
                 .join(', ');
         }
         if (this.limitValue !== undefined) {

package/dist/index.d.ts

@@ -1676,6 +1676,26 @@ export declare class SelectBuilder {
 	groupBy(...columns: string[]): SelectBuilder;
 	having(callback: (builder: TypedConditionBuilder<any>) => TypedConditionBuilder<any>): SelectBuilder;
 	orderBy(column: string, direction?: "ASC" | "DESC"): SelectBuilder;
+	/**
+	 * Order by with explicit NULLS FIRST or NULLS LAST placement.
+	 * PostgreSQL-specific ordering control for NULL values.
+	 *
+	 * @param column - Column to order by
+	 * @param direction - 'ASC' or 'DESC'
+	 * @param nulls - 'FIRST' puts NULLs at the beginning, 'LAST' puts them at the end
+	 *
+	 * @example
+	 * ```typescript
+	 * // NULLs at end for ascending order (default PostgreSQL behavior for DESC)
+	 * builder.orderByNulls('priority', 'ASC', 'LAST')
+	 * // SQL: ORDER BY "priority" ASC NULLS LAST
+	 *
+	 * // NULLs at start for descending order
+	 * builder.orderByNulls('created_at', 'DESC', 'FIRST')
+	 * // SQL: ORDER BY "created_at" DESC NULLS FIRST
+	 * ```
+	 */
+	orderByNulls(column: string, direction: "ASC" | "DESC", nulls: "FIRST" | "LAST"): SelectBuilder;
 	orderAsc(column: string): SelectBuilder;
 	orderDesc(column: string): SelectBuilder;
 	limit(count: number): SelectBuilder;
@@ -7706,9 +7726,31 @@ declare class ConnectedDeleteBuilder<TTable = any> {
 	run(): Promise<number>;
 	run(withMetadata: true): Promise<RelqRun>;
 	/**
-	 * Set RETURNING clause - returns executor with typed run()
-	 * Use '*' to return all columns, or specify column names
-	 * Pass null to skip RETURNING clause (useful for conditional returning)
+	 * Set RETURNING clause - returns executor with typed results.
+	 * Use '*' to return all columns, or specify column names.
+	 * Pass null to skip RETURNING clause (useful for conditional returning).
+	 *
+	 * **Dialect Support:**
+	 * | Dialect     | Supported | Notes |
+	 * |-------------|-----------|-------|
+	 * | PostgreSQL  | ✅        | Native RETURNING support |
+	 * | CockroachDB | ✅        | Native RETURNING support |
+	 * | Nile        | ✅        | Native RETURNING support |
+	 * | AWS DSQL    | ✅        | Native RETURNING support |
+	 * | MySQL       | ❌        | No RETURNING support |
+	 * | SQLite      | ✅        | Native RETURNING support (3.35+) |
+	 *
+	 * @param columns - '*' for all, column name(s), or null to skip
+	 * @throws {RelqConfigError} If dialect doesn't support RETURNING
+	 *
+	 * @example
+	 * ```typescript
+	 * // Get deleted row data
+	 * const deleted = await db.table.users.delete()
+	 *   .where(q => q.equal('id', userId))
+	 *   .returning('*')
+	 *   .run()
+	 * ```
 	 */
 	returning(columns: null): this;
 	returning(columns: "*"): ReturningExecutor<TTable extends {
@@ -7745,31 +7787,60 @@ declare class ConnectedInsertBuilder<TTable = any> {
 	clear(): this;
 	get total(): number;
 	/**
-	 * ON CONFLICT DO NOTHING - skip insert if conflict occurs
+	 * ON CONFLICT DO NOTHING - skip insert if conflict occurs.
+	 * The insert is silently skipped when a unique constraint violation occurs.
+	 *
+	 * **Dialect Support:**
+	 * | Dialect     | Supported | Notes |
+	 * |-------------|-----------|-------|
+	 * | PostgreSQL  | ✅        | Native ON CONFLICT support |
+	 * | CockroachDB | ✅        | Native ON CONFLICT support |
+	 * | Nile        | ✅        | Native ON CONFLICT support |
+	 * | AWS DSQL    | ✅        | Native ON CONFLICT support |
+	 * | MySQL       | ⚠️        | Uses INSERT IGNORE (different semantics) |
+	 * | SQLite      | ✅        | Native ON CONFLICT support |
+	 *
 	 * @param columns - Column(s) for conflict detection (array or multiple args)
+	 *
 	 * @example
 	 * ```typescript
-	 * .doNothing('email')
-	 * .doNothing('email', 'userId')
-	 * .doNothing(['email', 'userId'])
+	 * // Single column conflict
+	 * await db.table.users.insert({ email: 'test@example.com' })
+	 *   .doNothing('email')
+	 *   .execute()
+	 *
+	 * // Multiple columns (composite unique constraint)
+	 * await db.table.userRoles.insert({ userId, roleId })
+	 *   .doNothing('userId', 'roleId')
+	 *   .execute()
 	 * ```
 	 */
 	doNothing(columns: ColumnName<TTable>[]): this;
 	doNothing(...columns: ColumnName<TTable>[]): this;
 	/**
-	 * ON CONFLICT DO UPDATE - update row if conflict occurs
-	 * 100% type-safe, no raw SQL needed
+	 * ON CONFLICT DO UPDATE - update row if conflict occurs (UPSERT).
+	 * 100% type-safe, no raw SQL needed.
+	 *
+	 * **Dialect Support:**
+	 * | Dialect     | Supported | Notes |
+	 * |-------------|-----------|-------|
+	 * | PostgreSQL  | ✅        | Full EXCLUDED.* support |
+	 * | CockroachDB | ✅        | Full EXCLUDED.* support |
+	 * | Nile        | ✅        | Full EXCLUDED.* support |
+	 * | AWS DSQL    | ✅        | Full EXCLUDED.* support |
+	 * | MySQL       | ⚠️        | Uses ON DUPLICATE KEY UPDATE (different syntax) |
+	 * | SQLite      | ✅        | Uses ON CONFLICT DO UPDATE |
 	 *
 	 * @param columns - Column(s) for conflict detection
 	 * @param values - Values to update (static or expression functions)
-	 * @param where - Optional type-safe where clause builder (same as SELECT/UPDATE/DELETE)
+	 * @param where - Optional type-safe where clause for conditional updates
 	 *
 	 * @example
 	 * ```typescript
 	 * // Static values
 	 * .doUpdate('email', { status: 'updated' })
 	 *
-	 * // Expression functions
+	 * // Expression functions - access EXCLUDED and current row values
 	 * .doUpdate('email', {
 	 *   balance: (excluded, sql) => sql.add(excluded.balance, 100),
 	 *   count: (excluded, sql, row) => sql.increment(1),
@@ -7780,23 +7851,10 @@ declare class ConnectedInsertBuilder<TTable = any> {
 	 * // Multiple conflict columns
 	 * .doUpdate(['email', 'tenantId'], { status: 'updated' })
 	 *
-	 * // With type-safe where clause (FULL TypedConditionBuilder support!)
+	 * // With type-safe where clause
 	 * .doUpdate('email', { balance: 100 }, q =>
 	 *   q.notEqual('role', 'admin')
 	 *    .in('status', ['active', 'pending'])
-	 *    .or(q => q.isNull('deletedAt').greaterThan('score', 100))
-	 * )
-	 *
-	 * // JSONB conditions in conflict where
-	 * .doUpdate('email', { updatedAt: new Date() }, q =>
-	 *   q.jsonb.hasKey('metadata', 'verified')
-	 *    .array.contains('tags', ['premium'])
-	 * )
-	 *
-	 * // Regex, fulltext, and more
-	 * .doUpdate('email', { status: 'matched' }, q =>
-	 *   q.regex('code', '^[A-Z]{3}[0-9]+$')
-	 *    .fulltext.search('description', 'important')
 	 * )
 	 * ```
 	 */
@@ -7812,9 +7870,36 @@ declare class ConnectedInsertBuilder<TTable = any> {
 	run(): Promise<number>;
 	run(withMetadata: true): Promise<RelqRun>;
 	/**
-	 * Set RETURNING clause - returns executor with typed run()
-	 * Use '*' to return all columns, or specify column names
-	 * Pass null to skip RETURNING clause (useful for conditional returning)
+	 * Set RETURNING clause - returns executor with typed results.
+	 * Use '*' to return all columns, or specify column names.
+	 * Pass null to skip RETURNING clause (useful for conditional returning).
+	 *
+	 * **Dialect Support:**
+	 * | Dialect     | Supported | Notes |
+	 * |-------------|-----------|-------|
+	 * | PostgreSQL  | ✅        | Native RETURNING support |
+	 * | CockroachDB | ✅        | Native RETURNING support |
+	 * | Nile        | ✅        | Native RETURNING support |
+	 * | AWS DSQL    | ✅        | Native RETURNING support |
+	 * | MySQL       | ❌        | Use LAST_INSERT_ID() instead |
+	 * | SQLite      | ✅        | Native RETURNING support (3.35+) |
+	 *
+	 * @param columns - '*' for all, column name(s), or null to skip
+	 * @throws {RelqConfigError} If dialect doesn't support RETURNING
+	 *
+	 * @example
+	 * ```typescript
+	 * // Return all columns
+	 * const user = await db.table.users.insert({ name: 'John' })
+	 *   .returning('*')
+	 *   .run()
+	 * // user has all columns from users table
+	 *
+	 * // Return specific columns
+	 * const { id, createdAt } = await db.table.users.insert({ name: 'John' })
+	 *   .returning(['id', 'createdAt'])
+	 *   .run()
+	 * ```
 	 */
 	returning(columns: null): this;
 	returning(columns: "*"): ReturningExecutor<TTable extends {
@@ -7855,9 +7940,31 @@ declare class ConnectedUpdateBuilder<TTable = any> {
 	run(): Promise<number>;
 	run(withMetadata: true): Promise<RelqRun>;
 	/**
-	 * Set RETURNING clause - returns executor with typed run()
-	 * Use '*' to return all columns, or specify column names
-	 * Pass null to skip RETURNING clause (useful for conditional returning)
+	 * Set RETURNING clause - returns executor with typed results.
+	 * Use '*' to return all columns, or specify column names.
+	 * Pass null to skip RETURNING clause (useful for conditional returning).
+	 *
+	 * **Dialect Support:**
+	 * | Dialect     | Supported | Notes |
+	 * |-------------|-----------|-------|
+	 * | PostgreSQL  | ✅        | Native RETURNING support |
+	 * | CockroachDB | ✅        | Native RETURNING support |
+	 * | Nile        | ✅        | Native RETURNING support |
+	 * | AWS DSQL    | ✅        | Native RETURNING support |
+	 * | MySQL       | ❌        | No RETURNING support |
+	 * | SQLite      | ✅        | Native RETURNING support (3.35+) |
+	 *
+	 * @param columns - '*' for all, column name(s), or null to skip
+	 * @throws {RelqConfigError} If dialect doesn't support RETURNING
+	 *
+	 * @example
+	 * ```typescript
+	 * // Return updated row
+	 * const user = await db.table.users.update({ score: 100 })
+	 *   .where(q => q.equal('id', userId))
+	 *   .returning('*')
+	 *   .run()
+	 * ```
 	 */
 	returning(columns: null): this;
 	returning(columns: "*"): ReturningExecutor<TTable extends {
@@ -8287,6 +8394,30 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	private setupColumnResolver;
 	where(callback: (q: TypedConditionBuilder<TTable>) => TypedConditionBuilder<TTable>): this;
 	orderBy(column: ColumnName<TTable>, direction?: "ASC" | "DESC"): this;
+	/**
+	 * Order by with explicit NULLS FIRST or NULLS LAST placement.
+	 * PostgreSQL-specific ordering control for NULL values.
+	 *
+	 * @param column - Column to order by (type-safe)
+	 * @param direction - 'ASC' or 'DESC'
+	 * @param nulls - 'FIRST' puts NULLs at the beginning, 'LAST' puts them at the end
+	 *
+	 * @example
+	 * ```typescript
+	 * // NULLs at end for ascending order
+	 * db.table.users.select()
+	 *   .orderByNulls('deletedAt', 'ASC', 'LAST')
+	 *   .all()
+	 * // SQL: ORDER BY "deleted_at" ASC NULLS LAST
+	 *
+	 * // NULLs at start for descending order
+	 * db.table.posts.select()
+	 *   .orderByNulls('publishedAt', 'DESC', 'FIRST')
+	 *   .all()
+	 * // SQL: ORDER BY "published_at" DESC NULLS FIRST
+	 * ```
+	 */
+	orderByNulls(column: ColumnName<TTable>, direction: "ASC" | "DESC", nulls: "FIRST" | "LAST"): this;
 	limit(count: number): this;
 	offset(count: number): this;
 	groupBy(...columns: ColumnName<TTable>[]): this;
@@ -8444,6 +8575,20 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	 * Uses PostgreSQL LATERAL to efficiently fetch related rows with
 	 * ordering and limiting per parent row.
 	 *
+	 * **Dialect Support:**
+	 * | Dialect     | Supported | Notes |
+	 * |-------------|-----------|-------|
+	 * | PostgreSQL  | ✅        | Native LATERAL support |
+	 * | CockroachDB | ✅        | Native LATERAL support |
+	 * | Nile        | ✅        | Native LATERAL support |
+	 * | AWS DSQL    | ❌        | Use separate queries |
+	 * | MySQL       | ❌        | Use separate queries |
+	 * | SQLite      | ❌        | Use separate queries |
+	 *
+	 * @param tableOrAlias - Table name or [tableName, alias] tuple
+	 * @param callback - Join condition callback: `(on, left, right) => on.equal(...)`
+	 * @throws {RelqConfigError} If dialect doesn't support LATERAL joins
+	 *
 	 * @example
 	 * ```typescript
 	 * // Get top 5 orders per user
@@ -8451,7 +8596,7 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	 *   .joinMany('orders', (on, users, orders) =>
 	 *     on.equal(users.id, orders.userId)
 	 *       .where(q => q.equal('status', 'completed'))
-	 *       .orderBy(orders.createdAt, 'DESC')
+	 *       .orderBy('createdAt', 'DESC')
 	 *       .limit(5)
 	 *   )
 	 *   .all()
@@ -8461,7 +8606,7 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	 * db.table.users.select()
 	 *   .joinMany(['orders', 'recentOrders'], (on, users, orders) =>
 	 *     on.equal(users.id, orders.userId)
-	 *       .orderBy(orders.createdAt, 'DESC')
+	 *       .orderBy('createdAt', 'DESC')
 	 *       .limit(3)
 	 *   )
 	 * // Result: Array<{ ...User, recentOrders: Order[] }>
@@ -8476,6 +8621,20 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	 * Type-safe one-to-many LEFT JOIN using LATERAL subquery.
 	 * Returns an array of related rows (empty array if no matches).
 	 *
+	 * **Dialect Support:**
+	 * | Dialect     | Supported | Notes |
+	 * |-------------|-----------|-------|
+	 * | PostgreSQL  | ✅        | Native LATERAL support |
+	 * | CockroachDB | ✅        | Native LATERAL support |
+	 * | Nile        | ✅        | Native LATERAL support |
+	 * | AWS DSQL    | ❌        | Use separate queries |
+	 * | MySQL       | ❌        | Use separate queries |
+	 * | SQLite      | ❌        | Use separate queries |
+	 *
+	 * @param tableOrAlias - Table name or [tableName, alias] tuple
+	 * @param callback - Join condition callback: `(on, left, right) => on.equal(...)`
+	 * @throws {RelqConfigError} If dialect doesn't support LATERAL joins
+	 *
 	 * @example
 	 * ```typescript
 	 * // Get all users with their orders (empty array if no orders)
@@ -8496,16 +8655,31 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	leftJoinMany<TRightKey extends keyof TSchema & string, TResult>(table: TRightKey, callback: JoinManyCallback<TSchema, TTable, TSchema[TRightKey], TRightKey, TResult>): ConnectedSelectBuilder<TSchema, TTable, TColumns, TJoined & NestedJoinMany<TRightKey, TResult>>;
 	distinct(): this;
 	/**
-	 * DISTINCT ON - select unique rows by specified columns
-	 * PostgreSQL-specific feature
+	 * DISTINCT ON - select unique rows by specified columns.
+	 * Returns only the first row for each distinct combination of columns.
+	 *
+	 * **Dialect Support:**
+	 * | Dialect     | Supported | Notes |
+	 * |-------------|-----------|-------|
+	 * | PostgreSQL  | ✅        | Native support |
+	 * | CockroachDB | ✅        | Native support |
+	 * | Nile        | ✅        | Native support |
+	 * | AWS DSQL    | ❌        | Use GROUP BY instead |
+	 * | MySQL       | ❌        | Use GROUP BY instead |
+	 * | SQLite      | ❌        | Use GROUP BY instead |
+	 *
+	 * @param columns - Columns to select distinct on (must be first in ORDER BY)
+	 * @throws {RelqConfigError} If dialect doesn't support DISTINCT ON
 	 *
 	 * @example
 	 * ```typescript
+	 * // Get latest log per user
 	 * db.table.logs.select()
 	 *     .distinctOn('userId')
 	 *     .orderBy('userId')
 	 *     .orderBy('createdAt', 'DESC')
 	 *     .all()
+	 * // SQL: SELECT DISTINCT ON ("user_id") * FROM "logs" ORDER BY "user_id", "created_at" DESC
 	 * ```
 	 */
 	distinctOn(...columns: string[]): this;
@@ -8538,7 +8712,31 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	 */
 	forUpdate(): this;
 	/**
-	 * FOR UPDATE SKIP LOCKED - skip locked rows (job queue pattern)
+	 * FOR UPDATE SKIP LOCKED - skip locked rows (job queue pattern).
+	 * Essential for implementing efficient work queues.
+	 *
+	 * **Dialect Support:**
+	 * | Dialect     | Supported | Notes |
+	 * |-------------|-----------|-------|
+	 * | PostgreSQL  | ✅        | Native support |
+	 * | CockroachDB | ✅        | Native support |
+	 * | Nile        | ✅        | Native support |
+	 * | AWS DSQL    | ❌        | Use FOR UPDATE only |
+	 * | MySQL       | ✅        | Native support (8.0+) |
+	 * | SQLite      | ❌        | No row locking |
+	 *
+	 * @throws {RelqConfigError} If dialect doesn't support SKIP LOCKED
+	 *
+	 * @example
+	 * ```typescript
+	 * // Job queue pattern - claim next available job
+	 * const job = await db.table.jobs.select()
+	 *   .where(q => q.equal('status', 'pending'))
+	 *   .orderBy('createdAt')
+	 *   .limit(1)
+	 *   .forUpdateSkipLocked()
+	 *   .get()
+	 * ```
 	 */
 	forUpdateSkipLocked(): this;
 	/**
@@ -8583,26 +8781,39 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	 */
 	value<T = any>(column: string): Promise<T | null>;
 	/**
-	 * Iterate through query results row-by-row using PostgreSQL cursors
-	 * Efficient for large datasets as it doesn't load all data into memory
+	 * Iterate through query results row-by-row using PostgreSQL cursors.
+	 * Efficient for large datasets as it doesn't load all data into memory.
+	 *
+	 * **Dialect Support:**
+	 * | Dialect     | Supported | Notes |
+	 * |-------------|-----------|-------|
+	 * | PostgreSQL  | ✅        | Native cursor support |
+	 * | CockroachDB | ✅        | Native cursor support |
+	 * | Nile        | ✅        | Native cursor support |
+	 * | AWS DSQL    | ❌        | Use pagination() instead |
+	 * | MySQL       | ❌        | Use pagination() instead |
+	 * | SQLite      | ❌        | Use pagination() instead |
 	 *
-	 * @param callback - Async function called for each row
+	 * @param callback - Async function called for each row. Return `false` to stop iteration.
 	 * @param options - Optional configuration
 	 * @param options.batchSize - Number of rows to fetch per batch (default: 100)
+	 * @throws {RelqConfigError} If dialect doesn't support cursors
 	 *
 	 * @example
 	 * ```typescript
-	 * await db.table('results')
-	 *     .select(['email', 'userId'])
+	 * // Process all unverified users
+	 * await db.table.users.select('email', 'userId')
 	 *     .where(q => q.equal('verified', false))
 	 *     .each(async (row) => {
-	 *         console.log(row.email);
+	 *         await sendVerificationEmail(row.email);
 	 *     });
 	 *
-	 * // With custom batch size
-	 * await db.table('results')
-	 *     .select(['email'])
-	 *     .each(async (row) => { ... }, { batchSize: 50 });
+	 * // Stop early with false return
+	 * await db.table.logs.select()
+	 *     .each(async (row, index) => {
+	 *         if (index >= 1000) return false; // Stop after 1000
+	 *         processLog(row);
+	 *     }, { batchSize: 50 });
 	 * ```
 	 */
 	each<T = InferResultType<TSchema, TTable, TColumns> & TJoined>(callback: (row: T, index: number) => void | false | Promise<void | false>, options?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relq",
-  "version": "1.0.69",
+  "version": "1.0.71",
   "description": "The Fully-Typed PostgreSQL ORM for TypeScript",
   "author": "Olajide Mathew O. <olajide.mathew@yuniq.solutions>",
   "license": "MIT",
@@ -67,7 +67,9 @@
   },
   "dependencies": {
     "@aws-sdk/dsql-signer": "^3.971.0",
+    "@clack/prompts": "^1.0.0",
     "@pgsql/types": "^17.6.2",
+    "citty": "^0.2.0",
     "cli-spinners": "^3.4.0",
     "jiti": "^2.6.1",
     "ora": "^9.0.0",