README
¶
go-dqlite 
This repository provides the go-dqlite Go package, containing bindings for the
dqlite C library and a pure-Go
client for the dqlite wire protocol.
Usage
The best way to understand how to use the go-dqlite package is probably by
looking at the source code of the demo
program and
use it as example.
Build
In order to use the go-dqlite package in your application, you'll need to have
the dqlite C library installed on your
system, along with its dependencies. You then need to pass the -tags
argument to the Go tools when building or testing your packages, for example:
go build -tags libsqlite3
go test -tags libsqlite3
Documentation
The documentation for this package can be found on Godoc.
Demo
To see dqlite in action, either install the Debian package from the PPA:
sudo add-apt-repository -y ppa:dqlite/stable
sudo apt install dqlite libdqlite-dev
or build the dqlite C library and its dependencies from source, as described here, and then run:
go install -tags libsqlite3 ./cmd/dqlite-demo
from the top-level directory of this repository.
Once the dqlite-demo binary is installed, start three nodes of the demo
application, respectively with IDs 1, 2, and 3:
dqlite-demo start 1 &
dqlite-demo start 2 &
dqlite-demo start 3 &
The node with ID 1 automatically becomes the leader of a single node
cluster, while the nodes with IDs 2 and 3 are waiting to be notified
what cluster they belong to. Let's make nodes 2 and 3 join the
cluster:
dqlite-demo add 2
dqlite-demo add 3
Now we can start using the cluster. The demo application is just a simple key/value store that stores data in a SQLite table. Let's insert a key pair:
dqlite-demo update my-key my-value
and then retrive it from the database:
dqlite-demo query my-key
Currently node 1 is the leader. If we stop it and then try to query the
key again we'll notice that the query command hangs for a bit waiting for
the failover to occur and for another node to step up as leader:
kill -TERM %1; sleep 0.1; dqlite-demo query my-key; dqlite-demo cluster
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConfigMultiThread ¶ added in v1.2.0
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.
Types ¶
type Node ¶ added in v1.0.0
type Node struct {
// contains filtered or unexported fields
}
Node runs a dqlite node.
func (*Node) BindAddress ¶ added in v1.0.0
BindAddress returns the network address the node is listening to.
type Option ¶ added in v1.0.0
type Option func(*options)
Option can be used to tweak node parameters.
func WithBindAddress ¶ added in v1.0.0
WithBindAddress sets a custom bind address for the server.
func WithDialFunc ¶
WithDialFunc sets a custom dial function for the server.
func WithNetworkLatency ¶ added in v1.0.0
WithNetworkLatency sets the average one-way network latency.
Source Files
Directories