cluster

Documentation

Index

• Constants
• Variables
• func FreshSchema() string
• type APIExtensions
• type BasicAPIExtensions
  • func NewBasicAPIExtensions(count int) *BasicAPIExtensions
  • func (e *BasicAPIExtensions) Count() int
• type Cluster
  • func New(apiExtensions APIExtensions, schemaProvider SchemaProvider, options ...Option) *Cluster
  • func (c *Cluster) DB() database.DB
  • func (c *Cluster) EnsureSchema(address string, dir string) (bool, error)
  • func (c *Cluster) Open(store ServerStore, options ...dqlite.DriverOption) error
  • func (c *Cluster) SchemaVersion() int
• type DQliteNameProvider
  • func (p *DQliteNameProvider) DriverName() string
• type DatabaseDriver
• type DatabaseIO
• type DatabaseOpener
• type DatabaseRegistrar
• type NameProvider
• type Option
  • func WithAPIExtensions(apiExtensions APIExtensions) Option
  • func WithDatabase(database database.DB) Option
  • func WithDatabaseIO(databaseIO DatabaseIO) Option
  • func WithFileSystem(fileSystem fsys.FileSystem) Option
  • func WithNameProvider(nameProvider NameProvider) Option
  • func WithSchemaProvider(schemaProvider SchemaProvider) Option
  • func WithSleeper(sleeper clock.Sleeper) Option
• type Schema
• type SchemaProvider
  • func NewSchema(fileSysyem fsys.FileSystem) SchemaProvider
• type ServerInfo
• type ServerStore

Constants

const StmtSelectNodesVersions = `
SELECT schema, api_extensions FROM nodes
`

StmtSelectNodesVersions defines the SQL template for selecting a schema and api_extensions from nodes.

const StmtUpdateNodeVersion = `
UPDATE nodes SET schema=?, api_extensions=? WHERE address=?
`

StmtUpdateNodeVersion defines the SQL template for updating a node version

Variables

var ErrSomeNodesAreBehind = errors.New("some nodes are behind this node's version")

ErrSomeNodesAreBehind states if some nodes are behind and can be used to identify when this happens.

var StmtInitialNode = `` /* 226-byte string literal not displayed */

StmtInitialNode defines a transactional statement for inserting a new node into the db

Functions

func FreshSchema

func FreshSchema() string

FreshSchema returns the fresh schema definition of the global database.

Types

type APIExtensions

type APIExtensions interface {
	// Count returns the number of APIExtensions are available.
	Count() int
}

APIExtensions represents the various API Extensions there are to offer.

type BasicAPIExtensions

type BasicAPIExtensions struct {
	// contains filtered or unexported fields
}

BasicAPIExtensions represents the various API Extensions there are to offer.

func NewBasicAPIExtensions

func NewBasicAPIExtensions(count int) *BasicAPIExtensions

NewBasicAPIExtensions creates simple APIExtensions provider

func (*BasicAPIExtensions) Count

func (e *BasicAPIExtensions) Count() int

Count returns the number of APIExtensions are available.

type Cluster

type Cluster struct {
	// contains filtered or unexported fields
}

Cluster represents a cluster of database nodes, in the sense that you can open and query a cluster.

func New

func New(apiExtensions APIExtensions, schemaProvider SchemaProvider, options ...Option) *Cluster

New creates a cluster ensuring that sane defaults are employed.

func (*Cluster) DB

func (c *Cluster) DB() database.DB

DB return the current database source.

func (*Cluster) EnsureSchema

func (c *Cluster) EnsureSchema(address string, dir string) (bool, error)

EnsureSchema applies all relevant schema updates to the cluster database.

Before actually doing anything, this function will make sure that all nodes in the cluster have a schema version and a number of API extensions that match our one. If it's not the case, we either return an error (if some nodes have version greater than us and we need to be upgraded), or return false and no error (if some nodes have a lower version, and we need to wait till they get upgraded and restarted).

func (*Cluster) Open

func (c *Cluster) Open(store ServerStore, options ...dqlite.DriverOption) error

Open the cluster database object.

The name argument is the name of the cluster database. It defaults to 'db.bin', but can be overwritten for testing.

The dialer argument is a function that returns a gRPC dialer that can be used to connect to a database node using the gRPC SQL package.

func (*Cluster) SchemaVersion

func (c *Cluster) SchemaVersion() int

SchemaVersion returns the underlying schema version for the cluster

type DQliteNameProvider

type DQliteNameProvider struct{}

DQliteNameProvider creates a new name provider for the cluster

func (*DQliteNameProvider) DriverName

func (p *DQliteNameProvider) DriverName() string

DriverName generates a new name for the dqlite driver registration. We need it to be unique for testing, see below.

type DatabaseDriver

type DatabaseDriver interface {

	// Create a new driver from a given Dialer
	Create(ServerStore, ...dqlite.DriverOption) (driver.Driver, error)
}

DatabaseDriver represents a way to create a new database driver.

type DatabaseIO

type DatabaseIO interface {
	DatabaseDriver
	DatabaseRegistrar
	DatabaseOpener
}

DatabaseIO captures all the input/output (IO) of the database in one logical interface.

type DatabaseOpener

type DatabaseOpener interface {
	// Open opens a database specified by its database driver name and a
	// driver-specific data source name, usually consisting of at least a
	// database name and connection information.
	Open(driverName, dataSourceName string) (database.DB, error)
}

DatabaseOpener represents a way to open a database source

type DatabaseRegistrar

type DatabaseRegistrar interface {
	// Register makes a database driver available by the provided name.
	// If Register is called twice with the same name or if driver is nil,
	// it panics.
	Register(name string, driver driver.Driver)

	// Drivers returns a sorted list of the names of the registered drivers.
	Drivers() []string
}

DatabaseRegistrar represents a way to register and un-register drivers with associated name.

type NameProvider

type NameProvider interface {
	// DriverName returns a unique name for a driver.
	DriverName() string
}

NameProvider represents a way to get names for getting names for specific flows.

type Option

type Option func(*options)

Option to be passed to NewRaft to customize the resulting instance.

func WithAPIExtensions

func WithAPIExtensions(apiExtensions APIExtensions) Option

WithAPIExtensions sets the api extensions on the options

func WithDatabase

func WithDatabase(database database.DB) Option

WithDatabase sets the database on the options

func WithDatabaseIO

func WithDatabaseIO(databaseIO DatabaseIO) Option

WithDatabaseIO sets the database IO on the options

func WithFileSystem

func WithFileSystem(fileSystem fsys.FileSystem) Option

WithFileSystem sets the file system on the options

func WithNameProvider

func WithNameProvider(nameProvider NameProvider) Option

WithNameProvider sets the name provider on the options

func WithSchemaProvider

func WithSchemaProvider(schemaProvider SchemaProvider) Option

WithSchemaProvider sets the schema provider on the options

func WithSleeper

func WithSleeper(sleeper clock.Sleeper) Option

WithSleeper sets the sleeper on the options

type Schema

type Schema interface {

	// Fresh sets a statement that will be used to create the schema from scratch
	// when bootstraping an empty database. It should be a "flattening" of the
	// available updates, generated using the Dump() method. If not given, all
	// patches will be applied in order.
	Fresh(string)
	// File extra queries from a file. If the file is exists, all SQL queries in it
	// will be executed transactionally at the very start of Ensure(), before
	// anything else is done.
	File(string)
	// Check instructs the schema to invoke the given function whenever Ensure is
	// invoked, before applying any due update. It can be used for aborting the
	// operation.
	Check(schema.Check)
	// Hook instructs the schema to invoke the given function whenever a update is
	// about to be applied. The function gets passed the update version number and
	// the running transaction, and if it returns an error it will cause the schema
	// transaction to be rolled back. Any previously installed hook will be
	// replaced.
	Hook(schema.Hook)

	// Ensure makes sure that the actual schema in the given database matches the
	// one defined by our updates.
	//
	// All updates are applied transactionally. In case any error occurs the
	// transaction will be rolled back and the database will remain unchanged.
	Ensure(database.DB) (int, error)
}

Schema captures the schema of a database in terms of a series of ordered updates.

type SchemaProvider

type SchemaProvider interface {

	// Schema creates a new Schema that captures the schema of a database in
	// terms of a series of ordered updates.
	Schema() Schema

	// Updates returns the schema updates that is required for the updating of
	// the database.
	Updates() []schema.Update
}

SchemaProvider defines a factory for creating schemas

func NewSchema

func NewSchema(fileSysyem fsys.FileSystem) SchemaProvider

NewSchema creates a schema for updating a cluster node

type ServerInfo

type ServerInfo struct {
	ID      uint64
	Address string
}

ServerInfo is the Go equivalent of dqlite_server_info.

type ServerStore

type ServerStore interface {
	// Get return the list of known servers.
	Get(context.Context) ([]ServerInfo, error)

	// Set updates the list of known cluster servers.
	Set(context.Context, []ServerInfo) error
}

ServerStore is used by a dqlite client to get an initial list of candidate dqlite servers that it can dial in order to find a leader server to connect to.

Once connected, the client periodically updates the server addresses in the store by querying the leader about changes in the cluster (such as servers being added or removed).