pocketbase-ha

PocketBase HA

Highly Available Leader/Leaderless PocketBase Cluster powered by go-ha database/sql driver.

Features

• High Availability: Run multiple PocketBase instances in a leader or leaderless cluster.
• Replication: Synchronize data across nodes using NATS.
• Embedded or External NATS: Choose between an embedded NATS server or an external one for replication.
• Remote direct access to Database: via a secured gRPC endpoint for direct database access from remote clients. Use terminal or DBeaver.
• Undo transactions: Use pocketbase-ha cli (or any gRPC client) to execute UNDO commands on already commited transactions.

Prerequisites

• Go: Version 1.25 or later is required.

Installation

Download from releases page.

Install from source

Install the latest version of pocketbase-ha using:

go install github.com/litesql/pocketbase-ha@latest

Docker image

docker pull ghcr.io/litesql/pocketbase-ha:latest

Install from 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 pb litesql/pocketbase-ha

• Visit litesql helm charts repository to customize the installation;

Configuration

Set up your environment variables to configure the cluster:

Usage

Starting a Cluster

1. Start the first PocketBase HA instance:

   PB_NAME=node1 PB_NATS_PORT=4222 pocketbase-ha serve
   

2. Start a second instance in a different directory:

   PB_ASYNC_PUBLISHER=true PB_NAME=node2 PB_REPLICATION_URL=nats://localhost:4222 pocketbase-ha serve --http 127.0.0.1:8091
   

Note: You can skip setting the superuser password for the second instance.

Running a NATS Cluster with docker

To run a NATS cluster using Docker Compose, use the following command:

docker compose up

• Superuser e-mail: test@example.com
• Superuser pass: 1234567890

You can define the superuser password using this command:

docker compose exec -e PB_NATS_CONFIG="" -e PB_LOCAL_TARGET="" node1 /app/pocketbase-ha superuser upsert EMAIL PASS

Access the three nodes using the following address:

• Node1: http://localhost:8090
• Node2: http://localhost:8091
• Node3: http://localhost:8092

Tip: Ensure all nodes are synchronized by verifying the logs or using the PocketBase admin interface.

Event Hooks on replica nodes

On replica nodes (the nodes that users do not directly interact with), only the following events are triggered by the PocketBase event hooks system:

• OnModelAfterCreateSuccess
• OnModelAfterCreateError
• OnModelAfterUpdateSuccess
• OnModelAfterUpdateError
• OnModelAfterDeleteSuccess
• OnModelAfterDeleteError

Data Replication and Conflict Resolution

PocketBase HA uses a last-writer-wins strategy for conflict resolution by default. To implement custom resolution strategies, modify the ChangeSetInterceptor in your code.

For applications that require strict consistency, configure a cluster leader to handle all write operations and prevent conflicts entirely.

Configuring a Cluster Leader

Set PB_LOCAL_TARGET or PB_STATIC_LEADER environment variables to designate a leader node that processes all write requests:

Static Leader

export PB_STATIC_LEADER=http://leader-addr:8090

Dynamic Leader

export PB_LOCAL_TARGET=http://local-advertise-addr:8090

This ensures all mutations route through the leader while reads can be distributed across replica nodes.

Remote database access from terminal

To enable remote access, set PB_GRPC_PORT before starting the service:

export PB_GRPC_PORT=9090
pocketbase-ha serve

Then, from another terminal, connect with:

pocketbase-ha remote http://localhost:9090

Then execute any SQL command:

data.db> SELECT * FROM PRAGMA_table_list;

Protect the connection with a token

Set PB_GRPC_TOKEN to require authentication for remote gRPC access.

export PB_GRPC_PORT=9090
export PB_GRPC_TOKEN=secret
pocketbase-ha serve

Then, from another terminal, connect with:

pocketbase-ha remote http://localhost:9090 --token secret

Undo transactions

You can undo transactions using pocketbase-ha cli UNDO command:

# connect
pocketbase-ha remote http://host:port

# undo latest transaction
undo;

# undo last N transactions
undo N;

# undo transactions since time. Ex: undo 5m; (5 minutes ago)
undo <time duration>;

# show the latest transaction
history;

# show the last N transactions
history N;

# show the transactions since time.
history <time duration>;

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests to improve this project.

License

This project is licensed under the MIT License.