Data Import

Move your existing punishment records into PhantomBans without losing history.

Switching to PhantomBans from another ban plugin? The importer reads punishments out of AdvancedBan, LiteBans, or LibertyBans and writes them into PhantomBans, so your bans, mutes, warns, kicks, and their history all come across.


/pb import <advancedban|litebans|libertybans> [dry|confirm]

Needs the phantombans.import permission (included in phantombans.admin, default op).

Preview first, write only on confirm

The importer never writes anything until you explicitly add confirm. This makes it impossible to import by accident.

Flag	What happens
(no flag) or `dry`	Safe preview. Reads the source and reports a per-type breakdown and a total. Writes nothing.
`confirm`	Actually writes the imported rows. Required to make any change.

Always start with a preview to confirm the counts look right, then re-run with confirm.

Back up PhantomBans’ plugins/PhantomBans/data.db (or your MySQL database) before running with confirm.

Before you start

Stop the source plugin (for a file database)

AdvancedBan and LibertyBans store data in HSQLDB, LiteBans in H2. All three lock the file while their server is running. Either stop that plugin’s server before importing, or copy its data files somewhere else and point the importer at the copy. A MySQL or MariaDB source can be read while live.

Let the drivers download once

On its first launch, PhantomBans downloads the hsqldb and h2 database drivers from Maven Central (needs internet once). After that they are cached.

Fill in the one source you are importing from

Open plugins/PhantomBans/config.yml, find the import: block near the bottom, and set the jdbc-url for the single plugin you are migrating from. Then /pb reload.

How the config works

The import: block is added to your config.yml automatically on first run.


import:
  mark: "imported"                 # imported rows get server = "imported:<source>" so origin is traceable
  wipe-existing-on-rerun: true     # re-running the same source replaces its previous import (no duplicates)
  sources:
    advancedban: { jdbc-url, driver, user, password, table-prefix }
    litebans:    { jdbc-url, driver, user, password, table-prefix }
    libertybans: { jdbc-url, driver, user, password, table-prefix }

Each source ships with a commented-out MySQL alternative right below it. If your source plugin runs on a network database instead of a local file, swap to those lines.

Every imported row is stamped server = imported:<source> (for example imported:litebans) so you can always tell where it came from. That tag is also what lets a re-run stay clean: with wipe-existing-on-rerun: true, importing the same source again deletes the previous import first, so you never get duplicates.

Per-plugin notes

AdvancedBan

Default jdbc-url:


jdbc:hsqldb:file:plugins/AdvancedBan/data/storage;ifexists=true;hsqldb.lock_file=false

The base name is the file without its .script / .data / .properties extension (storage is the AdvancedBan default). If AdvancedBan ran on MySQL, use the commented MySQL lines instead. A preview shows a per-type breakdown (BAN, IPBAN, MUTE, WARN, KICK) and a total.

LiteBans

Default jdbc-url:


jdbc:h2:./plugins/LiteBans/litebans;ACCESS_MODE_DATA=r

LiteBans names the file litebans.mv.db: drop the .mv.db in the url. If you changed LiteBans’ table prefix, set table-prefix to match (default litebans_).

LiteBans’ default H2 file is read directly as of 1.0.0-10. LiteBans writes its H2 file in an older storage format, so PhantomBans bundles the matching H2 1.4.x driver to read it (newer H2 cannot open the old format). No conversion or MySQL detour is needed for a normal LiteBans install.

After import, verify: silent bans stay silent, IP bans/mutes come in as IPBAN/IPMUTE, removed punishments show as removed, and names/IPs populate.

LibertyBans

Default jdbc-url:


jdbc:hsqldb:file:plugins/LibertyBans/internal/hypersql/punishments;ifexists=true;hsqldb.lock_file=false

LibertyBans keeps its file under internal/. If ifexists=true errors with “database does not exist”, look in plugins/LibertyBans/internal/hypersql/ for the *.script file and use its name (minus the extension).

LibertyBans stores times in seconds (the importer converts to milliseconds), IP punishments come in as IPBAN/IPMUTE, and console-issued punishments show the staff name as “Console”.

Things to know

One way only. The importer reads from the other plugin and writes into PhantomBans. It never writes back to the source.
Schemas vary by version. Columns are read defensively, so a missing column is skipped rather than aborting the whole import. If a preview shows zero or a type looks off, note the plugin and version so the mapping can be adjusted.
Imported rows are normal punishments. They show up in /history, /lookup, /checkban, and /checkmute, and active ones enforce: an imported active ban denies login, an imported active mute blocks chat.

If the import errors

As of 1.0.0-9, common problems report a clear one-line message in chat instead of printing a Java stack trace to console:

Message	What it means	Fix
No `<source>` data found. Looked at `<path>`…	The source plugin’s folder or database file is not where the importer looked.	Make sure that plugin’s data folder is present, and that the `jdbc-url` path in `config.yml` matches it.
`<source>` uses an H2 database format PhantomBans can’t read directly.	The H2 file is a format the bundled H2 1.4.x driver cannot open (a normal LiteBans file reads fine, so this means a newer H2 2.x file).	Point the source at MySQL/MariaDB and import from there (see the LiteBans tab above).

Any other failure still shows Import failed: with the underlying error.

Full step-by-step migration instructions for each plugin are in the tester guides.