database/sql: document args, add a couple examples
Fixes #3460
R=golang-dev, alex.brainman
CC=golang-dev
https://golang.org/cl/7096046
diff --git a/src/pkg/database/sql/example_test.go b/src/pkg/database/sql/example_test.go
new file mode 100644
index 0000000..d47eed5
--- /dev/null
+++ b/src/pkg/database/sql/example_test.go
@@ -0,0 +1,45 @@
+// Copyright 2013 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package sql_test
+
+import (
+ "database/sql"
+ "fmt"
+ "log"
+)
+
+var db *sql.DB
+
+func ExampleDB_Query() {
+ age := 27
+ rows, err := db.Query("SELECT name FROM users WHERE age=?", age)
+ if err != nil {
+ log.Fatal(err)
+ }
+ for rows.Next() {
+ var name string
+ if err := rows.Scan(&name); err != nil {
+ log.Fatal(err)
+ }
+ fmt.Printf("%s is %d\n", name, age)
+ }
+ if err := rows.Err(); err != nil {
+ log.Fatal(err)
+ }
+}
+
+func ExampleDB_QueryRow() {
+ id := 123
+ var username string
+ err := db.QueryRow("SELECT username FROM users WHERE id=?", id).Scan(&username)
+ switch {
+ case err == sql.ErrNoRows:
+ log.Printf("No user with that ID.")
+ case err != nil:
+ log.Fatal(err)
+ default:
+ fmt.Printf("Username is %s\n", username)
+ }
+}
diff --git a/src/pkg/database/sql/sql.go b/src/pkg/database/sql/sql.go
index 31fc830..29aef78 100644
--- a/src/pkg/database/sql/sql.go
+++ b/src/pkg/database/sql/sql.go
@@ -373,6 +373,7 @@
}
// Query executes a query that returns rows, typically a SELECT.
+// The args are for any placeholder parameters in the query.
func (db *DB) Query(query string, args ...interface{}) (*Rows, error) {
stmt, err := db.Prepare(query)
if err != nil {
