{"record":{"id":"6095df25e7940b44","repo":"gastownhall/beads","slug":"schema-pin-connection-w","errorCode":null,"errorMessage":"schema: pin connection: %w","messagePattern":"schema: pin connection: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/store.go","lineNumber":2595,"sourceCode":"\n// initSchemaOnDB applies pending schema migrations. schema.MigrateUp tracks\n// applied versions in schema_migrations and backfills legacy config-driven\n// tables. Returns the number of migrations applied.\nfunc initSchemaOnDB(ctx context.Context, db *sql.DB) (int, error) {\n\treturn initSchemaOnDBWithBootstrapHeal(ctx, db, nil, \"\")\n}\n\n// initSchemaOnDBWithBootstrapHeal threads one-shot, incarnation-bound reset\n// authority into the migration lock. A nil capability always fails closed.\nfunc initSchemaOnDBWithBootstrapHeal(\n\tctx context.Context,\n\tdb *sql.DB,\n\tbootstrapHeal *schema.FreshBootstrapHealCapability,\n\tendpoint string,\n) (int, error) {\n\tconn, err := db.Conn(ctx)\n\tif err != nil {\n\t\treturn 0, fmt.Errorf(\"schema: pin connection: %w\", err)\n\t}\n\tdefer conn.Close()\n\n\tvar dbName string\n\tif err := conn.QueryRowContext(ctx, \"SELECT DATABASE()\").Scan(&dbName); err != nil {\n\t\treturn 0, fmt.Errorf(\"schema: read database name: %w\", err)\n\t}\n\n\tvar opts []schema.MigrateLockOption\n\tif bootstrapHeal != nil {\n\t\topts = append(opts, schema.WithFreshBootstrapHeal(bootstrapHeal, endpoint))\n\t}\n\tapplied, err := schema.MigrateUpWithLock(ctx, conn, dbName, opts...)\n\tif err != nil {\n\t\treturn applied, fmt.Errorf(\"schema migration: %w\", err)\n\t}\n\treturn applied, nil\n}","sourceCodeStart":2577,"sourceCodeEnd":2613,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/store.go#L2577-L2613","documentation":"This error wraps a failure to acquire a dedicated single connection (*sql.Conn) from the pool via db.Conn(ctx) during schema initialization/migration setup. Migrations pin one connection so session state (SET variables, temp tables) is stable across all migration statements. It is only about grabbing the connection from the Go pool, not about the SQL executed on it.","triggerScenarios":"Calling schema initialization (initSchemaOnDBWithRetryAndGate / the pin-connection helper) when the sql.DB pool cannot hand out a connection: context canceled/timed out before a free connection is available, pool exhausted with all connections busy past conn lifetime limits, or the driver failing to dial a new connection.","commonSituations":"Server not running or wrong port in the DSN, context deadline exceeded because migrations queue behind long-held connections, application shutdown canceling ctx mid-init, network blips between app and Dolt SQL server.","solutions":["Check the wrapped cause (%w) with errors.Is/As: context.DeadlineExceeded means retry or increase timeout; driver.ErrBadConn/network errors mean fix connectivity","Verify the Dolt SQL server is up and the DSN host/port/credentials are correct","Increase context timeout or ensure the pool is not saturated (SetMaxOpenConns, long transactions) before schema init","Retry the operation; pool acquisition is transient under load"],"exampleFix":"// before\nctx := context.Background()\nconn, err := db.Conn(ctx)\n// after\nctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)\ndefer cancel()\nconn, err := db.Conn(ctx)","handlingStrategy":"retry","validationCode":"// pre-flight: ensure server is reachable before schema init\nif err := db.PingContext(ctx); err != nil {\n    return fmt.Errorf(\"dolt server unreachable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"// Go: inspect wrapped cause\nconn, err := db.Conn(ctx)\nif err != nil {\n    if errors.Is(err, context.DeadlineExceeded) {\n        // retry with longer timeout\n    }\n    var myErr *mysql.MySQLError\n    if errors.As(err, &myErr) { /* server-side rejection */ }\n    return err\n}","preventionTips":["Wrap schema init in a generous context timeout","Keep pool saturation low during startup/migration phases","Ping the server before schema operations","Retry transient pool errors with backoff"],"tags":["go","database","connection-pool","mysql"],"backgroundTag":"connection-acquisition-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}