Skip to content

5. Migration Guide

Jump to bottom
Tebrox edited this page Sep 3, 2026 · 1 revision

Migration Guide

VertexCore provides a built-in migration system for moving plugin data between supported database backends.

This allows plugins using the VertexCore database abstraction to migrate their stored data without implementing their own migration logic.

Supported backends include:

  • JSON (flat file)
  • H2
  • MySQL / MariaDB

Requirements

Before a plugin can use VertexCore migrations, it must register its database configuration and data classes with VertexCore.

import de.tebrox.vertexCore.VertexCoreApi;

VertexCoreApi.get().registry().register(
    this,
    () -> dbSettings,
    PlayerProfile.class
);

Multiple data classes can be registered:

VertexCoreApi.get().registry().register(
    this,
    () -> dbSettings,
    PlayerProfile.class,
    PlayerSettings.class,
    PlayerStatistics.class
);

After registration, VertexCore knows which data belongs to the plugin and can include it in migration operations.

Before Migrating

Database migrations modify persistent data.

Before starting a migration:

  1. Create a backup of the current database or data directory.
  2. Make sure the target database is reachable.
  3. Verify database credentials and configuration.
  4. Avoid modifying plugin data while the migration is running.
  5. Review the migration command before confirming the operation.

Always keep a backup of the source data until the migrated database has been verified.

Starting a Migration

VertexCore provides administrative migration commands through the /vertexcore command.

The migration command follows the general structure:

/vertexcore migrate ...

Available plugins, backends and options are exposed through command suggestions where supported.

Use tab completion to inspect the available arguments for the installed VertexCore version.

Source and Target Backends

A migration moves registered data from one backend to another.

Typical examples include:

JSON → H2

JSON → MySQL

H2 → MySQL

MySQL → H2

VertexCore prevents invalid migration configurations such as selecting the same backend as both the source and target.

Plugin Registration

Only plugins registered with the VertexCore data registry can participate in migrations.

Example:

VertexCoreApi.get().registry().register(
    this,
    () -> dbSettings,
    PlayerProfile.class
);

The registration provides VertexCore with:

  • The owning plugin
  • The current DatabaseSettings
  • The data classes belonging to the plugin

If a plugin is not registered, it will not be available as a migration target.

Data Classes

All data classes that should participate in migrations must be registered.

For example:

VertexCoreApi.get().registry().register(
    this,
    () -> dbSettings,
    PlayerProfile.class,
    PlayerHome.class,
    PlayerStatistics.class
);

Only fields exposed through the VertexCore database serialization system are persisted.

@DbExpose
public int coins;

See the Database System for details.

Migration Safety

VertexCore performs migrations through its database abstraction rather than requiring plugins to directly access backend implementations.

Migration handling includes validation designed to prevent unsafe or invalid operations.

A migration should never be treated as a replacement for backups.

Keep the original source data until the target has been verified.

After a Migration

After the migration completes:

  1. Verify that the migration reported success.
  2. Check that the expected data exists in the target backend.
  3. Update the plugin's configured backend if required.
  4. Restart or reload the affected plugin/server as appropriate.
  5. Verify normal plugin operation.
  6. Keep the source backup until the new backend has been used successfully.

Migration Failure

If a migration fails:

  • Do not delete the source data.
  • Check the VertexCore and server logs.
  • Verify the target database connection.
  • Verify database credentials.
  • Check whether all required data classes are registered.
  • Verify that source and target backends are different.
  • Do not repeatedly start migrations without first determining why the previous operation failed.

When using MySQL or MariaDB, also verify:

  • Hostname
  • Port
  • Database name
  • Username
  • Password
  • Network connectivity
  • Database permissions

Related Documentation

VertexCore 1.1.0 · Repository · Releases · Issues

Clone this wiki locally