README
¶
go-cowsql 
This repository provides the go-cowsql Go package, containing bindings for the
cowsql C library and a pure-Go
client for the cowsql wire protocol.
Fork of Canonical go-dqlite
These bindings are a cowsql-oriented fork of Canonical's go-dqlite ones, which were originally written by cowsql's author himself while working at Canonical.
Usage
The best way to understand how to use the go-cowsql package is probably by
looking at the source code of the demo
program and
use it as example.
In general your application will use code such as:
dir := "/path/to/data/directory"
address := "1.2.3.4:666" // Unique node address
cluster := []string{...} // Optional list of existing nodes, when starting a new node
app, err := app.New(dir, app.WithAddress(address), app.WithCluster(cluster))
if err != nil {
// ...
}
db, err := app.Open(context.Background(), "my-database")
if err != nil {
// ...
}
// db is a *sql.DB object
if _, err := db.Exec("CREATE TABLE my_table (n INT)"); err != nil
// ...
}
Build
In order to use the go-cowsql package in your application, you'll need to have the cowsql C library installed on your system, along with its dependencies.
By default, go-cowsql's client module supports storing a cache of the
cluster's state in a SQLite database, locally on each cluster member. (This is
not to be confused with any SQLite databases that are managed by cowsql.) In
order to do this, it imports https://github.com/mattn/go-sqlite3, and so you
can use the libsqlite3 build tag to control whether go-sqlite3 links to a
system libsqlite3 or builds its own. You can also disable support for SQLite
node stores entirely with the nosqlite3 build tag (unique to go-cowsql). If
you pass this tag, your application will not link directly to libsqlite3 (but
it will still link it indirectly via libcowsql, unless you've dropped the
sqlite3.c amalgamation into the cowsql build).
Documentation
The documentation for this package can be found on pkg.go.dev.
Demo
To see cowsql in action, either install the Debian package from the PPA:
sudo add-apt-repository -y ppa:cowsql/master
sudo apt install cowsql libcowsql-dev
or build the cowsql C library and its dependencies from source, as described here, and then run:
go install -tags libsqlite3 ./cmd/cowsql-demo
from the top-level directory of this repository.
This builds a demo cowsql application, which exposes a simple key/value store over an HTTP API.
Once the cowsql-demo binary is installed (normally under ~/go/bin or
/usr/bin/), start three nodes of the demo application:
cowsql-demo --api 127.0.0.1:8001 --db 127.0.0.1:9001 &
cowsql-demo --api 127.0.0.1:8002 --db 127.0.0.1:9002 --join 127.0.0.1:9001 &
cowsql-demo --api 127.0.0.1:8003 --db 127.0.0.1:9003 --join 127.0.0.1:9001 &
The --api flag tells the demo program where to expose its HTTP API.
The --db flag tells the demo program to use the given address for internal
database replication.
The --join flag is optional and should be used only for additional nodes after
the first one. It informs them about the existing cluster, so they can
automatically join it.
Now we can start using the cluster. Let's insert a key pair:
curl -X PUT -d my-value http://127.0.0.1:8001/my-key
and then retrieve it from the database:
curl http://127.0.0.1:8001/my-key
Currently the first node is the leader. If we stop it and then try to query the key again curl will fail, but we can simply change the endpoint to another node and things will work since an automatic failover has taken place:
kill -TERM %1; curl http://127.0.0.1:8002/my-key
Shell
A basic SQLite-like cowsql shell is available in the cowsql-tools package or
can be built with:
go install -tags libsqlite3 ./cmd/cowsql
Usage:
cowsql -s <servers> <database> [command] [flags]
Example usage in the case of the cowsql-demo example listed above:
cowsql -s 127.0.0.1:9001 demo
cowsql> SELECT * FROM model;
my-key|my-value
The shell supports normal SQL queries plus the special .cluster and .leader
commands to inspect the cluster members and the current leader.
Documentation
¶
Index ¶
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-cowsql configures SQLite to Single-thread mode, because the cowsql 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_COWSQL_MULTITHREAD environment variable to 1 at process startup, in order to prevent go-cowsql 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 ¶
ReconfigureMembership can be used to recover a cluster whose majority of nodes have died, and therefore has become unavailable.
It forces appending a new configuration to the raft log stored in the given directory, effectively replacing the current configuration.
func ReconfigureMembershipExt ¶
ReconfigureMembershipExt can be used to recover a cluster whose majority of nodes have died, and therefore has become unavailable.
It forces appending a new configuration to the raft log stored in the given directory, effectively replacing the current configuration. In comparision with ReconfigureMembership, this function takes the node role into account and makes use of a cowsql API that supports extending the NodeInfo struct.
Types ¶
type Node ¶
type Node struct {
// contains filtered or unexported fields
}
Node runs a cowsql 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 ¶ added in v1.21.0
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 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 cowsql'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