Quick start

Get up and running quickly with rqlite

The quickest way to get running is to download a pre-built release binary, available on the GitHub releases page. There are releases available for Linux and Windows.

Once installed, you can start a single rqlite node like so:

  1. $ rqlited -node-id=1 data/

data/ is the path to a directory rqlite will use for storage. Once launched rqlite will be listening on http://localhost:4001.

Docker

Docker images are available for a variety of platforms.

docker run -p 4001:4001 rqlite/rqlite

macOS

brew install rqlite

Inserting records

Let’s insert some records using the rqlite shell, using standard SQLite commands.

  1. $ rqlite
  2. 127.0.0.1:4001> CREATE TABLE foo (id INTEGER NOT NULL PRIMARY KEY, name TEXT)
  3. 1 row affected (0.000668 sec)
  4. 127.0.0.1:4001> .schema
  5. +-----------------------------------------------------------------------------+
  6. | sql                                                                         |
  7. +-----------------------------------------------------------------------------+
  8. | CREATE TABLE foo (id INTEGER NOT NULL PRIMARY KEY, name TEXT)               |
  9. +-----------------------------------------------------------------------------+
  10. 127.0.0.1:4001> INSERT INTO foo(name) VALUES("fiona")
  11. 1 row affected
  12. 127.0.0.1:4001> SELECT * FROM foo
  13. +----+-------+
  14. | id | name  |
  15. +----+-------+
  16. | 1  | fiona |
  17. +----+-------+

Forming a cluster

You don’t need to deploy cluster to use rqlite well, but running multiple nodes means you’ll have a fault-tolerant system. Start two more nodes, allowing the cluster to tolerate failure of a single node, like so:

  1. $ rqlited -node-id 2 -http-addr localhost:4003 -raft-addr localhost:4004 -join localhost:4002 data2/
  2. $ rqlited -node-id 3 -http-addr localhost:4005 -raft-addr localhost:4006 -join localhost:4002 data3/

This demonstration shows all 3 nodes running on the same host. In reality you probably wouldn’t do this, and then you wouldn’t need to select different -http-addr and -raft-addr ports for each rqlite node. Consult the Clustering Guide for more details.

Let’s head back to the rqlite shell, and check out the cluster.

  1. 127.0.0.1:4001> .nodes
  2. 1:
  3.   api_addr: http://localhost:4001
  4.   addr: localhost:4002
  5.   voter: true
  6.   reachable: true
  7.   leader: true
  8.   id: 1
  9. 2:
  10.   api_addr: http://localhost:4003
  11.   addr: localhost:4004
  12.   voter: true
  13.   reachable: true
  14.   leader: false
  15.   id: 2
  16. 3:
  17.   api_addr: http://localhost:4005
  18.   addr: localhost:4006
  19.   voter: true
  20.   reachable: true
  21.   leader: false
  22.   id: 3

With just these few steps you’ve now got a fault-tolerant, distributed relational database. Running on each rqlite node will be a fully-replicated copy of the SQLite database. Any data you insert will be replicated across the cluster, in a durable and fault-tolerant manner.

Next steps

Take a look at the Developer Guide, and check out the detailed guides for clustering and Kubernetes. And consider joining the rqlite Slack channel or signing up for Office Hours if you want to discuss rqlite.

Last modified September 26, 2024: Update _index.md (e2834e5)