rqloud

rqloud

rqloud combines Tailscale (tsnet) networking with rqlite (distributed SQLite) into a self-contained replicated application platform.

Your application gets a database/sql or native gorqlite interface backed by a Raft-replicated SQLite database, with all inter-node communication happening over your Tailscale network.

For a real-world example, see JustinAzoff/golink, a fork of tailscale/golink using rqloud instead of a local SQLite database.

Features

• Embedded rqlite — no separate database process to manage
• Tailscale networking — all traffic (Raft consensus, cluster coordination, HTTP API) runs over tsnet, with caller identity via WhoIs()
• Automatic clustering — nodes discover each other by hostname prefix and auto-join
• Two database interfaces — database/sql for standard Go code, or native gorqlite for rqlite-specific features

Standalone Binary

cmd/rqloud runs a bare rqlite cluster over Tailscale with no application code on top. Use it to deploy a replicated SQLite database accessible via the standard rqlite CLI or HTTP API.

CGO_ENABLED=1 go build -o rqloud ./cmd/rqloud/

Start a single node:

./rqloud -instance mydb /tmp/rqloud-test/mydb

Start a 3-node cluster:

./rqloud -instance mydb-1 -bootstrap-expect 3 /tmp/rqloud-test/mydb-1
./rqloud -instance mydb-2 -bootstrap-expect 3 /tmp/rqloud-test/mydb-2
./rqloud -instance mydb-3 -bootstrap-expect 3 /tmp/rqloud-test/mydb-3

The three nodes can all run on the same machine or on three different machines — since all communication happens over the tailnet, it doesn't matter where they are.

Connect via the rqlite CLI over the tailnet:

rqlite -H mydb-1 -p 4001

Or open the rqlite web console at http://mydb-1:4001/.

To access rqlite from outside of the tailnet, use -local-rqlite-bind:

./rqloud -instance mydb-1 -local-rqlite-bind 127.0.0.1:4001 /tmp/rqloud-test/mydb-1
rqlite  # connects to localhost:4001

This is useful for local tooling, monitoring, or applications that don't run on the tailnet.

Quick Start (Library)

package main

import (
    "flag"
    "fmt"
    "log"
    "net/http"

    "github.com/JustinAzoff/rqloud"
)

func main() {
    flag.Usage = func() {
        fmt.Fprintf(flag.CommandLine.Output(), "Usage: hitcount [hostname]\n\n")
        fmt.Fprintf(flag.CommandLine.Output(), "Use \"hitcount\" for a single node, or \"hitcount-1\", \"hitcount-2\", etc. for a cluster.\n\n")
        flag.PrintDefaults()
    }
    flag.Parse()

    hostname := "hitcount"
    if flag.NArg() > 0 {
        hostname = flag.Arg(0)
    }

    srv := &rqloud.Server{
        Hostname: hostname,
    }
    if err := srv.Start(); err != nil {
        log.Fatal(err)
    }
    defer srv.Close()

    db, _ := srv.DB()
    db.Exec(`CREATE TABLE IF NOT EXISTS hits (count INTEGER)`)
    db.Exec(`INSERT INTO hits (count) SELECT 0 WHERE NOT EXISTS (SELECT 1 FROM hits)`)

    ln, _ := srv.Listen("tcp", ":80")
    log.Printf("listening on http://%s/", hostname)
    http.Serve(ln, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        db.Exec(`UPDATE hits SET count = count + 1`)
        var count int
        db.QueryRow(`SELECT count FROM hits`).Scan(&count)
        fmt.Fprintf(w, "hits: %d\n", count)
    }))
}

Clustering

Nodes discover peers automatically by hostname prefix. Name your instances with a shared prefix and a unique suffix separated by a hyphen:

myapp-1
myapp-2
myapp-3

The first node to start bootstraps a new single-node cluster. Subsequent nodes discover existing peers on the tailnet and join automatically.

A standalone instance (hostname with no hyphen, e.g. myapp) runs as a single non-clustered node.

API

Constructors

// Create a server that manages its own tsnet node.
srv := rqloud.New()
srv.Hostname = "myapp-1"

// Or use an existing tsnet.Server.
srv := rqloud.NewWithTSNet(existingTS)

rqloud.Server

srv := &rqloud.Server{
    Hostname:      "myapp-1",         // tsnet hostname (required)
    Dir:           "/data/myapp-1",   // rqlite data directory (default: ~/.config/rqloud/<hostname>)
    TSDir:         "",                // tsnet config directory (default: ~/.config/tsnet-<hostname>)
    AuthKey:       "tskey-...",       // Tailscale auth key (default: interactive login)
    AdvertiseTags: []string{"tag:myapp"},
    Verbose:       false,
}

Example: Todo App

See examples/todo/ for a complete per-user todo list application.

CGO_ENABLED=1 go build -o rqloud-todo ./examples/todo/
./rqloud-todo -instance todo-1

Start a second instance to form a cluster:

./rqloud-todo -instance todo-2

They'll discover each other on the tailnet and replicate automatically.

Building

CGO is required (rqlite uses a fork of go-sqlite3):

CGO_ENABLED=1 go build ./...

rqlite Fork

rqloud depends on a fork of rqlite with two small patches:

• http/service.go — Listener field so Start() accepts an external net.Listener (for tsnet)
• store/store.go — ResolveAddress hook to override DNS resolution (tsnet handles its own name resolution)

These are tracked as separate branches (custom-http-listener, custom-dns) merged into the justin-integration branch, which go.mod references via a replace directive.