ha

HA - Highly Available SQLite Cluster

HA is a highly available SQLite cluster powered by an embedded NATS JetStream server. It provides distributed SQLite databases with replication, supporting multiple protocols for seamless integration.

Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• Usage
• API Documentation
• Contributing
• License

Features

• 🔌 Multiple Protocols: Connect via HTTP API, gRPC API, database/sql Go driver, JDBC driver, MySQL Wire Protocol, or PostgreSQL Wire Protocol
• 🔁 Replication: Use embedded or external NATS server for data replication
• 📝 Read/Write Replicas: Create live local read/write replicas with go-ha database/sql driver
• 📚 Read Replicas: Create live local read replicas with ha-sync SQLite extension
• 🔄 Change Data Capture (CDC): Supports CDC for real-time data streaming
• 🔌 Proxy: Proxy and replicate PostgreSQL or MySQL databases to the edge
• ⚙️ Cluster Modes: Configure leader-based or leaderless clusters with custom conflict resolution strategies
• 📚 Cross-Shard Queries: Execute queries across shards using SQL hints like /*+ db=DSN */
• 🔄 Transaction Undo: Supports undo operations on committed transactions, allowing rollback to previous states
• 📖 Full Documentation: https://litesql.github.io/ha/

Installation

Pre-built Binaries

Download the latest release from GitHub Releases.

Build from Source

Ensure you have Go 1.26+ installed.

go install github.com/litesql/ha@latest

Docker

Using a docker image:

docker run --name node1 \
-e HA_CREATE_DB_DIR=/data
-p 5432:5432 -p 8080:8080 -p 4222:4222 \
ghcr.io/litesql/ha:latest

• Set up a volume at /data to store the NATS streams state and database files.

Deploy on Kubernetes using Helm

• Add litesql helm charts repository to Helm:

helm repo add litesql https://litesql.github.io/helm-charts

• Update the chart repository:

helm repo update

• Deploy ha to kubernetes:

helm install ha litesql/ha

• Visit litesql helm charts repository to customize the installation;

Quick Start

1. Start the First HA Instance

mkdir db1
ha -n node1 --pg-port 5432 --mysql-port 3306 "file:db1/mydatabase.db"

This starts:

• Embedded NATS server on port 4222
• MySQL Wire Protocol server on port 3306
• PostgreSQL Wire Protocol server on port 5432
• HTTP/gRPC API server on port 8080

2. Start a Second HA Instance

mkdir db2
ha -n node2 --nats-port 0 -p 8081 --pg-port 5433 --mysql-port 3307 --replication-url nats://localhost:4222 "file:db2/mydatabase.db"

This starts:

• PostgreSQL Wire Protocol server on port 5433
• MySQL Wire Protocol server on port 3307
• HTTP/gRPC API server on port 8081

It connects to the first instance's NATS server for replication.

3. Connect and Test

Create a table and insert data:

ha -r http://localhost:8080
CREATE TABLE users(ID INTEGER PRIMARY KEY, name TEXT);
INSERT INTO users(name) VALUES('HA user');

Verify replication by connecting to the second instance and querying the data.

ha -r http://localhost:8081
SELECT * FROM users

Configuration

HA supports various command-line flags for configuration. Run ./ha --help for a complete list.

Key options:

• -n, --name: Node name
• -p, --port: HTTP API port (default: 8080)
• --pg-port: PostgreSQL Wire Protocol port
• --mysql-port: MySQL Wire Protocol port
• --nats-port: NATS server port (0 to disable embedded server)
• --replication-url: NATS server URL for replication

For advanced configuration, see the full documentation.

Usage

HA Client

Connect using the built-in HA client:

ha -r http://localhost:8080

Special commands:

• SHOW DATABASES;: List all databases
• CREATE DATABASE dsn;: Create a new database
• DROP DATABASE id;: Drop a database
• SET DATABASE TO id;: Switch to a specific database
• UNSET DATABASE;: Use default database
• EXIT;: Quit client

Transaction Operations

• HISTORY n: Retrieve transactions from sequence point n
• UNDO n: Revert transactions from sequence n
• UNDOE n: Roll back entity modifications from sequence n
• UNDOT n: Revert transactions affecting entities from sequence n

Where n can be a sequence number or time duration (e.g., '5m').

PostgreSQL Client

PGPASSWORD=ha psql -h localhost -U ha -p 5432

MySQL Client

mysql -h localhost --port 3306 -u ha

Proxy and Replicate Other Databases

HA can proxy connections to PostgreSQL and MySQL databases, replicating their data to achieve high availability and enable faster queries.

Proxy and Replicate PostgreSQL

PostgreSQL Example

Proxy and Replicate MySQL

MySQL Example

API Documentation

• HTTP API: https://litesql.github.io/ha/#5
• gRPC API: https://buf.build/litesql/sqlite-ha/sdks/main:grpc
• OpenAPI Spec: See openapi.yaml in the repository or access http://localhost:8080/docs

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

For major changes, please open an issue first to discuss the proposed changes.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.