From d472213c8d82ab13d5273d80377fc2f456cfad6c Mon Sep 17 00:00:00 2001 From: Cole Miller Date: Thu, 24 Oct 2024 18:08:32 -0400 Subject: [PATCH 1/4] Update README for v3 Signed-off-by: Cole Miller --- README.md | 98 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 57 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index bab7de71..162e612f 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,24 @@ -go-dqlite [![CI tests](https://github.com/canonical/go-dqlite/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/canonical/go-dqlite/actions/workflows/build-and-test.yml) [![Coverage Status](https://coveralls.io/repos/github/canonical/go-dqlite/badge.svg?branch=master)](https://coveralls.io/github/canonical/go-dqlite?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/canonical/go-dqlite)](https://goreportcard.com/report/github.com/canonical/go-dqlite) [![GoDoc](https://godoc.org/github.com/canonical/go-dqlite?status.svg)](https://godoc.org/github.com/canonical/go-dqlite) +go-dqlite [![CI tests][cibadge]][ciyml] [![Coverage Status][coverallsbadge]][coveralls] [![Go Report Card][reportcardbadge]][reportcard] [![GoDoc][godocbadge]][godoc] ====== -This repository provides the `go-dqlite` Go package, containing bindings for the -[dqlite](https://github.com/canonical/dqlite) C library and a pure-Go -client for the dqlite wire [protocol](https://github.com/canonical/dqlite/blob/master/doc/protocol.md). +This repository provides the `go-dqlite` Go package, containing bindings for +the [dqlite][dqlite] C library and a pure-Go client for the dqlite wire +[protocol][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](https://github.com/canonical/go-dqlite/blob/master/cmd/dqlite-demo/dqlite-demo.go) and -use it as example. +The current version of the package is `v3`: -In general your application will use code such as: +``` +$ go get github.com/canonical/go-dqlite/v3 +``` +The best way to understand how to use the `go-dqlite` package is probably by +looking at the source code of the [demo program](demo) and using it as an +example. + +In general your application will use code such as: ```go dir := "/path/to/data/directory" @@ -40,24 +44,20 @@ Build ----- In order to use the go-dqlite package in your application, you'll need to have -the [dqlite](https://github.com/canonical/dqlite) C library installed on your -system, along with its dependencies. - -By default, go-dqlite'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 dqlite.) 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-dqlite). If -you pass this tag, your application will not link *directly* to libsqlite3 (but -it will still link it *indirectly* via libdqlite, unless you've dropped the -sqlite3.c amalgamation into the dqlite build). +the [dqlite][dqlite] C library installed on your system, along with its +dependencies. + +go-dqlite can use the [go-sqlite3][go-sqlite3] package to store some +information about the cluster locally on each node in a SQLite database file. +Pass `-tags libsqlite3` when building go-dqlite to request that go-sqlite3 link +to your system's libsqlite3, instead of building its own. Alternatively, pass +`-tags nosqlite3` to disable the go-sqlite3 dependency; go-dqlite can store the +same information in YAML files instead. Documentation ------------- -The documentation for this package can be found on [pkg.go.dev](https://pkg.go.dev/github.com/canonical/go-dqlite). +The documentation for this package can be found on [pkg.go.dev][godoc]. Demo ---- @@ -65,15 +65,15 @@ Demo To see dqlite in action, either install the Debian package from the PPA: ```bash -sudo add-apt-repository -y ppa:dqlite/dev -sudo apt install dqlite-tools-v2 libdqlite1.17-dev +$ sudo add-apt-repository -y ppa:dqlite/dev +$ sudo apt install dqlite-tools-v3 libdqlite-dev ``` or build the dqlite C library and its dependencies from source, as described -[here](https://github.com/canonical/dqlite#build), and then run: +[here][dqlitebuild], and then run: ``` -go install -tags libsqlite3 ./cmd/dqlite-demo +$ go install -tags libsqlite3 ./cmd/dqlite-demo ``` from the top-level directory of this repository. @@ -85,9 +85,9 @@ Once the `dqlite-demo` binary is installed (normally under `~/go/bin` or `/usr/bin/`), start three nodes of the demo application: ```bash -dqlite-demo --api 127.0.0.1:8001 --db 127.0.0.1:9001 & -dqlite-demo --api 127.0.0.1:8002 --db 127.0.0.1:9002 --join 127.0.0.1:9001 & -dqlite-demo --api 127.0.0.1:8003 --db 127.0.0.1:9003 --join 127.0.0.1:9001 & +$ dqlite-demo --api 127.0.0.1:8001 --db 127.0.0.1:9001 & +$ dqlite-demo --api 127.0.0.1:8002 --db 127.0.0.1:9002 --join 127.0.0.1:9001 & +$ dqlite-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. @@ -102,13 +102,13 @@ automatically join it. Now we can start using the cluster. Let's insert a key pair: ```bash -curl -X PUT -d my-value http://127.0.0.1:8001/my-key +$ curl -X PUT -d my-value http://127.0.0.1:8001/my-key ``` and then retrieve it from the database: ```bash -curl http://127.0.0.1:8001/my-key +$ 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 @@ -116,29 +116,45 @@ 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: ```bash -kill -TERM %1; curl http://127.0.0.1:8002/my-key +$ kill -TERM %1; curl http://127.0.0.1:8002/my-key ``` Shell ------- +----- + +A basic SQLite-like dqlite shell is available in the `dqlite-tools-v3` package +or can be built with: -A basic SQLite-like dqlite shell is available in the `dqlite-tools` package or -can be built with: ``` -go install -tags libsqlite3 ./cmd/dqlite +$ go install -tags libsqlite3 ./cmd/dqlite ``` + +The general usage is: + ``` -Usage: - dqlite -s [command] [flags] +dqlite -s [command] [flags] ``` Example usage in the case of the `dqlite-demo` example listed above: -``` -dqlite -s 127.0.0.1:9001 demo +``` +$ dqlite -s 127.0.0.1:9001 demo dqlite> 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. + +[cibadge]: https://github.com/canonical/go-dqlite/actions/workflows/build-and-test.yml/badge.svg +[ciyml]: https://github.com/canonical/go-dqlite/actions/workflows/build-and-test.yml +[coveralls]: https://coveralls.io/github/canonical/go-dqlite?branch=v3 +[coverallsbadge]: https://coveralls.io/repos/github/canonical/go-dqlite/badge.svg?branch=v3 +[dqlite]: https://github.com/canonical/dqlite +[dqlitebuild]: https://github.com/canonical/dqlite#build +[go-sqlite3]: https://github.com/mattn/go-sqlite3 +[godoc]: https://godoc.org/github.com/canonical/go-dqlite/v3 +[godocbadge]: https://godoc.org/github.com/canonical/go-dqlite/v3?status.svg +[protocol]: https://dqlite.io/docs/reference/wire-protocol +[reportcard]: https://goreportcard.com/report/github.com/canonical/go-dqlite/v3 +[reportcardbadge]: https://goreportcard.com/badge/github.com/canonical/go-dqlite/v3 From c7cdfd3bc9b9ee49ae320f88c69644f5a06430a5 Mon Sep 17 00:00:00 2001 From: Cole Miller Date: Thu, 24 Oct 2024 18:11:56 -0400 Subject: [PATCH 2/4] Fix Signed-off-by: Cole Miller --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 162e612f..a78e8899 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ $ go get github.com/canonical/go-dqlite/v3 ``` The best way to understand how to use the `go-dqlite` package is probably by -looking at the source code of the [demo program](demo) and using it as an +looking at the source code of the [demo program][demo] and using it as an example. In general your application will use code such as: @@ -150,6 +150,7 @@ commands to inspect the cluster members and the current leader. [ciyml]: https://github.com/canonical/go-dqlite/actions/workflows/build-and-test.yml [coveralls]: https://coveralls.io/github/canonical/go-dqlite?branch=v3 [coverallsbadge]: https://coveralls.io/repos/github/canonical/go-dqlite/badge.svg?branch=v3 +[demo]: https://github.com/canonical/go-dqlite/blob/v3/cmd/dqlite-demo/dqlite-demo.go [dqlite]: https://github.com/canonical/dqlite [dqlitebuild]: https://github.com/canonical/dqlite#build [go-sqlite3]: https://github.com/mattn/go-sqlite3 From 139f3b1bb4e840eb630926419fcd793e7cbd6eb0 Mon Sep 17 00:00:00 2001 From: Cole Miller Date: Thu, 24 Oct 2024 18:17:00 -0400 Subject: [PATCH 3/4] Reword Signed-off-by: Cole Miller --- README.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index a78e8899..3f49d09c 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,25 @@ go-dqlite [![CI tests][cibadge]][ciyml] [![Coverage Status][coverallsbadge]][coveralls] [![Go Report Card][reportcardbadge]][reportcard] [![GoDoc][godocbadge]][godoc] ====== -This repository provides the `go-dqlite` Go package, containing bindings for +This repository provides the go-dqlite Go package, containing bindings for the [dqlite][dqlite] C library and a pure-Go client for the dqlite wire [protocol][protocol]. Usage ----- -The current version of the package is `v3`: +The current major version of the package is `v3`: ``` $ go get github.com/canonical/go-dqlite/v3 ``` -The best way to understand how to use the `go-dqlite` package is probably by -looking at the source code of the [demo program][demo] and using it as an -example. +The `v2` major version is used for an LTS series that gets fixes but no new +features. Major version 1 is no longer receiving updates of any kind and should +not be used. + +The best way to understand how to use the package is probably by looking at the +source code of the [demo program][demo] and using it as an example. In general your application will use code such as: From 98a02f8c405a153d238ac5bfa19f5e40a6bf6985 Mon Sep 17 00:00:00 2001 From: Cole Miller Date: Thu, 24 Oct 2024 18:24:52 -0400 Subject: [PATCH 4/4] Link Signed-off-by: Cole Miller --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3f49d09c..c5b838c9 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ The current major version of the package is `v3`: $ go get github.com/canonical/go-dqlite/v3 ``` -The `v2` major version is used for an LTS series that gets fixes but no new +The [`v2`][v2] major version is used for an LTS series that gets fixes but no new features. Major version 1 is no longer receiving updates of any kind and should not be used. @@ -162,3 +162,4 @@ commands to inspect the cluster members and the current leader. [protocol]: https://dqlite.io/docs/reference/wire-protocol [reportcard]: https://goreportcard.com/report/github.com/canonical/go-dqlite/v3 [reportcardbadge]: https://goreportcard.com/badge/github.com/canonical/go-dqlite/v3 +[v2]: https://github.com/canonical/go-dqlite/tree/v2