{"record":{"id":"5cbb726d942cd049","repo":"gastownhall/beads","slug":"uow-pin-connection-w-5cbb72","errorCode":null,"errorMessage":"uow: pin connection: %w","messagePattern":"uow: pin connection: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/uow/maintenance.go","lineNumber":18,"sourceCode":"package uow\n\nimport (\n\t\"context\"\n\t\"database/sql\"\n\t\"fmt\"\n)\n\ntype MaintenanceProvider interface {\n\tRunNonTx(ctx context.Context, fn func(ctx context.Context, conn *sql.Conn) error) error\n}\n\nvar _ MaintenanceProvider = (*doltSQLProvider)(nil)\n\nfunc (p *doltSQLProvider) RunNonTx(ctx context.Context, fn func(ctx context.Context, conn *sql.Conn) error) error {\n\tconn, err := p.db.Conn(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"uow: pin connection: %w\", err)\n\t}\n\tdefer func() { _ = conn.Close() }()\n\treturn fn(ctx, conn)\n}\n","sourceCodeStart":1,"sourceCodeEnd":23,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/uow/maintenance.go#L1-L23","documentation":"RunNonTx pins a dedicated connection from the Dolt SQL provider's connection pool via db.Conn(ctx). This error wraps any failure to obtain that connection (e.g. the pool is exhausted, the database is unreachable, or ctx is cancelled before a connection can be acquired), so the caller's fn never runs.","triggerScenarios":"Calling any maintenance operation routed through doltSQLProvider.RunNonTx when db.Conn(ctx) fails: pool exhausted (all conns checked out), database server down/unreachable, or ctx deadline/cancellation fires while waiting for a free connection.","commonSituations":"A long-running transaction or leaked connection exhausted the pool; the Dolt server was restarted or is unreachable; a per-command context timeout (e.g. bd's own timeout flag) expired while queued for a connection; network interruption to a remote dolt server.","solutions":["Check that the Dolt server is running and reachable (try any other bd command)","Check for leaked connections/long transactions holding all pool slots; restart the bd process or the server if the pool is wedged","Increase or verify context timeouts so connection acquisition is not cut short","Retry the command; if it recurs, inspect server logs for connection limits"],"exampleFix":"// before\nerr := bd doctor (fails: uow: pin connection: context deadline exceeded)\n// after\nbd doctor --timeout 120s  # allow more time to acquire a connection","handlingStrategy":"retry","validationCode":"// Go: check server reachability and give ctx room before the call\nif err := pingDatabase(ctx); err != nil { return fmt.Errorf(\"dolt server unreachable: %w\", err) }\nctx, cancel := context.WithTimeout(ctx, 120*time.Second); defer cancel()","typeGuard":"func isConnAcquireFailure(err error) bool {\n  return err != nil && (errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) || strings.Contains(err.Error(), \"pin connection\"))\n}","tryCatchPattern":"err := provider.RunNonTx(ctx, fn)\nif errors.Is(err, context.DeadlineExceeded) || isConnAcquireFailure(err) {\n  // back off and retry once\n  time.Sleep(time.Second); err = provider.RunNonTx(ctx, fn)\n}\nreturn err","preventionTips":["Keep the Dolt server running and reachable before invoking bd maintenance commands","Avoid leaking sql.Conn / long transactions that exhaust the pool","Set generous context timeouts for connection acquisition","Retry transient pin failures with backoff"],"tags":["database","connection","dolt","context-timeout"],"backgroundTag":"database-connection-acquisition-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}