Upgrade and Rollback

Upgrading VotingPlugin Safely

This guide is for administrators updating an existing installation, including standalone Paper servers and Velocity/BungeeCord networks. It focuses on preserving voting data and having a tested rollback before replacing a JAR.

Version baseline (November 2026): The latest published stable release is VotingPlugin 7.1.1, published July 23, 2026, and compiled for Java 21. Changes on the master/7.2-SNAPSHOT development line may not exist in that stable release. Check the release list and Spigot resource for the exact artifact being installed.

1. Identify the installation before touching files

Record:

• VotingPlugin build/version currently running, and the target build/version.
• Bukkit/Paper version, Java version, and whether you use a standalone server or a Velocity/BungeeCord network.
• VotifierPlus or NuVotifier version and how inbound votes reach VotingPlugin.
• Current storage: Config.yml → DataStorage: SQLITE or MYSQL, including relevant driver and database type.
• Other plugins receiving voting events or invoking VotingPlugin/AdvancedCore APIs, and any custom reward or placeholder integrations.

Do not assume a feature documented for a development commit is in the published stable JAR. If the wiki labels something development-only, verify the feature against the actual artifact you are upgrading to.

2. Make a recoverable backup

Take a coordinated, consistent recovery point while all data writers are stopped. Announce a maintenance window, stop external vote intake, and cleanly shut down every participating server and proxy before copying the plugin files, Users.db, or the shared SQL database. VoteShop purchases, scheduled resets, background saves, and queued rewards may continue writing even after external voting stops. An alternative is a genuinely coordinated application-consistent snapshot of both SQL storage and all plugin files, with writes quiesced across every node. Do not copy Users.db while its server is live.

Back up the whole plugins/VotingPlugin/ folder rather than just one YAML file, including files normally generated by the plugin. Take the SQL dump and file snapshots within the same stopped/quiesced maintenance window so they represent a matching restore point.

Environment	Minimum backup
Standalone / SQLite	Users.db and entire VotingPlugin configuration/data directory, plus previous VotingPlugin and Votifier listener JARs
Standalone / MySQL	Consistent SQL database backup plus configuration/data directory and previous JARs
Proxy network	One consistent SQL backup and all proxy/backend VotingPlugin configuration directories, selected listener configuration, and previous plugin JARs
Optional Control integration	Its separately managed backup/snapshot plan; do not assume a VotingPlugin folder copy includes the Control service's state

Never edit ServerData.yml directly; backing it up is different from modifying it. Protect copied SQL credentials, Votifier private keys, proxy secrets, and backups themselves.

A file-only backup is not sufficient for an SQL-backed installation, and rollback without restoring related data may leave counts/points/streaks inconsistent.

3. Test the target build off production first

1. Build a test server with an isolated copy of the configuration and a nonproduction copy of the database.
2. Install the correct JAR for the platform and start with the target Java 21 runtime.
3. Review console errors, new/removed config keys, listener compatibility, and storage-driver availability.
4. Compare behavior for /vote, website links, rewards, vote points, streaks, VoteParty, and monthly/daily resets.
5. Run an internal /av vote <player> <site> test and also a real/listener-generated Votifier test; the internal command does not verify the public listening port.
6. Verify an offline vote or a reconnect if your server relies on queued rewards. For proxy networks, test each eligible backend.
7. Keep an exact record of the candidate build and the rollback procedure. Avoid enabling unrelated new features during the same upgrade.

Do not run a staging listener against a production voting website and database—that could create duplicate votes or reward effects.

4. Upgrade a standalone server

1. Complete the isolated staging test described above, then schedule maintenance for production.
2. Stop external voting, cleanly shut down the server, and capture the consistent filesystem and (if used) SQL backup while stopped. Do not rely on Bukkit /reload or a hot-swap.
3. Replace the VotingPlugin backend JAR, keeping the previous artifact for rollback. Update the listener only when required and verified separately.
4. Start the server; inspect startup errors and the configured data-storage type.
5. Compare existing Config.yml and VoteSites.yml with release defaults without overwriting local customizations.
6. Perform the internal + real Votifier checks, inspect vote totals and reward delivery, and then reopen voting.

See Getting Started: Standalone for where the files live.

5. Upgrade a Velocity/BungeeCord network

The normal released topology installs VotingPlugin on the proxy and all participating backends, with a shared SQL database and a compatible Votifier listener on the proxy.

1. In staging, test proxy-to-backend compatibility and the selected BungeeMethod (usually PLUGINMESSAGING).
2. Schedule a maintenance window. Do not assume that every combination of stable and development proxy/backend versions can interoperate.
3. Stop external vote intake and cleanly shut down every participating proxy and backend, allowing pending writers to finish or be safely quiesced.
4. With all nodes stopped, back up every node and the shared SQL database as one coordinated restore point, then update the proxy and backend VotingPlugin JARs together.
5. Ensure each backend still has a unique Server name and the proxy and backends use compatible SQL settings and matching communication channels.
6. Restart nodes, verify /votingpluginproxy status, then test internal forwarding and a real/listener-generated vote into the proxy.
7. Check that a single incoming vote does not create duplicate rewards via multiple forwarding routes.

See Proxy Setups and Votifier Troubleshooting for the transport options and tests.

6. If the upgrade fails: rollback safely

Do not blindly downgrade a running server or keep writing to a database with incompatible versions.

1. Stop vote intake and all affected servers/proxies.
2. Keep the failed installation's logs and a separate diagnostic backup.
3. Restore the previous JARs and their corresponding configuration files.
4. If the new version changed the storage format or wrote incompatible data, restore the matching consistent database/SQLite backup as well. Coordinate all nodes if shared SQL is involved.
5. Restart the previous deployment as a whole, verify startup/storage connectivity, and run a bounded test vote.
6. Reconcile any votes received since the snapshot before reopening, rather than assuming those votes will automatically reappear.

Rollback can lose activity between the backup and failure. A recoverable backup and a maintenance window matter more than a quick JAR swap.

7. Database or identity migrations are separate operations

Do not combine an ordinary JAR upgrade with a storage or UUID migration unless you have tested the exact combination.

SQLite ↔ external SQL

The storage migration guide documents /av converttodata <storage> and /av convertfromdata <storage>. These commands copy user data and do not change DataStorage automatically. Back up source and destination, pause vote intake, verify the copy, switch storage, and restart only after confirmation.

For existing proxy networks, keep the supported shared-SQL layout; a local SQLite backend is not a drop-in replacement for the shared database.

Player identities (online/offline-mode and Bedrock)

Changing OnlineMode or BedrockPlayerPrefix can change which identity receives votes, points, and rewards. Coordinate proxy/backends and plan a separate migration with backups and verification; do not flip these settings just to fix a single unmatched vote.

See Online / Offline Mode and Bedrock Player Support.

Acceptance checklist

• Target JAR and Java version are known and supported
• Previous JARs, plugin folders, and SQL/SQLite state have verified backups
• Standalone or every proxy/backend component starts cleanly
• No storage-driver, service-site, UUID, or proxy transport errors
• Internal test and real Votifier vote both work
• Total, points, per-site rewards, milestones, VoteParty, and offline delivery meet expectations
• Rollback steps and source backup are retained until confidence is established

Further reading

File Layout · Storage Migration · Getting Started · FAQ