Introduce interface for optimistic concurrency check.

Author: mdwhatcott

contracts.go

@@ -6,7 +6,10 @@ import (
 	"errors"
 )
 
-var ErrParameterCountMismatch = errors.New("the number of parameters supplied does not match the statement")
+var (
+	ErrParameterCountMismatch           = errors.New("the number of parameters supplied does not match the statement")
+	ErrOptimisticConcurrencyCheckFailed = errors.New("optimistic concurrency check failed")
+)
 
 type (
 	logger interface {
@@ -48,6 +51,14 @@ type (
 		RowsAffected(uint64)
 	}
 
+	// OptimisticConcurrencyCheck provides an (optional) hook for a type implementing
+	// Script to verify whether the total count of all rows affected matches the returned
+	// value. If not, an error wrapped with ErrOptimisticConcurrencyCheckFailed will be
+	// returned by Handle.Execute().
+	OptimisticConcurrencyCheck interface {
+		ExpectedRowsAffected() uint64
+	}
+
 	// Query represents a SQL statement that is expected to provide rows as a result.
 	// Rows are provided to the Scan method.
 	Query interface {

db.go

@@ -69,6 +69,7 @@ func (this *defaultHandle) Execute(ctx context.Context, scripts ...Script) (err
 		if placeholderCount != len(parameters) {
 			return fmt.Errorf("%w: Expected: %d, received %d", ErrParameterCountMismatch, placeholderCount, len(parameters))
 		}
+		var actualRowsAffectedCount uint64
 		for statement, params := range interleaveParameters(statements, parameters...) {
 			prepared, err := this.prepare(ctx, statement)
 			if err != nil {
@@ -83,10 +84,22 @@ func (this *defaultHandle) Execute(ctx context.Context, scripts ...Script) (err
 			if err != nil {
 				return err
 			}
+			affected, err := result.RowsAffected()
+			if err != nil {
+				return err
+			}
+			rowCount := uint64(max(0, affected))
+			actualRowsAffectedCount += rowCount
 			if rows, ok := script.(RowsAffected); ok {
-				if affected, err := result.RowsAffected(); err == nil {
-					rows.RowsAffected(uint64(affected))
-				}
+				rows.RowsAffected(rowCount)
+			}
+		}
+		if check, ok := script.(OptimisticConcurrencyCheck); ok {
+			expectedRowsAffectedCount := check.ExpectedRowsAffected()
+			if actualRowsAffectedCount != expectedRowsAffectedCount {
+				return fmt.Errorf("%w: expected rows affected: %d (actual: %d)",
+					ErrOptimisticConcurrencyCheckFailed, expectedRowsAffectedCount, actualRowsAffectedCount,
+				)
 			}
 		}
 	}

integration/db_test.go

@@ -46,6 +46,21 @@ func (this *Fixture) Teardown() {
 	this.So(this.db.Close(), better.BeNil)
 }
 
+func (this *Fixture) TestScript() {
+	script := &InsertOne{name: "foo", expectedRowsAffected: 1}
+	err := this.DB.Execute(this.Context(), script)
+	this.So(err, better.BeNil)
+	row := this.db.QueryRowContext(this.Context(), "select name from sqldb_integration_test where name = 'foo';")
+	var foo string
+	err = row.Scan(&foo)
+	this.So(err, better.BeNil)
+	this.So(foo, should.Equal, "foo")
+}
+func (this *Fixture) TestScript_OptimisticConcurrencyCheckFailure() {
+	script := &InsertOne{name: "foo", expectedRowsAffected: 2}
+	err := this.DB.Execute(this.Context(), script)
+	this.So(err, should.WrapError, sqldb.ErrOptimisticConcurrencyCheckFailed)
+}
 func (this *Fixture) TestQuery() {
 	for range 10 { // should transition to prepared statements
 		query := &SelectAll{Result: make(map[int]string)}
@@ -74,6 +89,23 @@ func (this *Fixture) TestQueryQueryRow_NoResult() {
 
 ///////////////////////////////////////////////
 
+type InsertOne struct {
+	expectedRowsAffected uint64
+	name                 string
+}
+
+func (this *InsertOne) Statements() string {
+	return "INSERT INTO sqldb_integration_test (name) VALUES (?);"
+}
+func (this *InsertOne) Parameters() []any {
+	return []any{this.name}
+}
+func (this *InsertOne) ExpectedRowsAffected() uint64 {
+	return this.expectedRowsAffected
+}
+
+///////////////////////////////////////////////
+
 type DDL struct {
 	totalRows uint64
 }