Improve database resilience, load handling, cleanup, and Folia reloads

[Minecraft0122]

Summary

• retain queued database transactions during transient/recoverable connection outages and retry them in order with bounded exponential backoff
• reduce extension database lock contention by caching provider and table metadata and only writing it when the metadata changes
• handle MySQL 1205 statement failures with bounded iterative retries, return every connection exactly once, and report the actual 2-minute throttling window
• add /plan db remove_registered <after-date> <before-date> for confirmed, inclusive bulk deletion by first-join date
• make Folia reloads lifecycle-safe: cancelled tasks from the old lifecycle can no longer run after reload, and shutdown waits for already-running tasks before closing the database
• correct Folia asynchronous tick-to-millisecond conversion, which previously scheduled periodic work roughly 1000 times too frequently
• add regression coverage for merging a SQLite database into a non-empty MySQL-compatible destination while preserving existing server data
• fix transaction queue accounting when throwaway transactions are dropped

Command details

New command: /plan db remove_registered <after-date> <before-date>

• Aliases: /plan db removeregistered and /plan db remove_between
• Permission: plan.data.clear
• Accepts ISO dates in yyyy-MM-dd format and uses Plan's configured time zone.
• Selects players by their first-join/registration timestamp. Both dates are inclusive, from the start of after-date through the end of before-date.
• Rejects malformed dates and a range where after-date is later than before-date.
• Shows a confirmation prompt before making changes. After confirmation, it removes all Plan data linked to every matching player from the currently active database, invalidates their cached query data, and reports the number removed.
• Example: /plan db remove_registered 2026-01-01 2026-01-31

Existing command covered by this PR: /plan db merge <source> <destination>

• Permission: plan.data.merge
• The first database argument is the source and the second is the destination. For SQLite to MySQL, use /plan db merge SQLite MySQL and confirm the prompt.
• This command already existed; the PR does not add or rename it. The new regression test starts with data in both databases and verifies that the destination's original server and session data remain while the SQLite server and sessions are added.
• Existing server-UUID conflict options remain available: --on-conflict-delete deletes the conflicting destination server, while --on-conflict-swap assigns the imported conflicting server a different UUID. They are not needed when server UUIDs do not conflict and were not introduced by this PR.

Verification

• GitHub Actions full CI passed on the exact head commit (51ee784f6): https://github.com/Minecraft0122/Plan/actions/runs/30634140383
• full Gradle build and test suite, including MariaDB/MySQL, SQLite, Selenium/frontend tests, release JAR assembly, Javadocs generation, and Javadocs deployment
• new regression tests cover unchanged and changed extension metadata, dynamic table rows vs. table schema, failed/skipped metadata writes, bounded MySQL lock retries, connection return accounting, recovery, and non-critical transaction dropping
• MySQLTest > mergeSQLiteIntoNonEmptyDatabase() and SQLiteTest > mergeSQLiteIntoNonEmptyDatabase() both passed on the current head
• local full :common:check, Checkstyle, and targeted regression tests passed

The first CI attempt passed all code and test steps but could not deploy Javadocs because the fork's workflow token was read-only. After enabling read/write workflow permissions on the fork (without PR approval permission), the complete second attempt passed.

The SQLite-to-MySQL merge command already exists as /plan db merge SQLite MySQL; this PR adds the non-empty destination regression test requested for that workflow.

Closes #4727
Closes #4719
Closes #4599
Closes #2755

[AuroraLS3]

If you make further changes please keep each change to its own PR so that it's easier to review - It's difficult if one part of a PR is good and another isn't

[AuroraLS3]

I can't unfortunately merge this like this because it has 3 different completely unrelated things in it and it seems to be written by AI.

If it was 3 different PRs I could merge one and cleanup, then merge the next one and cleanup - but with it all in big lump I can't possibly hope of cleaning up the AI code to be up to standard.

Please separate the three things into three different branches and 3 PRs so that it is possible to review properly.

I've left some comments that may help when doing the changes.

---

I did not review properly because I got the feeling that my comments would be fed to AI to generate the fixes, and the larger the PR, the smaller the chances of success for AI to fix them are.
If you wrote this yourself and did not use AI, I can take another look.

[AuroraLS3]

Changes in this file should be done in https://github.com/plan-player-analytics/Platform-abstraction-layer instead.

[AuroraLS3]

Extra PlatformLayer specificly for Plan is not required in this case, changes to it should be done in https://github.com/plan-player-analytics/Platform-abstraction-layer instead

[AuroraLS3]

Changes in this file are not required after moving the other modifications in folia module to pal library.

[AuroraLS3]

Suggested change

	Class<?> foliaPlatformLayer = Class.forName("net.playeranalytics.plugin.PlanFoliaPlatformLayer");
	Class<?> foliaPlatformLayer = Class.forName("net.playeranalytics.plugin.FoliaPlatformLayer");

[AuroraLS3]

Database should not be stored in persistent variables, it is also not required here since DataValueGatherer is recreated at the same time if Database instance changes.

[AuroraLS3]

If the icon is null it is not stored, so this if-block is unnecessary

[Minecraft0122]

This was indeed written by AI. I just wanted it to solve a few problems that are really important to me, but I didn't notice that it sent a PR.

…

---Original--- From: "Aurora ***@***.***&gt; Date: Sun, Aug 2, 2026 23:38 PM To: ***@***.***&gt;; Cc: ***@***.******@***.***&gt;; Subject: Re: [plan-player-analytics/Plan] Improve database resilience, load handling, cleanup, and Folia reloads (PR #4772) @AuroraLS3 commented on this pull request. I can't unfortunately merge this like this because it has 3 different completely unrelated things in it and it seems to be written by AI. If it was 3 different PRs I could merge one and cleanup, then merge the next one and cleanup - but with it all in big lump I can't possibly hope of cleaning up the AI code to be up to standard. Please separate the three things into three different branches and 3 PRs so that it is possible to review properly. I've left some comments that may help when doing the changes. In Plan/folia/src/main/java/net/playeranalytics/plugin/scheduling/PlanFoliaRunnableFactory.java: &gt; + * along with Plan. If not, see <https://www.gnu.org/licenses/&gt;. + */ +package net.playeranalytics.plugin.scheduling; + +import io.papermc.paper.threadedregions.scheduler.AsyncScheduler; +import io.papermc.paper.threadedregions.scheduler.GlobalRegionScheduler; +import org.bukkit.plugin.java.JavaPlugin; + +import java.util.concurrent.atomic.AtomicLong; +import java.util.concurrent.locks.Condition; +import java.util.concurrent.locks.ReentrantLock; + +/** + * Folia runnable factory that prevents tasks from an old Plan lifecycle from running after reload. + */ +public class PlanFoliaRunnableFactory implements RunnableFactory { Changes in this file should be done in https://github.com/plan-player-analytics/Platform-abstraction-layer instead. In Plan/folia/src/main/java/net/playeranalytics/plugin/PlanFoliaPlatformLayer.java: &gt; + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with Plan. If not, see <https://www.gnu.org/licenses/&gt;. + */ +package net.playeranalytics.plugin; + +import net.playeranalytics.plugin.scheduling.PlanFoliaRunnableFactory; +import net.playeranalytics.plugin.scheduling.RunnableFactory; +import org.bukkit.plugin.java.JavaPlugin; + +/** + * Plan-specific Folia platform layer with reload-safe task scheduling. + */ +public class PlanFoliaPlatformLayer extends FoliaPlatformLayer { Extra PlatformLayer specificly for Plan is not required in this case, changes to it should be done in https://github.com/plan-player-analytics/Platform-abstraction-layer instead In Plan/folia/build.gradle: &gt; @@ -1,5 +1,12 @@ dependencies { - runtimeOnly "net.playeranalytics:platform-abstraction-layer-folia:$palVersion" + implementation "net.playeranalytics:platform-abstraction-layer-folia:$palVersion" + + compileOnly "dev.folia:folia-api:1.20.1-R0.1-SNAPSHOT" Changes in this file are not required after moving the other modifications in folia module to pal library. In Plan/bukkit/src/main/java/com/djrapitops/plan/Plan.java: &gt; @@ -66,7 +66,7 @@ public void onLoad() { if (isFolia()) { try { // Attempt to load and use the Folia library for Java 17+ - Class<?&gt; foliaPlatformLayer = Class.forName("net.playeranalytics.plugin.FoliaPlatformLayer"); + Class<?&gt; foliaPlatformLayer = Class.forName("net.playeranalytics.plugin.PlanFoliaPlatformLayer"); ⬇️ Suggested change - Class<?&gt; foliaPlatformLayer = Class.forName("net.playeranalytics.plugin.PlanFoliaPlatformLayer"); + Class<?&gt; foliaPlatformLayer = Class.forName("net.playeranalytics.plugin.FoliaPlatformLayer"); In Plan/common/src/main/java/com/djrapitops/plan/extension/implementation/providers/gathering/ExtensionMetadataStorage.java: &gt; + CompletableFuture<?&gt; completion, + Transaction transaction, + MetadataKey key, + MetadataFingerprint fingerprint + ) { + completion.whenComplete((result, failure) -&gt; { + if (failure != null || !transaction.wasExecuted()) { + synchronized (ExtensionMetadataStorage.this) { + storedMetadata.remove(key, fingerprint); + } + } + }); + } + + private static final class MetadataKey { + private final Database database; Database should not be stored in persistent variables, it is also not required here since DataValueGatherer is recreated at the same time if Database instance changes. In Plan/common/src/main/java/com/djrapitops/plan/extension/implementation/providers/gathering/ExtensionMetadataStorage.java: &gt; + addIcon(values, information.getIcon()); + values.add(information.isShownInPlayersTable()); + values.add(information.getTab().orElse(null)); + values.add(information.getCondition().orElse(null)); + values.add(information.isHidden()); + values.add(information.getProvidedCondition()); + values.add(information.getFormatType().orElse(null)); + values.add(information.isPlayerName()); + values.add(information.getTableColor()); + values.add(information.isPercentage()); + values.add(information.isComponent()); + return values; + } + + private static void addIcon(List<Object&gt; values, Icon icon) { + if (icon == null) { If the icon is null it is not stored, so this if-block is unnecessary — Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***&gt;

[Minecraft0122]

Sorry to bother you guys :(

…

---Original--- From: "Aurora ***@***.***&gt; Date: Sun, Aug 2, 2026 23:38 PM To: ***@***.***&gt;; Cc: ***@***.******@***.***&gt;; Subject: Re: [plan-player-analytics/Plan] Improve database resilience, load handling, cleanup, and Folia reloads (PR #4772) @AuroraLS3 commented on this pull request. I can't unfortunately merge this like this because it has 3 different completely unrelated things in it and it seems to be written by AI. If it was 3 different PRs I could merge one and cleanup, then merge the next one and cleanup - but with it all in big lump I can't possibly hope of cleaning up the AI code to be up to standard. Please separate the three things into three different branches and 3 PRs so that it is possible to review properly. I've left some comments that may help when doing the changes. In Plan/folia/src/main/java/net/playeranalytics/plugin/scheduling/PlanFoliaRunnableFactory.java: &gt; + * along with Plan. If not, see <https://www.gnu.org/licenses/&gt;. + */ +package net.playeranalytics.plugin.scheduling; + +import io.papermc.paper.threadedregions.scheduler.AsyncScheduler; +import io.papermc.paper.threadedregions.scheduler.GlobalRegionScheduler; +import org.bukkit.plugin.java.JavaPlugin; + +import java.util.concurrent.atomic.AtomicLong; +import java.util.concurrent.locks.Condition; +import java.util.concurrent.locks.ReentrantLock; + +/** + * Folia runnable factory that prevents tasks from an old Plan lifecycle from running after reload. + */ +public class PlanFoliaRunnableFactory implements RunnableFactory { Changes in this file should be done in https://github.com/plan-player-analytics/Platform-abstraction-layer instead. In Plan/folia/src/main/java/net/playeranalytics/plugin/PlanFoliaPlatformLayer.java: &gt; + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with Plan. If not, see <https://www.gnu.org/licenses/&gt;. + */ +package net.playeranalytics.plugin; + +import net.playeranalytics.plugin.scheduling.PlanFoliaRunnableFactory; +import net.playeranalytics.plugin.scheduling.RunnableFactory; +import org.bukkit.plugin.java.JavaPlugin; + +/** + * Plan-specific Folia platform layer with reload-safe task scheduling. + */ +public class PlanFoliaPlatformLayer extends FoliaPlatformLayer { Extra PlatformLayer specificly for Plan is not required in this case, changes to it should be done in https://github.com/plan-player-analytics/Platform-abstraction-layer instead In Plan/folia/build.gradle: &gt; @@ -1,5 +1,12 @@ dependencies { - runtimeOnly "net.playeranalytics:platform-abstraction-layer-folia:$palVersion" + implementation "net.playeranalytics:platform-abstraction-layer-folia:$palVersion" + + compileOnly "dev.folia:folia-api:1.20.1-R0.1-SNAPSHOT" Changes in this file are not required after moving the other modifications in folia module to pal library. In Plan/bukkit/src/main/java/com/djrapitops/plan/Plan.java: &gt; @@ -66,7 +66,7 @@ public void onLoad() { if (isFolia()) { try { // Attempt to load and use the Folia library for Java 17+ - Class<?&gt; foliaPlatformLayer = Class.forName("net.playeranalytics.plugin.FoliaPlatformLayer"); + Class<?&gt; foliaPlatformLayer = Class.forName("net.playeranalytics.plugin.PlanFoliaPlatformLayer"); ⬇️ Suggested change - Class<?&gt; foliaPlatformLayer = Class.forName("net.playeranalytics.plugin.PlanFoliaPlatformLayer"); + Class<?&gt; foliaPlatformLayer = Class.forName("net.playeranalytics.plugin.FoliaPlatformLayer"); In Plan/common/src/main/java/com/djrapitops/plan/extension/implementation/providers/gathering/ExtensionMetadataStorage.java: &gt; + CompletableFuture<?&gt; completion, + Transaction transaction, + MetadataKey key, + MetadataFingerprint fingerprint + ) { + completion.whenComplete((result, failure) -&gt; { + if (failure != null || !transaction.wasExecuted()) { + synchronized (ExtensionMetadataStorage.this) { + storedMetadata.remove(key, fingerprint); + } + } + }); + } + + private static final class MetadataKey { + private final Database database; Database should not be stored in persistent variables, it is also not required here since DataValueGatherer is recreated at the same time if Database instance changes. In Plan/common/src/main/java/com/djrapitops/plan/extension/implementation/providers/gathering/ExtensionMetadataStorage.java: &gt; + addIcon(values, information.getIcon()); + values.add(information.isShownInPlayersTable()); + values.add(information.getTab().orElse(null)); + values.add(information.getCondition().orElse(null)); + values.add(information.isHidden()); + values.add(information.getProvidedCondition()); + values.add(information.getFormatType().orElse(null)); + values.add(information.isPlayerName()); + values.add(information.getTableColor()); + values.add(information.isPercentage()); + values.add(information.isComponent()); + return values; + } + + private static void addIcon(List<Object&gt; values, Icon icon) { + if (icon == null) { If the icon is null it is not stored, so this if-block is unnecessary — Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***&gt;