Add generics and All functions (#10)

Author: mrj0

.github/workflows/ci.yaml

@@ -13,7 +13,19 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go-version: [1.22.12, 1.23.7, 1.24.1]
+        go-version: [1.23.8, 1.24.2]
+    services:
+      postgres:
+        image: postgres:17.4
+        ports:
+          - 5444:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        env:
+          POSTGRES_PASSWORD: password
     steps:
       - uses: actions/checkout@v3
       - name: Set up Go
@@ -34,6 +46,7 @@ jobs:
           mkdir -p /tmp/test-reports
           # gotestsum hash is version version v1.12.1
           go run gotest.tools/gotestsum@3f7ff0ec4aeb6f95f5d67c998b71f272aa8a8b41 --junitfile /tmp/test-reports/unit-tests.xml
+          make test-examples
       - uses: actions/upload-artifact@v4
         name: Upload test results
         with:
@@ -46,14 +59,14 @@ jobs:
           chart: true
           amend: true
         if: |
-          matrix.go-version == '1.23.7'
+          matrix.go-version == '1.24.2'
         continue-on-error: true
 
   test-race:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go-version: [1.22.12, 1.23.7, 1.24.1]
+        go-version: [1.23.8, 1.24.2]
     steps:
       - uses: actions/checkout@v3
       - name: Set up Go
@@ -76,7 +89,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go-version: [1.22.12, 1.23.7, 1.24.1]
+        go-version: [1.23.8, 1.24.2]
     steps:
       - uses: actions/checkout@v3
       - name: Set up Go
@@ -103,7 +116,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go-version: [1.22.12, 1.23.7, 1.24.1]
+        go-version: [1.23.8, 1.24.2]
     steps:
       - uses: actions/checkout@v3
       - name: Set up Go

.gitignore

@@ -1,3 +1,5 @@
+examples/**/main
+
 # Compiled Object files, Static and Dynamic libs (Shared Objects)
 *.o
 *.a

Makefile

@@ -28,3 +28,11 @@ test-race:
 update-dependencies:
 	go get -u -t -v ./...
 	go mod tidy
+
+test-examples:
+	for dir in $$(find examples -type d); do \
+		if [ -f $$dir/main.go ]; then \
+			echo "Building and running $$dir/main.go"; \
+			go build -o $$dir/main $$dir/main.go && $$dir/main; \
+		fi \
+	done

README.md

@@ -19,13 +19,27 @@ Major additional concepts are:
 * Marshal rows into structs (with embedded struct support), maps, and slices
 * Named parameter support including prepared statements
 * `Get` and `Select` to go quickly from query to struct/slice
+* Bulk insert SQL builder
+* Generic functions `One` and `List`
+* Range function `AllRows`, or for prepared statements use `All`
 
 In addition to the [godoc API documentation](http://godoc.org/github.com/jmoiron/sqlx),
 there is also some [user documentation](http://jmoiron.github.io/sqlx/) that
 explains how to use `database/sql` along with sqlx.
 
 ## Recent Changes
 
+* Set Go version to 1.23.
+
+* Added `AllRows` package function and `All` on statement types to
+  range over rows and automatically close the result set.
+
+* Added functions `One` and `List` for querying with
+  generics. Modifications to types Stmt and NamedStmt to support
+  generics may cause some small compatibility changes that should be
+  quick to resolve with a search and replace. Both are now type
+  aliases to attempt to minimize the impact of this change.
+
 * fix for sql in-list parsing that will properly ignore question marks
   in comments and strings. This frequently caused a confusing error
   ("number of bindVars exceeds arguments").
@@ -73,170 +87,64 @@ new changes.  Compatibility beyond that is not guaranteed.
 Versioning is done with Go modules.  Breaking changes (eg. removing deprecated API)
 will get major version number bumps.
 
-## install
+## Install
 
     go get github.com/vinovest/sqlx
 
-## issues
-
-Row headers can be ambiguous (`SELECT 1 AS a, 2 AS a`), and the result of
-`Columns()` does not fully qualify column names in queries like:
-
-```sql
-SELECT a.id, a.name, b.id, b.name FROM foos AS a JOIN foos AS b ON a.parent = b.id;
-```
-
-making a struct or map destination ambiguous.  Use `AS` in your queries
-to give columns distinct names, `rows.Scan` to scan them manually, or 
-`SliceScan` to get a slice of results.
+## Usage
 
-## usage
+There are several standalone examples in the examples directory that demonstrate various features of sqlx.
 
-Below is an example which shows some common use cases for sqlx.  Check 
-[sqlx_test.go](https://github.com/vinovest/sqlx/blob/master/sqlx_test.go) for more
-usage.
+* [Generics](./examples/generics/main.go) - query with generics
+* [Bulk inserts](./examples/bulk/main.go) - efficient bulk inserts
+* [Named queries](./examples/named/main.go) - named parameter queries
+* [SQL in-lists](./examples/inlist/main.go) - using `In` to generate SQL `IN` clauses
+* [Prepared statements](./examples/preparedstatements/main.go) - prepared statements offer better performance
 
+The simplified form of querying using sqlx looks like the below. Given a struct `Person`, querying all of the rows
+in the `person` table is as simple as:
 
 ```go
 package main
 
 import (
-    "database/sql"
     "fmt"
-    "log"
 
     _ "github.com/lib/pq"
     "github.com/vinovest/sqlx"
 )
 
-var schema = `
-CREATE TABLE person (
-    first_name text,
-    last_name text,
-    email text
-);
-
-CREATE TABLE place (
-    country text,
-    city text NULL,
-    telcode integer
-)`
-
 type Person struct {
     FirstName string `db:"first_name"`
     LastName  string `db:"last_name"`
     Email     string
 }
 
-type Place struct {
-    Country string
-    City    sql.NullString
-    TelCode int
-}
-
 func main() {
-    // this Pings the database trying to connect
-    // use sqlx.Open() for sql.Open() semantics
-    db, err := sqlx.Connect("postgres", "user=foo dbname=bar sslmode=disable")
-    if err != nil {
-        log.Fatalln(err)
-    }
+    db, _ := sqlx.Connect("postgres", "user=foo dbname=bar sslmode=disable")
+    people, _ := sqlx.List[Person](db, "SELECT * FROM person")
+    fmt.Printf("People %#v\n", people)
 
-    // exec the schema or fail; multi-statement Exec behavior varies between
-    // database drivers;  pq will exec them all, sqlite3 won't, ymmv
-    db.MustExec(schema)
-    
-    tx := db.MustBegin()
-    tx.MustExec("INSERT INTO person (first_name, last_name, email) VALUES ($1, $2, $3)", "Jason", "Moiron", "jmoiron@jmoiron.net")
-    tx.MustExec("INSERT INTO person (first_name, last_name, email) VALUES ($1, $2, $3)", "John", "Doe", "johndoeDNE@gmail.net")
-    tx.MustExec("INSERT INTO place (country, city, telcode) VALUES ($1, $2, $3)", "United States", "New York", "1")
-    tx.MustExec("INSERT INTO place (country, telcode) VALUES ($1, $2)", "Hong Kong", "852")
-    tx.MustExec("INSERT INTO place (country, telcode) VALUES ($1, $2)", "Singapore", "65")
-    // Named queries can use structs, so if you have an existing struct (i.e. person := &Person{}) that you have populated, you can pass it in as &person
-    tx.NamedExec("INSERT INTO person (first_name, last_name, email) VALUES (:first_name, :last_name, :email)", &Person{"Jane", "Citizen", "jane.citzen@example.com"})
-    tx.Commit()
-
-    // Query the database, storing results in a []Person (wrapped in []interface{})
-    people := []Person{}
-    db.Select(&people, "SELECT * FROM person ORDER BY first_name ASC")
-    jason, john := people[0], people[1]
-
-    fmt.Printf("%#v\n%#v", jason, john)
-    // Person{FirstName:"Jason", LastName:"Moiron", Email:"jmoiron@jmoiron.net"}
-    // Person{FirstName:"John", LastName:"Doe", Email:"johndoeDNE@gmail.net"}
-
-    // You can also get a single result, a la QueryRow
-    jason = Person{}
-    err = db.Get(&jason, "SELECT * FROM person WHERE first_name=$1", "Jason")
-    fmt.Printf("%#v\n", jason)
-    // Person{FirstName:"Jason", LastName:"Moiron", Email:"jmoiron@jmoiron.net"}
-
-    // if you have null fields and use SELECT *, you must use sql.Null* in your struct
-    places := []Place{}
-    err = db.Select(&places, "SELECT * FROM place ORDER BY telcode ASC")
-    if err != nil {
-        fmt.Println(err)
-        return
-    }
-    usa, singsing, honkers := places[0], places[1], places[2]
-    
-    fmt.Printf("%#v\n%#v\n%#v\n", usa, singsing, honkers)
-    // Place{Country:"United States", City:sql.NullString{String:"New York", Valid:true}, TelCode:1}
-    // Place{Country:"Singapore", City:sql.NullString{String:"", Valid:false}, TelCode:65}
-    // Place{Country:"Hong Kong", City:sql.NullString{String:"", Valid:false}, TelCode:852}
-
-    // Loop through rows using only one struct
-    place := Place{}
-    rows, err := db.Queryx("SELECT * FROM place")
-    for rows.Next() {
-        err := rows.StructScan(&place)
+    // alternatively, range over rows
+    rows, _ := db.Queryx("select * from person")
+    for person, err := range sqlx.AllRows[Person](rows) {
         if err != nil {
-            log.Fatalln(err)
-        } 
-        fmt.Printf("%#v\n", place)
-    }
-    // Place{Country:"United States", City:sql.NullString{String:"New York", Valid:true}, TelCode:1}
-    // Place{Country:"Hong Kong", City:sql.NullString{String:"", Valid:false}, TelCode:852}
-    // Place{Country:"Singapore", City:sql.NullString{String:"", Valid:false}, TelCode:65}
-
-    // Named queries, using `:name` as the bindvar.  Automatic bindvar support
-    // which takes into account the dbtype based on the driverName on sqlx.Open/Connect
-    _, err = db.NamedExec(`INSERT INTO person (first_name,last_name,email) VALUES (:first,:last,:email)`, 
-        map[string]interface{}{
-            "first": "Bin",
-            "last": "Smuth",
-            "email": "bensmith@allblacks.nz",
-    })
-
-    // Selects Mr. Smith from the database
-    rows, err = db.NamedQuery(`SELECT * FROM person WHERE first_name=:fn`, map[string]interface{}{"fn": "Bin"})
-
-    // Named queries can also use structs.  Their bind names follow the same rules
-    // as the name -> db mapping, so struct fields are lowercased and the `db` tag
-    // is taken into consideration.
-    rows, err = db.NamedQuery(`SELECT * FROM person WHERE first_name=:first_name`, jason)
-    
-    
-    // batch insert
-    
-    // batch insert with structs
-    personStructs := []Person{
-        {FirstName: "Ardie", LastName: "Savea", Email: "asavea@ab.co.nz"},
-        {FirstName: "Sonny Bill", LastName: "Williams", Email: "sbw@ab.co.nz"},
-        {FirstName: "Ngani", LastName: "Laumape", Email: "nlaumape@ab.co.nz"},
+            panic(err)
+        }
+        fmt.Printf("%#v\n", person)
     }
+}
+```
 
-    _, err = db.NamedExec(`INSERT INTO person (first_name, last_name, email)
-        VALUES (:first_name, :last_name, :email)`, personStructs)
+## Issues
 
-    // batch insert with maps
-    personMaps := []map[string]interface{}{
-        {"first_name": "Ardie", "last_name": "Savea", "email": "asavea@ab.co.nz"},
-        {"first_name": "Sonny Bill", "last_name": "Williams", "email": "sbw@ab.co.nz"},
-        {"first_name": "Ngani", "last_name": "Laumape", "email": "nlaumape@ab.co.nz"},
-    }
+Row headers can be ambiguous (`SELECT 1 AS a, 2 AS a`), and the result of
+`Columns()` does not fully qualify column names in queries like:
 
-    _, err = db.NamedExec(`INSERT INTO person (first_name, last_name, email)
-        VALUES (:first_name, :last_name, :email)`, personMaps)
-}
+```sql
+SELECT a.id, a.name, b.id, b.name FROM foos AS a JOIN foos AS b ON a.parent = b.id;
 ```
+
+making a struct or map destination ambiguous.  Use `AS` in your queries
+to give columns distinct names, `rows.Scan` to scan them manually, or
+`SliceScan` to get a slice of results.

bind.go

@@ -1,7 +1,6 @@
 package sqlx
 
 import (
-	"bytes"
 	"database/sql/driver"
 	"errors"
 	"reflect"
@@ -106,31 +105,6 @@ func Rebind(bindType int, query string) string {
 	return string(rqb)
 }
 
-// Experimental implementation of Rebind which uses a bytes.Buffer.  The code is
-// much simpler and should be more resistant to odd unicode, but it is twice as
-// slow.  Kept here for benchmarking purposes and to possibly replace Rebind if
-// problems arise with its somewhat naive handling of unicode.
-func rebindBuff(bindType int, query string) string {
-	if bindType != DOLLAR {
-		return query
-	}
-
-	b := make([]byte, 0, len(query))
-	rqb := bytes.NewBuffer(b)
-	j := 1
-	for _, r := range query {
-		if r == '?' {
-			rqb.WriteRune('$')
-			rqb.WriteString(strconv.Itoa(j))
-			j++
-		} else {
-			rqb.WriteRune(r)
-		}
-	}
-
-	return rqb.String()
-}
-
 func asSliceForIn(i interface{}) (v reflect.Value, ok bool) {
 	if i == nil {
 		return reflect.Value{}, false

examples/bulk/go.mod

@@ -0,0 +1,12 @@
+module bulk
+
+go 1.23
+
+require (
+	github.com/lib/pq v1.10.9
+	github.com/vinovest/sqlx v1.5.2
+)
+
+require github.com/muir/sqltoken v0.1.0 // indirect
+
+replace github.com/vinovest/sqlx => ../../

examples/bulk/go.sum

@@ -0,0 +1,18 @@
+filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
+filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-sql-driver/mysql v1.9.0 h1:Y0zIbQXhQKmQgTp44Y1dp3wTXcn804QoTptLZT1vtvo=
+github.com/go-sql-driver/mysql v1.9.0/go.mod h1:pDetrLJeA3oMujJuvXc8RJoasr589B6A9fwzD3QMrqw=
+github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
+github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
+github.com/mattn/go-sqlite3 v1.14.16 h1:yOQRA0RpS5PFz/oikGwBEqvAWhWg5ufRz4ETLjwpU1Y=
+github.com/mattn/go-sqlite3 v1.14.16/go.mod h1:2eHXhiwb8IkHr+BDWZGa96P6+rkvnG63S2DGjv9HUNg=
+github.com/muir/sqltoken v0.1.0 h1:edosEGsOClOZNfgGQNQSgxR9O6LiVefm2rDRqp2InuI=
+github.com/muir/sqltoken v0.1.0/go.mod h1:lgOIORnKekMsuc/ZwdPOfwz/PtWLPCke43cEbT3uDuY=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=