#6599·beads

bd doctor: Phantom Databases check false-positives on shared-server mode's own beads_global database

Author: FatimaMashoodCreated Sep 17, 2026Updated Sep 17, 2026

Summary

bd doctor's "Phantom Databases" check (checkPhantomDatabases in cmd/bd/doctor/dolt.go) always flags beads_global as a phantom entry on any repo running shared-server mode with a global_dolt_database configured in metadata.json — even though that database is legitimate, in active use, and was created intentionally by bd itself for shared-server/global routing.

This is a false positive, not a stale catalog entry. Restarting the Dolt server (the check's own suggested Fix, citing GH#2051) does not and cannot clear it, because there is nothing to clear — the database is real, populated with the expected shared-server schema (issues, dependencies, wisps, routes, federation_peers, etc.), and gets recreated by CREATE DATABASE IF NOT EXISTS on the next command anyway.

Reproduction

bash
# .beads/config.yaml
dolt.shared-server: true

# .beads/metadata.json
{
  "dolt_mode": "server",
  "dolt_database": "workflow_management",
  "global_dolt_database": "beads_global"
}
$ bd doctor
  ⚠  Phantom Databases: 1 phantom database(s) detected: beads_global
      Phantom entries: [beads_global]
      └─ Restart Dolt server to flush phantom entries. See GH#2051.
sql
-- but the database is real and correctly populated:
show databases;
-- beads_global | dolt | information_schema | mysql | workflow_management
use beads_global; show tables;
-- blocked_issues, child_counters, comments, ..., issues, ..., wisps

Restarting the dolt sql-server process does not clear the warning (verified — killed and restarted the server process, warning persists identically).

Root cause

checkPhantomDatabases (cmd/bd/doctor/dolt.go, confirmed present unchanged through v1.3.0) only excludes information_schema, mysql, and conn.cfg.GetDoltDatabase() (the project database) before flagging anything matching the beads_*/*_beads naming convention:

go
configuredDB := configfile.DefaultDoltDatabase
if conn.cfg != nil {
    configuredDB = conn.cfg.GetDoltDatabase()
}
...
if dbName == "information_schema" || dbName == "mysql" || dbName == configuredDB {
    continue
}
if strings.HasPrefix(dbName, "beads_") || strings.HasSuffix(dbName, "_beads") {
    phantoms = append(phantoms, dbName)
}

It never checks conn.cfg.GetGlobalDoltDatabase() (or the config's global_dolt_database / doltserver.GlobalDatabaseName), so the shared-server global database — which is named beads_global by convention and therefore always matches the beads_* prefix pattern — is unconditionally flagged on every repo using shared-server mode with a global database configured.

This looks like the same class of gap flagged in #2091's own test matrix ("Config DB not phantom | Configured DB matching beads_* | StatusOK") but that test case only covers the primary dolt_database, not the second, equally-legitimate global_dolt_database.

Suggested fix

In checkPhantomDatabases, also skip conn.cfg.GetGlobalDoltDatabase() (however that's currently surfaced on the config struct) before the beads_*/*_beads pattern check, mirroring the existing configuredDB skip.

Environment

  • bd version 1.0.4 (also confirmed present, unchanged, in v1.3.0's checkPhantomDatabases source)
  • Dolt shared-server mode (dolt.shared-server: true), macOS