BOOST.DB

A Java library for database migration management and multi-tenant database provisioning. It handles schema versioning via Flyway and automates tenant onboarding with database creation, migration, and seed data.

Architecture

Master-Tenant Pattern

• Master Database (qeeping) — stores organizational metadata and datasource configurations
• Tenant Databases (boost_<tenantId>) — individual databases per tenant with identical schemas
• Supports multiple MySQL servers via configurable datasource IDs

Master DB (qeeping)
    ├── organizations table (tenant metadata)
    ├── datasources table (connection info)
    │
    ↓ (lookup credentials)
┌────────────────────────────────┐
│ Tenant DBs                     │
│  boost_tenant1  boost_tenant2  │
│  boost_tenant3  ...            │
└────────────────────────────────┘

Prerequisites

• Java 11+ (uses Java module system)
• MySQL database server
• Maven for building

Configuration

hikari-qeeping-master.properties

jdbcUrl=jdbc:mysql://10.245.10.35:3306/qeeping?useUnicode=true&serverTimezone=UTC
dataSource.user=qeeping-master
dataSource.password=****
dataSource.minIdle=0
dataSource.maxLifetime=240000
dataSource.idleTimeout=240000

Core Services

MigrationService

Manages Flyway migrations for tenant databases.

MigrationService migrationService = new MigrationService();

// Run migrations for a tenant
migrationService.migrate(tenantOrgUUID, "classpath:db/migration", true);

// Establish a baseline version
migrationService.baseline(tenantOrgUUID, "20251103.001", "baseline", "classpath:db/migration.20251103");

Method	Description
migrate(tenantOrgUUID, location, repair)	Runs Flyway migrations, optionally repairing broken state first
baseline(tenantOrgUUID, version, description, location)	Sets a baseline schema version for new tenants

TenantOnboardingService

End-to-end tenant provisioning.

TenantOnboardingService onboarding = new TenantOnboardingService();

onboarding.onboardTenant(
    tenantId,           // Unique tenant identifier
    tenantName,         // Display name
    datasourceId,       // Target MySQL server
    orgUUID,            // Organization UUID
    personUUID,         // Initial user person UUID
    userUUID,           // Initial user UUID
    firstName,
    lastName,
    email,
    username
);

onboarding.close();

Onboarding workflow:

1. createDatabase() — Creates boost_<tenantId> with UTF8MB4 charset
2. runMigrations() — Applies baseline migrations from db/migration.20251103
3. customizeTenant() — Inserts organization, person, and user records

Migration Structure

Main Migrations (db/migration/)

90+ versioned SQL files covering the full schema evolution:

• Naming convention: V<YYYYMMDD>.<sequence>__<description>.sql
• Range: V20250323.001 through V20260122.001

Baseline Migrations (db/migration.20251103/)

A snapshot for bootstrapping new tenant databases:

• V20251103.001__baseline.sql — Full schema dump
• V20251103.002__seed_data.sql — Required seed data
• Subsequent migrations to bring up to current version

Schema Coverage

The migrations define tables for:

• Quartz scheduler (QRTZ_*)
• Business entities (items, orders, customers, suppliers)
• Document management and approval workflows
• Work orders and scheduling
• Inventory management
• Financial/accounting (journals, accounts, bank transactions)
• Personnel and skills tracking
• Audit logs and notes

Java Module Definition

module BOOST.DBLib {
    requires com.zaxxer.hikari;
    requires org.flywaydb.core;
    requires java.sql;
    exports com.luqon.boost.db;
}

Dependencies

Dependency	Version	Purpose
flyway-core	11.4.1	Database migration framework
flyway-mysql	11.4.1	MySQL-specific Flyway support
mysql-connector-j	9.2.0	MySQL JDBC driver
HikariCP	5.1.0	Connection pooling

Project Structure

BOOST.DB/
├── pom.xml
├── hikari-qeeping-master.properties
├── src/main/
│   ├── java/com/luqon/boost/db/
│   │   ├── BoostDB.java                    # Entry point / CLI
│   │   ├── MigrationService.java           # Migration orchestration
│   │   ├── TenantOnboardingService.java    # Tenant provisioning
│   │   └── TestTenantOnboarding.java       # Test/example
│   ├── resources/db/
│   │   ├── migration/                      # Main migration files (90+)
│   │   └── migration.20251103/             # Baseline migration set
│   └── module-info.java

Running

# Run migrations for all configured tenants
java -jar boostdblink.jar

# Or use programmatically as a library
MigrationService svc = new MigrationService();
svc.migrate(tenantUUID, "classpath:db/migration", true);