Add comment support for query builders

drizzle-orm/src/mysql-core/dialect.ts

@@ -18,7 +18,7 @@ import { Param, type QueryWithTypings, SQL, sql, type SQLChunk, View } from '~/s
 import { Subquery, SubqueryConfig } from '~/subquery.ts';
 import { getTableName, Table } from '~/table.ts';
 import { orderSelectedFields, type UpdateSet } from '~/utils.ts';
-import { DrizzleError, type Name, ViewBaseConfig, and, eq } from '../index.ts';
+import { and, DrizzleError, eq, type Name, ViewBaseConfig } from '../index.ts';
 import { MySqlColumn } from './columns/common.ts';
 import type { MySqlDeleteConfig } from './query-builders/delete.ts';
 import type { MySqlInsertConfig } from './query-builders/insert.ts';
@@ -79,14 +79,15 @@ export class MySqlDialect {
 		return `'${str.replace(/'/g, "''")}'`;
 	}
 
-	buildDeleteQuery({ table, where, returning }: MySqlDeleteConfig): SQL {
+	buildDeleteQuery({ table, where, returning, comment }: MySqlDeleteConfig): SQL {
 		const returningSql = returning
 			? sql` returning ${this.buildSelection(returning, { isSingleTable: true })}`
 			: undefined;
 
 		const whereSql = where ? sql` where ${where}` : undefined;
+		const commentSql = this.buildSqlComment(comment);
 
-		return sql`delete from ${table}${whereSql}${returningSql}`;
+		return sql`${commentSql}delete from ${table}${whereSql}${returningSql}`;
 	}
 
 	buildUpdateSet(table: MySqlTable, set: UpdateSet): SQL {
@@ -106,16 +107,22 @@ export class MySqlDialect {
 		);
 	}
 
-	buildUpdateQuery({ table, set, where, returning }: MySqlUpdateConfig): SQL {
+	buildUpdateQuery({ table, set, where, returning, comment }: MySqlUpdateConfig): SQL {
 		const setSql = this.buildUpdateSet(table, set);
 
 		const returningSql = returning
 			? sql` returning ${this.buildSelection(returning, { isSingleTable: true })}`
 			: undefined;
 
 		const whereSql = where ? sql` where ${where}` : undefined;
+		const commentSql = this.buildSqlComment(comment);
 
-		return sql`update ${table} set ${setSql}${whereSql}${returningSql}`;
+		return sql`${commentSql}update ${table} set ${setSql}${whereSql}${returningSql}`;
+	}
+
+	// Builds a SQL comment and removes /* and */ occurences
+	private buildSqlComment(comment?: string) {
+		return comment ? sql.raw(`/* ${comment.replace(/\/\*|\*\//g, '')} */`) : undefined;
 	}
 
 	/**
@@ -195,6 +202,7 @@ export class MySqlDialect {
 			offset,
 			lockingClause,
 			distinct,
+			comment,
 			setOperators,
 		}: MySqlSelectConfig,
 	): SQL {
@@ -323,8 +331,10 @@ export class MySqlDialect {
 			}
 		}
 
+		const commentSql = this.buildSqlComment(comment);
+
 		const finalQuery =
-			sql`${withSql}select${distinctSql} ${selection} from ${tableSql}${joinsSql}${whereSql}${groupBySql}${havingSql}${orderBySql}${limitSql}${offsetSql}${lockingClausesSql}`;
+			sql`${commentSql}${withSql}select${distinctSql} ${selection} from ${tableSql}${joinsSql}${whereSql}${groupBySql}${havingSql}${orderBySql}${limitSql}${offsetSql}${lockingClausesSql}`;
 
 		if (setOperators.length > 0) {
 			return this.buildSetOperations(finalQuery, setOperators);
@@ -394,7 +404,7 @@ export class MySqlDialect {
 		return sql`${leftChunk}${operatorChunk}${rightChunk}${orderBySql}${limitSql}${offsetSql}`;
 	}
 
-	buildInsertQuery({ table, values, ignore, onConflict }: MySqlInsertConfig): SQL {
+	buildInsertQuery({ table, values, ignore, onConflict, comment }: MySqlInsertConfig): SQL {
 		// const isSingleValue = values.length === 1;
 		const valuesSqlList: ((SQLChunk | SQL)[] | SQL)[] = [];
 		const columns: Record<string, MySqlColumn> = table[Table.Symbol.Columns];
@@ -431,7 +441,9 @@ export class MySqlDialect {
 
 		const onConflictSql = onConflict ? sql` on duplicate key ${onConflict}` : undefined;
 
-		return sql`insert${ignoreSql} into ${table} ${insertOrder} values ${valuesSql}${onConflictSql}`;
+		const commentSql = this.buildSqlComment(comment);
+
+		return sql`${commentSql}insert${ignoreSql} into ${table} ${insertOrder} values ${valuesSql}${onConflictSql}`;
 	}
 
 	sqlToQuery(sql: SQL): QueryWithTypings {
@@ -464,7 +476,7 @@ export class MySqlDialect {
 		joinOn?: SQL;
 	}): BuildRelationalQueryResult<MySqlTable, MySqlColumn> {
 		let selection: BuildRelationalQueryResult<MySqlTable, MySqlColumn>['selection'] = [];
-		let limit, offset, orderBy: MySqlSelectConfig['orderBy'], where;
+		let limit, offset, orderBy: MySqlSelectConfig['orderBy'], where, comment;
 		const joins: MySqlSelectJoinConfig[] = [];
 
 		if (config === true) {
@@ -554,6 +566,10 @@ export class MySqlDialect {
 				}
 			}
 
+			if (config.comment) {
+				comment = config.comment;
+			}
+
 			// Transform `fieldsSelection` into `selection`
 			// `fieldsSelection` shouldn't be used after this point
 			for (const { tsKey, value } of fieldsSelection) {
@@ -714,6 +730,7 @@ export class MySqlDialect {
 				limit,
 				offset,
 				orderBy,
+				comment,
 				setOperators: [],
 			});
 		} else {
@@ -729,6 +746,7 @@ export class MySqlDialect {
 				limit,
 				offset,
 				orderBy,
+				comment,
 				setOperators: [],
 			});
 		}
@@ -762,7 +780,7 @@ export class MySqlDialect {
 		joinOn?: SQL;
 	}): BuildRelationalQueryResult<MySqlTable, MySqlColumn> {
 		let selection: BuildRelationalQueryResult<MySqlTable, MySqlColumn>['selection'] = [];
-		let limit, offset, orderBy: MySqlSelectConfig['orderBy'] = [], where;
+		let limit, offset, orderBy: MySqlSelectConfig['orderBy'] = [], where, comment;
 
 		if (config === true) {
 			const selectionEntries = Object.entries(tableConfig.columns);
@@ -851,6 +869,10 @@ export class MySqlDialect {
 				}
 			}
 
+			if (config.comment) {
+				comment = config.comment;
+			}
+
 			// Transform `fieldsSelection` into `selection`
 			// `fieldsSelection` shouldn't be used after this point
 			for (const { tsKey, value } of fieldsSelection) {
@@ -1006,6 +1028,7 @@ export class MySqlDialect {
 				limit,
 				offset,
 				orderBy,
+				comment,
 				setOperators: [],
 			});
 		} else {
@@ -1020,6 +1043,7 @@ export class MySqlDialect {
 				limit,
 				offset,
 				orderBy,
+				comment,
 				setOperators: [],
 			});
 		}

drizzle-orm/src/mysql-core/query-builders/delete.ts

@@ -40,6 +40,7 @@ export interface MySqlDeleteConfig {
 	where?: SQL | undefined;
 	table: MySqlTable;
 	returning?: SelectedFieldsOrdered;
+	comment?: string;
 }
 
 export type MySqlDeletePrepare<T extends AnyMySqlDeleteBase> = PreparedQueryKind<
@@ -97,40 +98,61 @@ export class MySqlDeleteBase<
 		this.config = { table };
 	}
 
-	/** 
+	/**
 	 * Adds a `where` clause to the query.
-	 * 
+	 *
 	 * Calling this method will delete only those rows that fulfill a specified condition.
-	 * 
+	 *
 	 * See docs: {@link https://orm.drizzle.team/docs/delete}
-	 * 
+	 *
 	 * @param where the `where` clause.
-	 * 
+	 *
 	 * @example
 	 * You can use conditional operators and `sql function` to filter the rows to be deleted.
-	 * 
+	 *
 	 * ```ts
 	 * // Delete all cars with green color
 	 * db.delete(cars).where(eq(cars.color, 'green'));
 	 * // or
 	 * db.delete(cars).where(sql`${cars.color} = 'green'`)
 	 * ```
-	 * 
+	 *
 	 * You can logically combine conditional operators with `and()` and `or()` operators:
-	 * 
+	 *
 	 * ```ts
 	 * // Delete all BMW cars with a green color
 	 * db.delete(cars).where(and(eq(cars.color, 'green'), eq(cars.brand, 'BMW')));
-	 * 
+	 *
 	 * // Delete all cars with the green or blue color
 	 * db.delete(cars).where(or(eq(cars.color, 'green'), eq(cars.color, 'blue')));
 	 * ```
-	*/
+	 */
 	where(where: SQL | undefined): MySqlDeleteWithout<this, TDynamic, 'where'> {
 		this.config.where = where;
 		return this as any;
 	}
 
+	/**
+	 * Adds a `comment` to the query.
+	 *
+	 * Calling this method will add a comment to the query.
+	 *
+	 * See docs: {@link https://orm.drizzle.team/docs/delete#comment}
+	 *
+	 * @param comment the `comment` to be added.
+	 *
+	 * @example
+	 *
+	 * ```ts
+	 * // add a comment "action=delete-car"
+	 * await db.delete(cars).where(eq(cars.color, 'green')).comment("action=delete-car");
+	 * ```
+	 */
+	comment(comment: string): MySqlDeleteWithout<this, TDynamic, 'comment'> {
+		this.config.comment = comment;
+		return this as any;
+	}
+
 	/** @internal */
 	getSQL(): SQL {
 		return this.dialect.buildDeleteQuery(this.config);

drizzle-orm/src/mysql-core/query-builders/insert.ts

@@ -22,6 +22,7 @@ export interface MySqlInsertConfig<TTable extends MySqlTable = MySqlTable> {
 	values: Record<string, Param | SQL>[];
 	ignore: boolean;
 	onConflict?: SQL;
+	comment?: string;
 }
 
 export type AnyMySqlInsertConfig = MySqlInsertConfig<MySqlTable>;
@@ -160,25 +161,25 @@ export class MySqlInsertBase<
 
 	/**
 	 * Adds an `on duplicate key update` clause to the query.
-	 * 
+	 *
 	 * Calling this method will update update the row if any unique index conflicts. MySQL will automatically determine the conflict target based on the primary key and unique indexes.
-	 * 
+	 *
 	 * See docs: {@link https://orm.drizzle.team/docs/insert#on-duplicate-key-update}
-	 * 
+	 *
 	 * @param config The `set` clause
-	 * 
+	 *
 	 * @example
 	 * ```ts
 	 * await db.insert(cars)
 	 *   .values({ id: 1, brand: 'BMW'})
 	 *   .onDuplicateKeyUpdate({ set: { brand: 'Porsche' }});
 	 * ```
-	 * 
+	 *
 	 * While MySQL does not directly support doing nothing on conflict, you can perform a no-op by setting any column's value to itself and achieve the same effect:
-	 * 
+	 *
 	 * ```ts
 	 * import { sql } from 'drizzle-orm';
-	 * 
+	 *
 	 * await db.insert(cars)
 	 *   .values({ id: 1, brand: 'BMW' })
 	 *   .onDuplicateKeyUpdate({ set: { id: sql`id` } });
@@ -192,6 +193,27 @@ export class MySqlInsertBase<
 		return this as any;
 	}
 
+	/**
+	 * Adds a `comment` to the query.
+	 *
+	 * Calling this method will add a comment to the query.
+	 *
+	 * See docs: {@link https://orm.drizzle.team/docs/insert#comment}
+	 *
+	 * @param comment the `comment` to be added.
+	 *
+	 * @example
+	 *
+	 * ```ts
+	 * // add a comment "action=insert-car"
+	 * await db.insert(cars).values({ id: 1, brand: 'BMW' }).comment("action=insert-car");
+	 * ```
+	 */
+	comment(comment: string): MySqlInsertWithout<this, TDynamic, 'comment'> {
+		this.config.comment = comment;
+		return this as any;
+	}
+
 	/** @internal */
 	getSQL(): SQL {
 		return this.dialect.buildInsertQuery(this.config);