From 5d8a59cb3e1a14abc3fd18f75554f0278c996564 Mon Sep 17 00:00:00 2001
From: Levko Kravets <levko.ne@gmail.com>
Date: Wed, 2 Oct 2024 15:09:41 +0300
Subject: [PATCH] Update docs and examples

Signed-off-by: Levko Kravets <levko.ne@gmail.com>
---
 doc.go                      |  8 ++-
 examples/parameters/main.go | 99 ++++++++++++++++++++++++++-----------
 2 files changed, 77 insertions(+), 30 deletions(-)

diff --git a/doc.go b/doc.go
index 9463d77..2c14fb4 100644
--- a/doc.go
+++ b/doc.go
@@ -188,11 +188,17 @@ Use the driverctx package under driverctx/ctx.go to add callbacks to the query c
 
 Passing parameters to a query is supported when run against servers with version DBR 14.1.
 
+	// Named parameters:
 	p := dbsql.Parameter{Name: "p_bool", Value: true},
-	rows, err1 := db.QueryContext(ctx, `select * from sometable where condition=:p_bool`,dbsql.Parameter{Name: "p_bool", Value: true})
+	rows, err := db.QueryContext(ctx, `select * from sometable where condition=:p_bool`,dbsql.Parameter{Name: "p_bool", Value: true})
+
+	// Positional parameters - both `dbsql.Parameter` and plain values can be used:
+	rows, err := db.Query(`select *, ? from sometable where field=?`,dbsql.Parameter{Value: "123.456"}, "another parameter")
 
 For complex types, you can specify the SQL type using the dbsql.Parameter type field. If this field is set, the value field MUST be set to a string.
 
+Please note that named and positional parameters cannot be used together in the single query.
+
 # Staging Ingestion
 
 The Go driver now supports staging operations. In order to use a staging operation, you first must update the context with a list of folders that you are allowing the driver to access.
diff --git a/examples/parameters/main.go b/examples/parameters/main.go
index 4652bfa..362ede2 100644
--- a/examples/parameters/main.go
+++ b/examples/parameters/main.go
@@ -1,7 +1,6 @@
 package main
 
 import (
-	"context"
 	"database/sql"
 	"fmt"
 	"log"
@@ -12,6 +11,74 @@ import (
 	"github.com/joho/godotenv"
 )
 
+func queryWithNamedParameters(db *sql.DB) {
+	var p_bool bool
+	var p_int int
+	var p_double float64
+	var p_float float32
+	var p_date string
+
+	err := db.QueryRow(`
+		SELECT
+			:p_bool AS col_bool,
+			:p_int AS col_int,
+			:p_double AS col_double,
+			:p_float AS col_float,
+			:p_date AS col_date
+		`,
+		dbsql.Parameter{Name: "p_bool", Value: true},
+		dbsql.Parameter{Name: "p_int", Value: int(1234)},
+		dbsql.Parameter{Name: "p_double", Type: dbsql.SqlDouble, Value: "3.14"},
+		dbsql.Parameter{Name: "p_float", Type: dbsql.SqlFloat, Value: "3.14"},
+		dbsql.Parameter{Name: "p_date", Type: dbsql.SqlDate, Value: "2017-07-23 00:00:00"},
+	).Scan(&p_bool, &p_int, &p_double, &p_float, &p_date)
+
+	if err != nil {
+		if err == sql.ErrNoRows {
+			fmt.Println("not found")
+			return
+		} else {
+			fmt.Printf("err: %v\n", err)
+		}
+	} else {
+		fmt.Println(p_bool, p_int, p_double, p_float, p_date)
+	}
+}
+
+func queryWithPositionalParameters(db *sql.DB) {
+	var p_bool bool
+	var p_int int
+	var p_double float64
+	var p_float float32
+	var p_date string
+
+	err := db.QueryRow(`
+		SELECT
+			:p_bool AS col_bool,
+			:p_int AS col_int,
+			:p_double AS col_double,
+			:p_float AS col_float,
+			:p_date AS col_date
+		`,
+		true,
+		int(1234),
+		"3.14",
+		dbsql.Parameter{Type: dbsql.SqlFloat, Value: "3.14"},
+		dbsql.Parameter{Type: dbsql.SqlDate, Value: "2017-07-23 00:00:00"},
+	).Scan(&p_bool, &p_int, &p_double, &p_float, &p_date)
+
+	if err != nil {
+		if err == sql.ErrNoRows {
+			fmt.Println("not found")
+			return
+		} else {
+			fmt.Printf("err: %v\n", err)
+		}
+	} else {
+		fmt.Println(p_bool, p_int, p_double, p_float, p_date)
+	}
+}
+
 func main() {
 	// Opening a driver typically will not attempt to connect to the database.
 	err := godotenv.Load()
@@ -36,33 +103,7 @@ func main() {
 	}
 	db := sql.OpenDB(connector)
 	defer db.Close()
-	// ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	// defer cancel()
-	ctx := context.Background()
-	var p_bool bool
-	var p_int int
-	var p_double float64
-	var p_float float32
-	var p_date string
-	err1 := db.QueryRowContext(ctx, `SELECT
-	:p_bool AS col_bool,
-	:p_int AS col_int,
-	:p_double AS col_double,
-	:p_float AS col_float,
-	:p_date AS col_date`,
-		dbsql.Parameter{Name: "p_bool", Value: true},
-		dbsql.Parameter{Name: "p_int", Value: int(1234)},
-		dbsql.Parameter{Name: "p_double", Type: dbsql.SqlDouble, Value: "3.14"},
-		dbsql.Parameter{Name: "p_float", Type: dbsql.SqlFloat, Value: "3.14"},
-		dbsql.Parameter{Name: "p_date", Type: dbsql.SqlDate, Value: "2017-07-23 00:00:00"}).Scan(&p_bool, &p_int, &p_double, &p_float, &p_date)
-
-	if err1 != nil {
-		if err1 == sql.ErrNoRows {
-			fmt.Println("not found")
-			return
-		} else {
-			fmt.Printf("err: %v\n", err1)
-		}
-	}
 
+	queryWithNamedParameters(db)
+	queryWithPositionalParameters(db)
 }