InventoryFlow

A high-performance hybrid storage system for Minecraft network servers, implementing a write-behind cache pattern with Redis/Dragonfly and PostgreSQL/CockroachDB.

Features

• Submillisecond Performance: Player data loads from Redis cache during server switches
• Write-Behind Cache Pattern: Asynchronous data persistence to SQL database
• Data Locking Mechanism: Prevents race conditions during server transfers
• SOLID Architecture: Clean, extensible, and maintainable codebase
• Non-Blocking Operations: All database operations use CompletableFuture with virtual threads (Java 21)
• Dual Database Support: Compatible with both PostgreSQL and CockroachDB
• JSONB Storage: Efficient storage of complex player data structures
• Auto-Save System: Periodic background synchronization from Redis to SQL with configurable batch processing
• Comprehensive Sync Options: Synchronize inventory, ender chest, health, food, XP, effects, advancements, and statistics
• Fully Customizable Messages: All messages configurable in messages.yml with color codes and placeholders
• Performance Monitoring: Built-in performance tracking and warnings for slow operations
• Batch Processing: Efficient handling of multiple players with configurable batch sizes
• World Change Detection: Optional data saving when players change worlds
• SSL Support: Secure database connections with SSL/TLS

Architecture

Repository Pattern

PlayerRepository (Interface)
├── SqlPlayerRepository (PostgreSQL/CockroachDB)
└── RedisPlayerRepository (Dragonfly/Redis)

Data Flow

1. Player Join: Load from Redis → Fallback to SQL if cache miss → Update Redis
2. Server Switch: Save to Redis with lock → Transfer player → Release lock
3. Player Quit: Save to Redis → Asynchronously persist to SQL
4. Auto-Save: Periodic batch write from Redis to SQL

Requirements

• Java 21 or higher
• Gradle 8.x
• Paper/Spigot 1.21+
• Redis/Dragonfly instance
• PostgreSQL 12+ or CockroachDB

Configuration

The plugin automatically generates config.yml and messages.yml on first run.

config.yml

server:
  id: "survival-01"
  group: "survival"

database:
  type: POSTGRESQL
  host: localhost
  port: 5432
  name: network_data
  user: admin
  pass: 'password'
  ssl: false
  pool:
    max_size: 15
    connection_timeout: 5000

redis:
  host: localhost
  port: 6379
  pass: ''
  lock_timeout: 3

sync_settings:
  inventory: true
  ender_chest: true
  health: true
  food: true
  xp: true
  effects: true
  advancements: true
  statistics: true

automation:
  sql_backup_interval: 15
  save_on_quit: true
  save_on_world_change: true
  async_processing: true

performance:
  batch_size: 50
  use_compression: true
  achievement_timeout_ms: 5000

logging:
  level: INFO
  monitor_performance: true

messages.yml

All player-facing and console messages are fully customizable with color codes (&a, &b, etc.) and placeholders:

prefix: "&8[&bInventoryFlow&8]&r"

loading:
  start: "{prefix} &7Loading your data..."
  success: "{prefix} &aData loaded successfully!"
  
errors:
  data_locked: "{prefix} &cYour data is currently being transferred."
  
# ... and many more configurable messages

Configuration Options

Server

• id: Unique server identifier in the network
• group: Server group for applying group-based configurations

Database

• type: Database type (POSTGRESQL for both PostgreSQL and CockroachDB)
• host: Database server hostname
• port: Database server port
• name: Database name
• user: Database username
• pass: Database password
• ssl: Enable SSL connection
• pool.max_size: HikariCP maximum connections
• pool.connection_timeout: Connection timeout in milliseconds

Redis

• host: Redis/Dragonfly server hostname
• port: Redis/Dragonfly server port
• pass: Redis authentication password (leave empty if not required)
• lock_timeout: Lock duration in seconds during server transfers

Sync Settings

• inventory: Synchronize player inventory
• ender_chest: Synchronize ender chest contents
• health: Synchronize player health
• food: Synchronize hunger and saturation
• xp: Synchronize experience and levels
• effects: Synchronize potion effects
• advancements: Synchronize achievements/advancements
• statistics: Synchronize player statistics

Automation

• sql_backup_interval: Minutes between automatic Redis-to-SQL saves
• save_on_quit: Save data when player disconnects
• save_on_world_change: Save data when player changes worlds
• async_processing: Process all operations asynchronously

Performance

• batch_size: Number of players to process in each batch during auto-save
• use_compression: Compress JSON data before sending to Redis (saves bandwidth)
• achievement_timeout_ms: Timeout for achievement synchronization to prevent lag

Logging

• level: Log level (INFO or DEBUG for verbose output)
• monitor_performance: Log performance metrics for operations

Building

./gradlew build

The compiled plugin will be available in build/libs/InventoryFlow-1.0.0.jar

Installation

1. Build the plugin or download the JAR file
2. Place InventoryFlow-1.0.0.jar in your server's plugins/ directory
3. Start the server to generate the default configuration
4. Configure your database and Redis connection in config.yml
5. Restart the server

Database Setup

PostgreSQL

CREATE DATABASE minecraft_network;
CREATE USER admin WITH PASSWORD 'securepassword123';
GRANT ALL PRIVILEGES ON DATABASE minecraft_network TO admin;

CockroachDB

CREATE DATABASE minecraft_network;
CREATE USER admin WITH PASSWORD 'securepassword123';
GRANT ALL ON DATABASE minecraft_network TO admin;

The plugin automatically creates the required table schema on first run.

Technical Details

Data Snapshot Structure

Player data is serialized to JSONB format containing:

• Inventory: Base64-encoded ItemStack array
• EnderChest: Base64-encoded ItemStack array
• Health: Player health points
• Food: Hunger level and saturation
• XP: Total experience, level, and experience progress
• Effects: Base64-encoded active potion effects
• Statistics: Custom key-value statistics
• Advancements: Achievement/advancement completion status
• LastUpdate: Timestamp of last modification

Connection Pooling

Uses HikariCP for optimal database connection management:

• Prepared statement caching
• Batch insert rewriting
• Connection leak detection
• Health checks

Concurrency

• Virtual threads (Java 21) for all async operations
• ConcurrentHashMap for local cache
• Redis-based distributed locking
• CompletableFuture for non-blocking database access

Data Locking

When a player switches servers:

1. Acquire lock: player:lock:<uuid> with TTL
2. Save data to Redis cache
3. Player transfers to new server
4. New server waits for lock release
5. Load data from Redis cache

This prevents race conditions and data loss during transfers.

Performance

• Redis Read: < 1ms
• Redis Write: < 1ms
• SQL Read (cache miss): 5-20ms
• SQL Write (async): Non-blocking

Dependencies

• HikariCP: High-performance JDBC connection pool
• Jedis: Redis client for Java
• PostgreSQL JDBC: Database driver
• Gson: JSON serialization
• SnakeYAML: Configuration parsing

License

Under MIT license

Author

Sebastian Cheikh

Support

For issues or questions, please contact the development team.