From 3a9bdbffe3370edf6550cf0e8e2098301e235445 Mon Sep 17 00:00:00 2001
From: Mael Primet <mael.primet@gmail.com>
Date: Tue, 19 Aug 2025 09:57:19 +0200
Subject: [PATCH] feat: add a .meta to pgTable fields to add OpenAPI
 descriptions

---
 drizzle-orm/src/column-builder.ts | 18 ++++++++++++++++++
 drizzle-orm/src/column.ts         |  2 ++
 drizzle-zod/src/column.ts         |  5 +++++
 3 files changed, 25 insertions(+)

diff --git a/drizzle-orm/src/column-builder.ts b/drizzle-orm/src/column-builder.ts
index 1cc4c5ae1e..c223954ad2 100644
--- a/drizzle-orm/src/column-builder.ts
+++ b/drizzle-orm/src/column-builder.ts
@@ -115,6 +115,7 @@ export type ColumnBuilderRuntimeConfig<TData, TRuntimeConfig extends object = ob
 	columnType: string;
 	generated: GeneratedColumnConfig<TData> | undefined;
 	generatedIdentity: GeneratedIdentityConfig | undefined;
+	meta: Record<string, unknown> | undefined;
 } & TRuntimeConfig;
 
 export interface ColumnBuilderExtraConfig {
@@ -208,6 +209,7 @@ export abstract class ColumnBuilder<
 			dataType,
 			columnType,
 			generated: undefined,
+			meta: undefined,
 		} as ColumnBuilderRuntimeConfig<T['data'], TRuntimeConfig>;
 	}
 
@@ -288,6 +290,22 @@ export abstract class ColumnBuilder<
 	 */
 	$onUpdate = this.$onUpdateFn;
 
+	/**
+	 * Adds metadata to the column definition. This can be used by external tools like drizzle-zod
+	 * to add additional information to generated schemas.
+	 *
+	 * @example
+	 * ```ts
+	 * const users = pgTable('users', {
+	 *   age: integer('age').meta({ description: 'User age in years' }),
+	 * });
+	 * ```
+	 */
+	meta(meta: Record<string, unknown>): this {
+		this.config.meta = { ...this.config.meta, ...meta };
+		return this;
+	}
+
 	/**
 	 * Adds a `primary key` clause to the column definition. This implicitly makes the column `not null`.
 	 *
diff --git a/drizzle-orm/src/column.ts b/drizzle-orm/src/column.ts
index 1396e3a612..8cf9e60269 100644
--- a/drizzle-orm/src/column.ts
+++ b/drizzle-orm/src/column.ts
@@ -85,6 +85,7 @@ export abstract class Column<
 	readonly enumValues: T['enumValues'] = undefined;
 	readonly generated: GeneratedColumnConfig<T['data']> | undefined = undefined;
 	readonly generatedIdentity: GeneratedIdentityConfig | undefined = undefined;
+	readonly meta: Record<string, unknown> | undefined;
 
 	protected config: ColumnRuntimeConfig<T['data'], TRuntimeConfig>;
 
@@ -108,6 +109,7 @@ export abstract class Column<
 		this.columnType = config.columnType;
 		this.generated = config.generated;
 		this.generatedIdentity = config.generatedIdentity;
+		this.meta = config.meta;
 	}
 
 	abstract getSQLType(): string;
diff --git a/drizzle-zod/src/column.ts b/drizzle-zod/src/column.ts
index 996bd97720..ead7455509 100644
--- a/drizzle-zod/src/column.ts
+++ b/drizzle-zod/src/column.ts
@@ -131,6 +131,11 @@ export function columnToSchema(
 		schema = z.any();
 	}
 
+	// Apply metadata if available
+	if (column.meta && typeof column.meta === 'object') {
+		schema = schema.meta(column.meta);
+	}
+
 	return schema;
 }