This guide will walk you through how to upgrade from HuskSync v1.4.x to HuskSync v3.x. Data from HuskSync v2.x will automatically be imported into HuskSync v3.x.
## Requirements
- MySQL Database with HuskSync v1.4.x data
v3.0: New modular, more compatible data format, new API, better UX (#160)
* Start work on v3
* More work on task scheduling
* Add comment to notification display slot
* Synchronise branches
* Use new HuskHomes-style task system
* Bump to 2.3
* Remove HuskSyncInitializationException.java
* Optimise database for MariaDB
* Update libraries, move some around
* Tweak command registration
* Remove dummyhusksync
* Fixup core synchronisation logic to use new task system
* Implement new event dispatch subsystem
* Remove last remaining future calls
* Remove `Event#fire()`
* Refactor startup process
* New command subsystem, more initialization improvements, locale fixes
* Update docs, tweak command perms
* Reduce task number during data setting
* add todo
* Start work on data format / serialization refactor
* More work on Bukkit impl
* More serialization work
* Fixes to serialization, data preview system
* Start legacy conversion skeleton
* Handle setting empty inventories
* Start on-the-fly legacy conversion work
* Add advancement conversion
* Rewrite advancement get / apply logic
* Start work on locked map persistence
* More map persistence work
* More work on map serialization
* Move around persistence logic
* Add testing suite
* Fix item synchronisation
* Finalize more reliable locked map persistence
* Remove deprecated method call
* remove sync feature enum
* Fix held item slot syncing
* Make data types modular and API-extensible
* Remove some excessive debugging, minor refactor
* Fixup date formatting, improve menu UIs
* Finish up legacy data converting
* Null safety in item stack serializaiton
* Fix relocation of nbtapi, update dumping docs
* Add v1/MPDB Migrators back in
* Fix pinning/unpinning data not working
* Consumer instead of Function for editing data
* Show file size in DataSnapshotOverview
* Fix getIdentifier always returning empty
* Re-add items and inventory GUI commands
* Improve config file, fixup data restoration
* Add min time between backups (more useful backups!)
* More work on backups
* Fixup backup rotation frequency
* Remove stdout debug print in `#getEventPriority`
* Improve sync complete locale logic, fix synchronization spelling
* Remove `static` on exception
* Use dedicated thread for Redis, properly unsubscribe
* Refactor `player` package -> `user`
* `PlayerDataHolder` -> `UserDataHolder`
* Make `StatisticsMap` public, but `@ApiStatus.Internal`
* Suppress unused warnings on `Data`
* Add option to disable Plan hook
* Decompress legacy data before converting
* Decompress bytes in fromBytes
* Check permission node before serving TAB suggestions
* Actually convert legacy item stack data
* Fix syntax errors
* Minor method refactor in items command
* Fixup case-sensitive parsing in HuskSync command
* Start API work
* More work on API, fix potion effects
* Fix cross-server, config formatting for auto-pinned issue
* Fix confusion with UserData command, update docs images
* Update commands docs
* More docs updating
* Fix sync feature enabled/disabled checking logic
* Fix `#isCustom()`
* Enable persistent_data syncing by default
* docs: update Sync-Features config snippet
* docs: correct typo in Sync Features
* More API work
* bukkit: slightly optimized schedulers
* More API work, various refactorings
* docs: Start new API docs
* bump dependencies
* Add some basic unit tests
* docs: Correct typos
* More docs work, annotate DB methods as `@Blocking`
* Encapsulate `RedisMessage`, minor optimisations
* api: Simplify `#getCurrentData`
* api: Simplify `editCurrentData`, using `ThrowingConsumers` for better error handling
* docs: More Data Snapshot API documenting
* docs: add TOC to Data Snapshot API page
* bukkit: Make data types extend BukkitData
* Move where custom data is stored, finish up Custom Data API docs
* Optimise imports
* Fix `data_manager_advancements_preview_remaining` locale
* Fix advancement and playtime previews
* Fix potion effect deserialization
* Make snapshot_backup_frequency default to 4, more error handling/logging
* docs: Add ToC to Custom Data API
* docs: Minor legacy API tweaks
* Remove some unneeded catch logic
* Suppress a few warnings
* Fix Effect constructor being supplied in wrong order
1 year ago
- Migration from SQLite is not supported, as HuskSync v2.x requires a MySQL database and does not support SQLite. Apologies for the inconvenience.
- If you're running v1.3.x or older, follow the update instructions to 1.4.x first before updating to 2.x.
## Migration Instructions
### 1. Uninstall HuskSync v1.x from all servers
- Switch off all servers and your proxy
v3.0: New modular, more compatible data format, new API, better UX (#160)
* Start work on v3
* More work on task scheduling
* Add comment to notification display slot
* Synchronise branches
* Use new HuskHomes-style task system
* Bump to 2.3
* Remove HuskSyncInitializationException.java
* Optimise database for MariaDB
* Update libraries, move some around
* Tweak command registration
* Remove dummyhusksync
* Fixup core synchronisation logic to use new task system
* Implement new event dispatch subsystem
* Remove last remaining future calls
* Remove `Event#fire()`
* Refactor startup process
* New command subsystem, more initialization improvements, locale fixes
* Update docs, tweak command perms
* Reduce task number during data setting
* add todo
* Start work on data format / serialization refactor
* More work on Bukkit impl
* More serialization work
* Fixes to serialization, data preview system
* Start legacy conversion skeleton
* Handle setting empty inventories
* Start on-the-fly legacy conversion work
* Add advancement conversion
* Rewrite advancement get / apply logic
* Start work on locked map persistence
* More map persistence work
* More work on map serialization
* Move around persistence logic
* Add testing suite
* Fix item synchronisation
* Finalize more reliable locked map persistence
* Remove deprecated method call
* remove sync feature enum
* Fix held item slot syncing
* Make data types modular and API-extensible
* Remove some excessive debugging, minor refactor
* Fixup date formatting, improve menu UIs
* Finish up legacy data converting
* Null safety in item stack serializaiton
* Fix relocation of nbtapi, update dumping docs
* Add v1/MPDB Migrators back in
* Fix pinning/unpinning data not working
* Consumer instead of Function for editing data
* Show file size in DataSnapshotOverview
* Fix getIdentifier always returning empty
* Re-add items and inventory GUI commands
* Improve config file, fixup data restoration
* Add min time between backups (more useful backups!)
* More work on backups
* Fixup backup rotation frequency
* Remove stdout debug print in `#getEventPriority`
* Improve sync complete locale logic, fix synchronization spelling
* Remove `static` on exception
* Use dedicated thread for Redis, properly unsubscribe
* Refactor `player` package -> `user`
* `PlayerDataHolder` -> `UserDataHolder`
* Make `StatisticsMap` public, but `@ApiStatus.Internal`
* Suppress unused warnings on `Data`
* Add option to disable Plan hook
* Decompress legacy data before converting
* Decompress bytes in fromBytes
* Check permission node before serving TAB suggestions
* Actually convert legacy item stack data
* Fix syntax errors
* Minor method refactor in items command
* Fixup case-sensitive parsing in HuskSync command
* Start API work
* More work on API, fix potion effects
* Fix cross-server, config formatting for auto-pinned issue
* Fix confusion with UserData command, update docs images
* Update commands docs
* More docs updating
* Fix sync feature enabled/disabled checking logic
* Fix `#isCustom()`
* Enable persistent_data syncing by default
* docs: update Sync-Features config snippet
* docs: correct typo in Sync Features
* More API work
* bukkit: slightly optimized schedulers
* More API work, various refactorings
* docs: Start new API docs
* bump dependencies
* Add some basic unit tests
* docs: Correct typos
* More docs work, annotate DB methods as `@Blocking`
* Encapsulate `RedisMessage`, minor optimisations
* api: Simplify `#getCurrentData`
* api: Simplify `editCurrentData`, using `ThrowingConsumers` for better error handling
* docs: More Data Snapshot API documenting
* docs: add TOC to Data Snapshot API page
* bukkit: Make data types extend BukkitData
* Move where custom data is stored, finish up Custom Data API docs
* Optimise imports
* Fix `data_manager_advancements_preview_remaining` locale
* Fix advancement and playtime previews
* Fix potion effect deserialization
* Make snapshot_backup_frequency default to 4, more error handling/logging
* docs: Add ToC to Custom Data API
* docs: Minor legacy API tweaks
* Remove some unneeded catch logic
* Suppress a few warnings
* Fix Effect constructor being supplied in wrong order
1 year ago
- Delete the .jar file from your `~/plugins/` folders on your Spigot servers
- Also delete the .jar file from your `~/plugins/` folders on your Proxy. HuskSync v3.x no longer requires a proxy plugin.
- Delete (or make a copy and delete) all HuskSync config data folders (`~/plugins/HuskSync/`). HuskSync v3.x has new `config.yml` , `messages-xx-xx.yml` and `server.yml` files.
### 2. Install HuskSync v3.x on all Spigot servers
- HuskSync v3.x must only be installed on your Spigot servers, not your proxy.
- Follow the setup instructions [here ](Setup ).
### 3. Configure the migrator
- With your servers back on and correctly configured to run HuskSync v3.x, ensure nobody is online.
- Use the console on one of your Spigot servers to enter: `husksync migrate help legacy`
- Carefully read the migration configuration instructions. In most cases, you won't have to change the settings, but if you do need to adjust them, use `husksync migrate set legacy <setting> <value>` .
- Migration will be carried out *from* the database you specify with the settings in console *to* the database configured in `config.yml` . If you're migrating from multiple clusters, ensure you run the migrator on the correct servers corresponding to the migrator.
### 4. Start the migrator
- Run `husksync migrate start legacy` to begin the migration process. This may take some time, depending on the amount of data you're migrating.
### 5. Ensure the migration was successful
v3.0: New modular, more compatible data format, new API, better UX (#160)
* Start work on v3
* More work on task scheduling
* Add comment to notification display slot
* Synchronise branches
* Use new HuskHomes-style task system
* Bump to 2.3
* Remove HuskSyncInitializationException.java
* Optimise database for MariaDB
* Update libraries, move some around
* Tweak command registration
* Remove dummyhusksync
* Fixup core synchronisation logic to use new task system
* Implement new event dispatch subsystem
* Remove last remaining future calls
* Remove `Event#fire()`
* Refactor startup process
* New command subsystem, more initialization improvements, locale fixes
* Update docs, tweak command perms
* Reduce task number during data setting
* add todo
* Start work on data format / serialization refactor
* More work on Bukkit impl
* More serialization work
* Fixes to serialization, data preview system
* Start legacy conversion skeleton
* Handle setting empty inventories
* Start on-the-fly legacy conversion work
* Add advancement conversion
* Rewrite advancement get / apply logic
* Start work on locked map persistence
* More map persistence work
* More work on map serialization
* Move around persistence logic
* Add testing suite
* Fix item synchronisation
* Finalize more reliable locked map persistence
* Remove deprecated method call
* remove sync feature enum
* Fix held item slot syncing
* Make data types modular and API-extensible
* Remove some excessive debugging, minor refactor
* Fixup date formatting, improve menu UIs
* Finish up legacy data converting
* Null safety in item stack serializaiton
* Fix relocation of nbtapi, update dumping docs
* Add v1/MPDB Migrators back in
* Fix pinning/unpinning data not working
* Consumer instead of Function for editing data
* Show file size in DataSnapshotOverview
* Fix getIdentifier always returning empty
* Re-add items and inventory GUI commands
* Improve config file, fixup data restoration
* Add min time between backups (more useful backups!)
* More work on backups
* Fixup backup rotation frequency
* Remove stdout debug print in `#getEventPriority`
* Improve sync complete locale logic, fix synchronization spelling
* Remove `static` on exception
* Use dedicated thread for Redis, properly unsubscribe
* Refactor `player` package -> `user`
* `PlayerDataHolder` -> `UserDataHolder`
* Make `StatisticsMap` public, but `@ApiStatus.Internal`
* Suppress unused warnings on `Data`
* Add option to disable Plan hook
* Decompress legacy data before converting
* Decompress bytes in fromBytes
* Check permission node before serving TAB suggestions
* Actually convert legacy item stack data
* Fix syntax errors
* Minor method refactor in items command
* Fixup case-sensitive parsing in HuskSync command
* Start API work
* More work on API, fix potion effects
* Fix cross-server, config formatting for auto-pinned issue
* Fix confusion with UserData command, update docs images
* Update commands docs
* More docs updating
* Fix sync feature enabled/disabled checking logic
* Fix `#isCustom()`
* Enable persistent_data syncing by default
* docs: update Sync-Features config snippet
* docs: correct typo in Sync Features
* More API work
* bukkit: slightly optimized schedulers
* More API work, various refactorings
* docs: Start new API docs
* bump dependencies
* Add some basic unit tests
* docs: Correct typos
* More docs work, annotate DB methods as `@Blocking`
* Encapsulate `RedisMessage`, minor optimisations
* api: Simplify `#getCurrentData`
* api: Simplify `editCurrentData`, using `ThrowingConsumers` for better error handling
* docs: More Data Snapshot API documenting
* docs: add TOC to Data Snapshot API page
* bukkit: Make data types extend BukkitData
* Move where custom data is stored, finish up Custom Data API docs
* Optimise imports
* Fix `data_manager_advancements_preview_remaining` locale
* Fix advancement and playtime previews
* Fix potion effect deserialization
* Make snapshot_backup_frequency default to 4, more error handling/logging
* docs: Add ToC to Custom Data API
* docs: Minor legacy API tweaks
* Remove some unneeded catch logic
* Suppress a few warnings
* Fix Effect constructor being supplied in wrong order
1 year ago
- HuskSync will notify in console when migration is complete. Verify that the migration went OK by logging in and using the `/userdata list <username>` command to see if the data was imported with the `legacy migration` saveCause.
- You can delete the old tables in the database if you want. Be careful to make sure you delete the right ones. By default the *new* table names are `husksync_users` and `husksync_user_data` and the *old* ones were `husksync_players` and `husksync_data` , but you may have changed these.
