mirror of
https://github.com/EQEmu/Server.git
synced 2026-04-20 13:42:27 +00:00
110 lines
3.9 KiB
Markdown
110 lines
3.9 KiB
Markdown
# Bazaar Item Unique ID And Offline Trading Rollout
|
|
|
|
## Purpose
|
|
|
|
This rollout converts persisted item identity and offline trader or buyer session state to the new production-safe model. The migration is designed for a maintenance window and explicitly clears any in-flight trader, buyer, and offline sessions during cutover.
|
|
|
|
Do not reopen the server until every verification step passes.
|
|
|
|
## Preconditions
|
|
|
|
- Schedule a maintenance window.
|
|
- Stop new logins before beginning the migration.
|
|
- Ensure the `world` binary you are deploying includes this branch.
|
|
- Ensure operators have credentials to run schema updates and database dump commands.
|
|
|
|
## Mandatory Backup
|
|
|
|
Take a backup before any schema or migration command:
|
|
|
|
```powershell
|
|
world database:dump --player-tables --login-tables --dump-path=backups --compress
|
|
```
|
|
|
|
If you use a separate database backup process, complete it before continuing.
|
|
|
|
## Local Dev Validation
|
|
|
|
Run these commands against the local dev database before production:
|
|
|
|
```powershell
|
|
world database:updates --skip-backup
|
|
world database:item-unique-ids --preflight --verbose
|
|
world database:item-unique-ids --migrate --verbose
|
|
world database:item-unique-ids --verify --verbose
|
|
```
|
|
|
|
Validate these gameplay scenarios after the migration:
|
|
|
|
- Two traders listing the same item at different prices.
|
|
- One trader changing a price without affecting another trader.
|
|
- Offline trader purchase.
|
|
- Offline buyer purchase.
|
|
- Parcel retrieval for rows that previously had missing `item_unique_id` values.
|
|
- Alternate bazaar shard search.
|
|
|
|
## Production Sequence
|
|
|
|
1. Bring the server into maintenance mode and stop new gameplay activity.
|
|
2. Take the mandatory backup.
|
|
3. Apply schema updates:
|
|
|
|
```powershell
|
|
world database:updates
|
|
```
|
|
|
|
4. Run the migration preflight:
|
|
|
|
```powershell
|
|
world database:item-unique-ids --preflight --verbose
|
|
```
|
|
|
|
5. If preflight reports missing schema, duplicate live item IDs, or other unexpected errors, stop and resolve them before continuing.
|
|
6. Run the migration:
|
|
|
|
```powershell
|
|
world database:item-unique-ids --migrate --verbose
|
|
```
|
|
|
|
This step clears active trader, buyer, and offline session state. Players must re-enter those modes after deploy.
|
|
|
|
7. Run final verification:
|
|
|
|
```powershell
|
|
world database:item-unique-ids --verify --verbose
|
|
```
|
|
|
|
8. Reopen the server only after verification passes.
|
|
|
|
## What Preflight And Verify Must Show
|
|
|
|
The migration is not complete unless all of the following are true:
|
|
|
|
- `inventory`, `sharedbank`, and `trader` contain no null or blank `item_unique_id` values.
|
|
- `character_parcels`, `character_parcels_containers`, and `inventory_snapshots` contain no null or blank `item_unique_id` values.
|
|
- `inventory`, `sharedbank`, and `trader` contain no duplicate `item_unique_id` groups.
|
|
- There are no cross-table duplicate live `item_unique_id` values across `inventory`, `sharedbank`, and `trader`.
|
|
- `offline_character_sessions` is empty after migration.
|
|
- `account.offline` has no rows left set to `1`.
|
|
|
|
## Rollback Criteria
|
|
|
|
Rollback instead of reopening the server if any of the following occur:
|
|
|
|
- `world database:updates` fails.
|
|
- `world database:item-unique-ids --preflight` reports missing required schema.
|
|
- `world database:item-unique-ids --migrate` or `--verify` reports missing IDs, duplicate IDs, or stale offline session state.
|
|
- Bazaar listing, offline trader, offline buyer, or parcel retrieval smoke tests fail after migration.
|
|
|
|
## Rollback Actions
|
|
|
|
1. Keep the server in maintenance mode.
|
|
2. Restore the database backup taken before the rollout.
|
|
3. Redeploy the previous server build.
|
|
4. Confirm login, trader, buyer, and parcel behavior on the restored build before reopening the server.
|
|
|
|
## Notes
|
|
|
|
- `world database:item-unique-ids --keep-trading-state` exists for non-production diagnostics only. Do not use it during production cutover.
|
|
- The migration command expects schema updates to have been applied first. If required tables or columns are missing, the command fails and should not be bypassed.
|