The highest tagged major version is
README
¶
go-dqlite v2
This branch (v2) is used to develop major version 2 of go-dqlite, which is an
LTS release series. You can depend on it with
$ go get github.com/canonical/go-dqlite/v2
This release series will only include fixes for security issues and other major
bugs, not new features. Mainline development happens on v3. For more
information about go-dqlite, see the v3 README.
Documentation
¶
Index ¶
- Constants
- func ConfigMultiThread() error
- func GenerateID(address string) uint64
- func ReconfigureMembership(dir string, cluster []NodeInfo) errordeprecated
- func ReconfigureMembershipExt(dir string, cluster []NodeInfo) error
- type LastEntryInfo
- type Node
- type NodeInfo
- type Option
- func WithAutoRecovery(recovery bool) Option
- func WithBindAddress(address string) Option
- func WithDialFunc(dial client.DialFunc) Option
- func WithDiskMode(disk bool) Option
- func WithFailureDomain(code uint64) Option
- func WithNetworkLatency(latency time.Duration) Option
- func WithSnapshotParams(params SnapshotParams) Option
- type SnapshotParams
Examples ¶
Constants ¶
const BootstrapID = 0x2dc171858c3155be
BootstrapID is a magic ID that should be used for the fist node in a cluster. Alternatively ID 1 can be used as well.
Variables ¶
This section is empty.
Functions ¶
func ConfigMultiThread ¶
func ConfigMultiThread() error
ConfigMultiThread sets the threading mode of SQLite to Multi-thread.
By default go-dqlite configures SQLite to Single-thread mode, because the dqlite engine itself is single-threaded, and enabling Multi-thread or Serialized modes would incur in a performance penality.
If your Go process also uses SQLite directly (e.g. using the github.com/mattn/go-sqlite3 bindings) you might need to switch to Multi-thread mode in order to be thread-safe.
IMPORTANT: It's possible to successfully change SQLite's threading mode only if no SQLite APIs have been invoked yet (e.g. no database has been opened yet). Therefore you'll typically want to call ConfigMultiThread() very early in your process setup. Alternatively you can set the GO_DQLITE_MULTITHREAD environment variable to 1 at process startup, in order to prevent go-dqlite from setting Single-thread mode at all.
func GenerateID ¶
GenerateID generates a unique ID for a new node, based on a hash of its address and the current time.
func ReconfigureMembership
deprecated
ReconfigureMembership forces a new cluster configuration.
Deprecated: this function ignores the provided node roles and makes every node in the new configuration a voter. Use ReconfigureMembershipExt, which respects the provided roles.
func ReconfigureMembershipExt ¶
ReconfigureMembershipExt forces a new cluster configuration.
This function is useful to revive a cluster that can't achieve quorum in its old configuration because some nodes can't be brought online. Forcing a new configuration is unsafe, and you should follow these steps to avoid data loss and inconsistency:
- Make sure no dqlite node in the cluster is running.
- Identify all dqlite nodes that have survived and that you want to be part of the recovered cluster. Call this the "new member list".
- Call ReadLastEntryInfo on each node in the member list, and find which node has the most recent entry according to LastEntryInfo.Before. Call this the "template node".
- Invoke ReconfigureMembershipExt exactly one time, on the template node. The arguments are the data directory of the template node and the new member list.
- Copy the data directory of the template node to all other nodes in the new member list, replacing their previous data directories.
- Restart all nodes in the new member list.
Types ¶
type LastEntryInfo ¶
type LastEntryInfo struct {
Term, Index uint64
}
LastEntryInfo holds information about the last entry in the persistent raft log of a node.
The zero value is not a valid entry description, and can be used as a sentinel.
Example ¶
package main
import (
"fmt"
"sort"
dqlite "github.com/canonical/go-dqlite/v2"
)
type infoSorter []dqlite.LastEntryInfo
func (is infoSorter) Len() int {
return len(is)
}
func (is infoSorter) Less(i, j int) bool {
return is[i].Before(is[j])
}
func (is infoSorter) Swap(i, j int) {
is[i], is[j] = is[j], is[i]
}
func main() {
infos := []dqlite.LastEntryInfo{
{Term: 1, Index: 2},
{Term: 2, Index: 2},
{Term: 1, Index: 1},
{Term: 2, Index: 1},
}
sort.Sort(infoSorter(infos))
fmt.Println(infos)
}
Output: [{1 1} {1 2} {2 1} {2 2}]
func ReadLastEntryInfo ¶
func ReadLastEntryInfo(dir string) (LastEntryInfo, error)
ReadLastEntryInfo reads information about the last entry in the raft persistent log from a node's data directory.
This is intended to be used during the cluster recovery process, see ReconfigureMembershipExt. The node must not be running.
This is a non-destructive operation, but is not read-only, since it has the side effect of renaming raft open segment files to closed segment files.
func (LastEntryInfo) Before ¶
func (lhs LastEntryInfo) Before(rhs LastEntryInfo) bool
Before tells whether the entry described by the receiver is strictly less recent than another entry.
Entry A is less recent than entry B when A has a lower term number, or when A and B have the same term number and A has a lower index.
type Node ¶
type Node struct {
// contains filtered or unexported fields
}
Node runs a dqlite node.
func (*Node) BindAddress ¶
BindAddress returns the network address the node is listening to.
type Option ¶
type Option func(*options)
Option can be used to tweak node parameters.
func WithAutoRecovery ¶
WithAutoRecovery enables or disables auto-recovery of persisted data at startup for this node.
When auto-recovery is enabled, raft snapshots and segment files may be deleted at startup if they are determined to be corrupt. This helps the startup process to succeed in more cases, but can lead to data loss.
Auto-recovery is enabled by default.
func WithBindAddress ¶
WithBindAddress sets a custom bind address for the server.
func WithDialFunc ¶
WithDialFunc sets a custom dial function for the server.
func WithDiskMode ¶
WithDiskMode enables dqlite disk-mode on the node. WARNING: This is experimental API, use with caution and prepare for data loss. UNSTABLE: Behavior can change in future. NOT RECOMMENDED for production use-cases, use at own risk.
func WithFailureDomain ¶
WithFailureDomain sets the code of the failure domain the node belongs to.
func WithNetworkLatency ¶
WithNetworkLatency sets the average one-way network latency.
func WithSnapshotParams ¶
func WithSnapshotParams(params SnapshotParams) Option
WithSnapshotParams sets the snapshot parameters of the node.
type SnapshotParams ¶
type SnapshotParams = bindings.SnapshotParams
SnapshotParams exposes bindings.SnapshotParams. Used for setting dqlite's snapshot parameters. SnapshotParams.Threshold controls after how many raft log entries a snapshot is taken. The higher this number, the lower the frequency of the snapshots. SnapshotParams.Trailing controls how many raft log entries are retained after taking a snapshot.
Source Files
Directories