relq 1.0.4 → 1.0.6

package/dist/schema-builder.d.ts

@@ -1,3 +1,77 @@
+/**
+ * Type-safe PostgreSQL DEFAULT value helpers
+ * Covers all PostgreSQL default value types with 100% typed output
+ */
+export interface DefaultValue {
+	readonly $sql: string;
+	readonly $isDefault: true;
+}
+export declare const DEFAULT: {
+	readonly genRandomUuid: () => DefaultValue;
+	readonly uuidGenerateV4: () => DefaultValue;
+	readonly uuidGenerateV1: () => DefaultValue;
+	readonly uuidGenerateV1mc: () => DefaultValue;
+	readonly uuidNil: () => DefaultValue;
+	readonly now: () => DefaultValue;
+	readonly currentTimestamp: () => DefaultValue;
+	readonly currentDate: () => DefaultValue;
+	readonly currentTime: () => DefaultValue;
+	readonly localTimestamp: () => DefaultValue;
+	readonly localTime: () => DefaultValue;
+	readonly transactionTimestamp: () => DefaultValue;
+	readonly statementTimestamp: () => DefaultValue;
+	readonly clockTimestamp: () => DefaultValue;
+	readonly timeofday: () => DefaultValue;
+	readonly interval: (value: string) => DefaultValue;
+	readonly currentUser: () => DefaultValue;
+	readonly sessionUser: () => DefaultValue;
+	readonly user: () => DefaultValue;
+	readonly currentSchema: () => DefaultValue;
+	readonly currentDatabase: () => DefaultValue;
+	readonly currentCatalog: () => DefaultValue;
+	readonly inetClientAddr: () => DefaultValue;
+	readonly inetClientPort: () => DefaultValue;
+	readonly inetServerAddr: () => DefaultValue;
+	readonly inetServerPort: () => DefaultValue;
+	readonly pgBackendPid: () => DefaultValue;
+	readonly nextval: (sequenceName: string) => DefaultValue;
+	readonly currval: (sequenceName: string) => DefaultValue;
+	readonly lastval: () => DefaultValue;
+	readonly random: () => DefaultValue;
+	readonly pi: () => DefaultValue;
+	readonly emptyString: () => DefaultValue;
+	readonly emptyObject: () => DefaultValue;
+	readonly emptyJson: () => DefaultValue;
+	readonly emptyJsonb: () => DefaultValue;
+	readonly emptyArray: () => DefaultValue;
+	readonly emptyArrayOf: (type: string) => DefaultValue;
+	readonly true: () => DefaultValue;
+	readonly false: () => DefaultValue;
+	readonly null: () => DefaultValue;
+	readonly zero: () => DefaultValue;
+	readonly one: () => DefaultValue;
+	readonly negativeOne: () => DefaultValue;
+	readonly string: (value: string) => DefaultValue;
+	readonly number: (value: number) => DefaultValue;
+	readonly integer: (value: number) => DefaultValue;
+	readonly decimal: (value: number, precision?: number) => DefaultValue;
+	readonly cast: (value: string | number, type: string) => DefaultValue;
+	readonly emptyTsvector: () => DefaultValue;
+	readonly point: (x: number, y: number) => DefaultValue;
+	readonly inet: (address: string) => DefaultValue;
+	readonly cidr: (network: string) => DefaultValue;
+	readonly macaddr: (address: string) => DefaultValue;
+	readonly emptyInt4range: () => DefaultValue;
+	readonly emptyInt8range: () => DefaultValue;
+	readonly emptyNumrange: () => DefaultValue;
+	readonly emptyTsrange: () => DefaultValue;
+	readonly emptyTstzrange: () => DefaultValue;
+	readonly emptyDaterange: () => DefaultValue;
+	readonly emptyHstore: () => DefaultValue;
+	readonly emptyBytea: () => DefaultValue;
+	readonly money: (value: number | string) => DefaultValue;
+	readonly zeroMoney: () => DefaultValue;
+};
 export declare const EMPTY_OBJECT: unique symbol;
 export declare const EMPTY_ARRAY: unique symbol;
 export interface ColumnConfig<T = unknown> {
@@ -5,7 +79,7 @@ export interface ColumnConfig<T = unknown> {
 	$sqlType?: string;
 	$tsType?: T;
 	$nullable?: boolean;
-	$default?: T | (() => T) | string | object | typeof EMPTY_OBJECT | typeof EMPTY_ARRAY;
+	$default?: T | (() => T) | string | object | typeof EMPTY_OBJECT | typeof EMPTY_ARRAY | DefaultValue;
 	$primaryKey?: boolean;
 	$unique?: boolean;
 	$references?: {
@@ -27,6 +101,7 @@ export interface ColumnConfig<T = unknown> {
 	$scale?: number;
 	$withTimezone?: boolean;
 	$columnName?: string;
+	$trackingId?: string;
 }
 /** Table column references for generated columns - each column becomes a ChainableExpr */
 export type GeneratedTableRefs<T extends Record<string, ColumnConfig>> = {
@@ -109,13 +184,60 @@ export interface GeneratedFn {
 	extract(field: "year" | "month" | "day" | "hour" | "minute" | "second" | "dow" | "doy" | "week" | "quarter" | "epoch", col: ChainableExpr | GeneratedExpr): ChainableExpr;
 	datePart(field: string, col: ChainableExpr | GeneratedExpr): ChainableExpr;
 	age(col1: ChainableExpr | GeneratedExpr, col2: ChainableExpr | GeneratedExpr): ChainableExpr;
-	toTsvector(config: string, col: ChainableExpr | GeneratedExpr): ChainableExpr;
+	/** Create tsvector from text using specified config (e.g., 'english', 'simple') */
+	toTsvector(config: string, col: ChainableExpr | GeneratedExpr | string): ChainableExpr;
+	/** Assign weight (A, B, C, or D) to tsvector for ranking */
+	setweight(tsvector: ChainableExpr | GeneratedExpr, weight: "A" | "B" | "C" | "D"): ChainableExpr;
+	/** Concatenate multiple tsvectors using || operator */
+	tsvectorConcat(...vectors: (ChainableExpr | GeneratedExpr)[]): ChainableExpr;
+	/** Generic concatenation using || operator (works for text, tsvector, arrays) */
+	concat(...args: (ChainableExpr | GeneratedExpr | string)[]): ChainableExpr;
+	/** Text-specific concatenation using || operator */
+	textConcat(...args: (ChainableExpr | GeneratedExpr | string)[]): ChainableExpr;
+	/** Create tsquery from text */
+	toTsquery(config: string, col: ChainableExpr | GeneratedExpr | string): ChainableExpr;
+	/** Create tsquery from plain text (handles spaces and punctuation) */
+	plaintoTsquery(config: string, col: ChainableExpr | GeneratedExpr | string): ChainableExpr;
+	/** Create tsquery from web-style search (handles OR, quotes, etc.) */
+	websearchToTsquery(config: string, col: ChainableExpr | GeneratedExpr | string): ChainableExpr;
 	similarity(col1: ChainableExpr | GeneratedExpr, col2: ChainableExpr | GeneratedExpr | string): ChainableExpr;
 	point(x: ChainableExpr | GeneratedExpr | number, y: ChainableExpr | GeneratedExpr | number): ChainableExpr;
 	arrayLength(col: ChainableExpr | GeneratedExpr, dim?: number): ChainableExpr;
 	arrayPosition(arr: ChainableExpr | GeneratedExpr, elem: ChainableExpr | GeneratedExpr | string | number): ChainableExpr;
 	md5(col: ChainableExpr | GeneratedExpr): ChainableExpr;
 	sha256(col: ChainableExpr | GeneratedExpr): ChainableExpr;
+	/** Reference a column by name (used when importing SQL schemas) */
+	col(name: string, alias?: string): ChainableExpr;
+	/** Pass raw SQL expression directly - use for complex expressions */
+	raw(sql: string): ChainableExpr;
+	/** Cast to any PostgreSQL type by name */
+	cast(value: ChainableExpr | GeneratedExpr | string | number, typeName: string): ChainableExpr;
+	/** Call any SQL function by name */
+	func(name: string, ...args: (ChainableExpr | GeneratedExpr | string | number)[]): ChainableExpr;
+	/** Embed raw SQL - use with caution */
+	sql(expression: string): ChainableExpr;
+	/** Apply an operator between two values */
+	op(left: ChainableExpr | GeneratedExpr | string | number, operator: string, right: ChainableExpr | GeneratedExpr | string | number): ChainableExpr;
+	setWeight(tsvector: ChainableExpr | GeneratedExpr, weight: string): ChainableExpr;
+	asVarchar(col: ChainableExpr | GeneratedExpr): ChainableExpr;
+	/** Concatenate text or tsvector values using || operator */
+	textConcat(left: ChainableExpr | GeneratedExpr | string, right: ChainableExpr | GeneratedExpr | string): ChainableExpr;
+	/** Full-text search match: tsvector @@ tsquery */
+	tsMatch(left: ChainableExpr | GeneratedExpr, right: ChainableExpr | GeneratedExpr): ChainableExpr;
+	/** Compare two values with a comparison operator */
+	compare(left: ChainableExpr | GeneratedExpr | string | number, op: "=" | "<>" | "!=" | "<" | ">" | "<=" | ">=", right: ChainableExpr | GeneratedExpr | string | number): ChainableExpr;
+	/** Apply regex match operator */
+	regex(value: ChainableExpr | GeneratedExpr, op: "~" | "~*" | "!~" | "!~*", pattern: ChainableExpr | GeneratedExpr | string): ChainableExpr;
+	/** Logical AND */
+	and(...args: (ChainableExpr | GeneratedExpr)[]): ChainableExpr;
+	/** Logical OR */
+	or(...args: (ChainableExpr | GeneratedExpr)[]): ChainableExpr;
+	/** Logical NOT */
+	not(arg: ChainableExpr | GeneratedExpr): ChainableExpr;
+	/** IS NULL check */
+	isNull(col: ChainableExpr | GeneratedExpr): ChainableExpr;
+	/** IS NOT NULL check */
+	isNotNull(col: ChainableExpr | GeneratedExpr): ChainableExpr;
 }
 /** CASE expression builder */
 export interface CaseBuilder {
@@ -128,6 +250,133 @@ export interface GeneratedExpr {
 	readonly $sql: string;
 	readonly $expr: true;
 }
+/**
+ * Fluent chainable expression for generated columns.
+ * Provides a readable, chainable API similar to index WHERE clauses.
+ *
+ * ## Basic Usage
+ *
+ * Access columns via the table parameter in generatedAlwaysAs:
+ * ```typescript
+ * generatedAlwaysAs(table =>
+ *     table.firstName.concat(' ', table.lastName)
+ * )
+ * ```
+ *
+ * ## Chainable Methods
+ *
+ * ### Null Handling
+ * - `.coalesce(fallback)` - Returns first non-null value
+ * - `.nullif(value)` - Returns NULL if equal to value
+ *
+ * ### Type Casting
+ * - `.asText()` - Cast to TEXT
+ * - `.asInteger()` - Cast to INTEGER
+ * - `.asVarchar()` - Cast to VARCHAR
+ *
+ * ### Text Functions
+ * - `.lower()` - Convert to lowercase
+ * - `.upper()` - Convert to uppercase
+ * - `.trim()` - Remove whitespace
+ * - `.concat(...parts)` - Concatenate with other values/columns
+ * - `.substring(start, length?)` - Extract substring
+ * - `.replace(from, to)` - Replace text
+ * - `.length()` - Get string length
+ *
+ * ### Full-Text Search
+ * - `.toTsvector(config)` - Create tsvector (e.g., 'english')
+ * - `.setWeight(weight)` - Set weight A/B/C/D for ranking
+ * - `.tsvConcat(other)` - Concatenate tsvectors (|| operator)
+ *
+ * ### JSON/JSONB
+ * - `.jsonExtract(key)` - Extract JSON value (->)
+ * - `.jsonExtractText(key)` - Extract as text (->>)
+ *
+ * ### Math
+ * - `.add(n)`, `.subtract(n)`, `.multiply(n)`, `.divide(n)`
+ * - `.abs()`, `.round(precision?)`, `.floor()`, `.ceil()`
+ *
+ * @example Full-text search vector
+ * ```typescript
+ * searchVector: tsvector().generatedAlwaysAs(table =>
+ *     table.email.coalesce('').asText().toTsvector('english').setWeight('A')
+ *         .tsvConcat(table.name.coalesce('').toTsvector('english').setWeight('B'))
+ * )
+ * ```
+ *
+ * @example Computed full name
+ * ```typescript
+ * fullName: text().generatedAlwaysAs(table =>
+ *     table.firstName.concat(' ', table.lastName)
+ * )
+ * ```
+ */
+export interface FluentGenExpr extends GeneratedExpr {
+	/** COALESCE - returns first non-null value */
+	coalesce(fallback: FluentGenExpr | string | number): FluentGenExpr;
+	/** NULLIF - returns NULL if equal to value */
+	nullif(value: FluentGenExpr | string | number): FluentGenExpr;
+	/** Cast to TEXT */
+	asText(): FluentGenExpr;
+	/** Cast to INTEGER */
+	asInteger(): FluentGenExpr;
+	/** Cast to VARCHAR */
+	asVarchar(): FluentGenExpr;
+	/** Cast to any PostgreSQL type */
+	cast(typeName: string): FluentGenExpr;
+	/** Convert to lowercase */
+	lower(): FluentGenExpr;
+	/** Convert to uppercase */
+	upper(): FluentGenExpr;
+	/** Remove leading/trailing whitespace */
+	trim(): FluentGenExpr;
+	/** Concatenate with other values using || operator */
+	concat(...parts: (FluentGenExpr | string)[]): FluentGenExpr;
+	/** Extract substring */
+	substring(start: number, length?: number): FluentGenExpr;
+	/** Replace text */
+	replace(from: string, to: string): FluentGenExpr;
+	/** Get string length */
+	length(): FluentGenExpr;
+	/** Left pad to specified length */
+	lpad(length: number, fill?: string): FluentGenExpr;
+	/** Right pad to specified length */
+	rpad(length: number, fill?: string): FluentGenExpr;
+	/** Create tsvector with specified config (e.g., 'english') */
+	toTsvector(config: string): FluentGenExpr;
+	/** Set weight for tsvector ranking (A/B/C/D) */
+	setWeight(weight: "A" | "B" | "C" | "D"): FluentGenExpr;
+	/** Concatenate tsvectors using || operator */
+	tsvConcat(other: FluentGenExpr): FluentGenExpr;
+	/** Extract JSON value (->) */
+	jsonExtract(key: string): FluentGenExpr;
+	/** Extract JSON value as text (->>) */
+	jsonExtractText(key: string): FluentGenExpr;
+	/** Add value */
+	add(value: FluentGenExpr | number): FluentGenExpr;
+	/** Subtract value */
+	subtract(value: FluentGenExpr | number): FluentGenExpr;
+	/** Multiply by value */
+	multiply(value: FluentGenExpr | number): FluentGenExpr;
+	/** Divide by value */
+	divide(value: FluentGenExpr | number): FluentGenExpr;
+	/** Absolute value */
+	abs(): FluentGenExpr;
+	/** Round to precision */
+	round(precision?: number): FluentGenExpr;
+	/** Floor */
+	floor(): FluentGenExpr;
+	/** Ceiling */
+	ceil(): FluentGenExpr;
+	/** Extract date part */
+	extract(field: "year" | "month" | "day" | "hour" | "minute" | "second"): FluentGenExpr;
+	/** Get array length */
+	arrayLength(dimension?: number): FluentGenExpr;
+}
+/** Table refs for fluent generated column expressions */
+export type FluentGenTableRefs<T extends Record<string, ColumnConfig>> = {
+	[K in keyof T]: FluentGenExpr;
+};
 export type ColumnBuilder<T, Config extends ColumnConfig<T> = ColumnConfig<T>> = Config & {
 	notNull(): ColumnBuilder<T, Config & {
 		$nullable: false;
@@ -135,7 +384,7 @@ export type ColumnBuilder<T, Config extends ColumnConfig<T> = ColumnConfig<T>> =
 	nullable(): ColumnBuilder<T, Config & {
 		$nullable: true;
 	}>;
-	default<V extends T | (() => T)>(value: V): ColumnBuilder<T, Config & {
+	default<V extends T | (() => T) | DefaultValue>(value: V): ColumnBuilder<T, Config & {
 		$default: V;
 	}>;
 	primaryKey(): ColumnBuilder<T, Config & {
@@ -149,28 +398,31 @@ export type ColumnBuilder<T, Config extends ColumnConfig<T> = ColumnConfig<T>> =
 		onUpdate?: string;
 	}): ColumnBuilder<T, Config>;
 	/**
-	 * Add CHECK constraint with enum-like values.
-	 * Narrows the column type to the union of provided values.
-	 * @param values - Allowed string values
+	 * Add CHECK constraint with enum-like values and explicit constraint name.
+	 * Narrows the column type to the union of provided values for autocomplete.
+	 * @param name - Constraint name (preserved for 1:1 SQL parity)
+	 * @param values - Allowed string values array (literal types auto-inferred)
 	 * @example
-	 * .check('active', 'inactive', 'banned')
+	 * .check('users_status_check', ['active', 'inactive', 'banned'])
 	 * // Type becomes 'active' | 'inactive' | 'banned'
 	 */
-	check<V extends string>(...values: V[]): ColumnBuilder<V, ColumnConfig<V> & {
+	check<const V extends readonly string[]>(name: string, values: V): ColumnBuilder<V[number], ColumnConfig<V[number]> & {
 		$check: string;
-		$checkValues: readonly V[];
+		$checkName: string;
+		$checkValues: V;
 	}>;
 	/**
 	 * Add CHECK constraint that excludes specific values.
-	 * Narrows the column type to exclude provided values.
-	 * @param values - Disallowed string values
+	 * @param name - Constraint name (preserved for 1:1 SQL parity)
+	 * @param values - Disallowed string values array
 	 * @example
-	 * .checkNot('deleted', 'archived')
+	 * .checkNot('users_status_check', ['deleted', 'archived'])
 	 * // Column cannot have these values
 	 */
-	checkNot<V extends string>(...values: V[]): ColumnBuilder<T, Config & {
+	checkNot<const V extends readonly string[]>(name: string, values: V): ColumnBuilder<T, Config & {
 		$checkNot: string;
-		$checkNotValues: readonly V[];
+		$checkNotName: string;
+		$checkNotValues: V;
 	}>;
 	/** @deprecated Use generatedAlwaysAs with callback instead */
 	generatedAs(expression: string, stored?: boolean): ColumnBuilder<T, Config & {
@@ -199,6 +451,14 @@ export type ColumnBuilder<T, Config extends ColumnConfig<T> = ColumnConfig<T>> =
 	 *     (table, F) => F.concat(table.firstName, ' ', table.lastName)
 	 * )
 	 */
+	generatedAlwaysAs(callback: (F: GeneratedFn) => GeneratedExpr, options?: {
+		stored?: boolean;
+	}): ColumnBuilder<T, Config & {
+		$generated: {
+			expression: string;
+			stored?: boolean;
+		};
+	}>;
 	generatedAlwaysAs<Cols extends Record<string, ColumnConfig>>(callback: (table: GeneratedTableRefs<Cols>, F: GeneratedFn) => GeneratedExpr, options?: {
 		stored?: boolean;
 	}): ColumnBuilder<T, Config & {
@@ -245,7 +505,30 @@ export type ColumnBuilder<T, Config extends ColumnConfig<T> = ColumnConfig<T>> =
 	dimensions(d: number): ColumnBuilder<T, Config & {
 		$dimensions: number;
 	}>;
+	/**
+	 * Add a comment/description to the column.
+	 * This will be stored in the database schema and used for documentation.
+	 * @param text - The comment text
+	 * @example
+	 * email: varchar(255).notNull().comment('User primary email address')
+	 */
+	comment(text: string): ColumnBuilder<T, Config & {
+		$comment: string;
+	}>;
+	/**
+	 * Set tracking ID for rename detection.
+	 * This ID persists across column renames and allows detecting RENAME vs DROP+ADD.
+	 * Auto-generated during pull/import if not present.
+	 * @param trackingId - Unique tracking identifier (e.g., 'col_a1b2c3')
+	 * @example
+	 * userId: varchar('user_id').notNull().$id('col_abc123')
+	 */
+	$id(trackingId: string): ColumnBuilder<T, Config & {
+		$trackingId: string;
+	}>;
 };
+/** Create a fluent chainable expression for generated columns */
+export declare function createFluentGenExpr(sql: string): FluentGenExpr;
 export declare const integer: (columnName?: string) => ColumnBuilder<number, ColumnConfig<number>>;
 export declare const int: (columnName?: string) => ColumnBuilder<number, ColumnConfig<number>>;
 export declare const int4: (columnName?: string) => ColumnBuilder<number, ColumnConfig<number>>;
@@ -764,14 +1047,17 @@ export declare function generateCompositeTypeSQL<T extends Record<string, Column
  * data: customType('my_type').notNull().array()
  */
 export declare const customType: <T = string>(typeName: string, columnName?: string) => ColumnBuilder<T, ColumnConfig<T>>;
-export declare const enumType: <T extends string>(name: string, values: readonly T[], columnName?: string) => ColumnConfig<T> & {
+export declare const enumType: <T extends string>(name: string | {
+	name: string;
+	values: readonly T[];
+}, values?: readonly T[], columnName?: string) => ColumnConfig<T> & {
 	notNull(): ColumnBuilder<T, ColumnConfig<T> & {
 		$nullable: false;
 	}>;
 	nullable(): ColumnBuilder<T, ColumnConfig<T> & {
 		$nullable: true;
 	}>;
-	default<V extends T | (() => T)>(value: V): ColumnBuilder<T, ColumnConfig<T> & {
+	default<V extends DefaultValue | T | (() => T)>(value: V): ColumnBuilder<T, ColumnConfig<T> & {
 		$default: V;
 	}>;
 	primaryKey(): ColumnBuilder<T, ColumnConfig<T> & {
@@ -785,28 +1071,31 @@ export declare const enumType: <T extends string>(name: string, values: readonly
 		onUpdate?: string;
 	}): ColumnBuilder<T, ColumnConfig<T>>;
 	/**
-	 * Add CHECK constraint with enum-like values.
-	 * Narrows the column type to the union of provided values.
-	 * @param values - Allowed string values
+	 * Add CHECK constraint with enum-like values and explicit constraint name.
+	 * Narrows the column type to the union of provided values for autocomplete.
+	 * @param name - Constraint name (preserved for 1:1 SQL parity)
+	 * @param values - Allowed string values array (literal types auto-inferred)
 	 * @example
-	 * .check('active', 'inactive', 'banned')
+	 * .check('users_status_check', ['active', 'inactive', 'banned'])
 	 * // Type becomes 'active' | 'inactive' | 'banned'
 	 */
-	check<V extends string>(...values: V[]): ColumnBuilder<V, ColumnConfig<V> & {
+	check<const V extends readonly string[]>(name: string, values: V): ColumnBuilder<V[number], ColumnConfig<V[number]> & {
 		$check: string;
-		$checkValues: readonly V[];
+		$checkName: string;
+		$checkValues: V;
 	}>;
 	/**
 	 * Add CHECK constraint that excludes specific values.
-	 * Narrows the column type to exclude provided values.
-	 * @param values - Disallowed string values
+	 * @param name - Constraint name (preserved for 1:1 SQL parity)
+	 * @param values - Disallowed string values array
 	 * @example
-	 * .checkNot('deleted', 'archived')
+	 * .checkNot('users_status_check', ['deleted', 'archived'])
 	 * // Column cannot have these values
 	 */
-	checkNot<V extends string>(...values: V[]): ColumnBuilder<T, ColumnConfig<T> & {
+	checkNot<const V extends readonly string[]>(name: string, values: V): ColumnBuilder<T, ColumnConfig<T> & {
 		$checkNot: string;
-		$checkNotValues: readonly V[];
+		$checkNotName: string;
+		$checkNotValues: V;
 	}>;
 	/** @deprecated Use generatedAlwaysAs with callback instead */
 	generatedAs(expression: string, stored?: boolean): ColumnBuilder<T, ColumnConfig<T> & {
@@ -835,6 +1124,14 @@ export declare const enumType: <T extends string>(name: string, values: readonly
 	 *     (table, F) => F.concat(table.firstName, ' ', table.lastName)
 	 * )
 	 */
+	generatedAlwaysAs(callback: (F: GeneratedFn) => GeneratedExpr, options?: {
+		stored?: boolean;
+	}): ColumnBuilder<T, ColumnConfig<T> & {
+		$generated: {
+			expression: string;
+			stored?: boolean;
+		};
+	}>;
 	generatedAlwaysAs<Cols extends Record<string, ColumnConfig>>(callback: (table: GeneratedTableRefs<Cols>, F: GeneratedFn) => GeneratedExpr, options?: {
 		stored?: boolean;
 	}): ColumnBuilder<T, ColumnConfig<T> & {
@@ -881,9 +1178,43 @@ export declare const enumType: <T extends string>(name: string, values: readonly
 	dimensions(d: number): ColumnBuilder<T, ColumnConfig<T> & {
 		$dimensions: number;
 	}>;
+	/**
+	 * Add a comment/description to the column.
+	 * This will be stored in the database schema and used for documentation.
+	 * @param text - The comment text
+	 * @example
+	 * email: varchar(255).notNull().comment('User primary email address')
+	 */
+	comment(text: string): ColumnBuilder<T, ColumnConfig<T> & {
+		$comment: string;
+	}>;
+	/**
+	 * Set tracking ID for rename detection.
+	 * This ID persists across column renames and allows detecting RENAME vs DROP+ADD.
+	 * Auto-generated during pull/import if not present.
+	 * @param trackingId - Unique tracking identifier (e.g., 'col_a1b2c3')
+	 * @example
+	 * userId: varchar('user_id').notNull().$id('col_abc123')
+	 */
+	$id(trackingId: string): ColumnBuilder<T, ColumnConfig<T> & {
+		$trackingId: string;
+	}>;
 } & {
 	$enumValues: readonly T[];
 };
+/**
+ * Create a column that references a domain type
+ * @param domainDef - The domain definition from pgDomain() or just the domain name
+ * @param columnName - Optional explicit column name
+ * @example
+ * // With domain definition
+ * email: domainType(emailDomain)
+ * // With domain name
+ * email: domainType('email_domain')
+ */
+export declare const domainType: <T = string>(domainDef: string | {
+	$domainName: string;
+}, columnName?: string) => ColumnBuilder<T, ColumnConfig<T>>;
 /** @deprecated Use pgComposite() instead for better type inference */
 export declare const compositeType: <T>(typeName: string, columnName?: string) => ColumnBuilder<T, ColumnConfig<T>>;
 /** SQL expression brand - marks a value as SQL expression for runtime detection */
@@ -1257,6 +1588,49 @@ export interface IndexDefinition {
 	include?: string[];
 	/** Expression for expression-based indexes */
 	expression?: string;
+	/**
+	 * Generate CREATE INDEX IF NOT EXISTS instead of CREATE INDEX.
+	 *
+	 * When true, the generated SQL will be:
+	 * `CREATE INDEX IF NOT EXISTS index_name ON table_name (...)`
+	 *
+	 * This makes index creation idempotent - if the index already exists,
+	 * PostgreSQL will skip creation instead of throwing an error.
+	 *
+	 * Use cases:
+	 * - Idempotent migrations that can be run multiple times safely
+	 * - Manual schema management where you want to avoid errors on re-runs
+	 * - Incremental schema updates in development environments
+	 * - CI/CD pipelines where schema might already exist
+	 *
+	 * @default false
+	 */
+	ifNotExists?: boolean;
+	/**
+	 * Use ON ONLY clause for partitioned tables.
+	 *
+	 * When true, the generated SQL will be:
+	 * `CREATE INDEX index_name ON ONLY table_name (...)`
+	 *
+	 * This creates an index on the parent partitioned table only, without
+	 * automatically creating matching indexes on child partitions. Each
+	 * partition must have its own index created separately.
+	 *
+	 * Use cases:
+	 * - When you want different index configurations per partition
+	 * - When partitions have different access patterns
+	 * - When you want to control index creation timing per partition
+	 * - For declarative partitioning with custom index strategies
+	 * - When some partitions don't need certain indexes (e.g., archive partitions)
+	 *
+	 * @default false
+	 * @see https://www.postgresql.org/docs/current/ddl-partitioning.html#DDL-PARTITIONING-DECLARATIVE-MAINTENANCE
+	 */
+	tableOnly?: boolean;
+	/** Index comment/description */
+	comment?: string;
+	/** Tracking ID for rename detection */
+	trackingId?: string;
 }
 export interface IndexBuilder {
 	name: string;
@@ -1278,6 +1652,8 @@ export interface IndexBuilder {
 	on<T>(callback: (F: SqlFunctions) => SqlExpr): IndexBuilder;
 	/** Expression-based index columns */
 	on(...columns: string[]): IndexBuilder;
+	/** Add a comment/description to the index */
+	comment(text: string): IndexBuilder;
 }
 /** Where builder for index conditions */
 export interface IndexWhereBuilder<T extends Record<string, unknown>> {
@@ -1348,6 +1724,11 @@ export interface CheckExpr<T = unknown> extends SqlExpr {
 	 * @example table.role.neq('banned') // role <> 'banned'
 	 */
 	neq(value: T | CheckExpr<T>): WhereCondition;
+	/**
+	 * Not equals (alias for neq) - SQL: `column <> value`
+	 * @example table.role.ne('banned') // role <> 'banned'
+	 */
+	ne(value: T | CheckExpr<T>): WhereCondition;
 	/**
 	 * Is null - SQL: `column IS NULL`
 	 * @example table.deletedAt.isNull() // deleted_at IS NULL
@@ -1440,25 +1821,136 @@ export interface CheckConstraintBuilder<T extends Record<string, unknown>> {
 	col(name: keyof T): CheckExpr;
 	/** Create a named check constraint */
 	constraint(name: string, condition: WhereCondition): CheckConstraintDef;
+	/** Create a raw SQL expression condition */
+	raw(expression: string): WhereCondition;
 }
-/** Column expression for use in where conditions */
+/**
+ * Column expression for use in index WHERE clauses and check constraints.
+ *
+ * Provides a fluent, chainable API for building type-safe SQL conditions.
+ * All comparison methods return a {@link WhereCondition} which can be further
+ * chained with `.and()` and `.or()` for compound conditions.
+ *
+ * ## Basic Usage
+ *
+ * In index definitions, access columns via the table parameter:
+ * ```typescript
+ * defineTable('users', { ... }, {
+ *     indexes: [{
+ *         columns: ['email'],
+ *         where: table => table.isDeleted.eq(false)
+ *     }]
+ * })
+ * ```
+ *
+ * ## Comparison Operators
+ *
+ * | Method | SQL | Example |
+ * |--------|-----|---------|
+ * | `.eq(value)` | `=` | `table.status.eq('active')` → `"status" = 'active'` |
+ * | `.neq(value)` | `!=` | `table.status.neq('deleted')` → `"status" != 'deleted'` |
+ * | `.ne(value)` | `!=` | Alias for `.neq()` |
+ * | `.gt(value)` | `>` | `table.age.gt(18)` → `"age" > 18` |
+ * | `.gte(value)` | `>=` | `table.age.gte(21)` → `"age" >= 21` |
+ * | `.lt(value)` | `<` | `table.price.lt(100)` → `"price" < 100` |
+ * | `.lte(value)` | `<=` | `table.price.lte(50)` → `"price" <= 50` |
+ *
+ * ## Null Checks
+ *
+ * | Method | SQL | Example |
+ * |--------|-----|---------|
+ * | `.isNull()` | `IS NULL` | `table.deletedAt.isNull()` → `"deleted_at" IS NULL` |
+ * | `.isNotNull()` | `IS NOT NULL` | `table.email.isNotNull()` → `"email" IS NOT NULL` |
+ *
+ * ## Collection Operators
+ *
+ * | Method | SQL | Example |
+ * |--------|-----|---------|
+ * | `.in([...])` | `IN (...)` | `table.status.in(['a', 'b'])` → `"status" IN ('a', 'b')` |
+ * | `.notIn([...])` | `NOT IN (...)` | `table.type.notIn([1, 2])` → `"type" NOT IN (1, 2)` |
+ * | `.between(min, max)` | `BETWEEN ... AND ...` | `table.age.between(18, 65)` → `"age" BETWEEN 18 AND 65` |
+ *
+ * ## Pattern Matching
+ *
+ * | Method | SQL | Example |
+ * |--------|-----|---------|
+ * | `.like(pattern)` | `LIKE` | `table.name.like('John%')` → `"name" LIKE 'John%'` |
+ * | `.ilike(pattern)` | `ILIKE` | `table.email.ilike('%@gmail%')` → `"email" ILIKE '%@gmail%'` |
+ *
+ * ## Compound Conditions
+ *
+ * Chain conditions using `.and()` and `.or()`:
+ *
+ * ```typescript
+ * // Simple AND: status = 'active' AND is_deleted = false
+ * table.status.eq('active').and(table.isDeleted.eq(false))
+ *
+ * // Simple OR: role = 'admin' OR role = 'moderator'
+ * table.role.eq('admin').or(table.role.eq('moderator'))
+ *
+ * // Complex: (a = 3 AND b = 7) OR (a = 9 AND b = 1)
+ * table.a.eq(3).and(table.b.eq(7))
+ *     .or(table.a.eq(9).and(table.b.eq(1)))
+ * ```
+ *
+ * Each `.and()` and `.or()` wraps operands in parentheses for correct precedence.
+ *
+ * ## Arithmetic (for computed expressions)
+ *
+ * | Method | SQL | Example |
+ * |--------|-----|---------|
+ * | `.plus(n)` | `+` | `table.price.plus(tax)` → `("price" + "tax")` |
+ * | `.minus(n)` | `-` | `table.total.minus(5)` → `("total" - 5)` |
+ *
+ * @example Partial index on active, non-deleted users
+ * ```typescript
+ * indexes: [{
+ *     columns: ['email'],
+ *     unique: true,
+ *     where: table => table.status.eq('active').and(table.isDeleted.eq(false))
+ * }]
+ * ```
+ *
+ * @example Partial index with null check
+ * ```typescript
+ * indexes: [{
+ *     columns: ['verified_at'],
+ *     where: table => table.verifiedAt.isNotNull()
+ * }]
+ * ```
+ */
 export interface ColumnExpr extends SqlExpr {
+	/** Equals: `column = value` */
 	eq(value: unknown): WhereCondition;
+	/** Not equals (alternative syntax): `column != value` */
 	neq(value: unknown): WhereCondition;
+	/** Not equals (SQL standard): `column <> value` */
+	ne(value: unknown): WhereCondition;
+	/** Greater than: `column > value` */
 	gt(value: unknown): WhereCondition;
+	/** Greater than or equal: `column >= value` */
 	gte(value: unknown): WhereCondition;
+	/** Less than: `column < value` */
 	lt(value: unknown): WhereCondition;
+	/** Less than or equal: `column <= value` */
 	lte(value: unknown): WhereCondition;
+	/** Is null: `column IS NULL` */
 	isNull(): WhereCondition;
+	/** Is not null: `column IS NOT NULL` */
 	isNotNull(): WhereCondition;
+	/** In list: `column IN (value1, value2, ...)` */
 	in(values: unknown[]): WhereCondition;
+	/** Not in list: `column NOT IN (value1, value2, ...)` */
 	notIn(values: unknown[]): WhereCondition;
+	/** Between range: `column BETWEEN min AND max` */
 	between(min: unknown, max: unknown): WhereCondition;
+	/** Like pattern (case-sensitive): `column LIKE pattern` */
 	like(pattern: string): WhereCondition;
+	/** Like pattern (case-insensitive): `column ILIKE pattern` */
 	ilike(pattern: string): WhereCondition;
-	/** Add interval to column: col.plus(interval('30 days')) */
+	/** Add value: `(column + value)` - returns ColumnExpr for chaining */
 	plus(value: SqlExpr | number): ColumnExpr;
-	/** Subtract interval from column: col.minus(interval('1 hour')) */
+	/** Subtract value: `(column - value)` - returns ColumnExpr for chaining */
 	minus(value: SqlExpr | number): ColumnExpr;
 }
 export type IndexInput = IndexDefinition | IndexBuilder | IndexBuilderChain | {
@@ -1503,6 +1995,140 @@ export interface IndexBuilderChain {
 	desc(): IndexBuilderChain;
 	include(...columns: string[]): IndexBuilderChain;
 	opclass(opclass: string): IndexBuilderChain;
+	/**
+	 * Generate CREATE INDEX IF NOT EXISTS instead of CREATE INDEX.
+	 *
+	 * This makes the index creation idempotent - if the index already exists,
+	 * PostgreSQL will skip creation instead of throwing an error.
+	 *
+	 * @example
+	 * ```typescript
+	 * indexes: (table, index) => [
+	 *     // Idempotent index - safe to run multiple times
+	 *     index('idx_users_email')
+	 *         .on(table.email)
+	 *         .ifNotExists(),
+	 * ]
+	 * ```
+	 *
+	 * Generated SQL:
+	 * ```sql
+	 * CREATE INDEX IF NOT EXISTS idx_users_email ON users (email);
+	 * ```
+	 *
+	 * **Use cases:**
+	 * - **Idempotent migrations** - Migrations that can be run multiple times
+	 *   without causing errors, useful for CI/CD pipelines
+	 * - **Manual schema management** - When you want to manually run schema
+	 *   scripts without tracking which statements have already been executed
+	 * - **Development environments** - When databases may already have some
+	 *   indexes and you want to apply incremental changes
+	 * - **Multi-tenant systems** - When creating tenant-specific indexes that
+	 *   may or may not exist
+	 *
+	 * **Important Notes:**
+	 * - When the index already exists, PostgreSQL will NOT verify that the
+	 *   existing index matches your definition (columns, type, options)
+	 * - If you need to modify an existing index, you must DROP and recreate it
+	 * - For schema validation, use `relq diff` to compare definitions
+	 *
+	 * @returns The index builder chain for further method chaining
+	 */
+	ifNotExists(): IndexBuilderChain;
+	/**
+	 * Use ON ONLY clause to create index on parent partitioned table only.
+	 *
+	 * When called, generates: `CREATE INDEX name ON ONLY table_name (...)`
+	 *
+	 * By default, when you create an index on a partitioned table, PostgreSQL
+	 * automatically creates matching indexes on all child partitions. Using
+	 * `tableOnly()` prevents this automatic propagation.
+	 *
+	 * @example
+	 * ```typescript
+	 * indexes: (table, index) => [
+	 *     // Index only on parent table, not on partitions
+	 *     index('idx_orders_date')
+	 *         .on(table.orderDate)
+	 *         .tableOnly(),
+	 * ]
+	 * ```
+	 *
+	 * Generated SQL:
+	 * ```sql
+	 * CREATE INDEX idx_orders_date ON ONLY orders (order_date);
+	 * ```
+	 *
+	 * Use cases:
+	 * - When you want different index configurations per partition
+	 * - When partitions have vastly different access patterns
+	 * - When you want to control index creation timing per partition
+	 * - For declarative partitioning with custom index strategies
+	 * - When some partitions don't need certain indexes (e.g., archive partitions)
+	 *
+	 * Without `tableOnly()`, PostgreSQL would:
+	 * 1. Create the index on the parent table
+	 * 2. Automatically create matching indexes on ALL child partitions
+	 *
+	 * With `tableOnly()`, you must manually create indexes on each partition:
+	 * ```sql
+	 * CREATE INDEX idx_orders_2024_date ON orders_2024 (order_date);
+	 * CREATE INDEX idx_orders_2025_date ON orders_2025 (order_date);
+	 * ```
+	 *
+	 * @returns The index builder chain for further method chaining
+	 * @see https://www.postgresql.org/docs/current/ddl-partitioning.html#DDL-PARTITIONING-DECLARATIVE-MAINTENANCE
+	 */
+	tableOnly(): IndexBuilderChain;
+	/** Add a comment/description to the index */
+	comment(text: string): IndexBuilderChain;
+	/**
+	 * Set tracking ID for rename detection.
+	 * This ID persists across index renames and allows detecting RENAME vs DROP+ADD.
+	 * @param trackingId - Unique tracking identifier (e.g., 'idx_a1b2c3')
+	 */
+	$id(trackingId: string): IndexBuilderChain;
+}
+/** Options for constraints (name is optional - auto-generated if not provided) */
+export interface ConstraintOptions {
+	name?: string;
+	columns: ColumnRef$1[];
+}
+/** Constraint builder for table-level constraints (composite PKs, etc.) */
+export interface ConstraintBuilder<T extends Record<string, ColumnConfig>> {
+	/**
+	 * Define composite primary key constraint
+	 * @example
+	 * // Without name (auto-generates name):
+	 * constraint.primaryKey(table.id, table.userId)
+	 *
+	 * // With name:
+	 * constraint.primaryKey({ name: 'pk_results', columns: [table.id, table.userId] })
+	 */
+	primaryKey(...columns: ColumnRef$1[]): ConstraintDef;
+	primaryKey(options: ConstraintOptions): ConstraintDef;
+	/**
+	 * Define unique constraint across multiple columns
+	 * @example
+	 * // Without name (auto-generates name):
+	 * constraint.unique(table.email, table.tenantId)
+	 *
+	 * // With name:
+	 * constraint.unique({ name: 'uq_email_tenant', columns: [table.email, table.tenantId] })
+	 */
+	unique(...columns: ColumnRef$1[]): ConstraintDef;
+	unique(options: ConstraintOptions): ConstraintDef;
+	/** Define exclusion constraint with raw SQL expression */
+	exclude(name: string, expression: string): ConstraintDef;
+}
+/** Constraint definition result */
+export interface ConstraintDef {
+	readonly $type: "PRIMARY KEY" | "UNIQUE" | "EXCLUDE";
+	readonly $name: string;
+	readonly $columns: string[];
+	readonly $expression?: string;
+	/** Tracking ID for rename detection */
+	readonly $trackingId?: string;
 }
 export interface TableConfig<T extends Record<string, ColumnConfig>> {
 	columns: T;
@@ -1512,6 +2138,15 @@ export interface TableConfig<T extends Record<string, ColumnConfig>> {
 		columns: string[];
 		name?: string;
 	}>;
+	/**
+	 * Table-level constraints with typed callback API (composite primary keys, etc.)
+	 * @example
+	 * constraints: (table, constraint) => [
+	 *     constraint.primaryKey(table.id, table.userId),
+	 *     constraint.unique({ name: 'uq_email_date', columns: [table.email, table.date] }),
+	 * ]
+	 */
+	constraints?: ((table: ColumnRefs<T>, constraint: ConstraintBuilder<T>) => ConstraintDef[]);
 	/**
 	 * CHECK constraints with typed callback API
 	 * @example
@@ -1531,9 +2166,11 @@ export interface TableConfig<T extends Record<string, ColumnConfig>> {
 		onDelete?: "CASCADE" | "SET NULL" | "SET DEFAULT" | "RESTRICT" | "NO ACTION";
 		onUpdate?: "CASCADE" | "SET NULL" | "SET DEFAULT" | "RESTRICT" | "NO ACTION";
 		name?: string;
+		/** Tracking ID for rename detection */
+		trackingId?: string;
 	}>;
-	/** Index definitions - use (table, index, F) => [index('name').on(F.lower(table.email))] */
-	indexes?: IndexInput[] | ((table: ColumnRefs<T>, index: IndexFactory, F: SqlFunctions) => IndexInput[]);
+	/** Index definitions - use (table, index, F) => [index('name').on(table.email).where(table.isActive.eq(true))] */
+	indexes?: IndexInput[] | ((table: IndexTableRefs<T>, index: IndexFactory, F: SqlFunctions) => IndexInput[]);
 	inherits?: string[];
 	/** Partition strategy - use (table, p) => p.list(table.col) / p.range(table.col) / p.hash(table.col, modulus) */
 	partitionBy?: (table: ColumnRefs<T>, p: PartitionStrategyFactory) => PartitionStrategyDef;
@@ -1541,6 +2178,68 @@ export interface TableConfig<T extends Record<string, ColumnConfig>> {
 	partitions?: (partition: PartitionFactory) => ChildPartitionDef[];
 	tablespace?: string;
 	withOptions?: Record<string, unknown>;
+	/**
+	 * Generate CREATE TABLE IF NOT EXISTS instead of CREATE TABLE.
+	 *
+	 * When `ifNotExists: true`, the generated SQL will be:
+	 * `CREATE TABLE IF NOT EXISTS table_name (...)`
+	 *
+	 * This makes table creation idempotent - if the table already exists,
+	 * PostgreSQL will skip creation instead of throwing an error.
+	 *
+	 * **Use Cases:**
+	 * - **Idempotent migrations** - Migrations that can be run multiple times
+	 *   without causing errors, useful for CI/CD pipelines
+	 * - **Manual schema management** - When you want to manually run schema
+	 *   scripts without tracking which statements have already been executed
+	 * - **Development environments** - When databases may already have some
+	 *   tables and you want to apply incremental changes
+	 * - **Multi-tenant systems** - When creating tenant-specific tables that
+	 *   may or may not exist
+	 * - **Bootstrap scripts** - Initial setup scripts that might run on
+	 *   existing databases
+	 *
+	 * **Example:**
+	 * ```typescript
+	 * export const users = defineTable('users', {
+	 *     id: uuid().primaryKey().default('gen_random_uuid()'),
+	 *     email: varchar(255).notNull(),
+	 * }, {
+	 *     ifNotExists: true,  // Safe to run multiple times
+	 * });
+	 * ```
+	 *
+	 * **Generated SQL:**
+	 * ```sql
+	 * CREATE TABLE IF NOT EXISTS users (
+	 *     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+	 *     email VARCHAR(255) NOT NULL
+	 * );
+	 * ```
+	 *
+	 * **Important Notes:**
+	 * - When `ifNotExists: true` and the table already exists, PostgreSQL
+	 *   will NOT verify that the existing table matches your schema
+	 * - Column differences, missing columns, or type mismatches are NOT detected
+	 * - For schema validation, use proper migration tools or `relq diff`
+	 * - The existing table's structure may differ from your definition
+	 *
+	 * @default false - Standard CREATE TABLE that throws if table exists
+	 */
+	ifNotExists?: boolean;
+	/**
+	 * Table comment/description.
+	 * This will be stored in the database schema and used for documentation.
+	 * @example
+	 * defineTable('users', { ... }, { comment: 'Stores user account information' })
+	 */
+	comment?: string;
+	/**
+	 * Tracking ID for rename detection.
+	 * Auto-generated during pull/import if not present.
+	 * @example 't1a2b3'
+	 */
+	$trackingId?: string;
 }
 type ColumnRef$1 = string & {
 	__columnRef: true;
@@ -1548,6 +2247,16 @@ type ColumnRef$1 = string & {
 export type ColumnRefs<T extends Record<string, ColumnConfig>> = {
 	[K in keyof T]: ColumnRef$1;
 };
+/**
+ * Table refs for index WHERE clauses - each column is a ColumnExpr with comparison methods
+ *
+ * Used in: `indexes: (table, index) => [index('name').on(table.col).where(table.isActive.eq(true))]`
+ *
+ * @template T - Record of column names to ColumnConfig types
+ */
+export type IndexTableRefs<T extends Record<string, ColumnConfig>> = {
+	[K in keyof T]: ColumnExpr;
+};
 /**
  * Table refs for check constraints - each column is a typed CheckExpr
  * The type is inferred from the column's ColumnConfig type parameter
@@ -1649,6 +2358,8 @@ export interface TableDefinition<T extends Record<string, ColumnConfig>> {
 		expression: string;
 		name?: string;
 	}>;
+	/** Table-level constraints (composite PKs, etc.) */
+	$constraints?: ConstraintDef[];
 	$foreignKeys?: Array<{
 		columns: string[];
 		references: {
@@ -1658,12 +2369,18 @@ export interface TableDefinition<T extends Record<string, ColumnConfig>> {
 		onDelete?: string;
 		onUpdate?: string;
 		name?: string;
+		/** Tracking ID for rename detection */
+		trackingId?: string;
 	}>;
 	$indexes?: IndexDefinition[];
 	$inherits?: string[];
 	$partitionBy?: PartitionStrategyDef;
 	$tablespace?: string;
 	$withOptions?: Record<string, unknown>;
+	/** Whether to use CREATE TABLE IF NOT EXISTS */
+	$ifNotExists?: boolean;
+	/** Tracking ID for rename detection */
+	$trackingId?: string;
 	$inferSelect: BuildSelectType<T>;
 	$inferInsert: BuildInsertType<T>;
 	toSQL(): string;
@@ -1770,6 +2487,523 @@ export declare function manyToMany<TFrom extends TableDefinition<Record<string,
 	throughFromKey?: string;
 	throughToKey?: string;
 }): ManyToManyRelation<TFrom, TTo, TThrough>;
+/**
+ * PostgreSQL referential actions for ON DELETE and ON UPDATE clauses.
+ *
+ * | Action | Behavior |
+ * |--------|----------|
+ * | `'NO ACTION'` | Default. Raises error if referenced rows exist. Checked at statement end. |
+ * | `'RESTRICT'` | Like NO ACTION but checked immediately (cannot be deferred). |
+ * | `'CASCADE'` | Deletes/updates child rows when parent is deleted/updated. |
+ * | `'SET NULL'` | Sets FK columns to NULL when parent is deleted/updated. |
+ * | `'SET DEFAULT'` | Sets FK columns to their default values when parent changes. |
+ *
+ * @example
+ * ```typescript
+ * // When an order is deleted, delete all order items
+ * orderId: r.referenceTo.orders(t => ({ onDelete: 'CASCADE' }))
+ *
+ * // When a user is deleted, orphan their comments (set user_id to NULL)
+ * userId: r.referenceTo.users(t => ({ onDelete: 'SET NULL' }))
+ *
+ * // Prevent deleting a category that has products
+ * categoryId: r.referenceTo.categories(t => ({ onDelete: 'RESTRICT' }))
+ * ```
+ */
+export type ReferentialAction = "NO ACTION" | "RESTRICT" | "CASCADE" | "SET NULL" | "SET DEFAULT";
+/**
+ * PostgreSQL MATCH types for foreign key constraints.
+ *
+ * | Match Type | Behavior |
+ * |------------|----------|
+ * | `'SIMPLE'` | Default. Any NULL in FK columns satisfies constraint. |
+ * | `'FULL'` | All FK columns must be NULL together, or all must be non-NULL. |
+ *
+ * Note: MATCH PARTIAL is defined in SQL standard but not implemented in PostgreSQL.
+ *
+ * @example
+ * ```typescript
+ * // Composite FK where all columns must match or all be NULL
+ * productWarehouse: r.referenceTo.inventory(t => ({
+ *     columns: [r.orderItems.productId, r.orderItems.warehouseId],
+ *     references: [t.productId, t.warehouseId],
+ *     match: 'FULL',
+ * }))
+ * ```
+ */
+export type MatchType = "SIMPLE" | "FULL";
+/**
+ * Column reference with table and column metadata for relations.
+ * Used internally by the builder to track column references.
+ */
+export interface RelationColumnRef<TTableName extends string = string, TColumnName extends string = string> {
+	/** SQL table name */
+	$table: TTableName;
+	/** SQL column name */
+	$column: TColumnName;
+	/** Schema key (TypeScript property name) */
+	$schemaKey?: string;
+}
+/**
+ * Options for a single-column foreign key constraint.
+ *
+ * Maps to PostgreSQL syntax:
+ * ```sql
+ * column_name type REFERENCES target_table(target_column)
+ *     [ON DELETE action]
+ *     [ON UPDATE action]
+ *     [MATCH FULL | MATCH SIMPLE]
+ *     [DEFERRABLE | NOT DEFERRABLE]
+ *     [INITIALLY DEFERRED | INITIALLY IMMEDIATE]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Simple FK to primary key (references defaults to PK)
+ * userId: r.referenceTo.users(t => ({
+ *     onDelete: 'CASCADE',
+ * }))
+ *
+ * // FK to non-PK unique column
+ * walletAddress: r.referenceTo.wallets(t => ({
+ *     references: t.address,  // References wallets.address, not wallets.id
+ *     onDelete: 'SET NULL',
+ * }))
+ *
+ * // Full options
+ * orderId: r.referenceTo.orders(t => ({
+ *     references: t.id,
+ *     onDelete: 'CASCADE',
+ *     onUpdate: 'NO ACTION',
+ *     match: 'SIMPLE',
+ *     deferrable: true,
+ *     initiallyDeferred: true,
+ * }))
+ * ```
+ */
+export interface ForeignKeyOptions<TTargetColumns extends Record<string, RelationColumnRef>> {
+	/**
+	 * Target column on the referenced table.
+	 *
+	 * - If omitted: References the PRIMARY KEY of the target table
+	 * - If specified: Must be a PRIMARY KEY or UNIQUE column
+	 *
+	 * @example
+	 * ```typescript
+	 * // References users.id (primary key, default)
+	 * userId: r.referenceTo.users(t => ({ onDelete: 'CASCADE' }))
+	 *
+	 * // References users.email (must be UNIQUE)
+	 * userEmail: r.referenceTo.users(t => ({
+	 *     references: t.email,
+	 *     onDelete: 'SET NULL',
+	 * }))
+	 * ```
+	 */
+	references?: RelationColumnRef;
+	/**
+	 * Action when referenced row is deleted.
+	 *
+	 * | Action | Effect |
+	 * |--------|--------|
+	 * | `'NO ACTION'` | Raises error (default, checked at statement end) |
+	 * | `'RESTRICT'` | Raises error (checked immediately) |
+	 * | `'CASCADE'` | Deletes this row too |
+	 * | `'SET NULL'` | Sets this column to NULL |
+	 * | `'SET DEFAULT'` | Sets this column to its default value |
+	 *
+	 * @default 'NO ACTION'
+	 *
+	 * @example
+	 * ```typescript
+	 * // Delete order items when order is deleted
+	 * orderId: r.referenceTo.orders(t => ({ onDelete: 'CASCADE' }))
+	 *
+	 * // Keep comment but orphan it when user deleted
+	 * userId: r.referenceTo.users(t => ({ onDelete: 'SET NULL' }))
+	 * ```
+	 */
+	onDelete?: ReferentialAction;
+	/**
+	 * Action when referenced column value is updated.
+	 *
+	 * Rarely used since primary keys typically don't change.
+	 * Same actions as onDelete.
+	 *
+	 * @default 'NO ACTION'
+	 *
+	 * @example
+	 * ```typescript
+	 * // If order.id changes, update order_items.order_id too
+	 * orderId: r.referenceTo.orders(t => ({
+	 *     onDelete: 'CASCADE',
+	 *     onUpdate: 'CASCADE',
+	 * }))
+	 * ```
+	 */
+	onUpdate?: ReferentialAction;
+	/**
+	 * MATCH type for the foreign key constraint.
+	 *
+	 * - `'SIMPLE'` (default): Any NULL in FK columns satisfies constraint
+	 * - `'FULL'`: All FK columns must be NULL together, or all non-NULL
+	 *
+	 * Only relevant for composite (multi-column) foreign keys.
+	 *
+	 * @default 'SIMPLE'
+	 */
+	match?: MatchType;
+	/**
+	 * Whether the constraint can be deferred to transaction end.
+	 *
+	 * When `true`, you can use `SET CONSTRAINTS ... DEFERRED` to defer
+	 * constraint checking until transaction commit.
+	 *
+	 * Useful for circular references or bulk operations.
+	 *
+	 * @default false
+	 *
+	 * @example
+	 * ```typescript
+	 * // Allow deferring this constraint
+	 * parentId: r.referenceTo.categories(t => ({
+	 *     onDelete: 'CASCADE',
+	 *     deferrable: true,
+	 * }))
+	 *
+	 * // Then in a transaction:
+	 * // SET CONSTRAINTS category_parent_fk DEFERRED;
+	 * // ... insert circular references ...
+	 * // COMMIT; -- constraint checked here
+	 * ```
+	 */
+	deferrable?: boolean;
+	/**
+	 * Whether deferred constraints start in deferred mode.
+	 *
+	 * Only applies when `deferrable: true`.
+	 * - `false`: Constraint is checked after each statement (can be deferred manually)
+	 * - `true`: Constraint is checked at transaction commit by default
+	 *
+	 * @default false
+	 */
+	initiallyDeferred?: boolean;
+	/**
+	 * Tracking ID for rename detection.
+	 * Auto-generated during pull/import if not present.
+	 * @example 'fk_a1b2c3'
+	 */
+	trackingId?: string;
+}
+/**
+ * Options for a composite (multi-column) foreign key constraint.
+ *
+ * Maps to PostgreSQL table-level constraint:
+ * ```sql
+ * FOREIGN KEY (col1, col2, ...)
+ *     REFERENCES target_table(target_col1, target_col2, ...)
+ *     [ON DELETE action]
+ *     [ON UPDATE action]
+ *     ...
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Composite FK: (product_id, warehouse_id) → inventory(product_id, warehouse_id)
+ * productWarehouse: r.referenceTo.inventory(t => ({
+ *     columns: [r.orderItems.productId, r.orderItems.warehouseId],
+ *     references: [t.productId, t.warehouseId],
+ *     onDelete: 'CASCADE',
+ *     match: 'FULL',  // All columns must match or all be NULL
+ * }))
+ * ```
+ */
+export interface CompositeForeignKeyOptions<TTargetColumns extends Record<string, RelationColumnRef>> {
+	/**
+	 * Source columns on THIS table (array for composite FK).
+	 * Column count must match `references` array.
+	 */
+	columns: RelationColumnRef[];
+	/**
+	 * Target columns on the referenced table (array for composite FK).
+	 * Must be a PRIMARY KEY or UNIQUE constraint together.
+	 */
+	references: RelationColumnRef[];
+	/** Action when referenced row is deleted */
+	onDelete?: ReferentialAction;
+	/** Action when referenced column values are updated */
+	onUpdate?: ReferentialAction;
+	/** MATCH type (FULL recommended for composite FKs) */
+	match?: MatchType;
+	/** Whether constraint can be deferred */
+	deferrable?: boolean;
+	/** Whether deferred constraints start deferred */
+	initiallyDeferred?: boolean;
+	/** Tracking ID for rename detection */
+	trackingId?: string;
+}
+/**
+ * Foreign key relation definition (runtime representation).
+ * Stores all metadata about a REFERENCES constraint.
+ */
+export interface ForeignKeyRelationDef {
+	/** Relation type marker */
+	$type: "foreignKey";
+	/** Target table name (SQL name) */
+	$targetTable: string;
+	/** Source column(s) on this table */
+	$columns: Array<{
+		table: string;
+		column: string;
+	}>;
+	/** Target column(s) on referenced table (undefined = PK) */
+	$references?: Array<{
+		table: string;
+		column: string;
+	}>;
+	/** ON DELETE action */
+	$onDelete?: ReferentialAction;
+	/** ON UPDATE action */
+	$onUpdate?: ReferentialAction;
+	/** MATCH type */
+	$match?: MatchType;
+	/** DEFERRABLE flag */
+	$deferrable?: boolean;
+	/** INITIALLY DEFERRED flag */
+	$initiallyDeferred?: boolean;
+	/** Tracking ID for rename detection */
+	$trackingId?: string;
+}
+/** Relation definition type */
+export type RelationDef = ForeignKeyRelationDef;
+/** Table's relations map */
+export type TableRelations = Record<string, RelationDef>;
+/** All relations for a schema */
+export type SchemaRelations = Record<string, TableRelations>;
+/**
+ * Target table column accessor.
+ * Provides autocomplete for target table's columns.
+ */
+export type TargetTableColumns<TTable extends TableDefinition<any>> = {
+	[K in keyof TTable["$columns"]]: RelationColumnRef<TTable["$name"], K & string>;
+};
+/**
+ * Callback function type for referenceTo builder.
+ * Receives target table columns and returns FK options.
+ */
+export type ReferenceToCallback<TTargetTable extends TableDefinition<any>> = (t: TargetTableColumns<TTargetTable>) => ForeignKeyOptions<TargetTableColumns<TTargetTable>> | CompositeForeignKeyOptions<TargetTableColumns<TTargetTable>>;
+/**
+ * The referenceTo builder - provides target table selection with autocomplete.
+ *
+ * @example
+ * ```typescript
+ * // r.referenceTo.users gives autocomplete for users table
+ * userId: r.referenceTo.users(t => ({
+ *     references: t.id,  // Autocomplete shows users columns
+ *     onDelete: 'CASCADE',
+ * }))
+ * ```
+ */
+export type ReferenceToBuilder<TSchema extends Record<string, TableDefinition<any>>> = {
+	[K in keyof TSchema]: (callback: ReferenceToCallback<TSchema[K]>) => ForeignKeyRelationDef;
+};
+/**
+ * Source table column accessor.
+ * Used for composite FK columns on the current table.
+ */
+export type SourceTableColumns<TTable extends TableDefinition<any>> = {
+	[K in keyof TTable["$columns"]]: RelationColumnRef<TTable["$name"], K & string>;
+};
+/**
+ * All source table column refs for the schema.
+ * Enables referencing columns on any table for composite FKs.
+ *
+ * @example
+ * ```typescript
+ * // Access columns from any table
+ * columns: [r.orderItems.productId, r.orderItems.warehouseId]
+ * ```
+ */
+export type SchemaColumnRefs<TSchema extends Record<string, TableDefinition<any>>> = {
+	[K in keyof TSchema]: SourceTableColumns<TSchema[K]>;
+};
+/**
+ * Full relation builder passed to pgRelations callback.
+ *
+ * @example
+ * ```typescript
+ * pgRelations(schema, (r) => ({
+ *     // r.referenceTo.tableName - define FK to that table
+ *     // r.tableName.columnName - reference columns (for composite FKs)
+ * }))
+ * ```
+ */
+export interface FullRelationBuilder<TSchema extends Record<string, TableDefinition<any>>> {
+	/**
+	 * Define a foreign key reference to another table.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Single-column FK
+	 * userId: r.referenceTo.users(t => ({
+	 *     references: t.id,
+	 *     onDelete: 'CASCADE',
+	 * }))
+	 *
+	 * // FK to non-PK column
+	 * email: r.referenceTo.users(t => ({
+	 *     references: t.email,  // Must be UNIQUE
+	 *     onDelete: 'SET NULL',
+	 * }))
+	 * ```
+	 */
+	referenceTo: ReferenceToBuilder<TSchema>;
+}
+/** Full builder with table column refs for composite FKs */
+export type FullRelationBuilderWithRefs<TSchema extends Record<string, TableDefinition<any>>> = FullRelationBuilder<TSchema> & SchemaColumnRefs<TSchema>;
+/**
+ * Define PostgreSQL foreign key relations between tables.
+ *
+ * Creates a type-safe relations object that mirrors PostgreSQL REFERENCES constraints
+ * exactly, including ON DELETE, ON UPDATE, MATCH, and DEFERRABLE options.
+ *
+ * @param schema - The schema object containing all table definitions (use `as const`)
+ * @param builder - Callback receiving the relation builder for each table
+ * @returns The relations object with full FK metadata
+ *
+ * @example Basic foreign keys
+ * ```typescript
+ * export const schema = { users, posts, comments } as const;
+ *
+ * export const relations = pgRelations(schema, (r) => ({
+ *     posts: {
+ *         // posts.user_id REFERENCES users ON DELETE CASCADE
+ *         userId: r.referenceTo.users(t => ({
+ *             onDelete: 'CASCADE',
+ *         })),
+ *     },
+ *     comments: {
+ *         postId: r.referenceTo.posts(t => ({ onDelete: 'CASCADE' })),
+ *         userId: r.referenceTo.users(t => ({ onDelete: 'SET NULL' })),
+ *     },
+ * }));
+ * ```
+ *
+ * @example FK to non-primary key column
+ * ```typescript
+ * export const relations = pgRelations(schema, (r) => ({
+ *     orders: {
+ *         // orders.wallet_address REFERENCES wallets(address)
+ *         walletAddress: r.referenceTo.wallets(t => ({
+ *             references: t.address,  // Not wallets.id, but wallets.address
+ *             onDelete: 'SET NULL',
+ *         })),
+ *     },
+ * }));
+ * ```
+ *
+ * @example Composite (multi-column) foreign key
+ * ```typescript
+ * export const relations = pgRelations(schema, (r) => ({
+ *     orderItems: {
+ *         // FOREIGN KEY (product_id, warehouse_id)
+ *         //     REFERENCES inventory(product_id, warehouse_id)
+ *         productWarehouse: r.referenceTo.inventory(t => ({
+ *             columns: [r.orderItems.productId, r.orderItems.warehouseId],
+ *             references: [t.productId, t.warehouseId],
+ *             onDelete: 'CASCADE',
+ *             match: 'FULL',
+ *         })),
+ *     },
+ * }));
+ * ```
+ *
+ * @example Deferrable constraint (for circular references)
+ * ```typescript
+ * export const relations = pgRelations(schema, (r) => ({
+ *     employees: {
+ *         // Can defer constraint check to transaction commit
+ *         managerId: r.referenceTo.employees(t => ({
+ *             references: t.id,
+ *             onDelete: 'SET NULL',
+ *             deferrable: true,
+ *             initiallyDeferred: true,
+ *         })),
+ *     },
+ * }));
+ * ```
+ */
+export declare function pgRelations<TSchema extends Record<string, TableDefinition<any>>>(schema: TSchema, builder: (tables: {
+	[K in keyof TSchema]: (defineRelations: (r: FullRelationBuilderWithRefs<TSchema>) => TableRelations) => TableRelations;
+}) => SchemaRelations): SchemaRelations;
+/**
+ * Simplified pgRelations API - direct table → relations mapping.
+ *
+ * @example
+ * ```typescript
+ * export const relations = defineRelations(schema, {
+ *     posts: (r) => ({
+ *         userId: r.referenceTo.users(t => ({ onDelete: 'CASCADE' })),
+ *     }),
+ *     comments: (r) => ({
+ *         postId: r.referenceTo.posts(t => ({ onDelete: 'CASCADE' })),
+ *         userId: r.referenceTo.users(t => ({ onDelete: 'SET NULL' })),
+ *     }),
+ * });
+ * ```
+ */
+export declare function defineRelations<TSchema extends Record<string, TableDefinition<any>>, TRelations extends {
+	[K in keyof TSchema]?: (r: FullRelationBuilderWithRefs<TSchema>) => TableRelations;
+}>(schema: TSchema, relationDefs: TRelations): SchemaRelations;
+/**
+ * Helper type to derive DatabaseSchema type from a schema const object.
+ *
+ * Use this to create a type alias for your database schema, enabling
+ * full type inference across your application.
+ *
+ * @example
+ * ```typescript
+ * // In db/schema.ts
+ * export const schema = { users, posts, comments } as const;
+ * export type DatabaseSchema = RelqDatabaseSchema<typeof schema>;
+ *
+ * // Now you can use DatabaseSchema for typing
+ * function getUser(db: Relq<DatabaseSchema>, id: string) {
+ *     return db.table.users.select('*').where(q => q.equal('id', id)).one();
+ * }
+ * ```
+ */
+export type RelqDatabaseSchema<TSchema extends Record<string, TableDefinition<any>>> = {
+	[K in keyof TSchema]: TSchema[K];
+};
+/**
+ * Convert action code from pgsql-parser to ReferentialAction string.
+ *
+ * @internal Used by code generator
+ */
+export declare function actionCodeToString(code: string): ReferentialAction;
+/**
+ * Convert ReferentialAction to action code for pgsql-parser.
+ *
+ * @internal Used for SQL generation
+ */
+export declare function stringToActionCode(action: ReferentialAction): string;
+/**
+ * Convert match code from pgsql-parser to MatchType string.
+ *
+ * @internal Used by code generator
+ */
+export declare function matchCodeToString(code: string): MatchType;
+/**
+ * Generate SQL REFERENCES clause from a ForeignKeyRelationDef.
+ *
+ * @example
+ * ```typescript
+ * const sql = generateReferencesSQL(relationDef, 'user_id');
+ * // "user_id uuid REFERENCES users(id) ON DELETE CASCADE"
+ * ```
+ */
+export declare function generateReferencesSQL(relation: ForeignKeyRelationDef, columnName: string, columnType?: string): string;
 export interface PgEnumConfig<T extends readonly string[]> {
 	/** Enum type name in PostgreSQL */
 	$enumName: string;
@@ -2173,6 +3407,54 @@ export declare function dropSequenceSQL(seq: SequenceConfig): string;
  * Type guard to check if a value is a SequenceConfig
  */
 export declare function isSequenceConfig(value: unknown): value is SequenceConfig;
+/**
+ * PostgreSQL View Definitions
+ *
+ * Provides typed helpers for defining views and materialized views.
+ */
+export interface ViewConfig {
+	_type: "view";
+	name: string;
+	definition: string;
+	isMaterialized: false;
+}
+export interface MaterializedViewConfig {
+	_type: "materialized_view";
+	name: string;
+	definition: string;
+	isMaterialized: true;
+	withData?: boolean;
+}
+/**
+ * Define a PostgreSQL view
+ *
+ * @example
+ * export const activeUsers = pgView('active_users', `
+ *     SELECT id, name, email FROM users WHERE status = 'active'
+ * `)
+ */
+export declare function pgView(name: string, definition: string): ViewConfig;
+/**
+ * Define a PostgreSQL materialized view
+ *
+ * @example
+ * export const userStats = pgMaterializedView('user_stats', `
+ *     SELECT user_id, COUNT(*) as order_count, SUM(total) as total_spent
+ *     FROM orders
+ *     GROUP BY user_id
+ * `)
+ */
+export declare function pgMaterializedView(name: string, definition: string, options?: {
+	withData?: boolean;
+}): MaterializedViewConfig;
+/**
+ * Generate CREATE VIEW SQL
+ */
+export declare function viewToSQL(view: ViewConfig): string;
+/**
+ * Generate CREATE MATERIALIZED VIEW SQL
+ */
+export declare function materializedViewToSQL(view: MaterializedViewConfig): string;
 /**
  * SQL Tagged Template Literal
  *