feat(contrib/drivers/dm): add Replace/InsertIgnore support and field type/length enhancements for dm database (gogf#4541)

This pull request introduces significant improvements to the DM database
driver, especially around insert operations, and refines documentation
and tests to reflect these changes. The main focus is enabling support
for "replace" and "insert ignore" operations using DM's `MERGE`
statement, improving type reporting for table fields, and updating
documentation for clarity and accuracy.

### DM Driver Insert Operations

* Added support for `Replace` and `InsertIgnore` operations in the DM
driver by internally mapping them to DM's `MERGE` statement. This
enables upsert and insert-ignore behavior for DM databases, improving
compatibility with other drivers.
* Implemented helper methods (`doMergeInsert`, `doInsertIgnore`, and
`getPrimaryKeys`) to generate correct `MERGE` SQL statements and
automatically detect primary keys when needed.
[[1]](diffhunk://#diff-f51b30e3f0b0f1284b905385a89992efd0de2fe9ff8c5a4062344dfab17d428eL31-R94)
[[2]](diffhunk://#diff-f51b30e3f0b0f1284b905385a89992efd0de2fe9ff8c5a4062344dfab17d428eL115-R212)
* Updated the logic for building update values and SQL generation to
ensure correct behavior for both upsert and insert-ignore cases.
[[1]](diffhunk://#diff-f51b30e3f0b0f1284b905385a89992efd0de2fe9ff8c5a4062344dfab17d428eL61-R109)
[[2]](diffhunk://#diff-f51b30e3f0b0f1284b905385a89992efd0de2fe9ff8c5a4062344dfab17d428eL89-R132)
[[3]](diffhunk://#diff-f51b30e3f0b0f1284b905385a89992efd0de2fe9ff8c5a4062344dfab17d428eL100-R144)
[[4]](diffhunk://#diff-f51b30e3f0b0f1284b905385a89992efd0de2fe9ff8c5a4062344dfab17d428eL115-R212)

### Table Field Type Reporting

* Improved the DM driver's `TableFields` method to report column types
with length/precision (e.g., `VARCHAR(128)` instead of just `VARCHAR`),
aligning with expectations and other drivers.
[[1]](diffhunk://#diff-40a365112421ae1967bd960f8acefcc91ddb8180865b78bc49cd090fbf4883daL26-R26)
[[2]](diffhunk://#diff-40a365112421ae1967bd960f8acefcc91ddb8180865b78bc49cd090fbf4883daR88-R105)
* Updated related unit tests to expect the new type format for DM table
fields.

### Documentation Updates

* Removed outdated or redundant documentation in both English and
Chinese driver README files, and clarified supported features and
limitations for DM and other drivers.
[[1]](diffhunk://#diff-d49f5bc3a34b11a6ccb82cc54675b06a7dea5f0a943ae91c4ca0d28bd5003299L1)
[[2]](diffhunk://#diff-d49f5bc3a34b11a6ccb82cc54675b06a7dea5f0a943ae91c4ca0d28bd5003299L47-R46)
[[3]](diffhunk://#diff-d49f5bc3a34b11a6ccb82cc54675b06a7dea5f0a943ae91c4ca0d28bd5003299L119-L122)
[[4]](diffhunk://#diff-05411a14e9c7ca235f7f436bfde732853aa93b364361fe80d65ac768f4e4d613L1-L126)

### Test Suite Enhancements

* Refactored and restored unit tests for DM driver insert operations,
including tests for `Save`, `Insert`, and the new `InsertIgnore`
functionality to ensure correct behavior and compatibility.
[[1]](diffhunk://#diff-2b1a59b8b2adaa1ca3074629374ab122929e4d4fbb4cc794b8e1db60ebf8d4c2L143-L245)
[[2]](diffhunk://#diff-2b1a59b8b2adaa1ca3074629374ab122929e4d4fbb4cc794b8e1db60ebf8d4c2R512-R632)
* Minor adjustments to DM test initialization for improved clarity.

### Core Insert Logic Minor Refactoring

* Minor variable renaming for clarity in the core insert logic
(`gdb_core.go`), improving code readability.
[[1]](diffhunk://#diff-b1bbe5e3995261813e4e0ac6ffee8a37c236eaa2759f2bd82e211711695a70bcL449-R452)
[[2]](diffhunk://#diff-b1bbe5e3995261813e4e0ac6ffee8a37c236eaa2759f2bd82e211711695a70bcL466-R474)

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: gqcn

contrib/drivers/README.MD

@@ -1,4 +1,3 @@
-English | [简体中文](README.zh_CN.MD)
 
 # Database drivers
 
@@ -44,7 +43,7 @@ func main() {
 
 ## Supported Drivers
 
-### MySQL/MariaDB/TiDB
+### MySQL/MariaDB/TiDB/OceanBase
 
 ```go
 import _ "github.com/gogf/gf/contrib/drivers/mysql/v2"
@@ -116,10 +115,6 @@ Note:
 import _ "github.com/gogf/gf/contrib/drivers/dm/v2"
 ```
 
-Note:
-
-- It does not support `Replace` features.
-
 ## Custom Drivers
 
 It's quick and easy, please refer to current driver source.

contrib/drivers/README.zh_CN.MD

@@ -14,6 +14,7 @@ import (
 	"github.com/gogf/gf/v2/frame/g"
 )
 
+// Driver is the driver for dm database.
 type Driver struct {
 	*gdb.Core
 }

contrib/drivers/dm/dm.go

@@ -28,28 +28,70 @@ func (d *Driver) DoInsert(
 		return d.doSave(ctx, link, table, list, option)
 
 	case gdb.InsertOptionReplace:
-		// TODO:: Should be Supported
-		return nil, gerror.NewCode(
-			gcode.CodeNotSupported, `Replace operation is not supported by dm driver`,
-		)
-	}
+		// dm does not support REPLACE INTO syntax, use SAVE instead.
+		return d.doSave(ctx, link, table, list, option)
+
+	case gdb.InsertOptionIgnore:
+		// dm does not support INSERT IGNORE syntax, use MERGE instead.
+		return d.doInsertIgnore(ctx, link, table, list, option)
 
-	return d.Core.DoInsert(ctx, link, table, list, option)
+	default:
+		return d.Core.DoInsert(ctx, link, table, list, option)
+	}
 }
 
 // doSave support upsert for dm
 func (d *Driver) doSave(ctx context.Context,
 	link gdb.Link, table string, list gdb.List, option gdb.DoInsertOption,
 ) (result sql.Result, err error) {
-	if len(option.OnConflict) == 0 {
-		return nil, gerror.NewCode(
-			gcode.CodeMissingParameter, `Please specify conflict columns`,
-		)
+	return d.doMergeInsert(ctx, link, table, list, option, true)
+}
+
+// doInsertIgnore implements INSERT IGNORE operation using MERGE statement for DM database.
+// It only inserts records when there's no conflict on primary/unique keys.
+func (d *Driver) doInsertIgnore(ctx context.Context,
+	link gdb.Link, table string, list gdb.List, option gdb.DoInsertOption,
+) (result sql.Result, err error) {
+	return d.doMergeInsert(ctx, link, table, list, option, false)
+}
+
+// doMergeInsert implements MERGE-based insert operations for DM database.
+// When withUpdate is true, it performs upsert (insert or update).
+// When withUpdate is false, it performs insert ignore (insert only when no conflict).
+func (d *Driver) doMergeInsert(
+	ctx context.Context,
+	link gdb.Link,
+	table string,
+	list gdb.List,
+	option gdb.DoInsertOption,
+	withUpdate bool,
+) (result sql.Result, err error) {
+	// If OnConflict is not specified, automatically get the primary key of the table
+	conflictKeys := option.OnConflict
+	if len(conflictKeys) == 0 {
+		conflictKeys, err = d.getPrimaryKeys(ctx, table)
+		if err != nil {
+			return nil, gerror.WrapCode(
+				gcode.CodeInternalError,
+				err,
+				`failed to get primary keys for table`,
+			)
+		}
+		if len(conflictKeys) == 0 {
+			return nil, gerror.NewCode(
+				gcode.CodeMissingParameter,
+				`Please specify conflict columns or ensure the table has a primary key`,
+			)
+		}
 	}
 
 	if len(list) == 0 {
-		return nil, gerror.NewCode(
-			gcode.CodeInvalidRequest, `Save operation list is empty by oracle driver`,
+		opName := "Save"
+		if !withUpdate {
+			opName = "InsertIgnore"
+		}
+		return nil, gerror.NewCodef(
+			gcode.CodeInvalidRequest, `%s operation list is empty by dm driver`, opName,
 		)
 	}
 
@@ -58,14 +100,13 @@ func (d *Driver) doSave(ctx context.Context,
 		oneLen       = len(one)
 		charL, charR = d.GetChars()
 
-		conflictKeys   = option.OnConflict
 		conflictKeySet = gset.New(false)
 
-		// queryHolders:	Handle data with Holder that need to be upsert
-		// queryValues:		Handle data that need to be upsert
+		// queryHolders:	Handle data with Holder that need to be merged
+		// queryValues:		Handle data that need to be merged
 		// insertKeys:		Handle valid keys that need to be inserted
 		// insertValues:	Handle values that need to be inserted
-		// updateValues:	Handle values that need to be updated
+		// updateValues:	Handle values that need to be updated (only when withUpdate=true)
 		queryHolders = make([]string, oneLen)
 		queryValues  = make([]any, oneLen)
 		insertKeys   = make([]string, oneLen)
@@ -86,9 +127,9 @@ func (d *Driver) doSave(ctx context.Context,
 		insertKeys[index] = keyWithChar
 		insertValues[index] = fmt.Sprintf("T2.%s", keyWithChar)
 
-		// filter conflict keys in updateValues.
-		// And the key is not a soft created field.
-		if !(conflictKeySet.Contains(key) || d.Core.IsSoftCreatedFieldName(key)) {
+		// Build updateValues only when withUpdate is true
+		// Filter conflict keys and soft created fields from updateValues
+		if withUpdate && !(conflictKeySet.Contains(key) || d.Core.IsSoftCreatedFieldName(key)) {
 			updateValues = append(
 				updateValues,
 				fmt.Sprintf(`T1.%s = T2.%s`, keyWithChar, keyWithChar),
@@ -97,8 +138,10 @@ func (d *Driver) doSave(ctx context.Context,
 		index++
 	}
 
-	batchResult := new(gdb.SqlResult)
-	sqlStr := parseSqlForUpsert(table, queryHolders, insertKeys, insertValues, updateValues, conflictKeys)
+	var (
+		batchResult = new(gdb.SqlResult)
+		sqlStr      = parseSqlForMerge(table, queryHolders, insertKeys, insertValues, updateValues, conflictKeys)
+	)
 	r, err := d.DoExec(ctx, link, sqlStr, queryValues...)
 	if err != nil {
 		return r, err
@@ -112,40 +155,58 @@ func (d *Driver) doSave(ctx context.Context,
 	return batchResult, nil
 }
 
-// parseSqlForUpsert
-// MERGE INTO {{table}} T1
-// USING ( SELECT {{queryHolders}} FROM DUAL T2
-// ON (T1.{{duplicateKey}} = T2.{{duplicateKey}} AND ...)
-// WHEN NOT MATCHED THEN
-// INSERT {{insertKeys}} VALUES {{insertValues}}
-// WHEN MATCHED THEN
-// UPDATE SET {{updateValues}}
-func parseSqlForUpsert(table string,
+// getPrimaryKeys retrieves the primary key field names of the table as a slice of strings.
+// This method extracts primary key information from TableFields.
+func (d *Driver) getPrimaryKeys(ctx context.Context, table string) ([]string, error) {
+	tableFields, err := d.TableFields(ctx, table)
+	if err != nil {
+		return nil, err
+	}
+
+	var primaryKeys []string
+	for _, field := range tableFields {
+		if field.Key == "PRI" {
+			primaryKeys = append(primaryKeys, field.Name)
+		}
+	}
+
+	return primaryKeys, nil
+}
+
+// parseSqlForMerge generates MERGE statement for DM database.
+// When updateValues is empty, it only inserts (INSERT IGNORE behavior).
+// When updateValues is provided, it performs upsert (INSERT or UPDATE).
+// Examples:
+// - INSERT IGNORE: MERGE INTO table T1 USING (...) T2 ON (...) WHEN NOT MATCHED THEN INSERT(...) VALUES (...)
+// - UPSERT: MERGE INTO table T1 USING (...) T2 ON (...) WHEN NOT MATCHED THEN INSERT(...) VALUES (...) WHEN MATCHED THEN UPDATE SET ...
+func parseSqlForMerge(table string,
 	queryHolders, insertKeys, insertValues, updateValues, duplicateKey []string,
 ) (sqlStr string) {
 	var (
 		queryHolderStr  = strings.Join(queryHolders, ",")
 		insertKeyStr    = strings.Join(insertKeys, ",")
 		insertValueStr  = strings.Join(insertValues, ",")
-		updateValueStr  = strings.Join(updateValues, ",")
 		duplicateKeyStr string
-		pattern         = gstr.Trim(`MERGE INTO %s T1 USING (SELECT %s FROM DUAL) T2 ON (%s) WHEN NOT MATCHED THEN INSERT(%s) VALUES (%s) WHEN MATCHED THEN UPDATE SET %s;`)
 	)
 
+	// Build ON condition
 	for index, keys := range duplicateKey {
 		if index != 0 {
 			duplicateKeyStr += " AND "
 		}
-		duplicateTmp := fmt.Sprintf("T1.%s = T2.%s", keys, keys)
-		duplicateKeyStr += duplicateTmp
+		duplicateKeyStr += fmt.Sprintf("T1.%s = T2.%s", keys, keys)
 	}
 
-	return fmt.Sprintf(pattern,
-		table,
-		queryHolderStr,
-		duplicateKeyStr,
-		insertKeyStr,
-		insertValueStr,
-		updateValueStr,
-	)
+	// Build SQL based on whether UPDATE is needed
+	pattern := gstr.Trim(`MERGE INTO %s T1 USING (SELECT %s FROM DUAL) T2 ON (%s) WHEN NOT MATCHED THEN INSERT(%s) VALUES (%s)`)
+	if len(updateValues) > 0 {
+		// Upsert: INSERT or UPDATE
+		pattern += gstr.Trim(`WHEN MATCHED THEN UPDATE SET %s`)
+		return fmt.Sprintf(
+			pattern, table, queryHolderStr, duplicateKeyStr, insertKeyStr, insertValueStr,
+			strings.Join(updateValues, ","),
+		)
+	}
+	// Insert Ignore: INSERT only
+	return fmt.Sprintf(pattern, table, queryHolderStr, duplicateKeyStr, insertKeyStr, insertValueStr)
 }