Add doc comments and remove old DML query builder functions

Author: danieljoos

go/sql/builder.go

@@ -402,140 +402,17 @@ func buildUniqueKeyMinMaxValuesPreparedQuery(databaseName, tableName string, uni
 	return query, nil
 }
 
-func BuildDMLDeleteQuery(databaseName, tableName string, tableColumns, uniqueKeyColumns *ColumnList, args []interface{}) (result string, uniqueKeyArgs []interface{}, err error) {
-	if len(args) != tableColumns.Len() {
-		return result, uniqueKeyArgs, fmt.Errorf("args count differs from table column count in BuildDMLDeleteQuery")
-	}
-	if uniqueKeyColumns.Len() == 0 {
-		return result, uniqueKeyArgs, fmt.Errorf("No unique key columns found in BuildDMLDeleteQuery")
-	}
-	for _, column := range uniqueKeyColumns.Columns() {
-		tableOrdinal := tableColumns.Ordinals[column.Name]
-		arg := column.convertArg(args[tableOrdinal], true)
-		uniqueKeyArgs = append(uniqueKeyArgs, arg)
-	}
-	databaseName = EscapeName(databaseName)
-	tableName = EscapeName(tableName)
-	equalsComparison, err := BuildEqualsPreparedComparison(uniqueKeyColumns.Names())
-	if err != nil {
-		return result, uniqueKeyArgs, err
-	}
-	result = fmt.Sprintf(`
-		delete /* gh-ost %s.%s */
-		from
-			%s.%s
-		where
-			%s`,
-		databaseName, tableName,
-		databaseName, tableName,
-		equalsComparison,
-	)
-	return result, uniqueKeyArgs, nil
-}
-
-func BuildDMLInsertQuery(databaseName, tableName string, tableColumns, sharedColumns, mappedSharedColumns *ColumnList, args []interface{}) (result string, sharedArgs []interface{}, err error) {
-	if len(args) != tableColumns.Len() {
-		return result, args, fmt.Errorf("args count differs from table column count in BuildDMLInsertQuery")
-	}
-	if !sharedColumns.IsSubsetOf(tableColumns) {
-		return result, args, fmt.Errorf("shared columns is not a subset of table columns in BuildDMLInsertQuery")
-	}
-	if sharedColumns.Len() == 0 {
-		return result, args, fmt.Errorf("No shared columns found in BuildDMLInsertQuery")
-	}
-	databaseName = EscapeName(databaseName)
-	tableName = EscapeName(tableName)
-
-	for _, column := range sharedColumns.Columns() {
-		tableOrdinal := tableColumns.Ordinals[column.Name]
-		arg := column.convertArg(args[tableOrdinal], false)
-		sharedArgs = append(sharedArgs, arg)
-	}
-
-	mappedSharedColumnNames := duplicateNames(mappedSharedColumns.Names())
-	for i := range mappedSharedColumnNames {
-		mappedSharedColumnNames[i] = EscapeName(mappedSharedColumnNames[i])
-	}
-	preparedValues := buildColumnsPreparedValues(mappedSharedColumns)
-
-	result = fmt.Sprintf(`
-		replace /* gh-ost %s.%s */
-		into
-			%s.%s
-			(%s)
-		values
-			(%s)`,
-		databaseName, tableName,
-		databaseName, tableName,
-		strings.Join(mappedSharedColumnNames, ", "),
-		strings.Join(preparedValues, ", "),
-	)
-	return result, sharedArgs, nil
-}
-
-func BuildDMLUpdateQuery(databaseName, tableName string, tableColumns, sharedColumns, mappedSharedColumns, uniqueKeyColumns *ColumnList, valueArgs, whereArgs []interface{}) (result string, sharedArgs, uniqueKeyArgs []interface{}, err error) {
-	if len(valueArgs) != tableColumns.Len() {
-		return result, sharedArgs, uniqueKeyArgs, fmt.Errorf("value args count differs from table column count in BuildDMLUpdateQuery")
-	}
-	if len(whereArgs) != tableColumns.Len() {
-		return result, sharedArgs, uniqueKeyArgs, fmt.Errorf("where args count differs from table column count in BuildDMLUpdateQuery")
-	}
-	if !sharedColumns.IsSubsetOf(tableColumns) {
-		return result, sharedArgs, uniqueKeyArgs, fmt.Errorf("shared columns is not a subset of table columns in BuildDMLUpdateQuery")
-	}
-	if !uniqueKeyColumns.IsSubsetOf(sharedColumns) {
-		return result, sharedArgs, uniqueKeyArgs, fmt.Errorf("unique key columns is not a subset of shared columns in BuildDMLUpdateQuery")
-	}
-	if sharedColumns.Len() == 0 {
-		return result, sharedArgs, uniqueKeyArgs, fmt.Errorf("No shared columns found in BuildDMLUpdateQuery")
-	}
-	if uniqueKeyColumns.Len() == 0 {
-		return result, sharedArgs, uniqueKeyArgs, fmt.Errorf("No unique key columns found in BuildDMLUpdateQuery")
-	}
-	databaseName = EscapeName(databaseName)
-	tableName = EscapeName(tableName)
-
-	for _, column := range sharedColumns.Columns() {
-		tableOrdinal := tableColumns.Ordinals[column.Name]
-		arg := column.convertArg(valueArgs[tableOrdinal], false)
-		sharedArgs = append(sharedArgs, arg)
-	}
-
-	for _, column := range uniqueKeyColumns.Columns() {
-		tableOrdinal := tableColumns.Ordinals[column.Name]
-		arg := column.convertArg(whereArgs[tableOrdinal], true)
-		uniqueKeyArgs = append(uniqueKeyArgs, arg)
-	}
-
-	setClause, err := BuildSetPreparedClause(mappedSharedColumns)
-	if err != nil {
-		return "", sharedArgs, uniqueKeyArgs, err
-	}
-
-	equalsComparison, err := BuildEqualsPreparedComparison(uniqueKeyColumns.Names())
-	if err != nil {
-		return "", sharedArgs, uniqueKeyArgs, err
-	}
-	result = fmt.Sprintf(`
-		update /* gh-ost %s.%s */
-			%s.%s
-		set
-			%s
-		where
-			%s`,
-		databaseName, tableName,
-		databaseName, tableName,
-		setClause,
-		equalsComparison,
-	)
-	return result, sharedArgs, uniqueKeyArgs, nil
-}
-
+// DMLDeleteQueryBuilder can build DELETE queries for DML events.
+// It holds the prepared query statement so it doesn't need to be recreated every time.
 type DMLDeleteQueryBuilder struct {
 	tableColumns, uniqueKeyColumns *ColumnList
 	preparedStatement              string
 }
 
+// NewDMLDeleteQueryBuilder creates a new DMLDeleteQueryBuilder.
+// It prepares the DELETE query statement.
+// Returns an error if no unique key columns are given
+// or the prepared statement cannot be built.
 func NewDMLDeleteQueryBuilder(databaseName, tableName string, tableColumns, uniqueKeyColumns *ColumnList) (*DMLDeleteQueryBuilder, error) {
 	if uniqueKeyColumns.Len() == 0 {
 		return nil, fmt.Errorf("no unique key columns found in NewDMLDeleteQueryBuilder")
@@ -566,6 +443,9 @@ func NewDMLDeleteQueryBuilder(databaseName, tableName string, tableColumns, uniq
 	return b, nil
 }
 
+// BuildQuery builds the arguments array for a DML event DELETE query.
+// It returns the query string and the unique key arguments array.
+// Returns an error if the number of arguments is not equal to the number of table columns.
 func (b *DMLDeleteQueryBuilder) BuildQuery(args []interface{}) (string, []interface{}, error) {
 	if len(args) != b.tableColumns.Len() {
 		return "", nil, fmt.Errorf("args count differs from table column count in BuildDMLDeleteQuery")
@@ -579,11 +459,17 @@ func (b *DMLDeleteQueryBuilder) BuildQuery(args []interface{}) (string, []interf
 	return b.preparedStatement, uniqueKeyArgs, nil
 }
 
+// DMLInsertQueryBuilder can build INSERT queries for DML events.
+// It holds the prepared query statement so it doesn't need to be recreated every time.
 type DMLInsertQueryBuilder struct {
 	tableColumns, sharedColumns *ColumnList
 	preparedStatement           string
 }
 
+// NewDMLInsertQueryBuilder creates a new DMLInsertQueryBuilder.
+// It prepares the INSERT query statement.
+// Returns an error if no shared columns are given, the shared columns are not a subset of the table columns,
+// or the prepared statement cannot be built.
 func NewDMLInsertQueryBuilder(databaseName, tableName string, tableColumns, sharedColumns, mappedSharedColumns *ColumnList) (*DMLInsertQueryBuilder, error) {
 	if !sharedColumns.IsSubsetOf(tableColumns) {
 		return nil, fmt.Errorf("shared columns is not a subset of table columns in NewDMLInsertQueryBuilder")
@@ -619,6 +505,9 @@ func NewDMLInsertQueryBuilder(databaseName, tableName string, tableColumns, shar
 	}, nil
 }
 
+// BuildQuery builds the arguments array for a DML event INSERT query.
+// It returns the query string and the shared arguments array.
+// Returns an error if the number of arguments differs from the number of table columns.
 func (b *DMLInsertQueryBuilder) BuildQuery(args []interface{}) (string, []interface{}, error) {
 	if len(args) != b.tableColumns.Len() {
 		return "", nil, fmt.Errorf("args count differs from table column count in BuildDMLInsertQuery")
@@ -632,11 +521,17 @@ func (b *DMLInsertQueryBuilder) BuildQuery(args []interface{}) (string, []interf
 	return b.preparedStatement, sharedArgs, nil
 }
 
+// DMLUpdateQueryBuilder can build UPDATE queries for DML events.
+// It holds the prepared query statement so it doesn't need to be recreated every time.
 type DMLUpdateQueryBuilder struct {
 	tableColumns, sharedColumns, uniqueKeyColumns *ColumnList
 	preparedStatement                             string
 }
 
+// NewDMLUpdateQueryBuilder creates a new DMLUpdateQueryBuilder.
+// It prepares the UPDATE query statement.
+// Returns an error if no shared columns are given, the shared columns are not a subset of the table columns,
+// no unique key columns are given or the prepared statement cannot be built.
 func NewDMLUpdateQueryBuilder(databaseName, tableName string, tableColumns, sharedColumns, mappedSharedColumns, uniqueKeyColumns *ColumnList) (*DMLUpdateQueryBuilder, error) {
 	if !sharedColumns.IsSubsetOf(tableColumns) {
 		return nil, fmt.Errorf("shared columns is not a subset of table columns in NewDMLUpdateQueryBuilder")
@@ -678,6 +573,8 @@ func NewDMLUpdateQueryBuilder(databaseName, tableName string, tableColumns, shar
 	}, nil
 }
 
+// BuildQuery builds the arguments array for a DML event UPDATE query.
+// It returns the query string, the shared arguments array, and the unique key arguments array.
 func (b *DMLUpdateQueryBuilder) BuildQuery(valueArgs, whereArgs []interface{}) (string, []interface{}, []interface{}, error) {
 	// TODO: move this check back to `NewDMLUpdateQueryBuilder()`, needs fix on generated columns.
 	if !b.uniqueKeyColumns.IsSubsetOf(b.sharedColumns) {