{"record":{"id":"5f06a2eacd90ba81","repo":"gastownhall/beads","slug":"uow-switching-to-database-w","errorCode":null,"errorMessage":"uow: switching to database: %w","messagePattern":"uow: switching to database: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"internal/storage/uow/dolt_sql_provider.go","lineNumber":248,"sourceCode":"\t}\n\tif _, err := schema.MigrateUpWithLock(ctx, conn, database,\n\t\tschema.WithDatabaseSelector(selectProbeDatabase),\n\t\tschema.WithLockedPreparation(p.serverEndpoint, preparer.prepare)); err != nil {\n\t\treturn classifyInitSchemaError(err)\n\t}\n\treturn nil\n}\n\n// verifyTeamServerSchema is the team-server open path: the schema is owned by\n// beads-team-server (bts), so bd never creates the database or migrates. It\n// attaches to the existing database and verifies the schema version, then the\n// project identity — identity is checked only after the schema check proves the\n// metadata table exists at this binary's version.\nfunc (p *doltSQLProvider) verifyTeamServerSchema(ctx context.Context, conn *sql.Conn, database string) error {\n\tddl := db.NewDDLSQLRepository(conn)\n\tif err := ddl.UseDatabase(ctx, database); err != nil {\n\t\tif isSerializationError(err) {\n\t\t\treturn fmt.Errorf(\"uow: switching to database: %w\", err)\n\t\t}\n\t\treturn backoff.Permanent(fmt.Errorf(\n\t\t\t\"uow: database %q not found — the schema is managed by beads-team-server; ask your operator to run 'bts init' first: %w\",\n\t\t\tdatabase, err))\n\t}\n\tif err := checkTeamServerSchema(ctx, conn, database); err != nil {\n\t\tif isSerializationError(err) {\n\t\t\treturn fmt.Errorf(\"uow: team-server schema check: %w\", err)\n\t\t}\n\t\treturn backoff.Permanent(err)\n\t}\n\tif err := checkTeamServerIdentity(ctx, conn, database, p.expectedProjectID); err != nil {\n\t\tif isSerializationError(err) {\n\t\t\treturn fmt.Errorf(\"uow: team-server identity check: %w\", err)\n\t\t}\n\t\treturn backoff.Permanent(err)\n\t}\n\treturn nil","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/uow/dolt_sql_provider.go#L230-L266","documentation":"On the team-server open path, verifyTeamServerSchema runs USE <database> via the DDL repository. If it fails with a serialization error, the error is wrapped as 'uow: switching to database: %w' and returned bare so initSchema's backoff retries. Otherwise the failure is terminal.","triggerScenarios":"initSchemaAttempt (teamServer=true) calls verifyTeamServerSchema; ddl.UseDatabase fails with a serialization-class error on the shared beads-team-server, typically while another session is migrating or committing on the server.","commonSituations":"Operator running 'bts init' concurrently with the first bd clients connecting; Dolt serialization conflicts on a loaded shared team server during startup.","solutions":["Retry — the backoff loop will re-attempt the USE once the peer's work settles.","Coordinate with the operator: ensure 'bts init' completed before clients connect.","Check server load; serialization errors spike on heavily contended Dolt servers.","If persistent, inspect the wrapped cause for the specific conflicting statement."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// check the team server is up and the database exists before connecting clients\nrows, err := adminConn.QueryContext(ctx, \"SHOW DATABASES LIKE ?\", dbName)\nif err != nil { return err }\nif !rows.Next() {\n    return fmt.Errorf(\"database %q missing on team server — run 'bts init' first\", dbName)\n}","typeGuard":"if uow.IsSerializationError(err) { /* transient USE failure — retryable */ }","tryCatchPattern":"err := provider.Open(ctx, cfg)\nif err != nil {\n    if uow.IsSerializationError(err) {\n        // team server busy — retry with backoff\n        return backoff.Retry(openFn, bo)\n    }\n    return err\n}","preventionTips":["Gate client rollouts on 'bts init' completing successfully.","Run schema checks against a snapshot of the shared DB in CI.","Avoid connecting clients during bts upgrades or heavy maintenance.","Monitor team-server serialization-failure rates."],"tags":["database","serialization","team-server","retry"],"backgroundTag":"serialization-retry","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}