{"id":13464057,"url":"https://github.com/canonical/go-dqlite","last_synced_at":"2026-02-19T11:16:24.777Z","repository":{"id":34010456,"uuid":"142890794","full_name":"canonical/go-dqlite","owner":"canonical","description":"Go bindings for libdqlite","archived":false,"fork":false,"pushed_at":"2025-04-07T19:43:29.000Z","size":6585,"stargazers_count":453,"open_issues_count":35,"forks_count":76,"subscribers_count":18,"default_branch":"v3","last_synced_at":"2025-04-14T02:58:19.453Z","etag":null,"topics":["database","dqlite","go","hacktoberfest","raft","sqlite"],"latest_commit_sha":null,"homepage":"https://dqlite.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/canonical.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-30T14:58:37.000Z","updated_at":"2025-04-04T13:44:23.000Z","dependencies_parsed_at":"2023-01-15T03:56:36.088Z","dependency_job_id":"161b667f-a8dd-4e4c-b3eb-af095a31d4c2","html_url":"https://github.com/canonical/go-dqlite","commit_stats":{"total_commits":878,"total_committers":32,"mean_commits":27.4375,"dds":"0.32232346241457854","last_synced_commit":"f8d5421dc5e7884bac0047c3772fb1cf715193e9"},"previous_names":["canonicalltd/go-dqlite"],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canonical%2Fgo-dqlite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canonical%2Fgo-dqlite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canonical%2Fgo-dqlite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canonical%2Fgo-dqlite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/canonical","download_url":"https://codeload.github.com/canonical/go-dqlite/tar.gz/refs/heads/v3","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248813790,"owners_count":21165633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","dqlite","go","hacktoberfest","raft","sqlite"],"created_at":"2024-07-31T14:00:33.090Z","updated_at":"2026-02-19T11:16:19.746Z","avatar_url":"https://github.com/canonical.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"go-dqlite [![CI tests][cibadge]][ciyml] [![Coverage Status][coverallsbadge]][coveralls] [![Go Report Card][reportcardbadge]][reportcard] [![GoDoc][godocbadge]][godoc]\n======\n\nThis repository provides the go-dqlite Go package, containing bindings for\nthe [dqlite][dqlite] C library and a pure-Go client for the dqlite wire\n[protocol][protocol].\n\nUsage\n-----\n\nThe current major version of the package is `v3`:\n\n```\n$ go get github.com/canonical/go-dqlite/v3\n```\n\nThe [`v2`][v2] major version is used for an LTS series that gets fixes but no new\nfeatures. Major version 1 is no longer receiving updates of any kind and should\nnot be used.\n\nThe best way to understand how to use the package is probably by looking at the\nsource code of the [demo program][demo] and using it as an example.\n\nIn general your application will use code such as:\n\n```go\ndir := \"/path/to/data/directory\"\naddress := \"1.2.3.4:666\" // Unique node address\ncluster := []string{...} // Optional list of existing nodes, when starting a new node\napp, err := app.New(dir, app.WithAddress(address), app.WithCluster(cluster))\nif err != nil {\n        // ...\n}\n\ndb, err := app.Open(context.Background(), \"my-database\")\nif err != nil {\n        // ...\n}\n\n// db is a *sql.DB object\nif _, err := db.Exec(\"CREATE TABLE my_table (n INT)\"); err != nil\n        // ...\n}\n```\n\nBuild\n-----\n\nIn order to use the go-dqlite package in your application, you'll need to have\nthe [dqlite][dqlite] C library installed on your system, along with its\ndependencies.\n\ngo-dqlite can use the [go-sqlite3][go-sqlite3] package to store some\ninformation about the cluster locally on each node in a SQLite database file.\nPass `-tags libsqlite3` when building go-dqlite to request that go-sqlite3 link\nto your system's libsqlite3, instead of building its own. Alternatively, pass\n`-tags nosqlite3` to disable the go-sqlite3 dependency; go-dqlite can store the\nsame information in YAML files instead.\n\nDocumentation\n-------------\n\nThe documentation for this package can be found on [pkg.go.dev][godoc].\n\nDemo\n----\n\nTo see dqlite in action, either install the Debian package from the PPA:\n\n```bash\n$ sudo add-apt-repository -y ppa:dqlite/dev\n$ sudo apt install dqlite-tools-v3 libdqlite-dev\n```\n\nor build the dqlite C library and its dependencies from source, as described\n[here][dqlitebuild], and then run:\n\n```\n$ go install -tags libsqlite3 ./cmd/dqlite-demo\n```\n\nfrom the top-level directory of this repository.\n\nThis builds a demo dqlite application, which exposes a simple key/value store\nover an HTTP API.\n\nOnce the `dqlite-demo` binary is installed (normally under `~/go/bin` or\n`/usr/bin/`), start three nodes of the demo application:\n\n```bash\n$ dqlite-demo --api 127.0.0.1:8001 --db 127.0.0.1:9001 \u0026\n$ dqlite-demo --api 127.0.0.1:8002 --db 127.0.0.1:9002 --join 127.0.0.1:9001 \u0026\n$ dqlite-demo --api 127.0.0.1:8003 --db 127.0.0.1:9003 --join 127.0.0.1:9001 \u0026\n```\n\nThe `--api` flag tells the demo program where to expose its HTTP API.\n\nThe `--db` flag tells the demo program to use the given address for internal\ndatabase replication.\n\nThe `--join` flag is optional and should be used only for additional nodes after\nthe first one. It informs them about the existing cluster, so they can\nautomatically join it.\n\nNow we can start using the cluster. Let's insert a key pair:\n\n```bash\n$ curl -X PUT -d my-value http://127.0.0.1:8001/my-key\n```\n\nand then retrieve it from the database:\n\n```bash\n$ curl http://127.0.0.1:8001/my-key\n```\n\nCurrently the first node is the leader. If we stop it and then try to query the\nkey again curl will fail, but we can simply change the endpoint to another node\nand things will work since an automatic failover has taken place:\n\n```bash\n$ kill -TERM %1; curl http://127.0.0.1:8002/my-key\n```\n\nShell\n-----\n\nA basic SQLite-like dqlite shell is available in the `dqlite-tools-v3` package\nor can be built with:\n\n```\n$ go install -tags libsqlite3 ./cmd/dqlite\n```\n\nThe general usage is:\n\n```\ndqlite -s \u003cservers\u003e \u003cdatabase\u003e [command] [flags]\n```\n\nExample usage in the case of the `dqlite-demo` example listed above:\n\n```\n$ dqlite -s 127.0.0.1:9001 demo\ndqlite\u003e SELECT * FROM model;\nmy-key|my-value\n```\n\nThe shell supports normal SQL queries plus the special `.cluster` and `.leader`\ncommands to inspect the cluster members and the current leader.\n\n[cibadge]: https://github.com/canonical/go-dqlite/actions/workflows/build-and-test.yml/badge.svg\n[ciyml]: https://github.com/canonical/go-dqlite/actions/workflows/build-and-test.yml\n[coveralls]: https://coveralls.io/github/canonical/go-dqlite?branch=v3\n[coverallsbadge]: https://coveralls.io/repos/github/canonical/go-dqlite/badge.svg?branch=v3\n[demo]: https://github.com/canonical/go-dqlite/blob/v3/cmd/dqlite-demo/dqlite-demo.go\n[dqlite]: https://github.com/canonical/dqlite\n[dqlitebuild]: https://github.com/canonical/dqlite#build\n[go-sqlite3]: https://github.com/mattn/go-sqlite3\n[godoc]: https://godoc.org/github.com/canonical/go-dqlite/v3\n[godocbadge]: https://godoc.org/github.com/canonical/go-dqlite/v3?status.svg\n[protocol]: https://dqlite.io/docs/reference/wire-protocol\n[reportcard]: https://goreportcard.com/report/github.com/canonical/go-dqlite/v3\n[reportcardbadge]: https://goreportcard.com/badge/github.com/canonical/go-dqlite/v3\n[v2]: https://github.com/canonical/go-dqlite/tree/v2\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcanonical%2Fgo-dqlite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcanonical%2Fgo-dqlite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcanonical%2Fgo-dqlite/lists"}