feat: add optional SQL directory for utility scripts

Utility SQL scripts for debugging, performance testing, and scenario recreation shouldn't run automatically but should be available in the repository for developers to use when needed.

The optional/sql/ directory holds these scripts separately from
deployment-specific sql/ directories, which are mounted to PostgreSQL's docker-entrypoint-initdb.d. This avoids duplicating utility scripts across deployments whilst keeping them discoverable.

Each script includes a header with compatibility information and usage instructions. Users can either copy files to their deployment's sql/ directory for automatic execution on fresh start, or run them manually against a running database.

README.md

@@ -48,6 +48,39 @@ SQL files use numeric prefixes to control execution order:
 
 If you need to add custom SQL scripts (e.g., for test data or configuration), use an appropriate numeric prefix to ensure correct execution order.
 
+## Optional SQL Files
+
+The `optional/sql/` directory contains utility SQL scripts that are **not** executed automatically. These are useful for debugging, performance testing, or recreating specific scenarios.
+
+### Using Optional SQL Files
+
+Each file includes a header documenting its purpose and compatibility with different deployment types.
+
+**Method 1: Copy to deployment directory (runs on next fresh start)**
+
+```bash
+# Copy the file to your deployment's sql/ directory
+cp optional/sql/001-generate-test-data.sql simple/sql/
+
+# Start fresh (remove existing DB volume first if needed)
+./start.sh
+```
+
+**Method 2: Run manually against a running database**
+
+```bash
+# Run directly without copying
+docker exec -i simple-db-1 psql -U openfire -d openfire < optional/sql/001-generate-test-data.sql
+```
+
+Replace `simple-db-1` with the appropriate container name for your deployment (e.g., `cluster-db-1`, `federation-db1-1`).
+
+### Available Optional SQL Files
+
+| File | Purpose | Compatibility |
+|------|---------|---------------|
+| `001-generate-test-data.sql` | Generates ~410K MUC messages for slow startup testing | All deployments |
+
 ## Remote Debugging
 
 All Openfire containers are configured with Java remote debugging enabled via JDWP. The debug agent runs in non-blocking mode (`suspend=n`), so containers start normally without waiting for a debugger to attach.

optional/sql/001-generate-test-data.sql

@@ -0,0 +1,76 @@
+-- =============================================================================
+-- Generate Test Data: Slow Startup Issue Recreation
+-- =============================================================================
+--
+-- Compatibility: all deployments (simple, cluster, federation, cluster_with_federation, proxy)
+--
+-- Purpose:
+--   Generates ~410,000 MUC messages to simulate a long-running environment
+--   experiencing slow startup due to large message history.
+--
+-- Usage:
+--   1. Copy this file to your deployment's sql/ directory:
+--
+--      cp optional/sql/001-generate-test-data.sql simple/sql/
+--
+--   2. Restart containers (or start fresh if DB already initialised):
+--
+--      ./start.sh
+--
+--   Alternatively, run manually against a running database:
+--
+--      docker exec -i simple-db-1 psql -U openfire -d openfire < optional/sql/001-generate-test-data.sql
+--
+-- =============================================================================
+
+DO $$
+DECLARE
+    base_time BIGINT := (EXTRACT(EPOCH FROM NOW()) * 1000)::BIGINT;
+    msg_id INTEGER := 100;
+    i INTEGER;
+    room_id INTEGER;
+    log_time CHAR(15);
+BEGIN
+    RAISE NOTICE 'Starting message generation at %', NOW();
+
+    FOR i IN 1..410000 LOOP
+        room_id := (i % 2) + 1;
+        log_time := LPAD((base_time - (i::BIGINT * 6480))::TEXT, 15, '0');
+
+        INSERT INTO ofmucconversationlog (roomid, messageid, sender, nickname, logtime, subject, body, stanza)
+        VALUES (
+            room_id,
+            msg_id,
+            'user1@xmpp.localhost.example/resource',
+            'User One',
+            log_time,
+            NULL,
+            'Test message ' || i,
+            NULL
+        );
+
+        msg_id := msg_id + 1;
+
+        IF i % 50000 = 0 THEN
+            RAISE NOTICE 'Progress: % messages inserted', i;
+        END IF;
+    END LOOP;
+
+    RAISE NOTICE 'Message generation complete at %', NOW();
+END $$;
+
+-- Set long history configuration
+INSERT INTO ofmucserviceprop (serviceid, name, propvalue)
+VALUES (1, 'history.maxNumber', '1000')
+ON CONFLICT (serviceid, name) DO UPDATE SET propvalue = '1000';
+
+INSERT INTO ofmucserviceprop (serviceid, name, propvalue)
+VALUES (1, 'history.type', 'number')
+ON CONFLICT (serviceid, name) DO UPDATE SET propvalue = 'number';
+
+-- Ensure NO reload limit (worst case scenario)
+DELETE FROM ofproperty WHERE name = 'xmpp.muc.history.reload.limit';
+
+-- Verify
+SELECT 'Total messages: ' || COUNT(*)::TEXT FROM ofmucconversationlog;
+SELECT 'Room ' || roomid || ': ' || COUNT(*)::TEXT || ' messages' FROM ofmucconversationlog GROUP BY roomid ORDER BY roomid;