context in database/sql & gRPC

database/sql and google.golang.org/grpc were designed around context.Context from day one.

Passing ctx into query and RPC methods ties database and network work to the same cancellation tree as your HTTP handler.

Summary

Use QueryContext, ExecContext, and BeginTx with context for every request-scoped database call.

gRPC client and server methods accept ctx as the first argument; deadlines propagate as RPC timeouts.

Streaming RPCs must check ctx.Done() between Recv and Send calls.

Recipe

Quick-reference recipe card - copy-paste ready.

func GetOrder(ctx context.Context, db *sql.DB, id string) (string, error) {
    var status string
    err := db.QueryRowContext(ctx, `SELECT status FROM orders WHERE id = ?`, id).Scan(&status)
    return status, err
}

When to reach for this:

• Replace Query/Exec without Context in any code path reachable from HTTP or gRPC handlers.
• Pass handler or interceptor context into gRPC stubs unchanged except for shorter child timeouts.
• Cancel streaming loops when ctx.Done() fires to avoid goroutine leaks.

Working Example

package main
 
import (
    "context"
    "database/sql"
    "fmt"
    "time"
 
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
 
    _ "github.com/mattn/go-sqlite3"
)
 
func queryStatus(ctx context.Context, db *sql.DB) (string, error) {
    ctx, cancel := context.WithTimeout(ctx, 200*time.Millisecond)
    defer cancel()
    var s string
    err := db.QueryRowContext(ctx, `SELECT 'shipped'`).Scan(&s)
    return s, err
}
 
func dialGRPC(ctx context.Context) (*grpc.ClientConn, error) {
    ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel()
    return grpc.DialContext(ctx, "localhost:50051",
        grpc.WithTransportCredentials(insecure.NewCredentials()),
    )
}
 
func main() {
    db, _ := sql.Open("sqlite3", ":memory:")
    defer db.Close()
 
    parent, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
    defer cancel()
 
    status, err := queryStatus(parent, db)
    fmt.Println(status, err)
 
    _, err = dialGRPC(parent)
    fmt.Println("grpc dial:", err)
}

What this demonstrates:

• QueryRowContext honors parent cancel and local child timeout.
• grpc.DialContext blocks only until the context ends or the connection succeeds.
• Child timeouts shrink within the parent budget for each subsystem.
• SQLite driver here illustrates the pattern; production pools use the same API with Postgres/MySQL drivers.

Deep Dive

How It Works

• database/sql passes context to driver QueryerContext interfaces; cancellation behavior depends on driver support.
• Connection pool acquisition respects context - slow pool exhaustion returns when ctx ends instead of blocking forever.
• Tx objects use BeginTx(ctx, opts); commit and rollback are fast but in-flight statements should already use the tx context.
• gRPC encodes deadlines in metadata; servers should fail fast with codes.DeadlineExceeded when insufficient time remains.

database/sql API Surface

gRPC Streaming Pattern

func consume(stream pb.Service_StreamServer) error {
    ctx := stream.Context()
    for {
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
        }
        msg, err := stream.Recv()
        if err != nil {
            return err
        }
        _ = msg
    }
}

Server streams expose Context(); client streams accept the caller's ctx on the initial RPC invocation.

controller-runtime Note

Kubernetes client calls from reconcilers should pass the reconcile context into API requests so watches stop when the manager shuts down.

Gotchas

• Using Query without Context in handlers - Abandoned HTTP requests keep DB work alive. Fix: ban non-Context methods in review for request paths.
• Long transactions without deadline - Locks held after client leaves. Fix: BeginTx with ctx; keep transactions short.
• Ignoring ctx in stream Recv loops - Server streams leak after client disconnect. Fix: select on ctx.Done() or handle Recv errors promptly.
• grpc.Dial instead of DialContext - No cancel during service discovery or TLS handshake. Fix: always DialContext with bounded ctx.
• Child timeout longer than gRPC deadline - Server may abort before client expects. Fix: read ctx.Deadline() server-side and clamp work.
• Assuming all drivers cancel instantly - Some drivers cancel only between network round trips. Fix: combine context with statement timeouts in SQL when needed.

Alternatives

FAQs

Related

• Cancellation Propagation in HTTP Handlers - where DB ctx starts
• Deadlines & Timeouts Across Service Boundaries - per-hop budgets
• Testing Code That Accepts context.Context - fakes and timeouts
• context Values: When and When Not - gRPC metadata vs values
• context Package Best Practices - SQL and RPC conventions

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build). 49454e4f4d5f434e4f5904434556494d43451e1b1256181a181c1a1d