From 3c944b9f2a44a6ffad71737ccc78f539acf90211 Mon Sep 17 00:00:00 2001
From: Nathan Bosscher <nate.bosscher@gmail.com>
Date: Mon, 27 Apr 2020 16:26:34 -0400
Subject: [PATCH] Update documentation and examples for some SelectBuilder
 methods and Eq (#242)

---
 expr.go        |   2 -
 expr_test.go   |   6 ++
 select.go      |   3 +
 select_test.go | 166 +++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 175 insertions(+), 2 deletions(-)

diff --git a/expr.go b/expr.go
index ad863c8..4c943e5 100644
--- a/expr.go
+++ b/expr.go
@@ -134,8 +134,6 @@ func (e aliasExpr) ToSql() (sql string, args []interface{}, err error) {
 }
 
 // Eq is syntactic sugar for use with Where/Having/Set methods.
-// Ex:
-//     .Where(Eq{"id": 1})
 type Eq map[string]interface{}
 
 func (eq Eq) toSQL(useNotOpr bool) (sql string, args []interface{}, err error) {
diff --git a/expr_test.go b/expr_test.go
index 792fab0..60d2ae5 100644
--- a/expr_test.go
+++ b/expr_test.go
@@ -456,3 +456,9 @@ func TestExprRecursion(t *testing.T) {
 		assert.Equal(t, expectedArgs, args)
 	}
 }
+
+func ExampleEq() {
+	Select("id", "created", "first_name").From("users").Where(Eq{
+		"company": 20,
+	})
+}
diff --git a/select.go b/select.go
index 5853e82..315fe02 100644
--- a/select.go
+++ b/select.go
@@ -184,6 +184,9 @@ func (b SelectBuilder) PlaceholderFormat(f PlaceholderFormat) SelectBuilder {
 // Runner methods
 
 // RunWith sets a Runner (like database/sql.DB) to be used with e.g. Exec.
+// For most cases runner will be a database connection.
+//
+// Internally we use this to mock out the database connection for testing.
 func (b SelectBuilder) RunWith(runner BaseRunner) SelectBuilder {
 	return setRunWith(b, runner).(SelectBuilder)
 }
diff --git a/select_test.go b/select_test.go
index baa34ce..3718c00 100644
--- a/select_test.go
+++ b/select_test.go
@@ -1,7 +1,11 @@
 package squirrel
 
 import (
+	"database/sql"
+	"fmt"
+	"log"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/assert"
 )
@@ -242,3 +246,165 @@ func TestSelectWithEmptyStringWhereClause(t *testing.T) {
 	assert.NoError(t, err)
 	assert.Equal(t, "SELECT * FROM users", sql)
 }
+
+func ExampleSelect() {
+	Select("id", "created", "first_name").From("users") // ... continue building up your query
+
+	// sql methods in select columns are ok
+	Select("first_name", "count(*)").From("users")
+
+	// column aliases are ok too
+	Select("first_name", "count(*) as n_users").From("users")
+}
+
+func ExampleSelectBuilder_From() {
+	Select("id", "created", "first_name").From("users") // ... continue building up your query
+}
+
+func ExampleSelectBuilder_Where() {
+	companyId := 20
+	Select("id", "created", "first_name").From("users").Where("company = ?", companyId)
+}
+
+func ExampleSelectBuilder_Where_helpers() {
+	companyId := 20
+
+	Select("id", "created", "first_name").From("users").Where(Eq{
+		"company": companyId,
+	})
+
+	Select("id", "created", "first_name").From("users").Where(GtOrEq{
+		"created": time.Now().AddDate(0, 0, -7),
+	})
+
+	Select("id", "created", "first_name").From("users").Where(And{
+		GtOrEq{
+			"created": time.Now().AddDate(0, 0, -7),
+		},
+		Eq{
+			"company": companyId,
+		},
+	})
+}
+
+func ExampleSelectBuilder_Where_multiple() {
+	companyId := 20
+
+	// multiple where's are ok
+
+	Select("id", "created", "first_name").
+		From("users").
+		Where("company = ?", companyId).
+		Where(GtOrEq{
+			"created": time.Now().AddDate(0, 0, -7),
+		})
+}
+
+func ExampleSelectBuilder_FromSelect() {
+	usersByCompany := Select("company", "count(*) as n_users").From("users").GroupBy("company")
+	query := Select("company.id", "company.name", "users_by_company.n_users").
+		FromSelect(usersByCompany, "users_by_company").
+		Join("company on company.id = users_by_company.company")
+
+	sql, _, _ := query.ToSql()
+	fmt.Println(sql)
+
+	// Output: SELECT company.id, company.name, users_by_company.n_users
+	// FROM (
+	//    SELECT company, count(*) as n_users
+	//    FROM users GROUP BY company
+	// ) AS users_by_company
+	// JOIN company on company.id = users_by_company.company
+}
+
+func ExampleSelectBuilder_Columns() {
+	query := Select("id").Columns("created", "first_name").From("users")
+
+	sql, _, _ := query.ToSql()
+	fmt.Println(sql)
+	// Output: SELECT id, created, first_name FROM users
+}
+
+func ExampleSelectBuilder_Columns_order() {
+	// out of order is ok too
+	query := Select("id").Columns("created").From("users").Columns("first_name")
+
+	sql, _, _ := query.ToSql()
+	fmt.Println(sql)
+	// Output: SELECT id, created, first_name FROM users
+}
+
+func ExampleSelectBuilder_Scan() {
+
+	var db *sql.DB
+
+	query := Select("id", "created", "first_name").From("users")
+	query = query.RunWith(db)
+
+	var id int
+	var created time.Time
+	var firstName string
+
+	if err := query.Scan(&id, &created, &firstName); err != nil {
+		log.Println(err)
+		return
+	}
+}
+
+func ExampleSelectBuilder_ScanContext() {
+
+	var db *sql.DB
+
+	query := Select("id", "created", "first_name").From("users")
+	query = query.RunWith(db)
+
+	var id int
+	var created time.Time
+	var firstName string
+
+	if err := query.ScanContext(ctx, &id, &created, &firstName); err != nil {
+		log.Println(err)
+		return
+	}
+}
+
+func ExampleSelectBuilder_RunWith() {
+
+	var db *sql.DB
+
+	query := Select("id", "created", "first_name").From("users").RunWith(db)
+
+	var id int
+	var created time.Time
+	var firstName string
+
+	if err := query.Scan(&id, &created, &firstName); err != nil {
+		log.Println(err)
+		return
+	}
+}
+
+func ExampleSelectBuilder_ToSql() {
+
+	var db *sql.DB
+
+	query := Select("id", "created", "first_name").From("users")
+
+	sql, args, err := query.ToSql()
+	if err != nil {
+		log.Println(err)
+		return
+	}
+
+	rows, err := db.Query(sql, args...)
+	if err != nil {
+		log.Println(err)
+		return
+	}
+
+	defer rows.Close()
+
+	for rows.Next() {
+		// scan...
+	}
+}