Documentation
¶
Overview ¶
Package doltserver manages the lifecycle of a local dolt sql-server process. It provides transparent auto-start so that `bd init` and `bd <command>` work without manual server management.
Port assignment uses OS-assigned ephemeral ports by default. When no explicit port is configured (env var, config.yaml, metadata.json), Start() asks the OS for a free port via net.Listen(":0"), passes it to dolt sql-server, and writes the actual port to dolt-server.port. This eliminates the birthday-problem collisions that plagued the old hash-derived port scheme (GH#2098, GH#2372).
Users with explicit port config via BEADS_DOLT_SERVER_PORT env var or config.yaml always use that port instead, with conflict detection via reclaimPort.
Server state files (PID, port, log, lock) live in the .beads/ directory.
Index ¶
- Constants
- func EnsurePortFile(beadsDir string, port int) error
- func EnsureRunning(beadsDir string) (int, error)
- func FlushWorkingSet(host string, port int) error
- func IsPreV56DoltDir(doltDir string) bool
- func IsSharedServerMode() bool
- func KillStaleServers(beadsDir string) ([]int, error)
- func LogPath(beadsDir string) string
- func ReadPortFile(beadsDir string) int
- func RecoverPreV56DoltDir(doltDir string) (bool, error)
- func ResolveDoltDir(beadsDir string) string
- func ResolveServerDir(beadsDir string) string
- func SharedDoltDir() (string, error)
- func SharedServerDir() (string, error)
- func Stop(beadsDir string) error
- func StopWithForce(beadsDir string, force bool) error
- type Config
- type State
Constants ¶
DefaultSharedServerPort is the default port for shared server mode. Uses 3308 to avoid conflict with Gas Town which uses 3307.
Variables ¶
This section is empty.
Functions ¶
func EnsurePortFile ¶
EnsurePortFile makes the repo-local port file match the connected server port. This is a best-effort repair path for upgraded repos that are missing .beads/dolt-server.port even though commands can still connect.
func EnsureRunning ¶
EnsureRunning starts the server if it is not already running. This is the main auto-start entry point. Thread-safe via file lock. Returns the port the server is listening on.
func FlushWorkingSet ¶
FlushWorkingSet connects to the running Dolt server and commits any uncommitted working set changes across all databases. This prevents data loss when the server is about to be stopped or restarted. Returns nil if there's nothing to flush or if the server is not reachable (best-effort).
func IsPreV56DoltDir ¶
IsPreV56DoltDir returns true if doltDir contains a .dolt/ directory that was NOT created by bd 0.56+ (missing .bd-dolt-ok marker). These databases were created by the old embedded Dolt mode and may be incompatible. Used by doctor checks to detect potentially problematic dolt databases.
func IsSharedServerMode ¶
func IsSharedServerMode() bool
IsSharedServerMode returns true if shared server mode is enabled. Checks (in priority order):
- BEADS_DOLT_SHARED_SERVER env var ("1" or "true")
- dolt.shared-server in config.yaml
Shared server mode means all projects on this machine share a single dolt sql-server process at SharedServerDir(), each using its own database (already unique via prefix-based naming in bd init).
func KillStaleServers ¶
KillStaleServers finds and kills orphan dolt sql-server processes not tracked by the canonical PID file. Returns the PIDs of killed processes.
func ReadPortFile ¶
ReadPortFile returns the port from the project's dolt-server.port file, or 0 if the file doesn't exist or is invalid. Exported for use by bd init to detect whether this project has its own running server (GH#2336).
func RecoverPreV56DoltDir ¶
RecoverPreV56DoltDir removes and reinitializes a dolt database that was created by a pre-0.56 bd version. Call this during version upgrade detection (e.g., from autoMigrateOnVersionBump when previousVersion < 0.56).
Pre-0.56 databases used embedded Dolt mode with a different Dolt library version that may produce nil DoltDB values, causing panics (GH#2137). The data is unrecoverable — the fix is to start fresh.
Returns true if recovery was performed, false if not needed.
func ResolveDoltDir ¶
ResolveDoltDir returns the dolt data directory for the given beadsDir. It checks the BEADS_DOLT_DATA_DIR env var and metadata.json for a custom dolt_data_dir, falling back to the default .beads/dolt/ path.
Note: we check for metadata.json existence before calling configfile.Load to avoid triggering the config.json → metadata.json migration side effect, which would create files in the .beads/ directory unexpectedly.
func ResolveServerDir ¶
ResolveServerDir is the exported version of resolveServerDir. CLI commands use this to resolve the server directory before calling Start, Stop, or IsRunning.
func SharedDoltDir ¶
SharedDoltDir returns the dolt data directory for the shared server. Returns ~/.beads/shared-server/dolt/ (created on first use).
func SharedServerDir ¶
SharedServerDir returns the directory for shared server state files. Returns ~/.beads/shared-server/ (created on first use).
func StopWithForce ¶
StopWithForce is like Stop but with an optional force flag.
Types ¶
type Config ¶
type Config struct {
BeadsDir string // Path to .beads/ directory
Port int // MySQL protocol port (0 = allocate ephemeral port on Start)
Host string // Bind address (default: 127.0.0.1)
}
Config holds the server configuration.
func DefaultConfig ¶
DefaultConfig returns config with sensible defaults. Priority: env var > port file > config.yaml / global config > metadata.json. Returns port 0 when no source provides a port, meaning Start() should allocate an ephemeral port from the OS.
The port file (dolt-server.port) is written by Start() with the actual port the server is listening on. Consulting it here ensures that commands connecting to an already-running server use the correct port.
type State ¶
type State struct {
Running bool `json:"running"`
PID int `json:"pid"`
Port int `json:"port"`
DataDir string `json:"data_dir"`
}
State holds runtime information about a managed server.
Source Files