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

• 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.

• Go: Version 1.25 or later is required.

Download from releases page.

Install the latest version of pocketbase-ha using:

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

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

• 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;

Set up your environment variables to configure the 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.

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: https://localhost:8090
• Node2: https://localhost:8091
• Node3: https://localhost:8092

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

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

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.

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

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

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

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

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

This project is licensed under the MIT License.