Migrating from LiteBans
NookureStaff+ includes a built-in, asynchronous migration tool (LiteBansMigrationService) to import your existing LiteBans data directly into NookureStaff without downtime or manual SQL scripts.
What Gets Migrated
Section titled “What Gets Migrated”- Player History: Creates or updates player records (
PlayerModel) with UUIDs, usernames, and login metadata. - Alt Account Links: Imports IP-to-account relationships (
AltAccountLinkModel) for/dupeip. - All Sanction Types:
- Permanent & Temporary Bans and IP-Bans
- Permanent & Temporary Mutes and IP-Mutes
- Warnings
- Kicks
- Safe Deduplication: Automatically skips duplicate records and optionally skips expired/inactive sanctions (
--active-only).
Migration Sources (--source)
Section titled “Migration Sources (--source)”NookureStaff supports three source modes when reading LiteBans data:
| Source Mode | Behavior | When to Use |
|---|---|---|
auto (Default) |
Uses LiteBansAPI if the LiteBans plugin is loaded on the server; otherwise falls back to direct JDBC using migrations.yml. |
Recommended for most setups. |
api |
Queries litebans.api.Database from the running LiteBans plugin. |
When LiteBans is currently running alongside NookureStaff. |
jdbc |
Connects directly to LiteBans’ MySQL/MariaDB or SQLite database using plugins/NookureStaff/migrations.yml. |
When LiteBans has already been removed or is on an external database. |
Configuration (migrations.yml)
Section titled “Configuration (migrations.yml)”If you are using jdbc (or auto without LiteBans loaded), configure your LiteBans database credentials in plugins/NookureStaff/migrations.yml:
# Configuration for migrating punishments, player history, and alt links from LiteBans.litebans: # Database host for direct JDBC migration when LiteBans plugin is not loaded. # Ignored if 'jdbc-url' is specified. host: localhost
# Database port (usually 3306 for MySQL/MariaDB). port: 3306
# LiteBans database name. database: litebans
# Database username. username: root
# Database password. password: ''
# Table prefix used by LiteBans (default: litebans_). table-prefix: litebans_
# Optional custom JDBC URL (overrides host, port, and database). # Examples: # jdbc:mysql://localhost:3306/litebans?useSSL=false # jdbc:sqlite:plugins/LiteBans/litebans.db jdbc-url: ''
# Number of records processed per database transaction batch. batch-size: 500Command & Flags
Section titled “Command & Flags”Requires permission: nookure.staff.admin
/nkstaff migrate litebans [--dry-run] [--active-only] [--source=auto|api|jdbc] [--batch-size=500]| Flag | Description |
|---|---|
--dry-run |
Simulates the entire migration and prints the summary report without writing any changes to the NookureStaff database. |
--active-only |
Only imports currently active bans, mutes, and warnings, skipping expired or pardoned history. |
--source=auto|api|jdbc |
Overrides the data source mode (auto, api, or jdbc). |
--batch-size=<n> |
Overrides the number of records processed per database transaction batch (default: 500). |
Recommended Migration Steps
Section titled “Recommended Migration Steps”- Back up your databases: Always take a backup of both your LiteBans and NookureStaff databases before migrating.
- Configure
migrations.yml: If LiteBans is not loaded on the server, fill in your MySQL credentials orjdbc-urlinplugins/NookureStaff/migrations.ymland run/nkstaff reload. - Run a Dry Run: Test the connection and preview the import counts without modifying your database:
Terminal window /nkstaff migrate litebans --dry-run - Run the Migration: Execute the migration (add
--active-onlyif you do not want expired history):Terminal window /nkstaff migrate litebans - Review the Summary Report: Once complete, NookureStaff outputs the counts of created/updated players, alt links, bans, mutes, warnings, kicks, skipped duplicates, and errors, and automatically invalidates punishment caches.
- Remove LiteBans: Once verified, remove the LiteBans JAR from your
plugins/folder and restart your server/proxy.