📦 Installation

This guide covers installing Sparrow Sync and configuring a unique server ID, Redis, and persistent storage.

Supported Server Software

Server Software	1.21.4 ~ 26.1.2	26.2+
Paper and its forks	✅	✅
Folia and its forks	✅	✅
Spigot	❌ Unsupported	✅

Installation

Place the Sparrow Sync .jar file in your server's plugins/ folder, then start the server. The plugin generates its configuration files in plugins/SparrowSync/. The main files and folders are shown below:

SparrowSync

libs

translations

commands.yml

config.yml

server.yml

The server shuts down on the first startup

The server-id in server.yml is empty by default. On the first startup, the plugin reports the missing server ID in the console and shuts down the server.

Before starting the server again, complete both steps below:

1. Set a unique server-id for this server in server.yml.
2. Configure Redis and persistent storage in config.yml and make sure the server can connect to both.

Configuring server.yml

Open plugins/SparrowSync/server.yml and replace the empty server-id string with a unique ID for this server. The following example uses lobby for a lobby server.

plugins/SparrowSync/server.yml

# Configuration version. Do not edit.
___version___: '1'

# A unique ID for this server. Each server taking part in synchronization must use a different value.
# Set this before startup. Leaving it blank shuts down the server.
# Avoid changing it later. A new ID is treated as a new server and may affect synchronization of existing maps.
server-id: 'lobby'

server-id identifies this server within the synchronization cluster. It is required and must be different from the IDs of all other participating servers.

For example, two survival servers could use survival-1 and survival-2, while a lobby server uses lobby. After copying the plugin configuration to another server, remember to change server-id for the new server.

Once the server is in use, avoid changing this ID. A different ID is treated as a new server and may also affect synchronization of existing maps.

Save server.yml, then configure the database connections below.

Configuring Databases

Sparrow Sync requires both Redis and one persistent storage backend. Redis handles cross-server communication, session locks, and snapshot caching. Persistent storage keeps player snapshots long-term. Both must be configured.

Check the service versions first

If you use Redis, its version must be greater than 7.2.4. If you use MySQL, its version must be greater than 8.0.0.

Prepare these services, then open plugins/SparrowSync/config.yml and edit the existing redis and database sections. The examples below only cover connection settings; do not replace the entire file with them.

Redis

config.yml · Redis

redis:
  # Redis host, port, and database number.
  url: 'redis://localhost:6379/0'
  # Set a username for ACL authentication; otherwise this can be left empty.
  username: ''
  # Redis password. Leave empty if no password is configured.
  password: ''

Replace localhost and the port with your Redis address. /0 selects Redis database 0. Servers in the same synchronization group must connect to the same Redis database with the correct credentials.

Persistent Storage

Sparrow Sync supports MySQL, MariaDB, PostgreSQL, and MongoDB for persistent storage.

The following example uses MySQL. First create a database for snapshots, such as minecraft, and prepare an account with permission to create tables and read and write data in that database.

config.yml · MySQL example

database:
  # Choose the persistent storage backend.
  type: MYSQL
  mysql:
    # Set the host, port, and database name, keeping the driver parameters you need.
    url: 'jdbc:mysql://localhost:3306/minecraft?connectTimeout=5000&socketTimeout=10000&characterEncoding=UTF-8'
    # Replace with your database account and password.
    username: 'sparrow_sync'
    password: 'your_database_password'
    # Use the same table prefix across the synchronization group.
    table-prefix: 'sparrow_sync_'

Servers in the same synchronization group should use the same storage type, connect to the same database, and use the same table prefix. For MongoDB, use the same collection-prefix instead. Each server must still have a different server-id.

Once the server ID, Redis, and persistent storage are configured, save the files and start the server again. Check the console to confirm that both Redis and persistent storage connected successfully. If a connection fails, use the error message to check the address, credentials, and database permissions before restarting.

See Key Configuration Options for other important synchronization settings and their tradeoffs.