Documentation
¶
Overview ¶
Package fdsql traces database/sql. Wrap a connector or a driver, and every query, exec, use of a prepared statement and transaction boundary made with a context that carries a span becomes a db.query child span of it (OBSERVABILITY.md §6.4), with the raw statement as its description: the server normalizes it.
db := sql.OpenDB(fdsql.NewConnector(connector, fdsql.WithSystem("postgresql")))
rows, err := db.QueryContext(ctx, "SELECT id FROM orders WHERE user_id = $1", userID)
For drivers known by name, Register wraps one under a new name:
if err := fdsql.Register("fivedock-postgres", "postgres", fdsql.WithSystem("postgresql")); err != nil { … }
db, err := sql.Open("fivedock-postgres", dsn)
Calls without a span on their context (or with the deprecated methods that take none) run untraced. A query's span ends when the driver returns its rows, not when they have been read. Like the fivedock package, fdsql uses only the standard library.
Index ¶
Examples ¶
Constants ¶
const ( Op = "db.query" Origin = fivedock.SpanOrigin("auto.db.fdsql") )
Operation and origin of the spans this package records.
Variables ¶
This section is empty.
Functions ¶
func NewConnector ¶
NewConnector wraps c so that the connections it makes are traced. Use it with sql.OpenDB.
Example ¶
package main
import (
"context"
"database/sql"
"database/sql/driver"
"log"
fivedock "fivedock.dev/go"
"fivedock.dev/go/fdsql"
)
func main() {
var connector driver.Connector // from the driver, e.g. pgx's stdlib.GetConnector(config)
if connector == nil {
return
}
db := sql.OpenDB(fdsql.NewConnector(connector, fdsql.WithSystem("postgresql"), fdsql.WithDatabaseName("shop")))
defer func() { _ = db.Close() }()
tx := fivedock.StartTransaction(context.Background(), "close orders")
defer tx.Finish()
// A db.query span under the transaction.
if _, err := db.ExecContext(tx.Context(), "UPDATE orders SET closed = true WHERE created_at < now() - interval '30 days'"); err != nil {
log.Print(err)
}
}
Output:
func Register ¶
Register registers the driver registered as driverName again as name, traced. It fails when driverName is unknown or name is taken. database/sql offers no other way to reach a registered driver than opening it, so it opens driverName with an empty data source name, which does not connect.
Example ¶
package main
import (
"database/sql"
"log"
"fivedock.dev/go/fdsql"
)
func main() {
// "postgres" was registered by the driver's package (lib/pq, say).
if err := fdsql.Register("fivedock-postgres", "postgres", fdsql.WithSystem("postgresql")); err != nil {
log.Print(err)
return
}
db, err := sql.Open("fivedock-postgres", "postgres://localhost/shop")
if err != nil {
log.Print(err)
return
}
defer func() { _ = db.Close() }()
}
Output:
Types ¶
Source Files
¶
- fdsql.go