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
• ⚙️ 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

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

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.