月度归档： 2023 年 4 月

本文翻译自《Go database/sql tutorial》。

在Go中使用SQL或类SQL的数据库的惯用方法是通过database/sql包。它为面向行的数据库提供了一个轻量级的接口。这个网站是关于如何使用它的最常见的方面的参考。

为什么需要这样做？这个包的文档告诉了你所有的功能，但并没有告诉你如何使用这个它。我们中的许多人发现自己希望获得一份入门手册，即讲故事，而不是列事实。欢迎你来做贡献：请在此处发送拉取请求。

概述

要在Go中访问数据库，你需要使用sql.DB。你可以使用sql.DB类型来创建语句和事务、执行查询和获取结果。

你应该知道的第一件事是sql.DB不是一个数据库连接。它也没有映射到任何特定数据库软件的“数据库”或“模式”这些概念。它是数据库的接口和数据库本身的抽象，抽象的内部可以多种多样：数据库可以是本地文件，可以通过网络连接访问，也可以存在于内存和进程中。

sql.DB在幕后为你执行一些重要任务：

• 它通过数据库驱动程序打开和关闭与实际底层数据库的连接。
• 它根据需要管理一个连接池，其中可能包括前面提到的各种内容。

sql.DB抽象旨在避免你担心如何管理对底层数据存储的并发访问。当你使用连接执行任务时，它会被标记为正在使用，然后在不再使用时返回到可用连接池。这样做的一个后果是，如果无法将连接释放回到连接池，可能会导致sql.DB打开大量连接，从而可能耗尽资源（连接太多、打开的文件句柄太多、缺少可用的网络端口等）。我们稍后将对此进行更多讨论。

在创建了一个sql.DB之后，你可以使用它来查询它所代表的数据库，以及创建语句和事务。

导入一个数据库驱动

要使用database/sql，你需要该包本身，和要使用的特定数据库的驱动程序。

你通常不应该直接使用特定数据库的驱动程序包，尽管一些驱动程序鼓励你这样做。（在我们看来，这通常是个坏主意。）相反，如果可能，你的代码应该只引用database/sql中定义的类型。这有助于避免让你的代码依赖于特定的驱动程序，当需要更改底层的数据库驱动程序（以及你正在访问的数据库）时，你就可以通过最少的代码来更改。你应该使用Go语言的惯用法，而不是驱动程序作者可能提供的特定的惯用法。

在本文档中，我们将使用@julienschmidt和@arnehormann开发的优秀的MySQL驱动程序作为示例。 将以下内容添加到Go源代码文件的顶部：

import (
	"database/sql"
	_ "github.com/go-sql-driver/mysql"
)

请注意，我们正在匿名加载这个驱动程序，将其包的别名设置为_，因此我们的代码看不到任何它的导出名称。在底层，该驱动程序将自己注册为对database/sql包可用，通常除了运行包的init函数之外没有其他任何事情发生。

现在你已准备好了访问数据库。

访问数据库

现在你已经加载了数据库驱动程序包，你已准备好创建一个数据库对象，一个sql.DB。

要创建sql.DB，你可以使用sql.Open()，返回一个*sql.DB：

func main() {
	db, err := sql.Open("mysql",
		"user:password@tcp(127.0.0.1:3306)/hello")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()
}

在以上示例中，我们说明了几件事：

1 sql.Open函数的第一个参数是驱动程序的名称。这是驱动程序用来向database/sql注册自己的字符串，通常与包名相同以避免混淆。例如，上例中是github.com/go-sql-driver/mysql包的mysql。一些驱动程序不遵循这一约定使用对应的数据库名称，例如github.com/mattn/go-sqlite3包的sqlite3和github.com/lib/pq包的postgres。

2 第二个参数是特定于驱动程序的数据源名称字符串（译者注：数据库连接字符串），它告诉驱动程序如何访问底层的数据存储。在此示例中，我们连接到本地的MySQL服务器中的“hello”数据库实例。

3 你应该（几乎）总是检查和处理从所有database/sql操作返回的错误。稍后我们将讨论一些特殊情况，在这些情况下这样做没有意义。

4 如果sql.DB的生命周期不应超出调用它函数的范围，则defer db.Close()是惯用的做法。

也许与直觉相反，sql.Open()并不建立任何与数据库的连接，也不验证驱动程序连接参数。相反，它只是为以后的使用做好准备，在程序确实需要用到与底层数据存储的实际连接时，才真正建立第一个连接。如果你想立即检查数据库是否可用和可访问（例如，检查你是否可以建立网络连接并登录），请使用db.Ping()来执行此操作，并记住检查是否返回了一个错误：

err = db.Ping()
if err != nil {
	// 错误处理
}

尽管在完成数据库时Close()是惯用方法，但sql.DB对象被设计为长寿命的。不要经常Open()和Close()数据库。相反，为你需要访问的每个不同的数据存储（数据库）创建一个sql.DB对象，并保留它，直到程序完成对该数据存储的访问。根据需要传递，或者以某种方式在全局范围内提供，保持打开状态。不要从一个短暂的函数中Open()和Close()。相反，将sql.DB作为参数传递到那个短暂的函数中。

如果你不将sql.DB视为一个长时间存活的对象，你可能会遇到一些问题，例如连接的重用和共享不足、可用网络资源不足，或者由于许多TCP连接仍处于TIME_WAIT状态而出现偶发故障。这些问题表明你没有按照设计使用database/sql。

现在是时候使用sql.DB对象了。

获取结果集

有几个惯用操作可以从数据存储中检索结果：

1 执行返回多行数据的查询。

2 准备一个要重复使用的SQL预处理语句，多次执行，然后销毁它。

3 以一次性的方式执行SQL语句，而无需为重复使用做准备。

4 执行一个返回单行数据的查询。对于这种特殊情况，有一种获取数据的快捷的方式。

Go的database/sql包里的函数名称非常重要。如果函数名中包含Query，那么它被设计为向数据库询问问题，并返回一组行数据或空。不返回行数据的语句不应该使用Query函数；他们应该使用Exec函数。

从数据库中获取数据

让我们看一个如何查询数据库并处理返回结果的示例。我们将在users表中查询id为1的用户，并打印出该用户的id和name。我们将把结果分配给变量，一次一行，用rows.Scan()函数。

var (
	id int
	name string
)
rows, err := db.Query("select id, name from users where id = ?", 1)
if err != nil {
	log.Fatal(err)
}
defer rows.Close()
for rows.Next() {
	err := rows.Scan(&id, &name)
	if err != nil {
		log.Fatal(err)
	}
	log.Println(id, name)
}
err = rows.Err()
if err != nil {
	log.Fatal(err)
}

以下是上面代码中发生的情况：

1 我们使用db.Query()将查询发送到数据库。我们像往常一样检查错误。

2 我们推迟执行rows.Close()。这非常重要。

3 我们用rows.Next()对行进行迭代。

4 我们使用rows.Scan()将每一行中的列值读取到对于的变量里。

5 在完成对行的迭代之后，我们检查这一过程中是否有错误发生。

这几乎是Go语言中唯一的方式。例如，你不能将一行数据读取到一个map里。这是因为所有东西都是强类型的。你需要创建正确类型的变量，并将指针传递给rows.Scan()，如上所示。

其中有几个部分很容易出错，并可能会产生不良后果：

• 你应该始终在for rows.Next()循环的末尾检查是否有错误发生。如果在循环过程中出现错误，你需要了解它。不要只假设循环会正常迭代完毕所有行。

• 其次，只要有一个打开的结果集（由rows表示），底层连接就很忙，不能用于任何其他查询。这意味着它在连接池中不可用。如果你使用rows.Next()遍历所有行，最终你将读取完最后一行，rows.Next()将遇到内部EOF错误并为你调用rows.Close()。但是，如果出于某种原因退出了那个循环——提前返回，等等——那么这些rows就不会关闭，底层数据库连接仍然是打开的。（不过，如果rows.Next()由于错误而返回false，它将会自动关闭）。记得defer rows.Close()，否则很容易耗尽资源。

• 如果rows已经关闭，那么rows.Close()已是一个无害的空操作(no-op)，所以你可以多次调用它。然而，请注意，我们首先检查是否有错误发生，如果没有错误发生才调用rows.Close()，以避免运行时panic。

• 你应该始终defer rows.Close()，即使你也在循环结束时显式调用rows.Close()，这也不是一个坏主意。

• 不要在循环体中defer。defer语句要等到函数退出后才能执行，所以长时间运行的函数不应该使用它。如果这样做，你会慢慢耗尽内存。如果在循环中重复查询和使用结果集，那么在处理完每个结果后，应该显式调用rows.Close()，而不要使用defer。

Scan()是怎么工作的

当你迭代行并将其中的列值扫描到目标变量中时，Go会在后台为你执行数据类型转换工作。它基于目标变量的类型。意识到这一点可以清理代码并避免重复工作。

例如，假设你从包含字符串列值的表中选择一些行，例如包含VARCHAR(45)的列或类似的行。然而，你碰巧知道，这个字符串列总是包含数字。如果将指针传递给字符串，Go将把字节复制到字符串中。现在，你可以使用strconv.ParseInt()或类似的方法将值转换为数字。你必须检查SQL操作中是否有错误发生，以及解析整数时是否有错误发生。这既混乱又乏味。

或者，你可以直接向Scan()传递一个指向整数的指针。Go将检测到这一点，并为你调用strconv.ParseInt()。如果转换中出现错误，调用Scan()会返回错误。你的代码现在更整洁、更小了。这是我们建议使用database/sql包的方式。

准备语句（预处理语句）

通常，你应该始终准备要多次使用的查询语句。准备查询语句的结果是一个准备好的语句（译者注：准备语句，预处理语句），它可以为语句的参数提供占位符（也称为绑定值）。由于所有常见的原因（例如，避免SQL注入攻击），这比连接SQL语句加参数值字符串的做法要好得多。

在MySQL中，参数占位符是?，在PostgreSQL中是$N，其中N是一个数字。SQLite接受其中任何一种。在Oracle中，占位符以冒号开头并命名，如:param1。我们将使用?因为我们使用MySQL作为示例。

stmt, err := db.Prepare("select id, name from users where id = ?")
if err != nil {
	log.Fatal(err)
}
defer stmt.Close()
rows, err := stmt.Query(1)
if err != nil {
	log.Fatal(err)
}
defer rows.Close()
for rows.Next() {
	// ...
}
if err = rows.Err(); err != nil {
	log.Fatal(err)
}

在底层，db.Query()实际上准备、执行和关闭一个准备好的语句。这会对数据库进行三次往返访问。如果你不小心，你的应用程序进行的数据库交互次数可能会增加三倍！某些驱动程序可以在特定情况下避免这种情况，但并非所有驱动程序都这样做。有关详细信息，请参阅准备好的语句。

查询单行

如果查询最多返回一行，则可以使用以下快捷的方式绕过一些冗长的样板代码：

var name string
err = db.QueryRow("select name from users where id = ?", 1).Scan(&name)
if err != nil {
	log.Fatal(err)
}
fmt.Println(name)

查询中的错误会延迟到调用Scan()，然后返回。准备好的语句也可以调用QueryRow()：

stmt, err := db.Prepare("select name from users where id = ?")
if err != nil {
	log.Fatal(err)
}
defer stmt.Close()
var name string
err = stmt.QueryRow(1).Scan(&name)
if err != nil {
	log.Fatal(err)
}
fmt.Println(name)

修改数据和使用事务

现在我们已经准备好了解如何修改数据和处理事务。如果你习惯于使用“语句(statement)”对象来获取行和更新数据的编程语言，那么Go语言的做法与它们有点区别，这种区别看起来是人为的，但有一个重要的原因。

修改数据的语句

使用Exec()，最好与准备语句（预处理语句）一起使用，以完成INSERT、UPDATE、DELETE或其他不返回行数据的语句。以下示例显示如何插入行并检查有关操作的元数据：

stmt, err := db.Prepare("INSERT INTO users(name) VALUES(?)")
if err != nil {
	log.Fatal(err)
}
res, err := stmt.Exec("Dolly")
if err != nil {
	log.Fatal(err)
}
lastId, err := res.LastInsertId()
if err != nil {
	log.Fatal(err)
}
rowCnt, err := res.RowsAffected()
if err != nil {
	log.Fatal(err)
}
log.Printf("ID = %d, affected = %d\n", lastId, rowCnt)

执行Exec()会返回一个sql.Result，它可以访问语句的元数据：最后插入行的ID和受影响的行数。

如果你不在乎执行结果怎么办？如果你只想执行一条语句并检查是否有任何错误发生，但忽略执行的结果怎么办？下面两行代码会做同样的事情吗？

_, err := db.Exec("DELETE FROM users")  // 可行
_, err := db.Query("DELETE FROM users") // 不可行

答案是不一样。它们不做同样的事情，你不应该像这样使用Query()。Query()将返回一个sql.Rows，它保留数据库连接直到sql.Rows关闭。由于可能有未读数据（例如多行数据的情况），因此无法重用连接。在上面的示例中，连接将永远不会被再次释放。垃圾收集器最终会为你关闭底层的net.Conn，但这可能需要很长时间之后。此外，database/sql包一直在连接池中跟踪这条连接，希望你在某个时候释放它，以便可以再次使用该连接。因此，这种反模式可能会耗尽资源（例如，太多连接）。

使用事务

在Go中，事务本质上是一个保留到数据库连接的对象。它允许执行到目前为止我们见过的所有操作，并且保证它们将在同一条连接上执行。

通过调用db.begin()开始事务，并对生成的Tx变量使用Commit()或Rollback()方法结束事务。在底层，Tx从连接池中获取一条连接，并将其保留为仅用于该事务。sql.DB的方法Tx也拥有对应的方法，例如Query()等等。

在事务中创建的准备语句专门绑定到该事务。有关详细信息，请参阅准备好的语句。

你不应该在代码中混合使用事务相关的函数（例如Begin()和Commit()）和SQL语句（例如Begin和Commit）。可能会出现以下不好的结果：

• Tx对象保持打开的状态，保留连接池中的一条连接而不返回。
• 数据库的状态可能与用来表示它的Go变量的状态不同步。
• 你可能会认为你在事务内部的一个连接上执行查询，而实际上Go已经无形地为你创建了几个连接，而有些语句不属于事务的一部分。

在事务内部工作时，应注意不要调用db变量。应该使用db.Begin()创建的Tx变量进行所有调用。db不在事务中，只有Tx对象在事务中。如果你调用db.Exec()或类似的函数，这些调用将发生在该事务范围之外的其他连接上，不在该事务中执行。

如果你需要执行修改连接状态的多个语句，即使你本身不想使用事务，也需要Tx。例如：

• 创建仅对一个连接可见的临时表。
• 设置数据库变量，例如MySQL的SET @var := somevalue语法。
• 更改数据库的连接选项，例如字符集或超时时间。

如果你需要做这些事情中的任何一件，你需要将你的活动绑定到一个连接上，而在Go中做到这一点的唯一方法就是使用Tx。

使用准备好的语句

准备好的语句具有Go中所有常见的好处：安全、高效、方便。但它们的实现方式与你习惯的可能有点不同，尤其是在如何与database/sql包的一些内部交互方面。

准备好的语句和数据库连接

在数据库级别，准备好的语句被绑定到单个数据库连接。典型的流程是，客户端向服务器发送一个带有参数占位符的SQL语句进行准备，服务器生成该语句的一个ID进行响应，然后客户端通过发送其ID和参数来执行该语句。

然而，在Go中，数据库连接不会直接暴露给database/sql包的用户。你不是在一条数据库连接上准备SQL语句。你可以在一个DB或Tx的实例上准备它。database/sql包有一些方便的行为，比如自动重试。由于这些原因，存在于驱动程序级别的准备好的语句和数据库连接之间的潜在关联，对代码来说是透明的。

以下是它的工作原理：

1 准备语句时，它是在连接池中的某条连接上准备的。

2 Stmt实例会记住使用了哪条连接。

3 当你执行Stmt时，它会尝试使用该连接。如果该连接因为关闭或忙于做其他事情而不可用，它将从连接池中获取另一条连接，并在这条连接上重新准备语句。

由于语句在原始连接繁忙时，会根据需要重新准备，因此当数据库在高并发使用时，可能会使许多连接繁忙，从而创建大量准备好的语句。这可能会导致明显的语句泄漏，语句的准备和重新准备的频率比你想象的要高，甚至会遇到服务器端对语句数量的限制。

避免准备好的语句

Go在底层为你创建准备好的语句。例如，一个简单的db.Query(sql, param1, param2)的工作原理是准备SQL语句，然后用参数执行它，最后关闭该语句。

然而，某些时候准备好的语句并不是你想要的，可能有如下几个原因：

1 某些数据库不支持准备好的语句。例如，当使用MySQL驱动程序时，你可以连接到MemSQL和Sphinx，因为它们支持MySQL连接协议。但它们不支持包含准备好的语句的“二进制”协议，因此它们可能会以令人困惑的方式执行失败。

2 某些SQL语句的复用程度不足以使用准备好的语句，而且安全问题可以用其他方式处理，因此无需额外性能开销。这方面的一个例子可以在VividCortex的博客上看到。

如果你不想使用准备好的语句，你需要使用fmt.Sprint()或类似的方法来组装SQL，并将其作为唯一的参数传递给db.Query()或db.QueryRow()。你的驱动程序需要支持执行纯文本查询，这是通过Execer和Queryer接口在Go 1.1中实现的，文档在此。

在事务中使用准备好的语句

在Tx实例中创建的准备好的语句专门绑定到Tx实例本身，因此前文关于重新准备的注意事项不再适用。当你对Tx实例进行操作时，你的操作会直接使用Tx实例底层连接的唯一一条连接。

这也意味着在Tx实例中创建的准备好的语句不能与它分开使用。同样，在DB中创建的准备好的语句也没法在事务中使用，因为它们被绑定到不同的数据库连接。

要在Tx中使用在事务外部准备的语句，可以使用Tx.Stmt()，它将从事务外部的准备好的语句创建一个新的绑定到本事务的准备好的语句。它通过获取一个已准备好的现有语句，设置与事务的连接，并在每次执行时重新准备所有语句来实现这一点。这种行为及其实现是不可取的，甚至在database/sql包源代码中有一个TODO来改进它；我们建议不要使用这种方法。

在事务中使用准备好的语句时必须谨慎。考虑以下示例：

tx, err := db.Begin()
if err != nil {
	log.Fatal(err)
}
defer tx.Rollback()
stmt, err := tx.Prepare("INSERT INTO foo VALUES (?)")
if err != nil {
	log.Fatal(err)
}
defer stmt.Close() // 危险！
for i := 0; i < 10; i++ {
	_, err = stmt.Exec(i)
	if err != nil {
		log.Fatal(err)
	}
}
err = tx.Commit()
if err != nil {
	log.Fatal(err)
}
// stmt.Close()在此处return

在Go 1.4关闭一个*sql.Tx之前，它会把与其关联的连接释放回连接池中，但对准备好的语句的延迟Close调用是在这之后执行的，可能会导致对基础连接的并发访问，从而导致连接状态不一致。如果使用Go 1.4或更低版本，则应确保在提交或回滚事务之前始终关闭该准备好的语句。在Go 1.4中修复了此问题，见CR 131650043。

参数占位符语法

准备语句中占位符参数的语法是特定于数据库的。例如，比较MySQL、PostgreSQL和Oracle：

MySQL               PostgreSQL            Oracle
=====               ==========            ======
WHERE col = ?       WHERE col = $1        WHERE col = :col
VALUES(?, ?, ?)     VALUES($1, $2, $3)    VALUES(:val1, :val2, :val3)

错误处理

几乎所有使用database/sql包里的类型的操作都会返回一个错误变量作为最后一个值。你应该经常检查这些错误，永远不要忽视它们。

在一些地方，错误行为代表了一种特殊情况，或者你可能需要了解其他信息。

迭代结果集的错误处理

考虑以下代码：

for rows.Next() {
	// ...
}
if err = rows.Err(); err != nil {
	// 在此处处理错误
}

来自rows.Err()的错误可能是rows.Next()循环中，各种可能发生的错误的其中一种。除了正常完成循环之外，循环可能会出于某种原因退出，因此你始终需要检查循环是否正常终止。异常终止会自动调用rows.Close()，尽管多次调用它是无害的。

关闭结果集的错误处理

如前所述，如果提早退出循环，则应始终显式关闭sql.Rows。如果循环正常退出或出现错误，它会自动关闭，但你可能会错误地这样做：

for rows.Next() {
	// ...
	break; // 此时rows没有关闭。
}
// 关闭rows并检查是否有错误发生。多次调用rows.Close()是可以的，即使rows已经关闭了。
if err = rows.Close(); err != nil {
	// 如果此处真的有错误发生，我们又该怎么做呢？
	log.Println(err)
}

常规规则是最好在所有数据库操作中捕获并检查是否有错误发生，rows.Close()返回错误是常规规则的唯一例外。如果rows.Close()返回错误，则不清楚你应该怎么做。记录错误消息到日志或引发panic可能是唯一明智的做法，如果这不明智，那么也许你应该忽略该错误。

QueryRow()的错误处理

考虑以下返回单行数据的代码：

var name string
err = db.QueryRow("select name from users where id = ?", 1).Scan(&name)
if err != nil {
	log.Fatal(err)
}
fmt.Println(name)

如果没有id为1的用户怎么办？这样结果中就不会有行，.Scan()也不会将值扫描到name中。然后会发生什么？

Go定义了一个特殊的错误常量，称为sql.ErrNoRows，当结果集为空时，它会从QueryRow()返回。在大多数情况下，这需要作为特殊情况处理。应用程序代码通常不会将空结果集视为一个错误，如果你不检查错误是否等于此特殊常量，则会导致意想不到的应用程序代码错误。

查询中的错误会延迟到调用Scan()，然后返回。上面的代码最好这样写：

var name string
err = db.QueryRow("select name from users where id = ?", 1).Scan(&name)
if err != nil {
	if err == sql.ErrNoRows {
		// 一行数据都没有，也没有其他错误发生
	} else {
		log.Fatal(err)
	}
}
fmt.Println(name)

有人可能会问，为什么空的结果集被认为是一个错误。空结果集并非错误。原因是QueryRow()方法需要使用这种特殊情况，以便让调用者区分QueryRow()是否真的找到了一行；如果没有它，Scan()就什么也不做，而你可能根本没有意识到你的变量没有从数据库中获得任何值。

只有在使用QueryRow()时才会遇到此错误。如果你在其他地方遇到这个错误，那就是你做错了什么。

鉴别特定的数据库错误

编写如下代码可能很诱人：

rows, err := db.Query("SELECT someval FROM sometable")
// err包含如下字符串：
// ERROR 1045 (28000): Access denied for user 'foo'@'::1' (using password: NO)
if strings.Contains(err.Error(), "Access denied") {
	// 处理"Access denied"错误
}

不过，这并不是最好的做法。例如，数据库服务器发送的错误消息所使用的语言不同时，我们会收到不同的字符串。比较错误号码来确定具体的错误是什么要好得多。

然而，实现这一点的机制因驱动程序而异，因为这不是database/sql本身的一部分。在本教程重点介绍的MySQL驱动程序中，你可以编写以下代码：

if driverErr, ok := err.(*mysql.MySQLError); ok { //现在可以直接获取错误号码
	if driverErr.Number == 1045 {
		// 处理拒绝权限错误
	}
}

同样，这里的MySQLError类型是由这个特定的驱动程序提供的，不同的驱动程序的.Number字段可能不同。然而，该数字的值取自MySQL的错误消息，因此是特定于数据库的，而不是特定于驱动程序的。

以上代码仍然很难看。像1045这样的神奇的数字是一种代码臭味。一些驱动程序（虽然不是MySQL驱动程序，但原因与这里的主题无关）提供了错误标识符列表。Postgres数据库的pq驱动程序在error.go中就是这样做的。还有一个由VividCortex维护的MySQL错误号码外部包。使用这样的列表，上面的代码可以更好地这样写：

if driverErr, ok := err.(*mysql.MySQLError); ok {
	if driverErr.Number == mysqlerr.ER_ACCESS_DENIED_ERROR {
		// 处理拒绝权限错误
	}
}

处理连接错误

如果你与数据库的连接被断开、终止或出现错误，该怎么办？

发生这种情况时，你不需要实现任何逻辑来重试失败的语句。作为database/sql中连接池的一部分，处理失败的连接是Go内建的。如果执行查询或其他语句，而底层连接出现故障，Go将重新打开一个新连接（或只是从连接池中获取另一个），然后重试，最多10次。

然而，可能会有一些意想不到的后果。当发生错误情况时，可能会重试某些类型的错误。这也可能是特定于驱动程序的。MySQL驱动程序的一个例子是，使用KILL取消不需要的语句（如长时间运行的查询），会导致该语句被重试多达10次。

处理空列值

可为null的列很烦人，会导致很多难看的代码。如果可以的话，应该避免它们。如果没有，那么你需要使用database/sql包中的特殊类型来处理它们，或者定义自己的类型。

database/sql包定义了可为null的布尔值、字符串、整数和浮点值的类型。以下是如何使用它们的一个示例：

for rows.Next() {
	var s sql.NullString
	err := rows.Scan(&s)
	// 检查err
	if s.Valid {
	   // 使用s.String
	} else {
	   // 是NULL值
	}
}

可为null的类型的限制，以及避免可为null列的原因：

1 没有sql.NullUint64或其他sql.NullYourFavoriteType类型。你需要为此定义自己的。

2 使用可为null的类型是一种奇技淫巧，而且不能经得起未来的考验。如果你认为某个东西不会为空，但你错了，你的程序就会崩溃，可能很少会在发布之前发现错误。

3 Go的一个好处是为每个变量都有一个有用的默认零值。但这不是可为null的类型的工作方式。

如果需要定义自己的类型来处理NULL，可以复制sql.NullString的设计来实现这一点。

如果你无法避免在数据库中使用NULL值，那么大多数数据库系统都支持另一种方法，即使用COALESCE()函数。你可以在不引入无数sql.Null*类型的情况下编写类似于以下的代码：

rows, err := db.Query(`
	SELECT
		name,
		COALESCE(other_field, '') as otherField
	WHERE id = ?
`, 42)

for rows.Next() {
	err := rows.Scan(&name, &otherField)
	// ..
	// 如果`other_field`列的值为NULL, 最终存入`otherField`变量的值就是空字符串。这种方式也以同样的逻辑处理其他数据类型。
}

处理未知列数

函数Scan()要求你传递正确数量的目标变量。如果你不知道查询将返回什么，该怎么办？

如果你不知道查询将返回多少列，可以使用columns()返回一个列名的列表。你可以检查此列表的长度以查看有多少列，还可以将一个具有正确列数的切片传递到Scan()中。例如，MySQL的一些分支执行SHOW PROCESSLIST命令返回不同的列，因此你必须为此做好准备，否则会导致错误。这里有一种方法：

cols, err := rows.Columns()
if err != nil {
	// 处理这个错误
} else {
	dest := []interface{}{ // 标准MySQL的列
		new(uint64), // id
		new(string), // host
		new(string), // user
		new(string), // db
		new(string), // command
		new(uint32), // time
		new(string), // state
		new(string), // info
	}
	if len(cols) == 11 {
		// 如果返回了11列，那么使用的数据库可能是Percona server for MySQL
	} else if len(cols) > 8 {
		// 如果返回的列数大于8，处理这种情况
	}
	err = rows.Scan(dest...)
	// 处理dest里的值
}

如果你不知道列数或它们的类型，那么应该使用sql.RawBytes。

cols, err := rows.Columns() // 记得无论如何都要检查err，此处省略，因为与主题无关
vals := make([]interface{}, len(cols))
for i, _ := range cols {
	vals[i] = new(sql.RawBytes)
}
for rows.Next() {
	err = rows.Scan(vals...)
	// Now you can check each element of vals for nil-ness, and you can use type introspection and type assertions to fetch the column into a typed variable.现在，你可以检查vals的每个元素是否为nil，并且可以使用类型内省(type introspection)和类型断言(type assertions)将列获取到特定类型的变量中。
}

连接池

database/sql包中有一个基本的连接池。没有太多的能力来控制或检查它，但以下是一些你可能会觉得有用的事情：

• 连接池意味着在一个数据库上执行两个连续的语句可能会打开两个连接并分别执行。对于程序员来说，对他们的代码为什么表现不佳感到困惑是很常见的。例如，LOCK TABLES后面跟着INSERT可能会阻塞，因为INSERT位于不包含LOCK TABLES锁表的连接上。
• 当连接池中没有可用的连接时，database/sql包会在需要时创建新的连接。
• 默认情况下，对连接的数量没有限制。如果你试图同时做很多事情，你可以创建任意数量的连接。这可能会导致数据库返回诸如“连接过多”之类的错误。
• 在Go 1.1或更新的版本中，可以使用db.SetMaxIdleConns(N)来限制连接池中的空闲连接数。不过，这并没有限制连接池的大小(size)。
• 在Go 1.2.1或更新的版本中，可以使用db.SetMaxOpenConn(N)来限制到数据库的打开连接的总数。不幸的是，一个死锁Bug（修复）使db.SetMaxOpenConn(N)无法在Go 1.2中安全使用。
• 连接的回收速度相当快。使用db.SetMaxIdleConns(N)设置更多空闲连接的数目可以减少这种流失，并有助于保持连接以供重用。
• 长时间保持空闲的连接可能会导致问题（例如Microsoft Azure上的MySQL的问题）。如果由于连接空闲时间过长而导致连接超时，请尝试db.SetMaxIdleConns(0)。
• 你还可以通过设置db.SetConnMaxLifetime(duration)来指定连接可以重复使用的最长时间，因为重复使用寿命过长的连接可能会导致网络问题。这会延迟关闭未使用的连接，即可能会延迟关闭过期的连接。

惊讶、反模式和限制

尽管一旦你习惯了database/sql包，数据库编程就很简单，但你可能会对它所支持的其他一些巧妙用法感到惊讶。这在Go的核心库中很常见。

资源耗尽

正如本网站中所提到的，如果你没有按预期使用database/sql，你肯定会给自己带来麻烦，通常是消耗一些资源或阻止它们被有效地重用：

• 过于频繁地打开和关闭数据库可能会导致资源耗尽。
• 未能读取完毕所有行数据或rows.Close()执行失败，将占据连接池中的一条连接。
• 对不返回行数据的语句使用Query()将占据连接池中的一条连接。
• 没有意识到准备好的语句是如何工作的，可能会导致大量额外的数据库活动。

大uint64值

这是一个令人惊讶的错误。如果设置了高位(high bit)，则不能将大的无符号整数作为参数传递给语句：

_, err := db.Exec("INSERT INTO users(id) VALUES", math.MaxUint64) // Error

这将引发一个错误。如果使用uint64值，请小心，因为它们可能一开始很小，工作时没有错误，但随着时间的推移而增大，并开始抛出错误。

连接状态不匹配

有些事情可能会改变连接状态，这可能会导致问题，原因有两个：

• 某些连接状态，例如是否处于事务中，应该通过Go类型来处理。
• 你可能会假设你的查询在某一个连接上运行，而事实并非如此。

例如，用USE语句设置当前数据库是许多人通常要做的事情。但在Go中，这么做只会影响当前运行它的这条数据库连接。除非在事务中（译者注：或者使用专用连接），否则你认为在该连接上执行的其他语句，实际上可能会在从连接池中获得的其他连接上运行，所以可能无法应用这些语句的更改。

此外，在你更改连接后，它将返回到池中，并可能污染其他代码的状态。这也是为什么永远不应该直接将BEGIN或COMMIT语句作为SQL命令发出的原因之一。

数据库的特定语法

database/sql包的API提供了面向行的数据库的抽象，但特定的数据库和驱动程序可能在行为和/或语法上有所不同，例如准备好的语句的占位符语法。

多个结果集

Go驱动程序无论如何都不支持来自单个查询返回的多个结果集，而且似乎没有任何计划这样做，尽管有一个支持批量复制等批量操作的功能请求。

这意味着，返回多个结果集的存储过程将无法正常工作。

调用存储过程

调用存储过程的语法是特定于驱动程序的，但在MySQL驱动程序中，目前无法做到这一点。你似乎可以通过执行以下操作来调用一个返回单个结果集的简单存储过程：

err := db.QueryRow("CALL mydb.myprocedure").Scan(&result) // Error

实际上它不能按预期执行，反而会报错：”Error 1312: PROCEDURE mydb.myprocedure can’t return a result set in the given context.”。这是因为MySQL希望连接被设置为多语句模式(multi-statement mode)，即使只是返回单个结果，而驱动程序目前不会这样做（尽管请参阅此议题）。

支持多语句

database/sql包目前没有明确支持多语句，这意味着它的行为依赖于后端实现：

_, err := db.Exec("DELETE FROM tbl1; DELETE FROM tbl2") // 出错或不能返回预期结果

database/sql包目前没有明确支持多语句，这意味着它的行为依赖于后端实现：

_, err := db.Exec("DELETE FROM tbl1; DELETE FROM tbl2") // 出错或不能返回预期结果

服务器可以按照自己的意愿对此进行解释，包括返回一个错误、只执行第一条语句或同时执行这两条语句。

类似地，没有办法在事务中批处理SQL语句。事务中的每条语句都必须串行执行，并且必须扫描或关闭结果中的资源，例如Row或Rows，以便底层连接可以供下一条语句使用。这与非事务的普通行为不同。在普通行为下，完全可以执行查询，在Rows上循环遍历，并在循环中对数据库进行另一次查询（这将在一条新连接上发生）：

rows, err := db.Query("select * from tbl1") // 使用数据库连接1
for rows.Next() {
	err = rows.Scan(&myvariable)
	// 因为连接1已经在使用，以下代码将不会使用连接1
	db.Query("select * from tbl2 where id = ?", myvariable)
}

但是事务只绑定到一个数据库连接，所以上述代码在事务中是不可能的：

tx, err := db.Begin()
rows, err := tx.Query("select * from tbl1") // 使用绑定到tx的数据库连接
for rows.Next() {
	err = rows.Scan(&myvariable)
	tx.Query("select * from tbl2 where id = ?", myvariable) // ERROR，tx的连接正在忙！
}

不过，Go并不能阻止你去尝试。如果你试图在第一个语句释放其资源并在其自身清理之前执行另一个语句，就可能会导致连接损坏。这也意味着事务中的每条语句与数据库服务器之间的网络通讯，是一组单独的网络往返。

其他相关文章和资源

以下是我们发现有帮助的一些外部信息资源：

• http://golang.org/pkg/database/sql/
• http://jmoiron.net/blog/gos-database-sql/
• http://jmoiron.net/blog/built-in-interfaces/
• The VividCortex blog, e.g. transparent encryption
• Overview of SQL Drivers from golang github

我们希望这个网站会有所帮助。如果你有任何改进建议，请到https://github.com/VividCortex/go-database-sql-tutorial发送拉取请求(pull request)或开启一个议题。

本文翻译自《Opening a database handle》。

目录

查找和导入一个数据库驱动程序

打开一个数据库句柄

确认一个数据库连接

存储数据库凭据

释放资源

database/sql包减少了你管理连接的需要，从而简化了数据库访问。与许多数据访问API不同，使用database/sql时，你不是显式地打开数据库连接、工作，然后关闭连接。相反，你的代码打开一个表示连接池的数据库句柄，然后使用该句柄执行数据访问操作，仅在需要释放资源时调用Close方法，例如检索到的行或准备好的语句所持有的资源。

换句话说，由sql.DB表示数据库句柄，用于处理连接，代表代码打开和关闭连接。当你的代码使用数据库句柄执行数据库操作时，这些操作可以并发地访问数据库。有关详细信息，请参阅管理数据库连接。

注意：你也可以使用一条专用的数据库连接。有关更多信息，请参阅使用专用连接。

除了database/sql包中提供的API之外，Go社区还为所有最常见（以及许多不常见）的数据库管理系统(DBMS)开发了驱动程序。

打开数据库句柄时，你执行以下高层级的步骤：

1 找到一个驱动程序。

驱动程序在Go代码和数据库之间转换请求和响应。有关详细信息，请参阅查找和导入一个数据库驱动程序。

2 打开一个数据库句柄。

导入驱动程序后，可以打开访问特定数据库的一个句柄。有关详细信息，请参见打开一个数据库句柄。

3 确认一个数据库连接。

打开数据库句柄后，代码就可以检查这个数据库连接是否可用。有关详细信息，请参阅确认一个数据库连接。

你的代码通常不会显式地打开或关闭数据库连接——这是由数据库句柄完成的。然而，你的代码应该释放在此过程中获得的资源，例如包含查询结果的sql.Rows。有关详细信息，请参见释放资源。

查找和导入一个数据库驱动程序

你需要一个支持你正在使用的DBMS的Go语言的数据库驱动程序。要查找数据库的驱动程序，请参阅SQLDrivers。

为了使驱动程序可用于你的代码，你可以像导入另一个Go包一样导入它。下面是一个例子：

import "github.com/go-sql-driver/mysql"

请注意，如果你不直接从驱动程序包调用任何函数，例如当sql包隐式使用它时，你需要使用一个空白导入，该导入在导入路径前加一个下划线：

import _ "github.com/go-sql-driver/mysql"

注意：作为最佳实践，避免使用数据库驱动程序自己的API进行数据库操作。相反，应该使用database/sql包中的函数。这将有助于保持代码与DBMS的松散耦合，从而在需要时更容易切换到不同的DBMS。

打开一个数据库句柄

sql.DB数据库句柄提供了单独或在事务中读取和写入数据库的能力。

你可以通过调用sql.Open函数（使用连接字符串）或sql.OpenDB函数（使用driver.Connector）来获取数据库句柄。两者都返回一个指向sql.DB的指针。

注意：请确保将你的数据库凭据放在Go源代码之外。有关更多信息，请参阅存储数据库凭据。

使用一个连接字符串

如果要使用连接字符串进行连接，请使用sql.Open函数。字符串的格式会因你使用的驱动程序而异。

以下是MySQL的一个示例：

db, err = sql.Open("mysql", "username:password@tcp(127.0.0.1:3306)/jazzrecords")
if err != nil {
    log.Fatal(err)
}

然而，你可能会发现，以更结构化的方式捕获连接属性可以为你提供更具可读性的代码。具体细节因数据库驱动而异。

例如，你可以将前面的示例替换为以下示例，该示例使用MySQL驱动程序的Config指定连接属性，并使用FormatDSN方法构建连接字符串。

// 指定连接属性。
cfg := mysql.Config{
    User:   username,
    Passwd: password,
    Net:    "tcp",
    Addr:   "127.0.0.1:3306",
    DBName: "jazzrecords",
}

// 获得一个数据库句柄。
db, err = sql.Open("mysql", cfg.FormatDSN())
if err != nil {
    log.Fatal(err)
}

使用一个连接器

当你想利用连接字符串中无法设置的特定于驱动程序的连接特性时，请通过sql.OpenDB函数。每个驱动程序都支持自己的连接特性集，通常用于自定义特定于DBMS的连接请求。

将前面的sql.Open示例改编为使用sql.OpenDB，你可以使用以下代码创建一个数据库句柄：

// 指定连接属性。
cfg := mysql.Config{
    User:   username,
    Passwd: password,
    Net:    "tcp",
    Addr:   "127.0.0.1:3306",
    DBName: "jazzrecords",
}

// 获取一个特定驱动的连接器
connector, err := mysql.NewConnector(&cfg)
if err != nil {
    log.Fatal(err)
}

// 获取一个数据库句柄。
db = sql.OpenDB(connector)

处理错误

你的代码应该检查尝试创建句柄时是否出现了一个错误，例如使用sql.Open函数。这不会是连接错误。相反，如果sql.Open函数无法初始化句柄，则会出现一个错误。例如，如果它无法解析你指定的DSN，就可能会发生这种情况。

确认一个数据库连接

打开一个数据库句柄时，sql包可能不会立即创建一个新的数据库连接。相反，它可能会在你的代码需要时创建这个连接。如果你不想立即使用数据库，并且想确认可以建立连接，请调用Ping或PingContext函数。

以下示例中的代码ping数据库以确认连接。

db, err = sql.Open("mysql", connString)

// 确认是否能连接数据库成功。
if err := db.Ping(); err != nil {
    log.Fatal(err)
}

存储数据库凭据

避免在Go源代码中存储数据库凭据，因为这可能会将数据库的内容暴露给其他人。相反，找到一种方法将它们存储在代码之外但可供使用的位置。例如，考虑一个秘密保管器应用程序，该应用程序存储凭据并提供一个API，代码可以使用该API来检索凭据，以便与DBMS进行身份验证。

一种流行的方法是在程序启动前将秘密信息存储在你的环境变量中，然后你的Go程序可以使用os.Getenv函数:

username := os.Getenv("DB_USER")
password := os.Getenv("DB_PASS")

这种方法还允许你自己设置用于本地测试的环境变量。

释放资源

尽管你没有使用database/sql包显式地管理或关闭连接，但当不再需要资源时，你的代码应该会释放所获得的资源。这些包括sql.Rows所拥有的资源，表示从查询返回的行数据，或者sql.Stmt表示准备好的语句。

通常，通过延迟对Close函数的调用来释放资源，以便在外部函数退出之前释放资源。

以下示例中的代码延迟调用Close函数以释放sql.Rows所拥有的资源。

rows, err := db.Query("SELECT * FROM album WHERE artist = ?", artist)
if err != nil {
    log.Fatal(err)
}
defer rows.Close()

// 循环遍历返回的行数据。

本文翻译自《Accessing relational databases》。

目录

支持的数据库管理系统

用于执行查询或更改数据库的函数

事务

取消查询

管理连接池

使用Go，你可以将各种各样的数据库和数据访问方法集成到你的应用程序中。本节中的主题描述了如何使用标准库的database/sql包来访问关系数据库。

有关Go访问数据的入门教程，请参阅教程：访问关系型数据库。

Go还支持其他数据访问技术，包括用于对关系型数据库进行更高级别访问的ORM库，以及非关系型的NoSQL数据库。

• 对象关系映射（Object-relational mapping，ORM）库。虽然database/sql包包括用于较低级别的数据访问逻辑的函数，但你也可以使用Go访问更高抽象级别的数据访问。有关Go的两个流行的对象关系映射(ORM)库的更多信息，请参阅GORM（引用该包的地址）和ent（引用该包的地址）。
• NoSQL数据存储。Go社区已经为大多数NoSQL数据存储开发了驱动程序，包括MongoDB和Couchbase。你可以搜索pkg.go.dev了解更多信息。

支持的数据库管理系统

Go支持所有最常见的关系型数据库管理系统，包括MySQL、Oracle、Postgres、SQL Server、SQLite等。

你可以在SQLDrivers页面上找到驱动程序的完整列表。

用于执行查询或更改数据库的函数

database/sql包包含专门为你正在执行的数据库操作设计的函数。例如，虽然你可以使用Query或QueryRow来执行查询，但QueryRow是为只期望返回一行数据的情况而设计的，省去了返回仅包括一行数据的sql.Rows的开销。你可以使用Exec函数传入SQL语句（例如INSERT、UPDATE或DELETE）更改数据库。

更多信息请参考：

• 执行不返回数据的SQL语句
• 查询数据

事务

通过sql.Tx，可以编写代码在事务中执行数据库操作。在事务中，多个操作可以一起执行并以最终提交(commit)结束，以在一个原子步骤中应用所有更改，或者回滚以所有更改。

有关事务的更多信息，请参阅执行事务。

取消查询

当你希望能够取消数据库操作时，例如当客户端的连接关闭或操作运行时间超过你的预期时，你可以使用context.Context。

对于任何数据库操作，你可以使用database/sql包里的将Context作为参数的函数。使用Context，你可以为操作指定超时时间或截止时间。你还可以使用Context通过应用程序将取消请求传播到执行SQL语句的函数，确保资源在不再需要时得到释放。 有关更多信息，请参阅取消正在进行中的数据库操作。

管理连接池

当你使用sql.DB数据库句柄时，你正在使用一个内置的连接池，该连接池根据你的代码创建和处理数据库连接。通过sql.DB的句柄是使用Go进行数据库访问的最常见方式。有关详细信息，请参阅打开一个数据库句柄。

database/sql包为你管理连接池。但是，对于更高级的需求，你可以设置连接池属性，详见设置连接池属性。

对于那些需要单个专用数据库连接的操作，database/sql包提供了sql.Conn。当使用sql.Tx的事务不是一个好选择时，Conn尤其有用。

例如，你的代码可能需要：

• 通过DDL更改数据库模式，包括自身就带事务语义的逻辑。将sql包的事务函数与SQL事务语句混合是一种不良做法，如执行事务中所述。
• 执行创建临时表等查询锁定（译者注：期间不允许执行查询语句）的操作。

有关更多信息，请参阅使用专用连接。

本文翻译自《Executing transactions》。

目录

最佳实践

例子

你可以使用代表事务的sql.Tx结构体执行数据库事务操作。除了表示事务特定语义的Commit和Rollback方法之外，sql.Tx还具有用来执行常见数据库操作的所有方法。要获取sql.Tx，你可以调用DB.Begin或DB.BeginTx方法。

数据库事务将多个数据库操作合成一组，作为更大目标的一部分。其中的所有数据库操作都必须成功执行或都不执行，在任何一种情况下都会保持数据的完整性。 通常，事务操作的流程包括：

1 开始事务。

2 执行一组数据库操作。

3 如果没有错误发生，提交事务以进行数据库更改。

4 如果发生错误，回滚事务以保持数据库不变。

sql包提供了开始和结束事务的方法，以及执行中间数据库操作的方法。这些方法对应于上述流程中的四个步骤。

1 开始事务。

DB.Begin或DB.BeginTx开始一个新的数据库事务，返回一个代表它的sql.Tx结构体。

2 执行数据库操作。

使用sql.Tx，你可以在单个数据库连接中查询或更新数据库。为了支持这一点，Tx导出了以下方法：

• Exec和ExecContext通过SQL语句（例如如INSERT、UPDATE和DELETE）更改数据库。有关详细信息，请参阅执行不返回行数据的SQL语句。
• Query、QueryContext、QueryRow和QueryRowContext用于执行返回行数据的SQL语句。有关更多信息，请参阅查询数据。
• Prepare、PrepareContext、Stmt和StmtContext用于预定义准备好的语句。有关更多信息，请参阅使用准备好的语句。

3 使用以下其中一项结束事务：

• 使用Tx.Commit方法提交事务。

如果Commit方法执行成功（返回nil错误），则所有查询结果都被确认为有效，并且所有已执行的更新都作为单个原子更改应用于数据库。如果Commit方法执行失败，则Tx上Query和Exec的所有结果都应被视为无效而丢弃。

• 使用Tx.Rollback方法回滚事务。

即使Tx.Rollback方法执行失败，事务也不再有效，也不会提交到数据库。

最佳实践

遵循以下最佳实践，以更好地应对事务有时需要的复杂语义和连接管理。

• 使用本节中描述的API来管理事务。不要直接使用BEGIN和COMMIT等与事务相关的SQL语句——这样做会使你的数据库处于不可预测的状态，尤其是在并发程序中。
• 使用事务的过程中，请注意不要直接调用非事务的sql.DB的方法，因为它们会在事务外部执行，从而使你的代码对数据库状态的看法不一致，甚至会导致死锁。

例子

以下示例中的函数使用事务为相册(album)创建新的客户订单(customer order)。在此过程中，该函数的代码将：

1 开始事务。

2 延迟事务的回滚。如果事务执行成功，它将在该函数退出之前提交，使延迟回滚调用(defer tx.Rollback())成为空操作。如果事务执行失败，则不会提交，这意味着回滚将在函数退出时被调用。

3 确认客户订购的专辑有足够的库存(inventory)。

4 如果足够，更新库存数量，减少订购的专辑数目。

5 创建一个新订单并获取新订单为客户生成的ID。

6 提交事务并返回这个ID。

此示例的Tx方法需要一个context.Context参数。使得函数的执行（包括数据库操作）在运行时间过长或客户端连接关闭时被取消。有关更多信息，请参阅取消正在进行中的数据库操作。

// CreateOrder函数为相册(album)创建一个新的客户订单(customer order)并返回这个新订单的ID。
func CreateOrder(ctx context.Context, albumID, quantity, custID int) (orderID int64, err error) {

    // 创建一个帮助函数用于返回失败的结果。
    fail := func(err error) (int64, error) {
        return 0, fmt.Errorf("CreateOrder: %v", err)
    }

    // 获取一个事务实例tx用来执行事务操作。
    tx, err := db.BeginTx(ctx, nil)
    if err != nil {
        return fail(err)
    }
    // 延迟执行一个回滚操作，以防在此事务中某些操作执行失败
    defer tx.Rollback()

    // 确认相册库存足以下这个订单。
    var enough bool
    if err = tx.QueryRowContext(ctx, "SELECT (quantity >= ?) from album where id = ?",
        quantity, albumID).Scan(&enough); err != nil {
        if err == sql.ErrNoRows {
            return fail(fmt.Errorf("no such album"))
        }
        return fail(err)
    }
    if !enough {
        return fail(fmt.Errorf("not enough inventory"))
    }

    // 更新相册库存以减去本订单中的相册数目。
    _, err = tx.ExecContext(ctx, "UPDATE album SET quantity = quantity - ? WHERE id = ?",
        quantity, albumID)
    if err != nil {
        return fail(err)
    }

    // 在album_order表中创建一个新行。
    result, err := tx.ExecContext(ctx, "INSERT INTO album_order (album_id, cust_id, quantity, date) VALUES (?, ?, ?, ?)",
        albumID, custID, quantity, time.Now())
    if err != nil {
        return fail(err)
    }
    // 获得刚刚创建的订单条目的ID。
    orderID, err = result.LastInsertId()
    if err != nil {
        return fail(err)
    }

    // 提交这个事务。
    if err = tx.Commit(); err != nil {
        return fail(err)
    }

    // 返回这个订单的ID。
    return orderID, nil
}

本文翻译自《Querying for data》。

目录

查询单行

查询多行

处理可null列的值

从列中获取数据

处理多个结果集

执行返回行数据的SQL语句时，请使用database/sql包中提供的Query方法之一。其中每一个都返回一行或多行，你可以使用Scan方法将其数据复制到变量中。例如，你可以使用这些方法来执行SELECT语句。

执行不返回行数据的语句，可以改用Exec或ExecContext方法。有关详细信息，请参阅执行不返回数据的SQL语句。

database/sql包提供了两种执行查询并返回结果的方法：

• 查询单行–QueryRow方法从数据库中最多返回一行作为一个Row结构体。有关详细信息，请参阅查询单行。
• 查询多行–Query方法返回所有匹配的行作为代码可以循环的Rows结构体。有关详细信息，请参阅查询多行。

如果你的代码将重复执行相同的SQL语句，请考虑使用准备好的语句（译者注：预处理语句）。有关详细信息，请参阅使用准备好的语句。

注意：不要使用fmt.Sprintf等字符串拼接函数来组装SQL语句！否则你可能会引入SQL注入风险。有关更多信息，请参阅避免SQL注入风险。

查询单行

QueryRow函数最多检索单个数据库行，例如通过唯一ID查找数据时。如果查询返回多行，则Scan方法会丢弃除第一行以外的所有行。

QueryRowContext函数的工作方式类似于QueryRow，但带有context.Context参数。有关更多信息，请参阅取消正在进行的数据库操作。

以下示例使用查询来确定是否有足够的库存来支持购买。如果足够，则SQL语句返回true，否则返回false。Row.Scan方法通过指针将布尔返回值复制到enough变量中。

func canPurchase(id int, quantity int) (bool, error) {
    var enough bool
    // 查询基于单行的值。
    if err := db.QueryRow("SELECT (quantity >= ?) from album where id = ?",
        quantity, id).Scan(&enough); err != nil {
        if err == sql.ErrNoRows {
            return false, fmt.Errorf("canPurchase %d: unknown album", id)
        }
        return false, fmt.Errorf("canPurchase %d: %v", id)
    }
    return enough, nil
}

注意：预处理语句中的参数占位符因所使用的DBMS和驱动程序而异。例如，Postgres的pq驱动程序需要像$1这样的占位符，而MySQL驱动程序使用?号。

处理错误

QueryRow函数本身不返回错误。相反，Scan方法会报告查找和扫描中的任何错误。当查询未找到任何行时，它返回sql.ErrNoRows错误。

以下列出返回单行的函数

DB.QueryRow

DB.QueryRowContext

单独运行单行查询。

Tx.QueryRow

Tx.QueryRowContext

在较大的事务中运行单行查询。有关更多信息，请参阅执行事务。

Stmt.QueryRow

Stmt.QueryRowContext

使用一个准备好的语句运行单行查询。有关更多信息，请参阅使用准备好的语句。

Conn.QueryRowContext

与专用的数据库连接一起使用。有关更多信息，请参阅管理数据库连接。

查询多行

你可以使用Query或QueryContext函数查询多行，它们返回表示查询结果的Rows结构体。你的代码使用rows.Next方法对返回的行进行迭代。每次迭代都调用Scan方法将列值复制到变量中。

QueryContext函数的工作方式与Query类似，但带有context.Context参数。有关更多信息，请参阅取消正在进行中的数据库操作。

以下示例执行查询以返回指定艺术家(artist)的专辑(album)信息。album在sql.Rows中返回。以下代码使用Rows.Scan函数将列值复制到由指针指出的变量中。

func albumsByArtist(artist string) ([]Album, error) {
    rows, err := db.Query("SELECT * FROM album WHERE artist = ?", artist)
    if err != nil {
        return nil, err
    }
    defer rows.Close()

    // 一个切片用来存储返回的行数据。
    var albums []Album

    // 循环遍历行数据，使用Scan方法把每一行的各列的值，赋值给一个结构体变量的对应字段。Loop through rows, using Scan to assign column data to struct fields.
    for rows.Next() {
        var alb Album
        if err := rows.Scan(&alb.ID, &alb.Title, &alb.Artist,
            &alb.Price, &alb.Quantity); err != nil {
            return albums, err
        }
        albums = append(albums, album)
    }
    if err = rows.Err(); err != nil {
        return albums, err
    }
    return albums, nil
}

请注意对rows.Close函数的延迟调用。无论函数如何返回，这都会释放sql.Rows占有的所有资源。虽然循环遍历完毕所有的行也会隐式关闭它，但最好使用defer来确保无论如何都能关闭。

注意：预处理语句中的参数占位符因所使用的DBMS和驱动程序而异。例如，Postgres的pq驱动程序需要像$1这样的占位符，而MySQL驱动程序使用?号。

处理错误

请务必在遍历查询结果后检查sql.Rows中是否有错误发生。如果查询失败，这就是你的代码发现错误的方式。

以下列出返回多行数据的函数

DB.Query

DB.QueryContext

单独运行查询。

Tx.Query

Tx.QueryContext

在较大的事务中执行查询。有关更多信息，请参阅执行事务。

Stmt.Query

Stmt.QueryContext

使用一个准备好的语句运行查询。有关更多信息，请参阅使用准备好的语句。

Conn.QueryContext

与专用的数据库连接一起使用。有关更多信息，请参阅管理数据库连接。

处理可null列的值

当列的值可能为null时，database/sql包提供了几种特殊类型，可以用作Scan函数的参数。每个特殊类型都包括一个Valid字段，该字段报告列值是否为非null，如果为非null则该类型有另一个字段包含该列值。

以下示例中的代码用于查询客户名称。如果名称值为null，则代码将用另一个值替换它，以在应用程序中使用。

var s sql.NullString
err := db.QueryRow("SELECT name FROM customer WHERE id = ?", id).Scan(&s)
if err != nil {
    log.Fatal(err)
}

name := "Valued Customer"
// 如果客户名称不为null（合法，s.Valid的值为true），那么赋值给name变量
if s.Valid {
    name = s.String
}

请参阅sql包关于每个特殊类型的更多信息：

• NullBool
• NullFloat64
• NullInt32
• NullInt64
• NullString
• NullTime

从列中获取数据

在查询返回的行上循环遍历时，可以使用Scan函数将行的列值复制到Go值中，例如rows.Scan的参考文档中所述。

所有驱动程序都支持一组基本的数据类型转换，例如将SQL的INT转换为Go的INT。一些驱动程序扩展了这组转换；有关详细信息，请参阅每个驱动程序的文档。

正如你所料，Scan函数将把列类型转换为类似的Go类型。例如，Scan将把SQL的CHAR、VARCHAR和TEXT转换为Go字符串。但是，Scan还可以把列值转换为另一个非常适合的Go类型。例如，如果列是始终包含数字的VARCHAR，则可以指定数字Go类型（例如int）来接收值，Scan将使用strconv.Atoi函数进行转换。

有关Scan函数进行类型转换的更多详细信息，请参阅Rows.Scan参考文档。

处理多个结果集

当数据库操作可能返回多个结果集时，你可以使用Rows.NextResultSet函数来检索这些结果集。例如，当你发送分别查询多个表的一个SQL语句，并为其中每个表都返回一个结果集时，这可能很有用。

Rows.NextResultSet函数会准备下一个结果集，以便调用Rows.Next函数从下一个集合中检索第一行。它返回一个布尔值，指示是否存在下一个结果集。

以下示例中的代码使用DB.Query函数来执行两条Select语句。第一个结果集来自第一个Select查询，检索相簿album表中的所有行。下一个结果集来自第二个Select查询，从歌曲表song中检索行。

rows, err := db.Query("SELECT * from album; SELECT * from song;")
if err != nil {
    log.Fatal(err)
}
defer rows.Close()

// 循环遍历第一个结果集。
for rows.Next() {
    // 处理结果集…
}

// 前进到下一个结果集。
rows.NextResultSet()

// 循环遍历第二个结果集。
for rows.Next() {
    // 处理结果集…
}

// 检查在处理所有结果集的过程中，是否有错误发生。
if err := rows.Err(); err != nil {
    log.Fatal(err)
}

本文翻译自《Using prepared statements》。

目录

什么是准备好的语句？

如何使用准备好的语句

准备好的语句的行为

你可以定义准备好的语句以供重复使用。这可以避免每次代码执行数据库操作时重新创建语句的额外开销，从而帮助你的代码运行得更快一些。

注意：准备好的语句中的参数占位符因你使用的DBMS和驱动程序而异。例如Postgres的pq驱动程序需要$1形式的占位符，而不是?号占位符。

什么是准备好的语句？

准备好的语句是由DBMS解析和保存的SQL，通常包含占位符但没有实际参数值。稍后，可以使用一组参数值来执行该语句。（译者注：准备好的语句，准备语句，也叫预处理语句。）

如何使用准备好的语句

当你希望重复执行同一条SQL时，可以使用一个sql.Stmt结构体预先准备好SQL语句，然后按需执行。

以下示例创建一个准备好的语句，从数据库中选择一个特定的专辑(album)的信息。DB.Prepare函数返回一个sql.Stmt结构体，代表给定SQL文本的准备语句。你可以将SQL语句的参数值传递给Stmt.Exec、Stmt.QueryRow或Stmt.Query方法以运行该语句。

// AlbumByID函数返回一个特定的专辑(album)的信息。
func AlbumByID(id int) (Album, error) {
    // 定义准备好的语句。你通常会在别处定义该语句并将其保存以供在诸如本函数之类的函数中使用。
    stmt, err := db.Prepare("SELECT * FROM album WHERE id = ?")
    if err != nil {
        log.Fatal(err)
    }

    var album Album

    // 执行准备好的语句，为占位符为?的参数传入一个id值。
    err := stmt.QueryRow(id).Scan(&album.ID, &album.Title, &album.Artist, &album.Price, &album.Quantity)
    if err != nil {
        if err == sql.ErrNoRows {
            // 处理没有一行数据返回的情况。
        }
        return album, err
    }
    return album, nil
}

准备好的语句的行为

准备好的sql.Stmt提供常用的Exec、QueryRow和Query方法来调用语句。有关使用这些方法的更多信息，请参阅查询数据和执行不返回数据的SQL语句。

但是，由于sql.Stmt已经代表了一条预设的SQL语句，所以它的Exec、QueryRow、Query方法只需占位符对应的参数值，省略了SQL文本。

你可以用不同的方式定义一个新的sql.Stmt，这取决于你将如何使用它。

• DB.Prepare和DB.PrepareContext方法创建一个准备好的语句，它可以在事务之外单独执行，就像DB.Exec和DB.Query方法一样。
• Tx.Prepare、Tx.PrepareContext、Tx.Stmt和Tx.StmtContext方法创建用于特定事务的准备好的语句。Prepare和PrepareContext方法使用SQL文本来定义语句。Stmt和StmtContext方法使用DB.Prepare或DB.PrepareContext方法的结果。也就是说，它们将一个非事务的sql.Stmt转换为一个事务的sql.Stmt。
• Conn.PrepareContext方法从sql.Conn方法创建准备好的语句，表示专用的连接。

当你的代码结束时，请确保调用stmt.Close方法。这将释放可能与其关联的任何数据库资源（例如底层连接）。对于函数中仅作为局部变量的语句，defer stmt.Close()就足够了。

用于创建准备好的语句的函数

DB.Prepare
DB.PrepareContext

准备一个单独执行的语句，或者使用Tx.Stmt方法把它转换为事务中的准备语句。

Tx.Prepare
Tx.PrepareContext
Tx.Stmt
Tx.StmtContext

准备用于特定事务的语句。有关更多信息，请参阅执行事务。

Conn.PrepareContext

与专用的连接一起使用。有关更多信息，请参阅管理数据库连接。