{"record":{"id":"748fc5c45a3b6d27","repo":"gastownhall/beads","slug":"uow-ping-db-w","errorCode":null,"errorMessage":"uow: ping db: %w","messagePattern":"uow: ping db: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/uow/dolt_sql_provider.go","lineNumber":387,"sourceCode":"func buildDSN(ep proxy.Endpoint, database, user, password, tlsConfigName string) string {\n\treturn util.DoltServerDSN{\n\t\tHost:            ep.Host,\n\t\tPort:            ep.Port,\n\t\tUser:            user,\n\t\tPassword:        password,\n\t\tDatabase:        database,\n\t\tTLSConfigName:   tlsConfigName,\n\t\tClientFoundRows: true,\n\t}.String()\n}\n\nfunc openDB(ctx context.Context, dsn string) (*sql.DB, error) {\n\tconn, err := sql.Open(\"mysql\", dsn)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"uow: open db: %w\", err)\n\t}\n\tif err := conn.PingContext(ctx); err != nil {\n\t\treturn nil, errors.Join(fmt.Errorf(\"uow: ping db: %w\", err), conn.Close())\n\t}\n\treturn conn, nil\n}\n\nfunc openAndInitSchema(ctx context.Context, ep proxy.Endpoint, database, rootUser, rootPassword, tlsConfigName string, teamServer bool, expectedProjectID string, opts providerOptions) (UnitOfWorkProvider, error) {\n\tinitDB, err := openDB(ctx, buildDSN(ep, \"\", rootUser, rootPassword, tlsConfigName))\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tinitProvider := &doltSQLProvider{\n\t\tdefaultBranch:     defaultBranch,\n\t\tdb:                initDB,\n\t\tserverEndpoint:    \"tcp:\" + ep.Address(),\n\t\tteamServer:        teamServer,\n\t\texpectedProjectID: expectedProjectID,\n\t\tpreview:           opts.preview,\n\t}","sourceCodeStart":369,"sourceCodeEnd":405,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/uow/dolt_sql_provider.go#L369-L405","documentation":"openDB verifies the freshly opened connection with conn.PingContext; this error wraps a ping failure and is returned joined with the connection Close error. It is thrown because the Dolt SQL server could not be reached or refused/authenticated the connection — the pool could not establish at least one live connection.","triggerScenarios":"conn.PingContext(ctx) fails during openAndInitSchema's openDB call — server not listening on endpoint, connection refused, TLS handshake failure, wrong credentials, or the context is cancelled/timed out before the ping completes.","commonSituations":"Dolt server not started (bd serve / embedded server down); wrong port or host in configuration; firewall or container networking blocking the port; stale server after restart; expired/mismatched TLS config name; rootPassword changed on the server.","solutions":["Confirm the Dolt SQL server is running and listening on the configured host:port (e.g. `bd serve` or the embedded server process).","Verify endpoint, username, and password in bd configuration match the server.","Check network reachability (firewall, Docker networking, localhost vs container hostname) and TLS settings.","Re-run after the server restarts — this is a transient connectivity failure, and context timeouts mean the operation may simply have been too slow.","Inspect the joined driver error for the exact root cause (connection refused vs access denied vs TLS)."],"exampleFix":"// before: server not started, ping fails\n$ bd init\n// after: start the Dolt SQL server first\n$ bd serve &\n$ bd init","handlingStrategy":"retry","validationCode":"// Before calling the library: probe the server yourself\nfunc serverUp(addr string) error {\n    conn, err := net.DialTimeout(\"tcp\", addr, 3*time.Second)\n    if err != nil {\n        return fmt.Errorf(\"dolt server not reachable at %s: %w\", addr, err)\n    }\n    _ = conn.Close()\n    return nil\n}","typeGuard":"func isPingError(err error) bool {\n    return err != nil && strings.Contains(err.Error(), \"uow: ping db:\")\n}","tryCatchPattern":"p, err := uow.Open(ctx, cfg)\nif err != nil {\n    if strings.Contains(err.Error(), \"uow: ping db:\") {\n        // transient connectivity: back off and retry\n        return retryWithBackoff(ctx, 3, 2*time.Second)\n    }\n    return err\n}","preventionTips":["Start the Dolt SQL server (bd serve / embedded) before opening providers","Health-check the endpoint with a TCP dial or ping before init","Verify host, port, credentials, and TLS config match the server","Use a context with adequate timeout for slow/loaded servers","Check firewall/container networking allows the server port"],"tags":["database","connection","ping","dolt","network"],"backgroundTag":"connection-refused","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}