cluster

Documentation

Index

• Constants
• type AliveNodes
• type Cluster
  • func NewCluster[T any](nodes []Node[T], checker NodeChecker[T], closer ConnCloser[T], ...) (*Cluster[T], error)
  • func (cl *Cluster[T]) Alive() Node[T]
  • func (cl *Cluster[T]) Close() error
  • func (cl *Cluster[T]) Err() error
  • func (cl *Cluster[T]) Node(criteria NodeStateCriteria) Node[T]
  • func (cl *Cluster[T]) Nodes() []Node[T]
  • func (cl *Cluster[T]) Primary() Node[T]
  • func (cl *Cluster[T]) PrimaryPreferred() Node[T]
  • func (cl *Cluster[T]) Standby() Node[T]
  • func (cl *Cluster[T]) StandbyPreferred() Node[T]
  • func (cl *Cluster[T]) WaitForAlive(ctx context.Context) (Node[T], error)
  • func (cl *Cluster[T]) WaitForNode(ctx context.Context, criteria NodeStateCriteria) (Node[T], error)
  • func (cl *Cluster[T]) WaitForPrimary(ctx context.Context) (Node[T], error)
  • func (cl *Cluster[T]) WaitForPrimaryPreferred(ctx context.Context) (Node[T], error)
  • func (cl *Cluster[T]) WaitForStandby(ctx context.Context) (Node[T], error)
  • func (cl *Cluster[T]) WaitForStandbyPreferred(ctx context.Context) (Node[T], error)
• type ClusterOption
  • func WithNodePicker[T any](picker NodePicker[T]) ClusterOption[T]
  • func WithTracer[T any](tracer Tracer[T]) ClusterOption[T]
  • func WithUpdateInterval[T any](d time.Duration) ClusterOption[T]
  • func WithUpdateTimeout[T any](d time.Duration) ClusterOption[T]
• type CollectedErrors
  • func (e *CollectedErrors) Error() string
• type ConnCloser
• type Node
  • func NewNode[T any](addr string, db T) Node[T]
• type NodeChecker
• type NodeError
  • func (e *NodeError) Error() string
• type NodePicker
  • func PickNodeClosest[T any]() NodePicker[T]
  • func PickNodeRandom[T any]() NodePicker[T]
  • func PickNodeRoundRobin[T any]() NodePicker[T]
• type NodeStateCriteria
  • func (c NodeStateCriteria) String() string
• type Tracer

Constants

const (
	DefaultUpdateInterval = time.Second * 5
	DefaultUpdateTimeout  = time.Second
)

Default values for cluster config

Types

type AliveNodes

type AliveNodes[T any] struct {
	Alive     []Node[T]
	Primaries []Node[T]
	Standbys  []Node[T]
}

AliveNodes of Cluster

type Cluster

type Cluster[T any] struct {
	// contains filtered or unexported fields
}

Cluster consists of number of 'nodes' of a single SQL database. Background goroutine periodically checks nodes and updates their status.

func NewCluster

func NewCluster[T any](nodes []Node[T],
	checker NodeChecker[T], closer ConnCloser[T],
	opts ...ClusterOption[T]) (*Cluster[T], error)

NewCluster constructs cluster object representing a single 'cluster' of SQL database. Close function must be called when cluster is not needed anymore.

func (*Cluster[T]) Alive

func (cl *Cluster[T]) Alive() Node[T]

Alive returns node that is considered alive

func (*Cluster[T]) Close

func (cl *Cluster[T]) Close() error

Close databases and stop node updates.

func (*Cluster[T]) Err

func (cl *Cluster[T]) Err() error

Err returns the combined error including most recent errors for all nodes. This error is CollectedErrors or nil.

func (*Cluster[T]) Node

func (cl *Cluster[T]) Node(criteria NodeStateCriteria) Node[T]

Node returns cluster node with specified status.

func (*Cluster[T]) Nodes

func (cl *Cluster[T]) Nodes() []Node[T]

Nodes returns list of all nodes

func (*Cluster[T]) Primary

func (cl *Cluster[T]) Primary() Node[T]

Primary returns first available node that is considered alive and is primary (able to execute write operations)

func (*Cluster[T]) PrimaryPreferred

func (cl *Cluster[T]) PrimaryPreferred() Node[T]

PrimaryPreferred returns primary node if possible, standby otherwise

func (*Cluster[T]) Standby

func (cl *Cluster[T]) Standby() Node[T]

Standby returns node that is considered alive and is standby (unable to execute write operations)

func (*Cluster[T]) StandbyPreferred

func (cl *Cluster[T]) StandbyPreferred() Node[T]

StandbyPreferred returns standby node if possible, primary otherwise

func (*Cluster[T]) WaitForAlive

func (cl *Cluster[T]) WaitForAlive(ctx context.Context) (Node[T], error)

WaitForAlive node to appear or until context is canceled

func (*Cluster[T]) WaitForNode

func (cl *Cluster[T]) WaitForNode(ctx context.Context, criteria NodeStateCriteria) (Node[T], error)

WaitForNode with specified status to appear or until context is canceled

func (*Cluster[T]) WaitForPrimary

func (cl *Cluster[T]) WaitForPrimary(ctx context.Context) (Node[T], error)

WaitForPrimary node to appear or until context is canceled

func (*Cluster[T]) WaitForPrimaryPreferred

func (cl *Cluster[T]) WaitForPrimaryPreferred(ctx context.Context) (Node[T], error)

WaitForPrimaryPreferred node to appear or until context is canceled

func (*Cluster[T]) WaitForStandby

func (cl *Cluster[T]) WaitForStandby(ctx context.Context) (Node[T], error)

WaitForStandby node to appear or until context is canceled

func (*Cluster[T]) WaitForStandbyPreferred

func (cl *Cluster[T]) WaitForStandbyPreferred(ctx context.Context) (Node[T], error)

WaitForStandbyPreferred node to appear or until context is canceled

type ClusterOption

type ClusterOption[T any] func(*Cluster[T])

ClusterOption is a functional option type for Cluster constructor

func WithNodePicker

func WithNodePicker[T any](picker NodePicker[T]) ClusterOption[T]

WithNodePicker sets algorithm for node selection (e.g. random, round robin etc)

func WithTracer

func WithTracer[T any](tracer Tracer[T]) ClusterOption[T]

WithTracer sets tracer for actions happening in the background

func WithUpdateInterval

func WithUpdateInterval[T any](d time.Duration) ClusterOption[T]

WithUpdateInterval sets interval between cluster node updates

func WithUpdateTimeout

func WithUpdateTimeout[T any](d time.Duration) ClusterOption[T]

WithUpdateTimeout sets ping timeout for update of each node in cluster

type CollectedErrors

type CollectedErrors struct {
	Errors []NodeError
}

CollectedErrors are errors collected when checking node statuses

func (*CollectedErrors) Error

func (e *CollectedErrors) Error() string

type ConnCloser

type ConnCloser[T any] func(T) error

type Node

type Node[T any] interface {
	fmt.Stringer

	Addr() string
	DB() T
}

Node of single cluster

func NewNode

func NewNode[T any](addr string, db T) Node[T]

NewNode constructs node from pgxpool v5

type NodeChecker

type NodeChecker[T any] func(ctx context.Context, db T) (bool, error)

type NodeError

type NodeError struct {
	Addr       string
	Err        error
	OccurredAt time.Time
}

NodeError is error that background goroutine got while check given node

func (*NodeError) Error

func (e *NodeError) Error() string

type NodePicker

type NodePicker[T any] func(nodes []Node[T]) Node[T]

func PickNodeClosest

func PickNodeClosest[T any]() NodePicker[T]

PickNodeClosest returns node with least latency

func PickNodeRandom

func PickNodeRandom[T any]() NodePicker[T]

PickNodeRandom returns random node from nodes set

func PickNodeRoundRobin

func PickNodeRoundRobin[T any]() NodePicker[T]

PickNodeRoundRobin returns next node based on Round Robin algorithm

type NodeStateCriteria

type NodeStateCriteria int

NodeStateCriteria for choosing a node

const (
	// Alive for choosing any alive node
	Alive NodeStateCriteria = iota + 1
	// Primary for choosing primary node
	Primary
	// Standby for choosing standby node
	Standby
	// PreferPrimary for choosing primary or any alive node
	PreferPrimary
	// PreferStandby for choosing standby or any alive node
	PreferStandby
)

func (NodeStateCriteria) String

func (c NodeStateCriteria) String() string

type Tracer

type Tracer[T any] struct {
	// UpdateNodes is called when before updating nodes status.
	UpdateNodes func()
	// UpdatedNodes is called after all nodes are updated. The nodes is a list of currently alive nodes.
	UpdatedNodes func(nodes AliveNodes[T])
	// NodeDead is called when it is determined that specified node is dead.
	NodeDead func(node Node[T], err error)
	// NodeAlive is called when it is determined that specified node is alive.
	NodeAlive func(node Node[T])
	// NotifiedWaiters is called when all callers of 'WaitFor*' functions have been notified.
	NotifiedWaiters func()
}

Tracer is a set of hooks to run at various stages of background nodes status update. Any particular hook may be nil. Functions may be called concurrently from different goroutines.