@cleverbrush/knex-schema 3.1.0 → 4.0.0

package/dist/extension.d.ts

@@ -1,4 +1,31 @@
-import type { AnySchemaBuilder, ArraySchemaBuilder, BooleanSchemaBuilder, DateSchemaBuilder, FunctionSchemaBuilder, GenericSchemaBuilder, NumberSchemaBuilder, ObjectSchemaBuilder, SchemaBuilder, StringSchemaBuilder, UnionSchemaBuilder } from '@cleverbrush/schema';
+import type { AnySchemaBuilder, ArraySchemaBuilder, BooleanSchemaBuilder, DateSchemaBuilder, FunctionSchemaBuilder, GenericSchemaBuilder, NumberSchemaBuilder, ObjectSchemaBuilder, PropertyDescriptor, PropertyDescriptorTree, SchemaBuilder, StringSchemaBuilder, UnionSchemaBuilder } from '@cleverbrush/schema';
+import { EXTRA_TYPE_BRAND, METHOD_LITERAL_BRAND } from '@cleverbrush/schema';
+import type { ResolvedVariantConfig, ResolvedVariantRelationSpec, VariantStorageType } from './types.js';
+export { EXTRA_TYPE_BRAND, METHOD_LITERAL_BRAND } from '@cleverbrush/schema';
+/**
+ * Phantom-type brand placed on a column schema by `.primaryKey()`.
+ * Carried on the property schema's type so that {@link PrimaryKeyOf} can
+ * locate primary-key columns at the type level.
+ *
+ * @public
+ */
+export declare const PRIMARY_KEY_BRAND: unique symbol;
+/**
+ * Phantom-type brand placed on an object schema by `.hasPrimaryKey([cols])`
+ * to record the composite primary-key column tuple at the type level.
+ *
+ * @public
+ */
+export declare const COMPOSITE_PRIMARY_KEY_BRAND: unique symbol;
+/**
+ * Phantom-type brand placed on an `ObjectSchemaBuilder` by `.withVariants()`.
+ * The brand carries the discriminated-union result type so that
+ * `query(db, polymorphicSchema)` automatically infers the correct union type
+ * without any extra type annotation.
+ *
+ * @public
+ */
+export declare const POLYMORPHIC_TYPE_BRAND: unique symbol;
 /**
  * Schema extension that adds database-mapping metadata to schema builders.
  *
@@ -99,6 +126,342 @@ export declare const dbExtension: import("@cleverbrush/schema").ExtensionDescrip
         hasTableName(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
     };
 }>;
+type FKAction = 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+/**
+ * DDL and ORM extension that adds database DDL metadata, relationship
+ * definitions, and ORM conveniences to schema builders.
+ *
+ * Column-level methods: `.primaryKey()`, `.references()`, `.unique()`,
+ * `.index()`, `.defaultTo()`, `.columnType()`, `.check()`, `.defaultToRaw()`.
+ *
+ * Object-level methods: `.hasIndex()`, `.hasUnique()`, `.hasCheck()`,
+ * `.hasPrimaryKey()`, `.hasRawColumn()`, `.hasRawIndex()`, `.hasMany()`,
+ * `.hasOne()`, `.belongsTo()`, `.belongsToMany()`, `.hasTimestamps()`,
+ * `.softDelete()`, `.scope()`, `.defaultScope()`, `.beforeInsert()`,
+ * `.afterInsert()`, `.beforeUpdate()`, `.beforeDelete()`.
+ */
+export declare const ddlExtension: import("@cleverbrush/schema").ExtensionDescriptor<{
+    number: {
+        /** Add a foreign key reference to another table.
+         * @param table - The referenced table name.
+         * @param column - The referenced column (defaults to `'id'`).
+         */
+        references(this: NumberSchemaBuilder<any, any, any, any, any>, table: string, column?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON DELETE action for a foreign key. */
+        onDelete(this: NumberSchemaBuilder<any, any, any, any, any>, action: FKAction): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON UPDATE action for a foreign key. */
+        onUpdate(this: NumberSchemaBuilder<any, any, any, any, any>, action: FKAction): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set a default value for this column. */
+        defaultTo(this: NumberSchemaBuilder<any, any, any, any, any>, value: number | "auto_increment"): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Add an index on this column.
+         * @param name - Optional index name.
+         */
+        index(this: NumberSchemaBuilder<any, any, any, any, any>, name?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Add a unique constraint on this column.
+         * @param name - Optional constraint name.
+         */
+        unique(this: NumberSchemaBuilder<any, any, any, any, any>, name?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Override the SQL column type (e.g. `'bigint'`, `'smallint'`). */
+        columnType(this: NumberSchemaBuilder<any, any, any, any, any>, type: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('bigint')`. */
+        bigint(this: NumberSchemaBuilder<any, any, any, any, any>): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('smallint')`. */
+        smallint(this: NumberSchemaBuilder<any, any, any, any, any>): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('decimal(p,s)')` — exact numeric.
+         * @param precision - Total digits.
+         * @param scale     - Digits after decimal point.
+         */
+        decimal(this: NumberSchemaBuilder<any, any, any, any, any>, precision: number, scale: number): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set a raw SQL default expression.
+         * @param expression - Raw SQL expression (e.g. `"nextval('my_seq')"`).
+         */
+        defaultToRaw(this: NumberSchemaBuilder<any, any, any, any, any>, expression: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /**
+         * Mark this integer column as an optimistic-concurrency row-version
+         * token checked by the ORM on every UPDATE / DELETE.
+         *
+         * A mismatch between the stored value and the snapshot taken at read
+         * time throws `ConcurrencyError`.
+         *
+         * @param opts.strategy
+         *   - `'increment'` (default) — ORM adds 1 on each UPDATE.
+         *   - `'manual'`    — caller supplies the new value.
+         */
+        rowVersion(this: NumberSchemaBuilder<any, any, any, any, any>, opts?: {
+            strategy?: "increment" | "manual";
+        }): NumberSchemaBuilder<any, any, any, any, any>;
+    };
+    string: {
+        /** Override the SQL column type (e.g. `'text'`, `'uuid'`, `'jsonb'`, `'citext'`). */
+        columnType(this: StringSchemaBuilder<any, any, any, any, any>, type: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('text')` — unlimited-length text. */
+        text(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('uuid')` — UUID column type.
+         * Note: this sets the *storage type* — for UUID format validation use
+         * the schema-level `.uuid()` validator instead.
+         */
+        asUuid(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('citext')` — case-insensitive text (Postgres). */
+        citext(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('jsonb')` — binary JSON (Postgres). */
+        jsonb(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('tsvector')` — full-text search vector (Postgres). */
+        tsvector(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a foreign key reference to another table. */
+        references(this: StringSchemaBuilder<any, any, any, any, any>, table: string, column?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON DELETE action for a foreign key. */
+        onDelete(this: StringSchemaBuilder<any, any, any, any, any>, action: FKAction): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON UPDATE action for a foreign key. */
+        onUpdate(this: StringSchemaBuilder<any, any, any, any, any>, action: FKAction): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a unique constraint on this column. */
+        unique(this: StringSchemaBuilder<any, any, any, any, any>, name?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add an index on this column. */
+        index(this: StringSchemaBuilder<any, any, any, any, any>, name?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set a default value for this column. */
+        defaultTo(this: StringSchemaBuilder<any, any, any, any, any>, value: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a CHECK constraint with raw SQL.
+         * @param sql - SQL expression for the check (e.g. `"role IN ('user','admin')"`).
+         */
+        check(this: StringSchemaBuilder<any, any, any, any, any>, sql: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set a raw SQL default expression. */
+        defaultToRaw(this: StringSchemaBuilder<any, any, any, any, any>, expression: string): StringSchemaBuilder<any, any, any, any, any>;
+        /**
+         * Mark this string column as an optimistic-concurrency row-version
+         * token (e.g. a UUID or opaque hash). Strategy is always `'manual'`
+         * — the caller must supply a new value on each UPDATE.
+         */
+        rowVersion(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+    };
+    boolean: {
+        /** Set a default value for this column. */
+        defaultTo(this: BooleanSchemaBuilder<any, any, any, any, any, any, any>, value: boolean): BooleanSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Override the SQL column type (e.g. `'smallint'`, `'integer'`). */
+        columnType(this: BooleanSchemaBuilder<any, any, any, any, any, any, any>, type: string): BooleanSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Add an index on this column. */
+        index(this: BooleanSchemaBuilder<any, any, any, any, any, any, any>, name?: string): BooleanSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Add a unique constraint on this column. */
+        unique(this: BooleanSchemaBuilder<any, any, any, any, any, any, any>, name?: string): BooleanSchemaBuilder<any, any, any, any, any, any, any>;
+    };
+    date: {
+        /** Set a default value (`'now'` for current timestamp). */
+        defaultTo(this: DateSchemaBuilder<any, any, any, any, any>, value: "now"): DateSchemaBuilder<any, any, any, any, any>;
+        /** Override the SQL column type
+         * (e.g. `'timestamptz'`, `'date'`, `'time'`).
+         */
+        columnType(this: DateSchemaBuilder<any, any, any, any, any>, type: string): DateSchemaBuilder<any, any, any, any, any>;
+        /** Add an index on this column. */
+        index(this: DateSchemaBuilder<any, any, any, any, any>, name?: string): DateSchemaBuilder<any, any, any, any, any>;
+        /** Set a raw SQL default expression. */
+        defaultToRaw(this: DateSchemaBuilder<any, any, any, any, any>, expression: string): DateSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('timestamptz')`. */
+        timestamptz(this: DateSchemaBuilder<any, any, any, any, any>): DateSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('date')` (date-only, no time). */
+        dateOnly(this: DateSchemaBuilder<any, any, any, any, any>): DateSchemaBuilder<any, any, any, any, any>;
+        /**
+         * Mark this date column as an optimistic-concurrency row-version
+         * token (timestamp-based). Strategy is always `'timestamp'` —
+         * the ORM sets the value to `new Date()` on each UPDATE.
+         */
+        rowVersion(this: DateSchemaBuilder<any, any, any, any, any>): DateSchemaBuilder<any, any, any, any, any>;
+    };
+    object: {
+        /** Override the SQL column type for an object property stored inline.
+         * Object-typed properties default to `jsonb` when used as columns in
+         * a parent schema's table.
+         */
+        columnType(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, type: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Shorthand for `.columnType('jsonb')` — store this nested object as
+         * a `jsonb` column (Postgres). Nested objects already default to
+         * `jsonb` in DDL; calling `.jsonb()` makes the intent explicit.
+         */
+        jsonb(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Shorthand for `.columnType('json')` — store this nested object as
+         * a plain `json` column (Postgres / MySQL).
+         */
+        json(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Add a composite index on multiple columns.
+         * @param columns - Column names to index.
+         * @param opts - Optional index name and unique flag.
+         */
+        hasIndex(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, columns: string[], opts?: {
+            name?: string;
+            unique?: boolean;
+        }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Add a composite unique constraint.
+         * @param columns - Column names.
+         * @param name - Optional constraint name.
+         */
+        hasUnique(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, columns: string[], name?: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Add a table-level CHECK constraint.
+         * @param sql - Raw SQL expression for the check.
+         */
+        hasCheck(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, sql: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Add a raw SQL column definition not backed by a schema property.
+         * @param name - Column name.
+         * @param definition - SQL type and constraints (e.g. `"tsvector GENERATED ALWAYS AS (...) STORED"`).
+         */
+        hasRawColumn(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, definition: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Add a raw SQL index statement executed after table creation.
+         * @param sql - Full `CREATE INDEX` SQL statement.
+         */
+        hasRawIndex(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, sql: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Define a one-to-many relationship.
+         * @param name - Relation name used with `include()`.
+         * @param opts - `{ schema, foreignKey }` — `foreignKey` is a ColumnRef on the foreign schema.
+         */
+        hasMany(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, opts: {
+            schema: any;
+            foreignKey: any;
+        }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Define a one-to-one relationship (FK on foreign table).
+         * @param name - Relation name used with `include()`.
+         * @param opts - `{ schema, foreignKey }` — `foreignKey` is a ColumnRef on the foreign schema.
+         */
+        hasOne(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, opts: {
+            schema: any;
+            foreignKey: any;
+        }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Define a belongs-to relationship (FK on local table).
+         * @param name - Relation name used with `include()`.
+         * @param opts - `{ schema, foreignKey }` — `foreignKey` is a ColumnRef on the local schema.
+         */
+        belongsTo(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, opts: {
+            schema: any;
+            foreignKey: any;
+        }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Define a many-to-many relationship through a pivot table.
+         * @param name - Relation name used with `include()`.
+         * @param opts - `{ schema, through: { table, localKey, foreignKey } }`.
+         */
+        belongsToMany(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, opts: {
+            schema: any;
+            through: {
+                table: string;
+                localKey: string;
+                foreignKey: string;
+            };
+        }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Auto-add `created_at` and `updated_at` timestamp columns.
+         * @param opts - Optional custom column names.
+         */
+        hasTimestamps(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, opts?: {
+            createdAt?: string;
+            updatedAt?: string;
+        }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Enable soft deletes (adds a `deleted_at` column, auto-filters queries).
+         * @param opts - Optional custom column name.
+         */
+        softDelete(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, opts?: {
+            column?: string;
+        }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Register a named query scope.
+         * @param name - Scope name to use with `.scoped(name)`.
+         * @param fn - Function that receives a `SchemaQueryBuilder` and applies filters.
+         */
+        scope<N extends string>(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: N, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any> & {
+            readonly [METHOD_LITERAL_BRAND]?: N;
+        };
+        /**
+         * Register a **named projection** — a reusable column subset that can be
+         * applied at query time via `.projected(name)`.
+         *
+         * When a projection is applied the query builder:
+         * 1. Issues `SELECT <cols>` instead of `SELECT *`.
+         * 2. Narrows the TypeScript result row type to `Pick<Row, Keys>`.
+         *
+         * Columns are passed as **rest parameters**. Each argument can be either:
+         *
+         * - A **string** literal of a property name (autocompleted against the
+         *   schema's properties):
+         *   ```ts
+         *   .projection('summary', 'id', 'title', 'completed')
+         *   ```
+         * - An **accessor callback** (refactor-safe — renaming a property
+         *   updates the projection automatically):
+         *   ```ts
+         *   .projection('listView', t => t.id, t => t.title, t => t.userId)
+         *   ```
+         *
+         * The two forms can be mixed freely:
+         * ```ts
+         * .projection('mixed', 'id', t => t.title)
+         * ```
+         *
+         * The literal property keys flow through the type system, so
+         * `.projected('listView')` still narrows the result type to
+         * `Pick<Row, 'id' | 'title' | 'userId'>`.
+         *
+         * @param name    - Unique projection name (used with `.projected()`).
+         * @param columns - One argument per column: either a property name
+         *   string or a `t => t.propName` accessor callback.
+         *
+         * @example
+         * ```ts
+         * const PostSchema = object({ id: number(), title: string(), body: string() })
+         *   .hasTableName('posts')
+         *   .projection('summary', 'id', 'title')
+         *   .projection('detail',  t => t.id, t => t.title, t => t.body);
+         *
+         * // Later:
+         * const rows = await query(db, PostSchema).projected('summary');
+         * // rows: Array<Pick<Post, 'id' | 'title'>>
+         * ```
+         *
+         * @see {@link SchemaQueryBuilder.projected}
+         */
+        projection<TProperties extends Record<string, SchemaBuilder<any, any, any, any, any>>, const N extends string, const TKey extends keyof TProperties & string>(this: ObjectSchemaBuilder<TProperties, any, any, any, any, any, any>, name: N, ...columns: ReadonlyArray<TKey | ((t: PropertyDescriptorTree<ObjectSchemaBuilder<TProperties, any, any, any, any, any, any>, ObjectSchemaBuilder<TProperties, any, any, any, any, any, any>>) => PropertyDescriptor<any, any, any, TKey>)>): ObjectSchemaBuilder<TProperties, any, any, any, any, any, any> & {
+            readonly [EXTRA_TYPE_BRAND]?: { [P in N]: readonly TKey[]; };
+        };
+        /** Set a default scope applied to all queries unless `.unscoped()` is called.
+         * @param fn - Function that receives a `SchemaQueryBuilder` and applies filters.
+         */
+        defaultScope(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Register a before-insert lifecycle hook.
+         * @param fn - Async function `(data) => data` called before inserting.
+         */
+        beforeInsert(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Register an after-insert lifecycle hook.
+         * @param fn - Async function `(row)` called after inserting.
+         */
+        afterInsert(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Register a before-update lifecycle hook.
+         * @param fn - Async function `(data) => data` called before updating.
+         */
+        beforeUpdate(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** Register a before-delete lifecycle hook.
+         * @param fn - Async function `(query)` called before deleting.
+         */
+        beforeDelete(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    };
+}>;
+/**
+ * @internal Input to {@link applyVariantsToSchema}: a single resolved variant
+ * entry, as produced by `Entity.ctiVariant()` / `Entity.stiVariant()`.
+ */
+export interface VariantInputForResolver {
+    /** CTI-only: FK column name on the variant table that joins back to base PK. */
+    foreignKeyColumn?: string;
+    /** Variant body schema (CTI table or STI extras). */
+    schema: ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    storage: VariantStorageType;
+    allowOrphan?: boolean;
+    enforceCheck?: boolean;
+    /**
+     * Variant-scoped relations (already resolved to FK column names). When
+     * the variant entry is sourced from another `Entity`, these are read
+     * from that entity's `'relations'` extension and passed in here.
+     */
+    relations?: ResolvedVariantRelationSpec[];
+}
+/**
+ * @internal Validate + apply a fully-resolved variant config to a base
+ * schema. Stores the `'variants'` and `'polymorphicVariants'` extensions
+ * read by {@link SchemaQueryBuilder}.
+ *
+ * Called by the {@link Entity} chain (`.discriminator().ctiVariant().stiVariant()`).
+ * Replaces the previous schema-level `.withVariants()` method.
+ */
+export declare function applyVariantsToSchema(baseSchema: ObjectSchemaBuilder<any, any, any, any, any, any, any>, discriminatorKey: string, variants: Record<string, VariantInputForResolver>): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
 export declare const string: {
     (): import("@cleverbrush/schema").CleanExtended<StringSchemaBuilder<string, true, false, false, {
         email(this: StringSchemaBuilder, errorMessage?: import("@cleverbrush/schema").ValidationErrorMessageProvider<StringSchemaBuilder>): StringSchemaBuilder<string, true, false, false, {}>;
@@ -124,6 +487,46 @@ export declare const string: {
          * @param name - The SQL column name.
          */
         hasColumnName(this: StringSchemaBuilder<any, any, any, any, any>, name: string): SchemaBuilder<any, any, any, false, {}>;
+    } & {
+        /** Override the SQL column type (e.g. `'text'`, `'uuid'`, `'jsonb'`, `'citext'`). */
+        columnType(this: StringSchemaBuilder<any, any, any, any, any>, type: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('text')` — unlimited-length text. */
+        text(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('uuid')` — UUID column type.
+         * Note: this sets the *storage type* — for UUID format validation use
+         * the schema-level `.uuid()` validator instead.
+         */
+        asUuid(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('citext')` — case-insensitive text (Postgres). */
+        citext(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('jsonb')` — binary JSON (Postgres). */
+        jsonb(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('tsvector')` — full-text search vector (Postgres). */
+        tsvector(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a foreign key reference to another table. */
+        references(this: StringSchemaBuilder<any, any, any, any, any>, table: string, column?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON DELETE action for a foreign key. */
+        onDelete(this: StringSchemaBuilder<any, any, any, any, any>, action: FKAction): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON UPDATE action for a foreign key. */
+        onUpdate(this: StringSchemaBuilder<any, any, any, any, any>, action: FKAction): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a unique constraint on this column. */
+        unique(this: StringSchemaBuilder<any, any, any, any, any>, name?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add an index on this column. */
+        index(this: StringSchemaBuilder<any, any, any, any, any>, name?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set a default value for this column. */
+        defaultTo(this: StringSchemaBuilder<any, any, any, any, any>, value: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a CHECK constraint with raw SQL.
+         * @param sql - SQL expression for the check (e.g. `"role IN ('user','admin')"`).
+         */
+        check(this: StringSchemaBuilder<any, any, any, any, any>, sql: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set a raw SQL default expression. */
+        defaultToRaw(this: StringSchemaBuilder<any, any, any, any, any>, expression: string): StringSchemaBuilder<any, any, any, any, any>;
+        /**
+         * Mark this string column as an optimistic-concurrency row-version
+         * token (e.g. a UUID or opaque hash). Strategy is always `'manual'`
+         * — the caller must supply a new value on each UPDATE.
+         */
+        rowVersion(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
     }>, {
         email(this: StringSchemaBuilder, errorMessage?: import("@cleverbrush/schema").ValidationErrorMessageProvider<StringSchemaBuilder>): StringSchemaBuilder<string, true, false, false, {}>;
         url(this: StringSchemaBuilder, optsOrError?: {
@@ -148,6 +551,46 @@ export declare const string: {
          * @param name - The SQL column name.
          */
         hasColumnName(this: StringSchemaBuilder<any, any, any, any, any>, name: string): SchemaBuilder<any, any, any, false, {}>;
+    } & {
+        /** Override the SQL column type (e.g. `'text'`, `'uuid'`, `'jsonb'`, `'citext'`). */
+        columnType(this: StringSchemaBuilder<any, any, any, any, any>, type: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('text')` — unlimited-length text. */
+        text(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('uuid')` — UUID column type.
+         * Note: this sets the *storage type* — for UUID format validation use
+         * the schema-level `.uuid()` validator instead.
+         */
+        asUuid(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('citext')` — case-insensitive text (Postgres). */
+        citext(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('jsonb')` — binary JSON (Postgres). */
+        jsonb(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('tsvector')` — full-text search vector (Postgres). */
+        tsvector(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a foreign key reference to another table. */
+        references(this: StringSchemaBuilder<any, any, any, any, any>, table: string, column?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON DELETE action for a foreign key. */
+        onDelete(this: StringSchemaBuilder<any, any, any, any, any>, action: FKAction): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON UPDATE action for a foreign key. */
+        onUpdate(this: StringSchemaBuilder<any, any, any, any, any>, action: FKAction): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a unique constraint on this column. */
+        unique(this: StringSchemaBuilder<any, any, any, any, any>, name?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add an index on this column. */
+        index(this: StringSchemaBuilder<any, any, any, any, any>, name?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set a default value for this column. */
+        defaultTo(this: StringSchemaBuilder<any, any, any, any, any>, value: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a CHECK constraint with raw SQL.
+         * @param sql - SQL expression for the check (e.g. `"role IN ('user','admin')"`).
+         */
+        check(this: StringSchemaBuilder<any, any, any, any, any>, sql: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set a raw SQL default expression. */
+        defaultToRaw(this: StringSchemaBuilder<any, any, any, any, any>, expression: string): StringSchemaBuilder<any, any, any, any, any>;
+        /**
+         * Mark this string column as an optimistic-concurrency row-version
+         * token (e.g. a UUID or opaque hash). Strategy is always `'manual'`
+         * — the caller must supply a new value on each UPDATE.
+         */
+        rowVersion(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
     }>;
     <T extends string>(equals: T): import("@cleverbrush/schema").CleanExtended<StringSchemaBuilder<T, true, false, false, {
         email(this: StringSchemaBuilder, errorMessage?: import("@cleverbrush/schema").ValidationErrorMessageProvider<StringSchemaBuilder>): StringSchemaBuilder<string, true, false, false, {}>;
@@ -173,6 +616,46 @@ export declare const string: {
          * @param name - The SQL column name.
          */
         hasColumnName(this: StringSchemaBuilder<any, any, any, any, any>, name: string): SchemaBuilder<any, any, any, false, {}>;
+    } & {
+        /** Override the SQL column type (e.g. `'text'`, `'uuid'`, `'jsonb'`, `'citext'`). */
+        columnType(this: StringSchemaBuilder<any, any, any, any, any>, type: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('text')` — unlimited-length text. */
+        text(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('uuid')` — UUID column type.
+         * Note: this sets the *storage type* — for UUID format validation use
+         * the schema-level `.uuid()` validator instead.
+         */
+        asUuid(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('citext')` — case-insensitive text (Postgres). */
+        citext(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('jsonb')` — binary JSON (Postgres). */
+        jsonb(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('tsvector')` — full-text search vector (Postgres). */
+        tsvector(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a foreign key reference to another table. */
+        references(this: StringSchemaBuilder<any, any, any, any, any>, table: string, column?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON DELETE action for a foreign key. */
+        onDelete(this: StringSchemaBuilder<any, any, any, any, any>, action: FKAction): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON UPDATE action for a foreign key. */
+        onUpdate(this: StringSchemaBuilder<any, any, any, any, any>, action: FKAction): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a unique constraint on this column. */
+        unique(this: StringSchemaBuilder<any, any, any, any, any>, name?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add an index on this column. */
+        index(this: StringSchemaBuilder<any, any, any, any, any>, name?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set a default value for this column. */
+        defaultTo(this: StringSchemaBuilder<any, any, any, any, any>, value: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a CHECK constraint with raw SQL.
+         * @param sql - SQL expression for the check (e.g. `"role IN ('user','admin')"`).
+         */
+        check(this: StringSchemaBuilder<any, any, any, any, any>, sql: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set a raw SQL default expression. */
+        defaultToRaw(this: StringSchemaBuilder<any, any, any, any, any>, expression: string): StringSchemaBuilder<any, any, any, any, any>;
+        /**
+         * Mark this string column as an optimistic-concurrency row-version
+         * token (e.g. a UUID or opaque hash). Strategy is always `'manual'`
+         * — the caller must supply a new value on each UPDATE.
+         */
+        rowVersion(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
     }>, {
         email(this: StringSchemaBuilder, errorMessage?: import("@cleverbrush/schema").ValidationErrorMessageProvider<StringSchemaBuilder>): StringSchemaBuilder<string, true, false, false, {}>;
         url(this: StringSchemaBuilder, optsOrError?: {
@@ -197,6 +680,46 @@ export declare const string: {
          * @param name - The SQL column name.
          */
         hasColumnName(this: StringSchemaBuilder<any, any, any, any, any>, name: string): SchemaBuilder<any, any, any, false, {}>;
+    } & {
+        /** Override the SQL column type (e.g. `'text'`, `'uuid'`, `'jsonb'`, `'citext'`). */
+        columnType(this: StringSchemaBuilder<any, any, any, any, any>, type: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('text')` — unlimited-length text. */
+        text(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('uuid')` — UUID column type.
+         * Note: this sets the *storage type* — for UUID format validation use
+         * the schema-level `.uuid()` validator instead.
+         */
+        asUuid(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('citext')` — case-insensitive text (Postgres). */
+        citext(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('jsonb')` — binary JSON (Postgres). */
+        jsonb(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('tsvector')` — full-text search vector (Postgres). */
+        tsvector(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a foreign key reference to another table. */
+        references(this: StringSchemaBuilder<any, any, any, any, any>, table: string, column?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON DELETE action for a foreign key. */
+        onDelete(this: StringSchemaBuilder<any, any, any, any, any>, action: FKAction): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON UPDATE action for a foreign key. */
+        onUpdate(this: StringSchemaBuilder<any, any, any, any, any>, action: FKAction): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a unique constraint on this column. */
+        unique(this: StringSchemaBuilder<any, any, any, any, any>, name?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add an index on this column. */
+        index(this: StringSchemaBuilder<any, any, any, any, any>, name?: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set a default value for this column. */
+        defaultTo(this: StringSchemaBuilder<any, any, any, any, any>, value: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Add a CHECK constraint with raw SQL.
+         * @param sql - SQL expression for the check (e.g. `"role IN ('user','admin')"`).
+         */
+        check(this: StringSchemaBuilder<any, any, any, any, any>, sql: string): StringSchemaBuilder<any, any, any, any, any>;
+        /** Set a raw SQL default expression. */
+        defaultToRaw(this: StringSchemaBuilder<any, any, any, any, any>, expression: string): StringSchemaBuilder<any, any, any, any, any>;
+        /**
+         * Mark this string column as an optimistic-concurrency row-version
+         * token (e.g. a UUID or opaque hash). Strategy is always `'manual'`
+         * — the caller must supply a new value on each UPDATE.
+         */
+        rowVersion(this: StringSchemaBuilder<any, any, any, any, any>): StringSchemaBuilder<any, any, any, any, any>;
     }>;
 };
 export declare const number: {
@@ -212,6 +735,55 @@ export declare const number: {
          * @param name - The SQL column name.
          */
         hasColumnName(this: NumberSchemaBuilder<any, any, any, any, any>, name: string): SchemaBuilder<any, any, any, false, {}>;
+    } & {
+        /** Add a foreign key reference to another table.
+         * @param table - The referenced table name.
+         * @param column - The referenced column (defaults to `'id'`).
+         */
+        references(this: NumberSchemaBuilder<any, any, any, any, any>, table: string, column?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON DELETE action for a foreign key. */
+        onDelete(this: NumberSchemaBuilder<any, any, any, any, any>, action: FKAction): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON UPDATE action for a foreign key. */
+        onUpdate(this: NumberSchemaBuilder<any, any, any, any, any>, action: FKAction): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set a default value for this column. */
+        defaultTo(this: NumberSchemaBuilder<any, any, any, any, any>, value: number | "auto_increment"): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Add an index on this column.
+         * @param name - Optional index name.
+         */
+        index(this: NumberSchemaBuilder<any, any, any, any, any>, name?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Add a unique constraint on this column.
+         * @param name - Optional constraint name.
+         */
+        unique(this: NumberSchemaBuilder<any, any, any, any, any>, name?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Override the SQL column type (e.g. `'bigint'`, `'smallint'`). */
+        columnType(this: NumberSchemaBuilder<any, any, any, any, any>, type: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('bigint')`. */
+        bigint(this: NumberSchemaBuilder<any, any, any, any, any>): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('smallint')`. */
+        smallint(this: NumberSchemaBuilder<any, any, any, any, any>): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('decimal(p,s)')` — exact numeric.
+         * @param precision - Total digits.
+         * @param scale     - Digits after decimal point.
+         */
+        decimal(this: NumberSchemaBuilder<any, any, any, any, any>, precision: number, scale: number): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set a raw SQL default expression.
+         * @param expression - Raw SQL expression (e.g. `"nextval('my_seq')"`).
+         */
+        defaultToRaw(this: NumberSchemaBuilder<any, any, any, any, any>, expression: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /**
+         * Mark this integer column as an optimistic-concurrency row-version
+         * token checked by the ORM on every UPDATE / DELETE.
+         *
+         * A mismatch between the stored value and the snapshot taken at read
+         * time throws `ConcurrencyError`.
+         *
+         * @param opts.strategy
+         *   - `'increment'` (default) — ORM adds 1 on each UPDATE.
+         *   - `'manual'`    — caller supplies the new value.
+         */
+        rowVersion(this: NumberSchemaBuilder<any, any, any, any, any>, opts?: {
+            strategy?: "increment" | "manual";
+        }): NumberSchemaBuilder<any, any, any, any, any>;
     }>, {
         positive(this: NumberSchemaBuilder, errorMessage?: import("@cleverbrush/schema").ValidationErrorMessageProvider<NumberSchemaBuilder>): NumberSchemaBuilder<number, true, false, false, {}>;
         negative(this: NumberSchemaBuilder, errorMessage?: import("@cleverbrush/schema").ValidationErrorMessageProvider<NumberSchemaBuilder>): NumberSchemaBuilder<number, true, false, false, {}>;
@@ -224,6 +796,55 @@ export declare const number: {
          * @param name - The SQL column name.
          */
         hasColumnName(this: NumberSchemaBuilder<any, any, any, any, any>, name: string): SchemaBuilder<any, any, any, false, {}>;
+    } & {
+        /** Add a foreign key reference to another table.
+         * @param table - The referenced table name.
+         * @param column - The referenced column (defaults to `'id'`).
+         */
+        references(this: NumberSchemaBuilder<any, any, any, any, any>, table: string, column?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON DELETE action for a foreign key. */
+        onDelete(this: NumberSchemaBuilder<any, any, any, any, any>, action: FKAction): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON UPDATE action for a foreign key. */
+        onUpdate(this: NumberSchemaBuilder<any, any, any, any, any>, action: FKAction): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set a default value for this column. */
+        defaultTo(this: NumberSchemaBuilder<any, any, any, any, any>, value: number | "auto_increment"): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Add an index on this column.
+         * @param name - Optional index name.
+         */
+        index(this: NumberSchemaBuilder<any, any, any, any, any>, name?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Add a unique constraint on this column.
+         * @param name - Optional constraint name.
+         */
+        unique(this: NumberSchemaBuilder<any, any, any, any, any>, name?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Override the SQL column type (e.g. `'bigint'`, `'smallint'`). */
+        columnType(this: NumberSchemaBuilder<any, any, any, any, any>, type: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('bigint')`. */
+        bigint(this: NumberSchemaBuilder<any, any, any, any, any>): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('smallint')`. */
+        smallint(this: NumberSchemaBuilder<any, any, any, any, any>): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('decimal(p,s)')` — exact numeric.
+         * @param precision - Total digits.
+         * @param scale     - Digits after decimal point.
+         */
+        decimal(this: NumberSchemaBuilder<any, any, any, any, any>, precision: number, scale: number): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set a raw SQL default expression.
+         * @param expression - Raw SQL expression (e.g. `"nextval('my_seq')"`).
+         */
+        defaultToRaw(this: NumberSchemaBuilder<any, any, any, any, any>, expression: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /**
+         * Mark this integer column as an optimistic-concurrency row-version
+         * token checked by the ORM on every UPDATE / DELETE.
+         *
+         * A mismatch between the stored value and the snapshot taken at read
+         * time throws `ConcurrencyError`.
+         *
+         * @param opts.strategy
+         *   - `'increment'` (default) — ORM adds 1 on each UPDATE.
+         *   - `'manual'`    — caller supplies the new value.
+         */
+        rowVersion(this: NumberSchemaBuilder<any, any, any, any, any>, opts?: {
+            strategy?: "increment" | "manual";
+        }): NumberSchemaBuilder<any, any, any, any, any>;
     }>;
     <T extends number>(equals: T): import("@cleverbrush/schema").CleanExtended<NumberSchemaBuilder<T, true, false, false, {
         positive(this: NumberSchemaBuilder, errorMessage?: import("@cleverbrush/schema").ValidationErrorMessageProvider<NumberSchemaBuilder>): NumberSchemaBuilder<number, true, false, false, {}>;
@@ -237,6 +858,55 @@ export declare const number: {
          * @param name - The SQL column name.
          */
         hasColumnName(this: NumberSchemaBuilder<any, any, any, any, any>, name: string): SchemaBuilder<any, any, any, false, {}>;
+    } & {
+        /** Add a foreign key reference to another table.
+         * @param table - The referenced table name.
+         * @param column - The referenced column (defaults to `'id'`).
+         */
+        references(this: NumberSchemaBuilder<any, any, any, any, any>, table: string, column?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON DELETE action for a foreign key. */
+        onDelete(this: NumberSchemaBuilder<any, any, any, any, any>, action: FKAction): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON UPDATE action for a foreign key. */
+        onUpdate(this: NumberSchemaBuilder<any, any, any, any, any>, action: FKAction): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set a default value for this column. */
+        defaultTo(this: NumberSchemaBuilder<any, any, any, any, any>, value: number | "auto_increment"): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Add an index on this column.
+         * @param name - Optional index name.
+         */
+        index(this: NumberSchemaBuilder<any, any, any, any, any>, name?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Add a unique constraint on this column.
+         * @param name - Optional constraint name.
+         */
+        unique(this: NumberSchemaBuilder<any, any, any, any, any>, name?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Override the SQL column type (e.g. `'bigint'`, `'smallint'`). */
+        columnType(this: NumberSchemaBuilder<any, any, any, any, any>, type: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('bigint')`. */
+        bigint(this: NumberSchemaBuilder<any, any, any, any, any>): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('smallint')`. */
+        smallint(this: NumberSchemaBuilder<any, any, any, any, any>): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('decimal(p,s)')` — exact numeric.
+         * @param precision - Total digits.
+         * @param scale     - Digits after decimal point.
+         */
+        decimal(this: NumberSchemaBuilder<any, any, any, any, any>, precision: number, scale: number): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set a raw SQL default expression.
+         * @param expression - Raw SQL expression (e.g. `"nextval('my_seq')"`).
+         */
+        defaultToRaw(this: NumberSchemaBuilder<any, any, any, any, any>, expression: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /**
+         * Mark this integer column as an optimistic-concurrency row-version
+         * token checked by the ORM on every UPDATE / DELETE.
+         *
+         * A mismatch between the stored value and the snapshot taken at read
+         * time throws `ConcurrencyError`.
+         *
+         * @param opts.strategy
+         *   - `'increment'` (default) — ORM adds 1 on each UPDATE.
+         *   - `'manual'`    — caller supplies the new value.
+         */
+        rowVersion(this: NumberSchemaBuilder<any, any, any, any, any>, opts?: {
+            strategy?: "increment" | "manual";
+        }): NumberSchemaBuilder<any, any, any, any, any>;
     }>, {
         positive(this: NumberSchemaBuilder, errorMessage?: import("@cleverbrush/schema").ValidationErrorMessageProvider<NumberSchemaBuilder>): NumberSchemaBuilder<number, true, false, false, {}>;
         negative(this: NumberSchemaBuilder, errorMessage?: import("@cleverbrush/schema").ValidationErrorMessageProvider<NumberSchemaBuilder>): NumberSchemaBuilder<number, true, false, false, {}>;
@@ -249,6 +919,55 @@ export declare const number: {
          * @param name - The SQL column name.
          */
         hasColumnName(this: NumberSchemaBuilder<any, any, any, any, any>, name: string): SchemaBuilder<any, any, any, false, {}>;
+    } & {
+        /** Add a foreign key reference to another table.
+         * @param table - The referenced table name.
+         * @param column - The referenced column (defaults to `'id'`).
+         */
+        references(this: NumberSchemaBuilder<any, any, any, any, any>, table: string, column?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON DELETE action for a foreign key. */
+        onDelete(this: NumberSchemaBuilder<any, any, any, any, any>, action: FKAction): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set the ON UPDATE action for a foreign key. */
+        onUpdate(this: NumberSchemaBuilder<any, any, any, any, any>, action: FKAction): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set a default value for this column. */
+        defaultTo(this: NumberSchemaBuilder<any, any, any, any, any>, value: number | "auto_increment"): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Add an index on this column.
+         * @param name - Optional index name.
+         */
+        index(this: NumberSchemaBuilder<any, any, any, any, any>, name?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Add a unique constraint on this column.
+         * @param name - Optional constraint name.
+         */
+        unique(this: NumberSchemaBuilder<any, any, any, any, any>, name?: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Override the SQL column type (e.g. `'bigint'`, `'smallint'`). */
+        columnType(this: NumberSchemaBuilder<any, any, any, any, any>, type: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('bigint')`. */
+        bigint(this: NumberSchemaBuilder<any, any, any, any, any>): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('smallint')`. */
+        smallint(this: NumberSchemaBuilder<any, any, any, any, any>): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Shorthand for `.columnType('decimal(p,s)')` — exact numeric.
+         * @param precision - Total digits.
+         * @param scale     - Digits after decimal point.
+         */
+        decimal(this: NumberSchemaBuilder<any, any, any, any, any>, precision: number, scale: number): NumberSchemaBuilder<any, any, any, any, any>;
+        /** Set a raw SQL default expression.
+         * @param expression - Raw SQL expression (e.g. `"nextval('my_seq')"`).
+         */
+        defaultToRaw(this: NumberSchemaBuilder<any, any, any, any, any>, expression: string): NumberSchemaBuilder<any, any, any, any, any>;
+        /**
+         * Mark this integer column as an optimistic-concurrency row-version
+         * token checked by the ORM on every UPDATE / DELETE.
+         *
+         * A mismatch between the stored value and the snapshot taken at read
+         * time throws `ConcurrencyError`.
+         *
+         * @param opts.strategy
+         *   - `'increment'` (default) — ORM adds 1 on each UPDATE.
+         *   - `'manual'`    — caller supplies the new value.
+         */
+        rowVersion(this: NumberSchemaBuilder<any, any, any, any, any>, opts?: {
+            strategy?: "increment" | "manual";
+        }): NumberSchemaBuilder<any, any, any, any, any>;
     }>;
 };
 export declare const boolean: () => import("@cleverbrush/schema").CleanExtended<BooleanSchemaBuilder<boolean, true, false, undefined, false, {
@@ -257,12 +976,30 @@ export declare const boolean: () => import("@cleverbrush/schema").CleanExtended<
      * @param name - The SQL column name.
      */
     hasColumnName(this: BooleanSchemaBuilder<any, any, any, any, any, any, any>, name: string): SchemaBuilder<any, any, any, false, {}>;
+} & {
+    /** Set a default value for this column. */
+    defaultTo(this: BooleanSchemaBuilder<any, any, any, any, any, any, any>, value: boolean): BooleanSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Override the SQL column type (e.g. `'smallint'`, `'integer'`). */
+    columnType(this: BooleanSchemaBuilder<any, any, any, any, any, any, any>, type: string): BooleanSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Add an index on this column. */
+    index(this: BooleanSchemaBuilder<any, any, any, any, any, any, any>, name?: string): BooleanSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Add a unique constraint on this column. */
+    unique(this: BooleanSchemaBuilder<any, any, any, any, any, any, any>, name?: string): BooleanSchemaBuilder<any, any, any, any, any, any, any>;
 }, boolean>, {
     /**
      * Override the SQL column name for this property.
      * @param name - The SQL column name.
      */
     hasColumnName(this: BooleanSchemaBuilder<any, any, any, any, any, any, any>, name: string): SchemaBuilder<any, any, any, false, {}>;
+} & {
+    /** Set a default value for this column. */
+    defaultTo(this: BooleanSchemaBuilder<any, any, any, any, any, any, any>, value: boolean): BooleanSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Override the SQL column type (e.g. `'smallint'`, `'integer'`). */
+    columnType(this: BooleanSchemaBuilder<any, any, any, any, any, any, any>, type: string): BooleanSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Add an index on this column. */
+    index(this: BooleanSchemaBuilder<any, any, any, any, any, any, any>, name?: string): BooleanSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Add a unique constraint on this column. */
+    unique(this: BooleanSchemaBuilder<any, any, any, any, any, any, any>, name?: string): BooleanSchemaBuilder<any, any, any, any, any, any, any>;
 }>;
 export declare const date: () => import("@cleverbrush/schema").CleanExtended<DateSchemaBuilder<Date, true, false, false, {
     /**
@@ -270,12 +1007,54 @@ export declare const date: () => import("@cleverbrush/schema").CleanExtended<Dat
      * @param name - The SQL column name.
      */
     hasColumnName(this: DateSchemaBuilder<any, any, any, any, any>, name: string): SchemaBuilder<any, any, any, false, {}>;
+} & {
+    /** Set a default value (`'now'` for current timestamp). */
+    defaultTo(this: DateSchemaBuilder<any, any, any, any, any>, value: "now"): DateSchemaBuilder<any, any, any, any, any>;
+    /** Override the SQL column type
+     * (e.g. `'timestamptz'`, `'date'`, `'time'`).
+     */
+    columnType(this: DateSchemaBuilder<any, any, any, any, any>, type: string): DateSchemaBuilder<any, any, any, any, any>;
+    /** Add an index on this column. */
+    index(this: DateSchemaBuilder<any, any, any, any, any>, name?: string): DateSchemaBuilder<any, any, any, any, any>;
+    /** Set a raw SQL default expression. */
+    defaultToRaw(this: DateSchemaBuilder<any, any, any, any, any>, expression: string): DateSchemaBuilder<any, any, any, any, any>;
+    /** Shorthand for `.columnType('timestamptz')`. */
+    timestamptz(this: DateSchemaBuilder<any, any, any, any, any>): DateSchemaBuilder<any, any, any, any, any>;
+    /** Shorthand for `.columnType('date')` (date-only, no time). */
+    dateOnly(this: DateSchemaBuilder<any, any, any, any, any>): DateSchemaBuilder<any, any, any, any, any>;
+    /**
+     * Mark this date column as an optimistic-concurrency row-version
+     * token (timestamp-based). Strategy is always `'timestamp'` —
+     * the ORM sets the value to `new Date()` on each UPDATE.
+     */
+    rowVersion(this: DateSchemaBuilder<any, any, any, any, any>): DateSchemaBuilder<any, any, any, any, any>;
 }>, {
     /**
      * Override the SQL column name for this property.
      * @param name - The SQL column name.
      */
     hasColumnName(this: DateSchemaBuilder<any, any, any, any, any>, name: string): SchemaBuilder<any, any, any, false, {}>;
+} & {
+    /** Set a default value (`'now'` for current timestamp). */
+    defaultTo(this: DateSchemaBuilder<any, any, any, any, any>, value: "now"): DateSchemaBuilder<any, any, any, any, any>;
+    /** Override the SQL column type
+     * (e.g. `'timestamptz'`, `'date'`, `'time'`).
+     */
+    columnType(this: DateSchemaBuilder<any, any, any, any, any>, type: string): DateSchemaBuilder<any, any, any, any, any>;
+    /** Add an index on this column. */
+    index(this: DateSchemaBuilder<any, any, any, any, any>, name?: string): DateSchemaBuilder<any, any, any, any, any>;
+    /** Set a raw SQL default expression. */
+    defaultToRaw(this: DateSchemaBuilder<any, any, any, any, any>, expression: string): DateSchemaBuilder<any, any, any, any, any>;
+    /** Shorthand for `.columnType('timestamptz')`. */
+    timestamptz(this: DateSchemaBuilder<any, any, any, any, any>): DateSchemaBuilder<any, any, any, any, any>;
+    /** Shorthand for `.columnType('date')` (date-only, no time). */
+    dateOnly(this: DateSchemaBuilder<any, any, any, any, any>): DateSchemaBuilder<any, any, any, any, any>;
+    /**
+     * Mark this date column as an optimistic-concurrency row-version
+     * token (timestamp-based). Strategy is always `'timestamp'` —
+     * the ORM sets the value to `new Date()` on each UPDATE.
+     */
+    rowVersion(this: DateSchemaBuilder<any, any, any, any, any>): DateSchemaBuilder<any, any, any, any, any>;
 }>;
 export declare const object: <P extends Record<string, SchemaBuilder<any, any, any, any, any>>>(properties?: P | undefined) => import("@cleverbrush/schema").CleanExtended<ObjectSchemaBuilder<P, true, false, undefined, false, {
     /**
@@ -287,6 +1066,174 @@ export declare const object: <P extends Record<string, SchemaBuilder<any, any, a
      * @param name - The SQL table name (e.g. `'users'`).
      */
     hasTableName(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+} & {
+    /** Override the SQL column type for an object property stored inline.
+     * Object-typed properties default to `jsonb` when used as columns in
+     * a parent schema's table.
+     */
+    columnType(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, type: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Shorthand for `.columnType('jsonb')` — store this nested object as
+     * a `jsonb` column (Postgres). Nested objects already default to
+     * `jsonb` in DDL; calling `.jsonb()` makes the intent explicit.
+     */
+    jsonb(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Shorthand for `.columnType('json')` — store this nested object as
+     * a plain `json` column (Postgres / MySQL).
+     */
+    json(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Add a composite index on multiple columns.
+     * @param columns - Column names to index.
+     * @param opts - Optional index name and unique flag.
+     */
+    hasIndex(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, columns: string[], opts?: {
+        name?: string;
+        unique?: boolean;
+    }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Add a composite unique constraint.
+     * @param columns - Column names.
+     * @param name - Optional constraint name.
+     */
+    hasUnique(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, columns: string[], name?: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Add a table-level CHECK constraint.
+     * @param sql - Raw SQL expression for the check.
+     */
+    hasCheck(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, sql: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Add a raw SQL column definition not backed by a schema property.
+     * @param name - Column name.
+     * @param definition - SQL type and constraints (e.g. `"tsvector GENERATED ALWAYS AS (...) STORED"`).
+     */
+    hasRawColumn(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, definition: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Add a raw SQL index statement executed after table creation.
+     * @param sql - Full `CREATE INDEX` SQL statement.
+     */
+    hasRawIndex(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, sql: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Define a one-to-many relationship.
+     * @param name - Relation name used with `include()`.
+     * @param opts - `{ schema, foreignKey }` — `foreignKey` is a ColumnRef on the foreign schema.
+     */
+    hasMany(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, opts: {
+        schema: any;
+        foreignKey: any;
+    }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Define a one-to-one relationship (FK on foreign table).
+     * @param name - Relation name used with `include()`.
+     * @param opts - `{ schema, foreignKey }` — `foreignKey` is a ColumnRef on the foreign schema.
+     */
+    hasOne(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, opts: {
+        schema: any;
+        foreignKey: any;
+    }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Define a belongs-to relationship (FK on local table).
+     * @param name - Relation name used with `include()`.
+     * @param opts - `{ schema, foreignKey }` — `foreignKey` is a ColumnRef on the local schema.
+     */
+    belongsTo(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, opts: {
+        schema: any;
+        foreignKey: any;
+    }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Define a many-to-many relationship through a pivot table.
+     * @param name - Relation name used with `include()`.
+     * @param opts - `{ schema, through: { table, localKey, foreignKey } }`.
+     */
+    belongsToMany(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, opts: {
+        schema: any;
+        through: {
+            table: string;
+            localKey: string;
+            foreignKey: string;
+        };
+    }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Auto-add `created_at` and `updated_at` timestamp columns.
+     * @param opts - Optional custom column names.
+     */
+    hasTimestamps(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, opts?: {
+        createdAt?: string;
+        updatedAt?: string;
+    }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Enable soft deletes (adds a `deleted_at` column, auto-filters queries).
+     * @param opts - Optional custom column name.
+     */
+    softDelete(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, opts?: {
+        column?: string;
+    }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Register a named query scope.
+     * @param name - Scope name to use with `.scoped(name)`.
+     * @param fn - Function that receives a `SchemaQueryBuilder` and applies filters.
+     */
+    scope<N extends string>(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: N, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any> & {
+        readonly [METHOD_LITERAL_BRAND]?: N;
+    };
+    /**
+     * Register a **named projection** — a reusable column subset that can be
+     * applied at query time via `.projected(name)`.
+     *
+     * When a projection is applied the query builder:
+     * 1. Issues `SELECT <cols>` instead of `SELECT *`.
+     * 2. Narrows the TypeScript result row type to `Pick<Row, Keys>`.
+     *
+     * Columns are passed as **rest parameters**. Each argument can be either:
+     *
+     * - A **string** literal of a property name (autocompleted against the
+     *   schema's properties):
+     *   ```ts
+     *   .projection('summary', 'id', 'title', 'completed')
+     *   ```
+     * - An **accessor callback** (refactor-safe — renaming a property
+     *   updates the projection automatically):
+     *   ```ts
+     *   .projection('listView', t => t.id, t => t.title, t => t.userId)
+     *   ```
+     *
+     * The two forms can be mixed freely:
+     * ```ts
+     * .projection('mixed', 'id', t => t.title)
+     * ```
+     *
+     * The literal property keys flow through the type system, so
+     * `.projected('listView')` still narrows the result type to
+     * `Pick<Row, 'id' | 'title' | 'userId'>`.
+     *
+     * @param name    - Unique projection name (used with `.projected()`).
+     * @param columns - One argument per column: either a property name
+     *   string or a `t => t.propName` accessor callback.
+     *
+     * @example
+     * ```ts
+     * const PostSchema = object({ id: number(), title: string(), body: string() })
+     *   .hasTableName('posts')
+     *   .projection('summary', 'id', 'title')
+     *   .projection('detail',  t => t.id, t => t.title, t => t.body);
+     *
+     * // Later:
+     * const rows = await query(db, PostSchema).projected('summary');
+     * // rows: Array<Pick<Post, 'id' | 'title'>>
+     * ```
+     *
+     * @see {@link SchemaQueryBuilder.projected}
+     */
+    projection<TProperties extends Record<string, SchemaBuilder<any, any, any, any, any>>, const N extends string, const TKey extends keyof TProperties & string>(this: ObjectSchemaBuilder<TProperties, any, any, any, any, any, any>, name: N, ...columns: ReadonlyArray<TKey | ((t: PropertyDescriptorTree<ObjectSchemaBuilder<TProperties, any, any, any, any, any, any>, ObjectSchemaBuilder<TProperties, any, any, any, any, any, any>>) => PropertyDescriptor<any, any, any, TKey>)>): ObjectSchemaBuilder<TProperties, any, any, any, any, any, any> & {
+        readonly [EXTRA_TYPE_BRAND]?: { [P_1 in N]: readonly TKey[]; };
+    };
+    /** Set a default scope applied to all queries unless `.unscoped()` is called.
+     * @param fn - Function that receives a `SchemaQueryBuilder` and applies filters.
+     */
+    defaultScope(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Register a before-insert lifecycle hook.
+     * @param fn - Async function `(data) => data` called before inserting.
+     */
+    beforeInsert(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Register an after-insert lifecycle hook.
+     * @param fn - Async function `(row)` called after inserting.
+     */
+    afterInsert(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Register a before-update lifecycle hook.
+     * @param fn - Async function `(data) => data` called before updating.
+     */
+    beforeUpdate(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Register a before-delete lifecycle hook.
+     * @param fn - Async function `(query)` called before deleting.
+     */
+    beforeDelete(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
 }, []>, {
     /**
      * Set the SQL table name for this object schema.
@@ -297,6 +1244,174 @@ export declare const object: <P extends Record<string, SchemaBuilder<any, any, a
      * @param name - The SQL table name (e.g. `'users'`).
      */
     hasTableName(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+} & {
+    /** Override the SQL column type for an object property stored inline.
+     * Object-typed properties default to `jsonb` when used as columns in
+     * a parent schema's table.
+     */
+    columnType(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, type: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Shorthand for `.columnType('jsonb')` — store this nested object as
+     * a `jsonb` column (Postgres). Nested objects already default to
+     * `jsonb` in DDL; calling `.jsonb()` makes the intent explicit.
+     */
+    jsonb(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Shorthand for `.columnType('json')` — store this nested object as
+     * a plain `json` column (Postgres / MySQL).
+     */
+    json(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Add a composite index on multiple columns.
+     * @param columns - Column names to index.
+     * @param opts - Optional index name and unique flag.
+     */
+    hasIndex(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, columns: string[], opts?: {
+        name?: string;
+        unique?: boolean;
+    }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Add a composite unique constraint.
+     * @param columns - Column names.
+     * @param name - Optional constraint name.
+     */
+    hasUnique(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, columns: string[], name?: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Add a table-level CHECK constraint.
+     * @param sql - Raw SQL expression for the check.
+     */
+    hasCheck(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, sql: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Add a raw SQL column definition not backed by a schema property.
+     * @param name - Column name.
+     * @param definition - SQL type and constraints (e.g. `"tsvector GENERATED ALWAYS AS (...) STORED"`).
+     */
+    hasRawColumn(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, definition: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Add a raw SQL index statement executed after table creation.
+     * @param sql - Full `CREATE INDEX` SQL statement.
+     */
+    hasRawIndex(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, sql: string): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Define a one-to-many relationship.
+     * @param name - Relation name used with `include()`.
+     * @param opts - `{ schema, foreignKey }` — `foreignKey` is a ColumnRef on the foreign schema.
+     */
+    hasMany(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, opts: {
+        schema: any;
+        foreignKey: any;
+    }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Define a one-to-one relationship (FK on foreign table).
+     * @param name - Relation name used with `include()`.
+     * @param opts - `{ schema, foreignKey }` — `foreignKey` is a ColumnRef on the foreign schema.
+     */
+    hasOne(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, opts: {
+        schema: any;
+        foreignKey: any;
+    }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Define a belongs-to relationship (FK on local table).
+     * @param name - Relation name used with `include()`.
+     * @param opts - `{ schema, foreignKey }` — `foreignKey` is a ColumnRef on the local schema.
+     */
+    belongsTo(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, opts: {
+        schema: any;
+        foreignKey: any;
+    }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Define a many-to-many relationship through a pivot table.
+     * @param name - Relation name used with `include()`.
+     * @param opts - `{ schema, through: { table, localKey, foreignKey } }`.
+     */
+    belongsToMany(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: string, opts: {
+        schema: any;
+        through: {
+            table: string;
+            localKey: string;
+            foreignKey: string;
+        };
+    }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Auto-add `created_at` and `updated_at` timestamp columns.
+     * @param opts - Optional custom column names.
+     */
+    hasTimestamps(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, opts?: {
+        createdAt?: string;
+        updatedAt?: string;
+    }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Enable soft deletes (adds a `deleted_at` column, auto-filters queries).
+     * @param opts - Optional custom column name.
+     */
+    softDelete(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, opts?: {
+        column?: string;
+    }): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Register a named query scope.
+     * @param name - Scope name to use with `.scoped(name)`.
+     * @param fn - Function that receives a `SchemaQueryBuilder` and applies filters.
+     */
+    scope<N_1 extends string>(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, name: N_1, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any> & {
+        readonly [METHOD_LITERAL_BRAND]?: N_1;
+    };
+    /**
+     * Register a **named projection** — a reusable column subset that can be
+     * applied at query time via `.projected(name)`.
+     *
+     * When a projection is applied the query builder:
+     * 1. Issues `SELECT <cols>` instead of `SELECT *`.
+     * 2. Narrows the TypeScript result row type to `Pick<Row, Keys>`.
+     *
+     * Columns are passed as **rest parameters**. Each argument can be either:
+     *
+     * - A **string** literal of a property name (autocompleted against the
+     *   schema's properties):
+     *   ```ts
+     *   .projection('summary', 'id', 'title', 'completed')
+     *   ```
+     * - An **accessor callback** (refactor-safe — renaming a property
+     *   updates the projection automatically):
+     *   ```ts
+     *   .projection('listView', t => t.id, t => t.title, t => t.userId)
+     *   ```
+     *
+     * The two forms can be mixed freely:
+     * ```ts
+     * .projection('mixed', 'id', t => t.title)
+     * ```
+     *
+     * The literal property keys flow through the type system, so
+     * `.projected('listView')` still narrows the result type to
+     * `Pick<Row, 'id' | 'title' | 'userId'>`.
+     *
+     * @param name    - Unique projection name (used with `.projected()`).
+     * @param columns - One argument per column: either a property name
+     *   string or a `t => t.propName` accessor callback.
+     *
+     * @example
+     * ```ts
+     * const PostSchema = object({ id: number(), title: string(), body: string() })
+     *   .hasTableName('posts')
+     *   .projection('summary', 'id', 'title')
+     *   .projection('detail',  t => t.id, t => t.title, t => t.body);
+     *
+     * // Later:
+     * const rows = await query(db, PostSchema).projected('summary');
+     * // rows: Array<Pick<Post, 'id' | 'title'>>
+     * ```
+     *
+     * @see {@link SchemaQueryBuilder.projected}
+     */
+    projection<TProperties extends Record<string, SchemaBuilder<any, any, any, any, any>>, const N extends string, const TKey extends keyof TProperties & string>(this: ObjectSchemaBuilder<TProperties, any, any, any, any, any, any>, name: N, ...columns: ReadonlyArray<TKey | ((t: PropertyDescriptorTree<ObjectSchemaBuilder<TProperties, any, any, any, any, any, any>, ObjectSchemaBuilder<TProperties, any, any, any, any, any, any>>) => PropertyDescriptor<any, any, any, TKey>)>): ObjectSchemaBuilder<TProperties, any, any, any, any, any, any> & {
+        readonly [EXTRA_TYPE_BRAND]?: { [P_1 in N]: readonly TKey[]; };
+    };
+    /** Set a default scope applied to all queries unless `.unscoped()` is called.
+     * @param fn - Function that receives a `SchemaQueryBuilder` and applies filters.
+     */
+    defaultScope(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Register a before-insert lifecycle hook.
+     * @param fn - Async function `(data) => data` called before inserting.
+     */
+    beforeInsert(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Register an after-insert lifecycle hook.
+     * @param fn - Async function `(row)` called after inserting.
+     */
+    afterInsert(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Register a before-update lifecycle hook.
+     * @param fn - Async function `(data) => data` called before updating.
+     */
+    beforeUpdate(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** Register a before-delete lifecycle hook.
+     * @param fn - Async function `(query)` called before deleting.
+     */
+    beforeDelete(this: ObjectSchemaBuilder<any, any, any, any, any, any, any>, fn: Function): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
 }>;
 export declare const array: <TElementSchema extends SchemaBuilder<any, any, any, any, any>>(elementSchema?: TElementSchema | undefined) => import("@cleverbrush/schema").CleanExtended<ArraySchemaBuilder<TElementSchema, true, false, undefined, false, {
     nonempty(this: ArraySchemaBuilder<any>, errorMessage?: import("@cleverbrush/schema").ValidationErrorMessageProvider<ArraySchemaBuilder<any>>): ArraySchemaBuilder<any, true, false, undefined, false, {}, any[] | unknown[]>;
@@ -356,6 +1471,33 @@ export declare const any: () => import("@cleverbrush/schema").CleanExtended<AnyS
      */
     hasColumnName(this: AnySchemaBuilder<any, any, any, any, any, any>, name: string): SchemaBuilder<any, any, any, false, {}>;
 }>;
+declare module '@cleverbrush/schema' {
+    interface NumberSchemaBuilder<TResult, TRequired extends boolean, TNullable extends boolean, THasDefault extends boolean, TExtensions> {
+        /** Mark this column as a primary key.
+         * @param opts - Options. `autoIncrement` defaults to `true`.
+         */
+        primaryKey(opts?: {
+            autoIncrement?: boolean;
+        }): this & {
+            readonly [PRIMARY_KEY_BRAND]?: true;
+        };
+    }
+    interface StringSchemaBuilder<TResult, TRequired extends boolean, TNullable extends boolean, THasDefault extends boolean, TExtensions> {
+        /** Mark this column as a primary key (non-auto-increment). */
+        primaryKey(): this & {
+            readonly [PRIMARY_KEY_BRAND]?: true;
+        };
+    }
+    interface ObjectSchemaBuilder<TProperties extends Record<string, SchemaBuilder<any, any, any, any, any>>, TRequired extends boolean, TNullable extends boolean, TExplicitType, THasDefault extends boolean, TExtensions, TConstructorSchemas> {
+        /** Set a composite primary key.
+         * @param columns - Column names (or property keys) forming the primary key,
+         *   in declaration order. Use `as const` to preserve ordering at the type level.
+         */
+        hasPrimaryKey<const TCols extends readonly string[]>(columns: TCols): this & {
+            readonly [COMPOSITE_PRIMARY_KEY_BRAND]?: TCols;
+        };
+    }
+}
 /**
  * Get the SQL column name for a schema property.
  * Returns the `hasColumnName()` value if set, otherwise falls back to `propertyKey`.
@@ -366,3 +1508,36 @@ export declare function getColumnName(schema: SchemaBuilder<any, any, any>, prop
  * Throws if `hasTableName()` was never called.
  */
 export declare function getTableName(schema: ObjectSchemaBuilder<any, any, any, any, any, any, any>): string;
+/**
+ * Retrieve the named projections registered on a schema via
+ * `.projection(name, columns)`.
+ *
+ * Returns a map of `{ [name]: { keys: readonly string[] } }` where each
+ * entry's `keys` array contains the **property keys** (not SQL column names)
+ * for that projection. Returns an empty object when no projections are
+ * defined.
+ *
+ * @example
+ * ```ts
+ * const projs = getProjections(PostSchema);
+ * // { summary: { keys: ['id', 'title'] } }
+ * ```
+ */
+export declare function getProjections(schema: ObjectSchemaBuilder<any, any, any, any, any, any, any>): Record<string, {
+    keys: readonly string[];
+}>;
+/**
+ * Retrieve the resolved variant configuration stored by `.withVariants()`.
+ * Returns `null` when the schema is not polymorphic.
+ *
+ * @internal — used by {@link SchemaQueryBuilder}.
+ */
+export declare function getVariants(schema: ObjectSchemaBuilder<any, any, any, any, any, any, any>): Omit<ResolvedVariantConfig, 'discriminatorColumn'> | null;
+/**
+ * Retrieve the array of variant `ObjectSchemaBuilder` instances stored by
+ * `.withVariants()`. Used by migration / DDL tools to discover variant
+ * tables without walking the full schema tree.
+ *
+ * @internal
+ */
+export declare function getPolymorphicVariantSchemas(schema: ObjectSchemaBuilder<any, any, any, any, any, any, any>): ObjectSchemaBuilder<any, any, any, any, any, any, any>[];