dbaccessor

Documentation

Index

• Constants
• func Manifold(config ManifoldConfig) dependency.Manifold
• func NewWorker(cfg WorkerConfig) (*dbWorker, error)
• type Client
• type ClusterConfig
• type Collector
  • func NewMetricsCollector() *Collector
  • func (c *Collector) Collect(ch chan<- prometheus.Metric)
  • func (c *Collector) DBMetricsForNamespace(namespace string) txn.Metrics
  • func (c *Collector) Describe(ch chan<- *prometheus.Desc)
• type DBApp
  • func NewApp(dataDir string, options ...app.Option) (DBApp, error)
  • func WrapApp(dqliteApp *app.App) DBApp
• type DBGetter
• type ManifoldConfig
  • func (cfg ManifoldConfig) Validate() error
• type NewDBWorkerFunc
• type NewNodeManagerFunc
• type NodeManager
  • func CAASNodeManager(cfg agent.Config, logger logger.Logger, ...) NodeManager
  • func IAASNodeManager(cfg agent.Config, logger logger.Logger, ...) NodeManager
• type TrackedDB
  • func NewTrackedDBWorker(ctx context.Context, dbApp DBApp, namespace string, ...) (TrackedDB, error)
• type TrackedDBWorkerOption
  • func WithClock(clock clock.Clock) TrackedDBWorkerOption
  • func WithLogger(logger logger.Logger) TrackedDBWorkerOption
  • func WithMetricsCollector(metrics *Collector) TrackedDBWorkerOption
  • func WithPingDBFunc(f func(context.Context, *sql.DB) error) TrackedDBWorkerOption
• type WorkerConfig
  • func (c *WorkerConfig) Validate() error

Constants

const (
	// PollInterval is the amount of time to wait between polling the database.
	PollInterval = time.Second * 10

	// DefaultVerifyAttempts is the number of attempts to verify the database,
	// by opening a new database on verification failure.
	DefaultVerifyAttempts = 3
)

Functions

func Manifold

func Manifold(config ManifoldConfig) dependency.Manifold

Manifold returns a dependency manifold that runs the dbaccessor worker, using the resource names defined in the supplied config.

func NewWorker

func NewWorker(cfg WorkerConfig) (*dbWorker, error)

NewWorker creates a new dbaccessor worker.

Types

type Client

type Client interface {
	// Cluster returns the current state of the Dqlite cluster.
	Cluster(context.Context) ([]dqlite.NodeInfo, error)
	// Leader returns information about the current leader, if any.
	Leader(ctx context.Context) (*dqlite.NodeInfo, error)
}

Client describes a client that speaks the Dqlite wire protocol, and can retrieve cluster information.

type ClusterConfig

type ClusterConfig interface {
	// DBBindAddresses returns a map of addresses keyed by controller unit ID.
	DBBindAddresses() (map[string]string, error)
}

ClusterConfig describes the ability to retrieve cluster configuration.

type Collector

type Collector struct {
	DBRequests  *prometheus.GaugeVec
	DBDuration  *prometheus.HistogramVec
	DBErrors    *prometheus.CounterVec
	DBSuccess   *prometheus.CounterVec
	TxnRequests *prometheus.CounterVec
	TxnRetries  *prometheus.CounterVec
}

Collector defines a prometheus collector for the dbaccessor.

func NewMetricsCollector

func NewMetricsCollector() *Collector

NewMetricsCollector returns a new Collector.

func (*Collector) Collect

func (c *Collector) Collect(ch chan<- prometheus.Metric)

Collect is part of the prometheus.Collector interface.

func (*Collector) DBMetricsForNamespace

func (c *Collector) DBMetricsForNamespace(namespace string) txn.Metrics

DBMetricsForNamespace returns a Metrics implementation for the given namespace.

func (*Collector) Describe

func (c *Collector) Describe(ch chan<- *prometheus.Desc)

Describe is part of the prometheus.Collector interface.

type DBApp

type DBApp interface {
	// Open the dqlite database with the given name
	Open(context.Context, string) (*sql.DB, error)

	// Ready can be used to wait for a node to complete tasks that
	// are initiated at startup. For example a new node will attempt
	// to join the cluster, a restarted node will check if it should
	// assume some particular role, etc.
	//
	// If this method returns without error it means that those initial
	// tasks have succeeded and follow-up operations like Open() are more
	// likely to succeed quickly.
	Ready(context.Context) error

	// Client returns a client that can be used
	// to interrogate the Dqlite cluster.
	Client(ctx context.Context) (Client, error)

	// Handover transfers all responsibilities for this node (such has
	// leadership and voting rights) to another node, if one is available.
	//
	// This method should always be called before invoking Close(),
	// in order to gracefully shut down a node.
	Handover(context.Context) error

	// ID returns the dqlite ID of this application node.
	ID() uint64

	// Address returns the bind address of this application node.
	Address() string

	// Close the application node, releasing all resources it created.
	Close() error
}

DBApp describes methods of a Dqlite database application, required to run this host as a Dqlite node.

func NewApp

func NewApp(dataDir string, options ...app.Option) (DBApp, error)

NewApp creates a new DQlite application.

func WrapApp

func WrapApp(dqliteApp *app.App) DBApp

WrapApp wraps a Dqlite App reference, so that we can shim out Client.

type DBGetter

type DBGetter interface {
	// GetDB returns a sql.DB reference for the dqlite-backed database that
	// contains the data for the specified namespace.
	// A NotFound error is returned if the worker is unaware of the requested DB.
	GetDB(namespace string) (database.TxnRunner, error)
}

DBGetter describes the ability to supply a sql.DB reference for a particular database.

type ManifoldConfig

type ManifoldConfig struct {
	AgentName                 string
	QueryLoggerName           string
	ControllerAgentConfigName string
	Clock                     clock.Clock
	Logger                    logger.Logger
	LogDir                    string
	PrometheusRegisterer      prometheus.Registerer
	NewApp                    func(string, ...app.Option) (DBApp, error)
	NewDBWorker               NewDBWorkerFunc
	NewNodeManager            NewNodeManagerFunc
	NewMetricsCollector       func() *Collector
}

ManifoldConfig contains: - The names of other manifolds on which the DB accessor depends. - Other dependencies from ManifoldsConfig required by the worker.

func (ManifoldConfig) Validate

func (cfg ManifoldConfig) Validate() error

type NewDBWorkerFunc

type NewDBWorkerFunc func(context.Context, DBApp, string, ...TrackedDBWorkerOption) (TrackedDB, error)

NewDBWorkerFunc creates a tracked db worker.

type NewNodeManagerFunc

type NewNodeManagerFunc func(agent.Config, logger.Logger, coredatabase.SlowQueryLogger) NodeManager

NewNodeManagerFunc creates a NodeManager

type NodeManager

type NodeManager interface {
	// IsExistingNode returns true if this machine of container has run a
	// Dqlite node in the past.
	IsExistingNode() (bool, error)

	// IsLoopbackPreferred returns true if the Dqlite application should
	// be bound to the loopback address.
	IsLoopbackPreferred() bool

	// IsLoopbackBound returns true if we are a cluster of one,
	// and bound to the loopback IP address.
	IsLoopbackBound(context.Context) (bool, error)

	// EnsureDataDir ensures that a directory for Dqlite data exists at
	// a path determined by the agent config, then returns that path.
	EnsureDataDir() (string, error)

	// ClusterServers returns the node information for
	// Dqlite nodes configured to be in the cluster.
	ClusterServers(context.Context) ([]dqlite.NodeInfo, error)

	//SetClusterServers reconfigures the Dqlite cluster members.
	SetClusterServers(context.Context, []dqlite.NodeInfo) error

	// SetNodeInfo rewrites the local node information
	// file in the Dqlite data directory.
	SetNodeInfo(dqlite.NodeInfo) error

	// SetClusterToLocalNode reconfigures the Dqlite cluster
	// so that it has the local node as its only member.
	SetClusterToLocalNode(ctx context.Context) error

	// WithLogFuncOption returns a Dqlite application Option that will proxy Dqlite
	// log output via this factory's logger where the level is recognised.
	WithLogFuncOption() app.Option

	// WithTracingOption returns a Dqlite application Option
	// that will enable tracing of Dqlite operations.
	WithTracingOption() app.Option

	// WithAddressOption returns a Dqlite application Option
	// for specifying the local address:port to use.
	WithAddressOption(string) app.Option

	// WithTLSOption returns a Dqlite application Option for TLS encryption
	// of traffic between clients and clustered application nodes.
	WithTLSOption() (app.Option, error)

	// WithClusterOption returns a Dqlite application Option for initialising
	// Dqlite as the member of a cluster with peers representing other controllers.
	WithClusterOption([]string) app.Option
}

NodeManager creates Dqlite `App` initialisation arguments and options.

func CAASNodeManager

func CAASNodeManager(cfg agent.Config, logger logger.Logger, slowQueryLogger coredatabase.SlowQueryLogger) NodeManager

CAASNodeManager returns a NodeManager that is configured to use the loopback address for Dqlite.

func IAASNodeManager

func IAASNodeManager(cfg agent.Config, logger logger.Logger, slowQueryLogger coredatabase.SlowQueryLogger) NodeManager

IAASNodeManager returns a NodeManager that is configured to use the cloud-local TLS terminated address for Dqlite.

type TrackedDB

type TrackedDB interface {
	coredatabase.TxnRunner
	worker.Worker
}

TrackedDB defines the union of a TxnRunner and a worker.Worker interface. This is local to the package, allowing for better testing of the underlying trackedDB worker.

func NewTrackedDBWorker

func NewTrackedDBWorker(
	ctx context.Context, dbApp DBApp, namespace string, opts ...TrackedDBWorkerOption,
) (TrackedDB, error)

NewTrackedDBWorker creates a new TrackedDBWorker

type TrackedDBWorkerOption

type TrackedDBWorkerOption func(*trackedDBWorker)

TrackedDBWorkerOption is a function that configures a TrackedDBWorker.

func WithClock

func WithClock(clock clock.Clock) TrackedDBWorkerOption

WithClock sets the clock used by the worker.

func WithLogger

func WithLogger(logger logger.Logger) TrackedDBWorkerOption

WithLogger sets the logger used by the worker.

func WithMetricsCollector

func WithMetricsCollector(metrics *Collector) TrackedDBWorkerOption

WithMetricsCollector sets the metrics collector used by the worker.

func WithPingDBFunc

func WithPingDBFunc(f func(context.Context, *sql.DB) error) TrackedDBWorkerOption

WithPingDBFunc sets the function used to verify the database connection.

type WorkerConfig

type WorkerConfig struct {
	NodeManager      NodeManager
	Clock            clock.Clock
	MetricsCollector *Collector

	Logger      logger.Logger
	NewApp      func(string, ...app.Option) (DBApp, error)
	NewDBWorker NewDBWorkerFunc

	// ControllerID uniquely identifies the controller that this
	// worker is running on. It is equivalent to the machine ID.
	ControllerID string

	// ControllerConfigWatcher is used to get notifications when the controller
	// agent configuration changes on disk. When it changes, we must reload it
	// and assess potential changes to the database cluster.
	ControllerConfigWatcher controlleragentconfig.ConfigWatcher

	// ClusterConfig supplies bind addresses used for Dqlite clustering.
	ClusterConfig ClusterConfig
}

WorkerConfig encapsulates the configuration options for the dbaccessor worker.

func (*WorkerConfig) Validate

func (c *WorkerConfig) Validate() error

Validate ensures that the config values are valid.