rqlite/rqlite repository overview

⁠

rqlite is a relational database which combines SQLite's simplicity with the power of a robust, fault-tolerant, distributed system. rqlite is simple to deploy, operating it is very straightforward, and its clustering capabilities provide you with fault-tolerance and high-availability.

• Website⁠
• Developer guide⁠
• Images mirrored on GitHub Container Registry⁠

⁠Why run rqlite?

rqlite is your solution for a rock-solid⁠, fault-tolerant, relational database with effortless installation, deployment, and operation. It's ideal as a lightweight, distributed relational data store for both developers and operators. Think Consul⁠ or etcd⁠, but with relational modeling available.

Use rqlite to reliably store your most important data, ensuring it's always available to your applications.

⁠Key features

• Easy Deployment: Up and running in seconds, with no separate SQLite installation.
• Developer-Friendly: Straightforward HTTP API⁠, CLI⁠, and client libraries⁠.
• Fully Replicated: SQL database with full-text search⁠, JSON support⁠, and SQLite extensions support⁠.
• Large data set support: rqlite works well, even when managing multi-GB data sets.
• Dynamic Clustering: Integrates with Kubernetes⁠, Consul, etcd, and DNS for automatic clustering⁠.
• Robust Security: Extensive encryption and TLS support⁠.
• Flexible Consistency: Customize read/write performance⁠ and durability⁠.
• Scalable Reads: Read-only nodes⁠ for enhanced scalability.
• Transactions: Supports a form of transactions.
• Easy Backups: Hot backups⁠, including automatic backups to AWS S3 and MinIO⁠, as well as restore directly from SQLite⁠.

⁠Starting a single node

docker run -p4001:4001 rqlite/rqlite

This will start a single node, connected to the default bridge network. The HTTP API will be available at http://$ADDRESS:4001. $ADDRESS is the network address Docker assigns to your rqlite container, and will be displayed in the rqlite logs. Passing -p4001:4001 is optional, and means the node is also reachable at http://localhost:4001.

⁠Running the command-line tool

Do this by first launching a shell within an rqlite container, and then launching the command-line tool. You must pass the HTTP API address of the node you wish to contact.

docker run --rm -it rqlite/rqlite rqlite -H $HTTP_ADDRESS

You can also download⁠ and run the command-line tool locally and connect to the container. You do not need to run the tool inside a container.

⁠Passing extra options to rqlite

rqlite supports many options, allowing you to control its behavior. To set an option simply append it your launch command. For example, to enable INFO-level logging:

docker run rqlite/rqlite -raft-log-level=INFO

The launch process will then merge your flags with its own flags, including any values set by the supported environment variables (see later on this page for details on supported environment variables). You can see the full set of options via:

docker run rqlite/rqlite -help

⁠Fully specifying launch process

If the first option passed to the Docker container is not a flag i.e. it does not begin with -, then the Docker image will invoke that exact command at launch time. For example:

docker run rqlite/rqlite rqlited -raft-log-level=INFO -raft-snap-int=1s /rqlite/file/data

This option gives you complete control over the launch of rqlite within the container. Environment variables are ignored in this mode.

⁠Clustering

When it comes to clustering, each Docker container must be reachable on its Raft port (which defaults to 4002). To launch a Docker container and join it to an already running node execute this command:

docker run rqlite/rqlite -join=$RAFT_ADDRESS:4002

where $RAFT_ADDRESS is the network address of the node you wish to join. For production clusters you should also set -node-id and, if running on Kubernetes, use a Stateful Set.

Check out the following for more details:

• General cluster management guidelines⁠
• Automatic clustering guide⁠
• Deploying rqlite on Kubernetes⁠

⁠Ensuring containers can communicate

Depending on your setup, you may need to set -raft-adv-addr for each node at startup. This flags controls the address the container advertises for Raft communication. This may be necessary because the Raft address advertised by a node by default (it defaults to the fully-quality domain name for the container) when running inside a container may not be reachable from outside the container. Setting -raft-adv-addr allows you to directly configure the advertised Raft address. -http-adv-addr similarly configures the advertised HTTP API address.

⁠Maintaining state across restarts

rqlite uses /rqlite/file/ for file storage. You need to mount a volume at this point if you wish a container to maintain state across restarts.

 docker volume create rqlite-dir
 docker run -v rqlite-dir:/rqlite/file rqlite/rqlite -node-id 1

Note that it is critical that the node ID for a given container remains stable across restarts. In the example above this is done by explicitly setting the node ID to 1.

⁠Environment variables

The Docker image supports the following environment variables:

• NODE_ID: the node ID. Defaults to the hostname for the container.
• DATA_DIR: the data directory for the node. Defaults to /rqlite/file/data.
• HTTP_ADDR: the HTTP bind address. Defaults to 0.0.0.0:4001.
• RAFT_ADDR: the Raft bind address. Defaults to 0.0.0.0:4002.
• HTTP_ADV_ADDR: the HTTP address the rqlite node should advertise. Defaults to the fully-qualified domain name for the container.
• RAFT_ADV_ADDR: the Raft address the rqlite node should advertise. Defaults to the fully-qualified domain name for the container.
• SQLITE_EXTENSIONS: the set of built-in SQLite extensions to load at launch time. See the documentation⁠ for more details. Can be set concurrently with CUSTOM_SQLITE_EXTENSIONS_PATH.
• CUSTOM_SQLITE_EXTENSIONS_PATH: comma-delimited paths to SQLite extensions to load at launch time. Can be set concurrently with SQLITE_EXTENSIONS.
• ENABLE_FK: if set to any non-empty string then Foreign Key constraints will be enabled.

⁠Docker Compose

If you're interested in Compose, check out the rqlite Docker Compose repository⁠ on GitHub.