serverid

Documentation

Overview

Package serverid manages persistent server identities for bintrail. Each source server is assigned a unique bintrail_id (UUID) on first contact — keyed on the server's @@server_uuid for MySQL, or on a synthesized address-derived anchor for MariaDB (which has no @@server_uuid; see SyntheticServerUUID). Identity resolution uses five rules to handle UUID regeneration, host migration, and cloned-server conflicts while preserving the bintrail_id.

Index

• Constants
• Variables
• func DecommissionServer(ctx context.Context, db *sql.DB, bintrailID string) error
• func DeriveServerID(dsn string) (uint32, error)
• func ResolveServer(ctx context.Context, db *sql.DB, serverUUID, host string, port uint16, ...) (string, error)
• func SyntheticServerUUID(host string, port uint16) string
• type Server

Constants

const DDLBintrailServerChanges = `` /* 505-byte string literal not displayed */

DDLBintrailServerChanges is the canonical CREATE TABLE statement for bintrail_server_changes. Append-only audit trail — never update or delete rows.

const DDLBintrailServers = `` /* 676-byte string literal not displayed */

DDLBintrailServers is the canonical CREATE TABLE statement for bintrail_servers. Used by `bintrail init` and by testutil.InitIndexTables to ensure a single source of truth for the schema.

Variables

var ErrConflict = errors.New("server identity conflict: server_uuid and host:port:username match different records — resolve manually")

ErrConflict is returned by ResolveServer when the observed server_uuid matches one active record while the observed host+port+username matches a different active record — a cloned-server situation that requires manual resolution.

Functions

func DecommissionServer

func DecommissionServer(ctx context.Context, db *sql.DB, bintrailID string) error

DecommissionServer sets decommissioned_at on the given bintrail_id, excluding it from future identity resolution. The record and its archived data are preserved.

func DeriveServerID

func DeriveServerID(dsn string) (uint32, error)

DeriveServerID returns a deterministic uint32 server-id by hashing the source DSN's host:user:dbname triple. The same DSN always produces the same ID, so `bintrail up` resumes cleanly across restarts without the user remembering what server-id they used last time.

Returns an error when the DSN cannot be parsed — callers must handle this rather than silently substituting a non-deterministic value, because a per-invocation ID breaks the resume-from-checkpoint contract (MySQL would treat each restart as a new replica).

func ResolveServer

func ResolveServer(ctx context.Context, db *sql.DB, serverUUID, host string, port uint16, username string) (string, error)

ResolveServer looks up or registers a server in bintrail_servers, returning its stable bintrail_id. It runs inside a transaction with SELECT ... FOR UPDATE to prevent concurrent callers from creating duplicate active entries for the same server. Any detected component changes are recorded in bintrail_server_changes.

Returns ErrConflict if server_uuid and host+port+username match two different active records (cloned-server situation). The caller should log a warning and refuse to operate until the conflict is resolved manually.

func SyntheticServerUUID

func SyntheticServerUUID(host string, port uint16) string

SyntheticServerUUID returns a deterministic UUIDv5 identity anchor for a source that exposes no @@server_uuid (i.e. MariaDB). It is derived from the source's host:port so that:

• the same server resolves to the same anchor across restarts (stable bintrail_id, stable archive prefix), and
• two different MariaDB servers — necessarily reachable at distinct addresses — resolve to distinct anchors, so they auto-separate into distinct bintrail_id=<uuid>/ Parquet prefixes instead of colliding.

The anchor feeds ResolveServer exactly like a real @@server_uuid: it is the strong re-identification key, while the bintrail_id itself stays a fresh random UUID assigned on first contact. Deriving from the address means a server moved to a new host gets a new identity — an accepted MariaDB limitation (MySQL's @@server_uuid survives migration; MariaDB has no equivalent), not a correctness bug.

Types

type Server

type Server struct {
	BintrailID string
	ServerUUID string
	Host       string
	Port       uint16
	Username   string
}

Server represents an active row in bintrail_servers.