cluster

package
v1.22.1-0...-0a71710 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 7, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

README

go-cowsql cluster

The cluster package exposes an opinionated pattern for setting up a resilient COWSQL cluster following the design in use by Incus in production clusters since 2018.

Implementation and Usage

The main entry point to the cluster package is cluster.Gateway.

// Initialize the gateway.
gateway, _ := gateway.NewGateway(ctx, node, clusterCert, serverCertFunc, state)

// Setup your API here, including gateway.HandlerFuncs.
go myServer.Serve(myListener)

// Open the COWSQL database.
driver, _ := gateway.Driver()
sql.Register("my-cowsql", driver)
db, _ := sql.Open("my-cowsql", driver)
gateway.SetClusterDB(db)

NewGateway depends on several interfaces to be set up by the consuming project:

  • State: Related to managing certificates on the filesystem, as well as listener setup and authentication.
  • Node: Used for per-member local store of cluster members.
  • Cluster: Content of the global COWSQL database set up by the cluster package. These methods are used to provide implementations for cluster membership, role changes, recovery, and heartbeats.
  • CertInfo: TLS certificate management for shared cluster certificates and per-member server certificates for TLS-based intra-cluster communication.

Example

An example package is provided, showing basic cluster setup with a recurring heartbeat and role rebalancing.

Note that while TLS is set up in this example, it is not verified for ease of testing.

# Start 3 daemons:
cluster daemon --address 10.0.0.101:8001 --name c1 --dir /tmp/cowsql-c1
cluster daemon --address 10.0.0.101:8002 --name c2 --dir /tmp/cowsql-c2
cluster daemon --address 10.0.0.101:8003 --name c3 --dir /tmp/cowsql-c3

# Bootstrap a cluster with 1 member:
cluster client bootstrap --address 10.0.0.101:8001

# Join an existing cluster from an uninitialized daemon:
cluster client join --address 10.0.0.101:8002 --target 10.0.0.101:8001
cluster client join --address 10.0.0.101:8003 --target 10.0.0.101:8001

# List cluster members:
cluster client list --address 10.0.0.101:8002

Name: "c1"  Address: "10.0.0.101:8001"  Role: "voter"  Offline: false
Name: "c2"  Address: "10.0.0.101:8002"  Role: "voter"  Offline: false
Name: "c3"  Address: "10.0.0.101:8003"  Role: "voter"  Offline: false

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func HasConnectivity

func HasConnectivity(networkCert tls.CertInfo, serverCert tls.CertInfo, address string, useTLS12 bool) bool

HasConnectivity probes the member with the given address for connectivity.

Types

type Gateway

type Gateway interface {
	HandlerFuncs(auth func(w http.ResponseWriter, r *http.Request) bool) map[string]http.HandlerFunc
	WaitUpgradeNotification()
	Initialized() bool
	DialFunc() client.DialFunc
	Context() context.Context
	NodeStore() client.NodeStore
	TransferLeadership(ctx context.Context) error
	DemoteOfflineNode(raftID uint64) error
	Cancel()
	ShutdownServer() error
	Stop(connTimeout time.Duration) error
	Sync()
	Reset(networkCert tls.CertInfo) error
	HeartbeatCancelFunc() func()
	NetworkUpdateCert(cert tls.CertInfo)
	WaitLeadership() error
	LeaderAddress() (string, error)
	HeartbeatRestart() bool
	Node() db.Node
	Cluster() db.Cluster
	Initialize(bootstrap bool) error
	CurrentRaftNodes(ctx context.Context) ([]db.RaftNode, error)
	Options() *options.Options
	HeartbeatOfflineThreshold() time.Duration
	RaftDial() client.DialFunc
	Standalone() bool
	NetworkCert() tls.CertInfo
	RaftNode() *db.RaftNode
	SetRaftNode(n *db.RaftNode)
	RaftClient(ctx context.Context) (*client.Client, error)
	AwaitHeartbeat()
	SetClusterDB(db.Cluster)
	HeartbeatInterval() time.Duration
	Heartbeat(ctx context.Context, m heartbeat.Mode)
	SetHeartbeatOfflineThreshold(time.Duration)
	SetHeartbeatNodeHook(f heartbeat.Hook)
	State() state.State
	ServerCert() tls.CertInfo
	NewNotifier(ctx context.Context, networkCert tls.CertInfo, serverCert tls.CertInfo, policy NotifierPolicy) (Notifier, error)
	IsLeader(ctx context.Context) (bool, error)
	Driver(opts ...driver.Option) (*driver.Driver, error)
}

Gateway represents the cluster gateway implementation.

type Notifier

type Notifier func(hook func(ctx context.Context, address string, networkCert, serverCert tls.CertInfo) error) []error

Notifier is a function that invokes the given function against each node in the cluster excluding the invoking one.

type NotifierPolicy

type NotifierPolicy int

NotifierPolicy can be used to tweak the behavior of NewNotifier in case of some nodes are down.

const (
	NotifyAll    NotifierPolicy = iota // Requires that all nodes are up.
	NotifyAlive                        // Only notifies nodes that are alive
	NotifyTryAll                       // Attempt to notify all nodes regardless of state.
)

Possible notification policies.

Directories

Path Synopsis
db
cmd command
tls
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL