SQLStore: Add deprecation comments for breaking migrations (#49740)

* Migrator: Extend support to rename columns

* SQLStore: Add deprecation comments for breaking migrations

pkg/services/sqlstore/migrator/migrations.go

@@ -31,6 +31,9 @@ type RawSQLMigration struct {
 	sql map[string]string
 }
 
+// NewRawSQLMigration should be used carefully, the usage
+// of SQL statements that cause breaking changes like renaming
+// a table or a column, or changing a column type should not be used.
 func NewRawSQLMigration(sql string) *RawSQLMigration {
 	m := &RawSQLMigration{}
 	if sql != "" {
@@ -111,12 +114,14 @@ func (m *AddColumnMigration) SQL(dialect Dialect) string {
 type RenameColumnMigration struct {
 	MigrationBase
 	table   Table
-	oldName string
+	column  *Column
 	newName string
 }
 
-func NewRenameColumnMigration(table Table, oldName, newName string) *RenameColumnMigration {
-	return &RenameColumnMigration{table: table, oldName: oldName, newName: newName}
+// NewRenameColumnMigration may cause breaking changes.
+// DEPRECATED: It should no longer be used. Kept only for legacy reasons.
+func NewRenameColumnMigration(table Table, column *Column, newName string) *RenameColumnMigration {
+	return &RenameColumnMigration{table: table, column: column, newName: newName}
 }
 
 func (m *RenameColumnMigration) Table(table Table) *RenameColumnMigration {
@@ -124,14 +129,18 @@ func (m *RenameColumnMigration) Table(table Table) *RenameColumnMigration {
 	return m
 }
 
-func (m *RenameColumnMigration) Rename(oldName string, newName string) *RenameColumnMigration {
-	m.oldName = oldName
+func (m *RenameColumnMigration) Column(column *Column) *RenameColumnMigration {
+	m.column = column
+	return m
+}
+
+func (m *RenameColumnMigration) Rename(newName string) *RenameColumnMigration {
 	m.newName = newName
 	return m
 }
 
 func (m *RenameColumnMigration) SQL(d Dialect) string {
-	return d.RenameColumn(m.table, m.oldName, m.newName)
+	return d.RenameColumn(m.table, m.column, m.newName)
 }
 
 type AddIndexMigration struct {
@@ -211,6 +220,8 @@ type RenameTableMigration struct {
 	newName string
 }
 
+// NewRenameTableMigration may cause breaking changes.
+// DEPRECATED: It should no longer be used. Kept only for legacy reasons.
 func NewRenameTableMigration(oldName string, newName string) *RenameTableMigration {
 	return &RenameTableMigration{oldName: oldName, newName: newName}
 }