{"record":{"id":"f8ed7e832931bf39","repo":"gastownhall/beads","slug":"acquire-connection-for-flatten-w","errorCode":null,"errorMessage":"acquire connection for flatten: %w","messagePattern":"acquire connection for flatten: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/store.go","lineNumber":2911,"sourceCode":"\t\treturn nil, fmt.Errorf(\"acquire connection for remote-ref prune: %w\", err)\n\t}\n\tdefer conn.Close()\n\treturn versioncontrolops.PruneRemoteRefs(ctx, conn)\n}\n\n// ListTags returns the names of all Dolt tags.\nfunc (s *DoltStore) ListTags(ctx context.Context) ([]string, error) {\n\treturn versioncontrolops.ListTags(ctx, s.db)\n}\n\n// Flatten squashes all Dolt commit history into a single commit.\n// Pins a single connection because the stored procedures (DOLT_CHECKOUT,\n// DOLT_RESET, etc.) rely on session-scoped state that would be lost if\n// steps execute on different pooled connections.\nfunc (s *DoltStore) Flatten(ctx context.Context) error {\n\tconn, err := s.db.Conn(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"acquire connection for flatten: %w\", err)\n\t}\n\tdefer conn.Close()\n\treturn versioncontrolops.Flatten(ctx, conn)\n}\n\n// Compact squashes old Dolt commits while preserving recent ones.\n// Pins a single connection for session-scoped stored procedures.\nfunc (s *DoltStore) Compact(ctx context.Context, initialHash, boundaryHash string, oldCommits int, recentHashes []string) error {\n\tconn, err := s.db.Conn(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"acquire connection for compact: %w\", err)\n\t}\n\tdefer conn.Close()\n\treturn versioncontrolops.Compact(ctx, conn, initialHash, boundaryHash, oldCommits, recentHashes)\n}\n\n// UnderlyingDB returns the underlying *sql.DB connection\nfunc (s *DoltStore) UnderlyingDB() *sql.DB {","sourceCodeStart":2893,"sourceCodeEnd":2929,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/store.go#L2893-L2929","documentation":"DoltStore.Flatten needs a single pinned connection from the *sql.DB pool because the DOLT_* stored procedures it invokes (via versioncontrolops.Flatten) depend on session-scoped state. This error wraps a failure to get that connection from the pool. It means Flatten never ran; the underlying driver error is in the wrapped chain.","triggerScenarios":"Calling DoltStore.Flatten when db.Conn(ctx) fails: pool exhausted (all connections checked out), context canceled/deadline exceeded before a connection is available, or the database/driver is unreachable.","commonSituations":"Long-running concurrent operations leak or hold pinned connections until the pool drains; test harnesses shut the DB down mid-operation; a caller passes an already-canceled context; connection limits on the embedded Dolt server are hit under load.","solutions":["Check the wrapped driver error in errors.Unwrap / %w chain to find the root cause (pool timeout vs context canceled vs connection refused).","Audit code paths that call s.db.Conn and confirm defer conn.Close() runs on every path, so the pool is not drained by leaks.","Retry Flatten with a fresh, non-canceled context after reducing concurrent DoltStore operations; consider raising the pool size (SetMaxOpenConns).","Verify the Dolt server/database is running and reachable if the wrapped error is a network or auth failure."],"exampleFix":"// before\nctx := context.Background() // parent ctx already expired upstream\nerr := store.Flatten(ctx)\n// after\nctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)\ndefer cancel()\nif err := store.Flatten(ctx); err != nil {\n\tlog.Printf(\"flatten failed: %v\", err) // inspect wrapped cause\n}","handlingStrategy":"retry","validationCode":"// before calling Flatten\nselect {\ncase <-ctx.Done():\n\treturn ctx.Err()\ndefault:\n}\n// ensure pool headroom (informational)\n// db.Stats().InUse / db.Stats().MaxOpenConnections","typeGuard":null,"tryCatchPattern":"err := store.Flatten(ctx)\nvar netErr net.Error\nif errors.As(err, &netErr) || errors.Is(err, context.DeadlineExceeded) {\n\t// retry with fresh context/backoff\n}","preventionTips":["Always pass a live context with adequate timeout to Flatten.","Avoid leaking db.Conn elsewhere; every pinned connection must be closed.","Keep concurrent DoltStore operations bounded; raise SetMaxOpenConns if needed.","Check database reachability before long batch jobs."],"tags":["go","database","connection-pool","dolt"],"backgroundTag":"db-connection-acquire-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}