Committing to (what is now called) the Handle interface.

No more package-level/static functions.

Author: mdwhatcott

config.go

@@ -1,7 +1,7 @@
 package sqldb
 
 type configuration struct {
-	logger    Logger
+	logger    logger
 	threshold int
 }
 type option func(*configuration)
@@ -24,7 +24,7 @@ func (singleton) defaults(options ...option) []option {
 	}, options...)
 }
 
-func (singleton) Logger(logger Logger) option {
+func (singleton) Logger(logger logger) option {
 	return func(this *configuration) { this.logger = logger }
 }
 

contracts.go

@@ -9,24 +9,25 @@ import (
 var ErrParameterCountMismatch = errors.New("the number of parameters supplied does not match the statement")
 
 type (
-	Logger interface {
+	logger interface {
 		Printf(string, ...any)
 	}
 
-	// Handle is a common subset of methods implemented by *sql.DB and *sql.Tx
-	Handle interface {
+	// Pool is a common subset of methods implemented by *sql.DB and *sql.Tx.
+	// The name is a nod to that fact that a *sql.DB implements a Pool of connections.
+	Pool interface {
 		PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)
 		ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
 		QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
 		QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
 	}
 
-	// DB is a high level approach to common database operations, where each operation implements either
+	// Handle is a high level approach to common database operations, where each operation implements either
 	// the Query or Script interface.
-	DB interface {
+	Handle interface {
 		Execute(ctx context.Context, script Script) error
-		QueryRow(ctx context.Context, query Query) error
-		Query(ctx context.Context, query Query) error
+		Populate(ctx context.Context, query Query) error
+		PopulateRow(ctx context.Context, query Query) error
 	}
 
 	// Script represents SQL statements that aren't expected to provide rows as a result.

db.go

@@ -5,30 +5,32 @@ import (
 	"database/sql"
 	"errors"
 	"fmt"
+	"iter"
+	"runtime/debug"
 	"strings"
 )
 
-type db struct {
-	handle    Handle
-	logger    Logger
+type defaultHandle struct {
+	pool      Pool
+	logger    logger
 	threshold int
 	counts    map[string]int
 	prepared  map[string]*sql.Stmt
 }
 
-func New(handle Handle, options ...option) DB {
+func New(handle Pool, options ...option) Handle {
 	var config configuration
 	Options.apply(options...)(&config)
-	return &db{
-		handle:    handle,
+	return &defaultHandle{
+		pool:      handle,
 		logger:    config.logger,
 		threshold: config.threshold,
 		counts:    make(map[string]int),
 		prepared:  make(map[string]*sql.Stmt),
 	}
 }
 
-func (this *db) prepare(ctx context.Context, rawStatement string) (*sql.Stmt, error) {
+func (this *defaultHandle) prepare(ctx context.Context, rawStatement string) (*sql.Stmt, error) {
 	if this.threshold < 0 {
 		return nil, nil
 	}
@@ -40,16 +42,16 @@ func (this *db) prepare(ctx context.Context, rawStatement string) (*sql.Stmt, er
 	if ok {
 		return statement, nil
 	}
-	statement, err := this.handle.PrepareContext(ctx, rawStatement)
+	statement, err := this.pool.PrepareContext(ctx, rawStatement)
 	if err != nil {
 		return nil, err
 	}
 	this.prepared[rawStatement] = statement
 	return statement, nil
 }
 
-func (this *db) Execute(ctx context.Context, script Script) (err error) {
-	defer func() { err = NormalizeErr(err) }()
+func (this *defaultHandle) Execute(ctx context.Context, script Script) (err error) {
+	defer func() { err = normalizeErr(err) }()
 	statements := script.Statements()
 	parameters := script.Parameters()
 	placeholderCount := strings.Count(statements, "?")
@@ -64,57 +66,89 @@ func (this *db) Execute(ctx context.Context, script Script) (err error) {
 		if prepared != nil {
 			_, err = prepared.ExecContext(ctx, params...)
 		} else {
-			_, err = this.handle.ExecContext(ctx, statement, params...)
+			_, err = this.pool.ExecContext(ctx, statement, params...)
 		}
 		if err != nil {
 			return err
 		}
 	}
 	return nil
 }
-func (this *db) QueryRow(ctx context.Context, query Query) (err error) {
-	defer func() { err = NormalizeErr(err) }()
+func (this *defaultHandle) Populate(ctx context.Context, query Query) (err error) {
+	defer func() { err = normalizeErr(err) }()
 	statement := query.Statement()
 	prepared, err := this.prepare(ctx, statement)
 	if err != nil {
 		return err
 	}
 	parameters := query.Parameters()
-	var row *sql.Row
+	var rows *sql.Rows
 	if prepared != nil {
-		row = prepared.QueryRowContext(ctx, parameters...)
+		rows, err = prepared.QueryContext(ctx, parameters...)
 	} else {
-		row = this.handle.QueryRowContext(ctx, statement, parameters...)
+		rows, err = this.pool.QueryContext(ctx, statement, parameters...)
 	}
-	err = query.Scan(row)
-	if errors.Is(err, sql.ErrNoRows) {
-		return nil
+	if err != nil {
+		return err
 	}
-	return err
+	defer func() { _ = rows.Close() }()
+	for rows.Next() {
+		err = query.Scan(rows)
+		if err != nil {
+			return err
+		}
+	}
+	return rows.Err()
 }
-func (this *db) Query(ctx context.Context, query Query) (err error) {
-	defer func() { err = NormalizeErr(err) }()
+func (this *defaultHandle) PopulateRow(ctx context.Context, query Query) (err error) {
+	defer func() { err = normalizeErr(err) }()
 	statement := query.Statement()
 	prepared, err := this.prepare(ctx, statement)
 	if err != nil {
 		return err
 	}
 	parameters := query.Parameters()
-	var rows *sql.Rows
+	var row *sql.Row
 	if prepared != nil {
-		rows, err = prepared.QueryContext(ctx, parameters...)
+		row = prepared.QueryRowContext(ctx, parameters...)
 	} else {
-		rows, err = this.handle.QueryContext(ctx, statement, parameters...)
+		row = this.pool.QueryRowContext(ctx, statement, parameters...)
 	}
-	if err != nil {
-		return err
+	err = query.Scan(row)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil
 	}
-	defer func() { _ = rows.Close() }()
-	for rows.Next() {
-		err = query.Scan(rows)
-		if err != nil {
-			return err
+	return err
+}
+
+// interleaveParameters splits the statements (on ';') and pairs each one with its corresponding parameters.
+func interleaveParameters(statements string, parameters ...any) iter.Seq2[string, []any] {
+	return func(yield func(string, []any) bool) {
+		index := 0
+		for statement := range strings.SplitSeq(statements, ";") {
+			if len(strings.TrimSpace(statement)) == 0 {
+				continue
+			}
+			statement += ";" // terminate the statement
+			indexOffset := strings.Count(statement, "?")
+			params := parameters[index : index+indexOffset]
+			index += indexOffset
+			if !yield(statement, params) {
+				return
+			}
 		}
 	}
-	return rows.Err()
+}
+
+// normalizeErr attaches a stack trace to non-nil errors and also normalizes errors that are
+// semantically equal to context.Canceled. At present we are unaware whether this is still a
+// commonly encountered scenario.
+func normalizeErr(err error) error {
+	if err == nil {
+		return nil
+	}
+	if strings.Contains(err.Error(), "operation was canceled") {
+		return fmt.Errorf("%w: %w", context.Canceled, err)
+	}
+	return fmt.Errorf("%w\nStack Trace:\n%s", err, string(debug.Stack()))
 }

integration/db_test.go

@@ -9,6 +9,8 @@ import (
 	"github.com/smarty/gunit/v2/better"
 	"github.com/smarty/gunit/v2/should"
 	"github.com/smarty/sqldb/v3"
+
+	_ "github.com/mattn/go-sqlite3"
 )
 
 func TestFixture(t *testing.T) {
@@ -19,7 +21,7 @@ type Fixture struct {
 	*gunit.Fixture
 	db *sql.DB
 	tx *sql.Tx
-	DB sqldb.DB
+	DB sqldb.Handle
 }
 
 func (this *Fixture) Setup() {
@@ -45,7 +47,7 @@ func (this *Fixture) Teardown() {
 func (this *Fixture) TestQuery() {
 	for range 10 { // should transition to prepared statements
 		query := &SelectAll{Result: make(map[int]string)}
-		err := this.DB.Query(this.Context(), query)
+		err := this.DB.Populate(this.Context(), query)
 		this.So(err, better.BeNil)
 		this.So(query.Result, should.Equal, map[int]string{
 			1: "a",
@@ -57,13 +59,13 @@ func (this *Fixture) TestQuery() {
 }
 func (this *Fixture) TestQueryRow() {
 	query := &SelectRow{id: 1}
-	err := this.DB.QueryRow(this.Context(), query)
+	err := this.DB.PopulateRow(this.Context(), query)
 	this.So(err, better.BeNil)
 	this.So(query.value, should.Equal, "a")
 }
 func (this *Fixture) TestQueryQueryRow_NoResult() {
 	query := &SelectRow{id: 5}
-	err := this.DB.QueryRow(this.Context(), query)
+	err := this.DB.PopulateRow(this.Context(), query)
 	this.So(err, better.BeNil)
 	this.So(query.value, should.BeEmpty)
 }
@@ -73,7 +75,18 @@ func (this *Fixture) TestQueryQueryRow_NoResult() {
 type DDL struct{}
 
 func (this *DDL) Statements() string {
-	return CreateInsert
+	return `
+		DROP TABLE IF EXISTS sqldb_integration_test;
+		
+		CREATE TABLE sqldb_integration_test (
+			id   INTEGER PRIMARY KEY AUTOINCREMENT,
+			name TEXT    NOT NULL
+		);
+		
+		INSERT INTO sqldb_integration_test (name) VALUES (?);
+		INSERT INTO sqldb_integration_test (name) VALUES (?);
+		INSERT INTO sqldb_integration_test (name) VALUES (?);
+		INSERT INTO sqldb_integration_test (name) VALUES (?);`
 }
 
 func (this *DDL) Parameters() []any {
@@ -92,7 +105,9 @@ type SelectAll struct {
 }
 
 func (this *SelectAll) Statement() string {
-	return QuerySelectAll
+	return `
+		SELECT id, name
+		  FROM sqldb_integration_test;`
 }
 
 func (this *SelectAll) Parameters() []any {
@@ -114,7 +129,7 @@ type SelectRow struct {
 }
 
 func (this *SelectRow) Statement() string {
-	return "SELECT name FROM sqldb_integration_test WHERE id = ?;"
+	return `SELECT name FROM sqldb_integration_test WHERE id = ?;`
 }
 func (this *SelectRow) Parameters() []any {
 	return []any{this.id}