feat: Add query comment into the query for improved debugging

This feature enhances debugging by including query comments in headers, allowing developers to trace the query's origin. By matching the query comment in the header, it's easier to identify the specific location in the code where the query was executed.

internal/dbtest/query_test.go

@@ -1596,6 +1596,149 @@ func TestQuery(t *testing.T) {
 				return db.NewDelete().Model(&Model{}).WherePK().Returning("*")
 			},
 		},
+		{
+			id: 173,
+			query: func(db *bun.DB) schema.QueryAppender {
+				return db.NewAddColumn().
+					Model(&Model{}).
+					Comment("test").
+					ColumnExpr("column_name VARCHAR(123)")
+			},
+		},
+		{
+			id: 174,
+			query: func(db *bun.DB) schema.QueryAppender {
+				return db.NewDropColumn().
+					Model(&Model{}).
+					Comment("test").
+					Column("column_name")
+			},
+		},
+		{
+			id: 175,
+			query: func(db *bun.DB) schema.QueryAppender {
+				return db.NewDelete().
+					Model(&Model{}).
+					WherePK().
+					Comment("test").
+					Returning("*")
+			},
+		},
+		{
+			id: 176,
+			query: func(db *bun.DB) schema.QueryAppender {
+				return db.NewCreateIndex().
+					Model(&Model{}).
+					Unique().
+					Index("index_name").
+					Comment("test").
+					Column("column_name")
+			},
+		},
+		{
+			id: 177,
+			query: func(db *bun.DB) schema.QueryAppender {
+				return db.NewDropIndex().
+					Model(&Model{}).
+					Comment("test").
+					Index("index_name").
+					Comment("test")
+			},
+		},
+		{
+			id: 178,
+			query: func(db *bun.DB) schema.QueryAppender {
+				return db.NewInsert().
+					Model(&Model{}).
+					Comment("test").
+					Value("column_name", "value")
+			},
+		},
+		{
+			id: 179,
+			query: func(db *bun.DB) schema.QueryAppender {
+				type Model struct {
+					ID    int64 `bun:",pk,autoincrement"`
+					Name  string
+					Value string
+				}
+
+				newModels := []*Model{
+					{Name: "A", Value: "world"},
+					{Name: "B", Value: "test"},
+				}
+
+				return db.NewMerge().
+					Model(new(Model)).
+					With("_data", db.NewValues(&newModels)).
+					Using("_data").
+					On("?TableAlias.name = _data.name").
+					WhenUpdate("MATCHED", func(q *bun.UpdateQuery) *bun.UpdateQuery {
+						return q.Set("value = _data.value")
+					}).
+					WhenInsert("NOT MATCHED", func(q *bun.InsertQuery) *bun.InsertQuery {
+						return q.Value("name", "_data.name").Value("value", "_data.value")
+					}).
+					Comment("test").
+					Returning("$action")
+
+			},
+		},
+		{
+			id: 180,
+			query: func(db *bun.DB) schema.QueryAppender {
+				return db.NewRaw("SELECT 1").Comment("test")
+			},
+		},
+		{
+			id: 181,
+			query: func(db *bun.DB) schema.QueryAppender {
+				return db.NewSelect().
+					Model(&Model{}).
+					Comment("test")
+			},
+		},
+		{
+			id: 182,
+			query: func(db *bun.DB) schema.QueryAppender {
+				return db.NewCreateTable().
+					Model(&Model{}).
+					Comment("test")
+			},
+		},
+		{
+			id: 183,
+			query: func(db *bun.DB) schema.QueryAppender {
+				return db.NewDropTable().
+					Model(&Model{}).
+					Comment("test")
+			},
+		},
+		{
+			id: 184,
+			query: func(db *bun.DB) schema.QueryAppender {
+				return db.NewTruncateTable().
+					Model(&Model{}).
+					Comment("test")
+			},
+		},
+		{
+			id: 185,
+			query: func(db *bun.DB) schema.QueryAppender {
+				return db.NewUpdate().
+					Model(&Model{}).
+					Comment("test").
+					Set("name = ?", "new-name").
+					Where("id = ?", 1)
+			},
+		},
+		{
+			id: 186,
+			query: func(db *bun.DB) schema.QueryAppender {
+				return db.NewValues(&[]Model{{1, "hello"}}).
+					Comment("test")
+			},
+		},
 	}
 
 	timeRE := regexp.MustCompile(`'2\d{3}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(\.\d+)?(\+\d{2}:\d{2})?'`)

internal/dbtest/testdata/snapshots/TestQuery-mariadb-173

@@ -0,0 +1 @@
+/* test */ ALTER TABLE `models` ADD column_name VARCHAR(123)

internal/dbtest/testdata/snapshots/TestQuery-mariadb-174

@@ -0,0 +1 @@
+/* test */ ALTER TABLE `models` DROP COLUMN `column_name`

internal/dbtest/testdata/snapshots/TestQuery-mariadb-175

@@ -0,0 +1 @@
+bun: returning is not supported for current dialect

internal/dbtest/testdata/snapshots/TestQuery-mariadb-176

@@ -0,0 +1 @@
+/* test */ CREATE UNIQUE INDEX `index_name` ON `models` (`column_name`)

internal/dbtest/testdata/snapshots/TestQuery-mariadb-177

@@ -0,0 +1 @@
+/* test */ DROP INDEX index_name

internal/dbtest/testdata/snapshots/TestQuery-mariadb-178

@@ -0,0 +1 @@
+/* test */ INSERT INTO `models` (`id`, `str`, `column_name`) VALUES (DEFAULT, '', value)

internal/dbtest/testdata/snapshots/TestQuery-mariadb-179

@@ -0,0 +1 @@
+bun: merge not supported for current dialect

internal/dbtest/testdata/snapshots/TestQuery-mariadb-180

@@ -0,0 +1 @@
+/* test */ SELECT 1

internal/dbtest/testdata/snapshots/TestQuery-mariadb-181

@@ -0,0 +1 @@
+/* test */ SELECT `model`.`id`, `model`.`str` FROM `models` AS `model`

internal/dbtest/testdata/snapshots/TestQuery-mariadb-182

@@ -0,0 +1 @@
+/* test */ CREATE TABLE `models` (`id` BIGINT NOT NULL AUTO_INCREMENT, `str` VARCHAR(255), PRIMARY KEY (`id`))

internal/dbtest/testdata/snapshots/TestQuery-mariadb-183

@@ -0,0 +1 @@
+/* test */ DROP TABLE `models`

internal/dbtest/testdata/snapshots/TestQuery-mariadb-184

@@ -0,0 +1 @@
+/* test */ TRUNCATE TABLE `models`

internal/dbtest/testdata/snapshots/TestQuery-mariadb-185

@@ -0,0 +1 @@
+/* test */ UPDATE `models` AS `model` SET name = 'new-name' WHERE (id = 1)

internal/dbtest/testdata/snapshots/TestQuery-mariadb-186

@@ -0,0 +1 @@
+/* test */ VALUES ROW(1, 'hello')

internal/dbtest/testdata/snapshots/TestQuery-mssql2019-173

@@ -0,0 +1 @@
+/* test */ ALTER TABLE "models" ADD column_name VARCHAR(123)

internal/dbtest/testdata/snapshots/TestQuery-mssql2019-174

@@ -0,0 +1 @@
+/* test */ ALTER TABLE "models" DROP COLUMN "column_name"

internal/dbtest/testdata/snapshots/TestQuery-mssql2019-175

@@ -0,0 +1 @@
+bun: returning is not supported for current dialect

internal/dbtest/testdata/snapshots/TestQuery-mssql2019-176

@@ -0,0 +1 @@
+/* test */ CREATE UNIQUE INDEX "index_name" ON "models" ("column_name")

internal/dbtest/testdata/snapshots/TestQuery-mssql2019-177

@@ -0,0 +1 @@
+/* test */ DROP INDEX index_name

internal/dbtest/testdata/snapshots/TestQuery-mssql2019-178

@@ -0,0 +1 @@
+/* test */ INSERT INTO "models" ("str", "column_name") OUTPUT INSERTED."id" VALUES (N'', value)

internal/dbtest/testdata/snapshots/TestQuery-mssql2019-179

@@ -0,0 +1 @@
+/* test */ WITH "_data" AS (SELECT * FROM (VALUES (NULL, N'A', N'world'), (NULL, N'B', N'test')) AS t ("id", "name", "value")) MERGE "models" AS "model" USING _data ON "model".name = _data.name WHEN MATCHED THEN UPDATE SET value = _data.value WHEN NOT MATCHED THEN INSERT ("name", "value") VALUES (_data.name, _data.value) OUTPUT $action;

internal/dbtest/testdata/snapshots/TestQuery-mssql2019-180

@@ -0,0 +1 @@
+/* test */ SELECT 1

internal/dbtest/testdata/snapshots/TestQuery-mssql2019-181

@@ -0,0 +1 @@
+/* test */ SELECT "model"."id", "model"."str" FROM "models" AS "model"

internal/dbtest/testdata/snapshots/TestQuery-mssql2019-182

@@ -0,0 +1 @@
+/* test */ CREATE TABLE "models" ("id" BIGINT NOT NULL IDENTITY, "str" VARCHAR(255), PRIMARY KEY ("id"))

internal/dbtest/testdata/snapshots/TestQuery-mssql2019-183

@@ -0,0 +1 @@
+/* test */ DROP TABLE "models"

internal/dbtest/testdata/snapshots/TestQuery-mssql2019-184

@@ -0,0 +1 @@
+/* test */ DELETE FROM "models"

internal/dbtest/testdata/snapshots/TestQuery-mssql2019-185

@@ -0,0 +1 @@
+/* test */ UPDATE "models" SET name = N'new-name' WHERE (id = 1)

internal/dbtest/testdata/snapshots/TestQuery-mssql2019-186

@@ -0,0 +1 @@
+/* test */ VALUES (1, N'hello')

internal/dbtest/testdata/snapshots/TestQuery-mysql5-173

@@ -0,0 +1 @@
+/* test */ ALTER TABLE `models` ADD column_name VARCHAR(123)

internal/dbtest/testdata/snapshots/TestQuery-mysql5-174

@@ -0,0 +1 @@
+/* test */ ALTER TABLE `models` DROP COLUMN `column_name`

internal/dbtest/testdata/snapshots/TestQuery-mysql5-175

@@ -0,0 +1 @@
+bun: returning is not supported for current dialect

internal/dbtest/testdata/snapshots/TestQuery-mysql5-176

@@ -0,0 +1 @@
+/* test */ CREATE UNIQUE INDEX `index_name` ON `models` (`column_name`)

internal/dbtest/testdata/snapshots/TestQuery-mysql5-177

@@ -0,0 +1 @@
+/* test */ DROP INDEX index_name

internal/dbtest/testdata/snapshots/TestQuery-mysql5-178

@@ -0,0 +1 @@
+/* test */ INSERT INTO `models` (`id`, `str`, `column_name`) VALUES (DEFAULT, '', value)

internal/dbtest/testdata/snapshots/TestQuery-mysql5-179

@@ -0,0 +1 @@
+bun: merge not supported for current dialect

internal/dbtest/testdata/snapshots/TestQuery-mysql5-180

@@ -0,0 +1 @@
+/* test */ SELECT 1

internal/dbtest/testdata/snapshots/TestQuery-mysql5-181

@@ -0,0 +1 @@
+/* test */ SELECT `model`.`id`, `model`.`str` FROM `models` AS `model`

internal/dbtest/testdata/snapshots/TestQuery-mysql5-182

@@ -0,0 +1 @@
+/* test */ CREATE TABLE `models` (`id` BIGINT NOT NULL AUTO_INCREMENT, `str` VARCHAR(255), PRIMARY KEY (`id`))

internal/dbtest/testdata/snapshots/TestQuery-mysql5-183

@@ -0,0 +1 @@
+/* test */ DROP TABLE `models`

internal/dbtest/testdata/snapshots/TestQuery-mysql5-184

@@ -0,0 +1 @@
+/* test */ TRUNCATE TABLE `models`

internal/dbtest/testdata/snapshots/TestQuery-mysql5-185

@@ -0,0 +1 @@
+/* test */ UPDATE `models` AS `model` SET name = 'new-name' WHERE (id = 1)

internal/dbtest/testdata/snapshots/TestQuery-mysql5-186

@@ -0,0 +1 @@
+/* test */ VALUES ROW(1, 'hello')

internal/dbtest/testdata/snapshots/TestQuery-mysql8-173

@@ -0,0 +1 @@
+/* test */ ALTER TABLE `models` ADD column_name VARCHAR(123)

internal/dbtest/testdata/snapshots/TestQuery-mysql8-174

@@ -0,0 +1 @@
+/* test */ ALTER TABLE `models` DROP COLUMN `column_name`

internal/dbtest/testdata/snapshots/TestQuery-mysql8-175

@@ -0,0 +1 @@
+bun: returning is not supported for current dialect

internal/dbtest/testdata/snapshots/TestQuery-mysql8-176

@@ -0,0 +1 @@
+/* test */ CREATE UNIQUE INDEX `index_name` ON `models` (`column_name`)

internal/dbtest/testdata/snapshots/TestQuery-mysql8-177

@@ -0,0 +1 @@
+/* test */ DROP INDEX index_name

internal/dbtest/testdata/snapshots/TestQuery-mysql8-178

@@ -0,0 +1 @@
+/* test */ INSERT INTO `models` (`id`, `str`, `column_name`) VALUES (DEFAULT, '', value)

internal/dbtest/testdata/snapshots/TestQuery-mysql8-179

@@ -0,0 +1 @@
+bun: merge not supported for current dialect

internal/dbtest/testdata/snapshots/TestQuery-mysql8-180

@@ -0,0 +1 @@
+/* test */ SELECT 1

internal/dbtest/testdata/snapshots/TestQuery-mysql8-181

@@ -0,0 +1 @@
+/* test */ SELECT `model`.`id`, `model`.`str` FROM `models` AS `model`

internal/dbtest/testdata/snapshots/TestQuery-mysql8-182

@@ -0,0 +1 @@
+/* test */ CREATE TABLE `models` (`id` BIGINT NOT NULL AUTO_INCREMENT, `str` VARCHAR(255), PRIMARY KEY (`id`))

internal/dbtest/testdata/snapshots/TestQuery-mysql8-183

@@ -0,0 +1 @@
+/* test */ DROP TABLE `models`

internal/dbtest/testdata/snapshots/TestQuery-mysql8-184

@@ -0,0 +1 @@
+/* test */ TRUNCATE TABLE `models`

internal/dbtest/testdata/snapshots/TestQuery-mysql8-185

@@ -0,0 +1 @@
+/* test */ UPDATE `models` AS `model` SET name = 'new-name' WHERE (id = 1)

internal/dbtest/testdata/snapshots/TestQuery-mysql8-186

@@ -0,0 +1 @@
+/* test */ VALUES ROW(1, 'hello')

internal/dbtest/testdata/snapshots/TestQuery-pg-173

@@ -0,0 +1 @@
+/* test */ ALTER TABLE "models" ADD column_name VARCHAR(123)

internal/dbtest/testdata/snapshots/TestQuery-pg-174

@@ -0,0 +1 @@
+/* test */ ALTER TABLE "models" DROP COLUMN "column_name"

internal/dbtest/testdata/snapshots/TestQuery-pg-175

@@ -0,0 +1 @@
+/* test */ DELETE FROM "models" AS "model" WHERE ("model"."id" = NULL) RETURNING *

internal/dbtest/testdata/snapshots/TestQuery-pg-176

@@ -0,0 +1 @@
+/* test */ CREATE UNIQUE INDEX "index_name" ON "models" ("column_name")

internal/dbtest/testdata/snapshots/TestQuery-pg-177

@@ -0,0 +1 @@
+/* test */ DROP INDEX index_name

internal/dbtest/testdata/snapshots/TestQuery-pg-178

@@ -0,0 +1 @@
+/* test */ INSERT INTO "models" ("id", "str", "column_name") VALUES (DEFAULT, '', value) RETURNING "id"

internal/dbtest/testdata/snapshots/TestQuery-pg-179

@@ -0,0 +1 @@
+/* test */ WITH "_data" ("id", "name", "value") AS (VALUES (NULL::BIGINT, 'A'::VARCHAR, 'world'::VARCHAR), (NULL::BIGINT, 'B'::VARCHAR, 'test'::VARCHAR)) MERGE INTO "models" AS "model" USING _data ON "model".name = _data.name WHEN MATCHED THEN UPDATE SET value = _data.value WHEN NOT MATCHED THEN INSERT ("id", "name", "value") VALUES (DEFAULT, _data.name, _data.value);

internal/dbtest/testdata/snapshots/TestQuery-pg-180

@@ -0,0 +1 @@
+/* test */ SELECT 1

internal/dbtest/testdata/snapshots/TestQuery-pg-181

@@ -0,0 +1 @@
+/* test */ SELECT "model"."id", "model"."str" FROM "models" AS "model"

internal/dbtest/testdata/snapshots/TestQuery-pg-182

@@ -0,0 +1 @@
+/* test */ CREATE TABLE "models" ("id" BIGSERIAL NOT NULL, "str" VARCHAR, PRIMARY KEY ("id"))

internal/dbtest/testdata/snapshots/TestQuery-pg-183

@@ -0,0 +1 @@
+/* test */ DROP TABLE "models"

internal/dbtest/testdata/snapshots/TestQuery-pg-184

@@ -0,0 +1 @@
+/* test */ TRUNCATE TABLE "models" RESTART IDENTITY

internal/dbtest/testdata/snapshots/TestQuery-pg-185

@@ -0,0 +1 @@
+/* test */ UPDATE "models" AS "model" SET name = 'new-name' WHERE (id = 1)

internal/dbtest/testdata/snapshots/TestQuery-pg-186

@@ -0,0 +1 @@
+/* test */ VALUES (1::BIGINT, 'hello'::VARCHAR)

internal/dbtest/testdata/snapshots/TestQuery-pgx-173

@@ -0,0 +1 @@
+/* test */ ALTER TABLE "models" ADD column_name VARCHAR(123)

internal/dbtest/testdata/snapshots/TestQuery-pgx-174

@@ -0,0 +1 @@
+/* test */ ALTER TABLE "models" DROP COLUMN "column_name"

internal/dbtest/testdata/snapshots/TestQuery-pgx-175

@@ -0,0 +1 @@
+/* test */ DELETE FROM "models" AS "model" WHERE ("model"."id" = NULL) RETURNING *

internal/dbtest/testdata/snapshots/TestQuery-pgx-176

@@ -0,0 +1 @@
+/* test */ CREATE UNIQUE INDEX "index_name" ON "models" ("column_name")

internal/dbtest/testdata/snapshots/TestQuery-pgx-177

@@ -0,0 +1 @@
+/* test */ DROP INDEX index_name

internal/dbtest/testdata/snapshots/TestQuery-pgx-178

@@ -0,0 +1 @@
+/* test */ INSERT INTO "models" ("id", "str", "column_name") VALUES (DEFAULT, '', value) RETURNING "id"

internal/dbtest/testdata/snapshots/TestQuery-pgx-179

@@ -0,0 +1 @@
+/* test */ WITH "_data" ("id", "name", "value") AS (VALUES (NULL::BIGINT, 'A'::VARCHAR, 'world'::VARCHAR), (NULL::BIGINT, 'B'::VARCHAR, 'test'::VARCHAR)) MERGE INTO "models" AS "model" USING _data ON "model".name = _data.name WHEN MATCHED THEN UPDATE SET value = _data.value WHEN NOT MATCHED THEN INSERT ("id", "name", "value") VALUES (DEFAULT, _data.name, _data.value);

internal/dbtest/testdata/snapshots/TestQuery-pgx-180

@@ -0,0 +1 @@
+/* test */ SELECT 1

internal/dbtest/testdata/snapshots/TestQuery-pgx-181

@@ -0,0 +1 @@
+/* test */ SELECT "model"."id", "model"."str" FROM "models" AS "model"

internal/dbtest/testdata/snapshots/TestQuery-pgx-182

@@ -0,0 +1 @@
+/* test */ CREATE TABLE "models" ("id" BIGSERIAL NOT NULL, "str" VARCHAR, PRIMARY KEY ("id"))

internal/dbtest/testdata/snapshots/TestQuery-pgx-183

@@ -0,0 +1 @@
+/* test */ DROP TABLE "models"

internal/dbtest/testdata/snapshots/TestQuery-pgx-184

@@ -0,0 +1 @@
+/* test */ TRUNCATE TABLE "models" RESTART IDENTITY

internal/dbtest/testdata/snapshots/TestQuery-pgx-185

@@ -0,0 +1 @@
+/* test */ UPDATE "models" AS "model" SET name = 'new-name' WHERE (id = 1)

internal/dbtest/testdata/snapshots/TestQuery-pgx-186

@@ -0,0 +1 @@
+/* test */ VALUES (1::BIGINT, 'hello'::VARCHAR)

internal/dbtest/testdata/snapshots/TestQuery-sqlite-173

@@ -0,0 +1 @@
+/* test */ ALTER TABLE "models" ADD column_name VARCHAR(123)

internal/dbtest/testdata/snapshots/TestQuery-sqlite-174

@@ -0,0 +1 @@
+/* test */ ALTER TABLE "models" DROP COLUMN "column_name"

internal/dbtest/testdata/snapshots/TestQuery-sqlite-175

@@ -0,0 +1 @@
+/* test */ DELETE FROM "models" AS "model" WHERE ("model"."id" = NULL) RETURNING *

internal/dbtest/testdata/snapshots/TestQuery-sqlite-176

@@ -0,0 +1 @@
+/* test */ CREATE UNIQUE INDEX "index_name" ON "models" ("column_name")

internal/dbtest/testdata/snapshots/TestQuery-sqlite-177

@@ -0,0 +1 @@
+/* test */ DROP INDEX index_name

internal/dbtest/testdata/snapshots/TestQuery-sqlite-178

@@ -0,0 +1 @@
+/* test */ INSERT INTO "models" ("str", "column_name") VALUES ('', value) RETURNING "id"

internal/dbtest/testdata/snapshots/TestQuery-sqlite-179

@@ -0,0 +1 @@
+bun: merge not supported for current dialect

internal/dbtest/testdata/snapshots/TestQuery-sqlite-180

@@ -0,0 +1 @@
+/* test */ SELECT 1

internal/dbtest/testdata/snapshots/TestQuery-sqlite-181

@@ -0,0 +1 @@
+/* test */ SELECT "model"."id", "model"."str" FROM "models" AS "model"

internal/dbtest/testdata/snapshots/TestQuery-sqlite-182

@@ -0,0 +1 @@
+/* test */ CREATE TABLE "models" ("id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, "str" VARCHAR)

internal/dbtest/testdata/snapshots/TestQuery-sqlite-183

@@ -0,0 +1 @@
+/* test */ DROP TABLE "models"

internal/dbtest/testdata/snapshots/TestQuery-sqlite-184

@@ -0,0 +1 @@
+/* test */ DELETE FROM "models"

internal/dbtest/testdata/snapshots/TestQuery-sqlite-185

@@ -0,0 +1 @@
+/* test */ UPDATE "models" AS "model" SET name = 'new-name' WHERE (id = 1)

internal/dbtest/testdata/snapshots/TestQuery-sqlite-186

@@ -0,0 +1 @@
+/* test */ VALUES (1, 'hello')

query_column_add.go

@@ -13,6 +13,7 @@ type AddColumnQuery struct {
 	baseQuery
 
 	ifNotExists bool
+	comment     string
 }
 
 var _ Query = (*AddColumnQuery)(nil)
@@ -85,6 +86,14 @@ func (q *AddColumnQuery) IfNotExists() *AddColumnQuery {
 
 //------------------------------------------------------------------------------
 
+// Comment adds a comment to the query, wrapped by /* ... */.
+func (q *AddColumnQuery) Comment(comment string) *AddColumnQuery {
+	q.comment = comment
+	return q
+}
+
+//------------------------------------------------------------------------------
+
 func (q *AddColumnQuery) Operation() string {
 	return "ADD COLUMN"
 }
@@ -93,6 +102,9 @@ func (q *AddColumnQuery) AppendQuery(fmter schema.Formatter, b []byte) (_ []byte
 	if q.err != nil {
 		return nil, q.err
 	}
+
+	b = appendComment(b, q.comment)
+
 	if len(q.columns) != 1 {
 		return nil, fmt.Errorf("bun: AddColumnQuery requires exactly one column")
 	}