perf(db): add UNLOGGED permission_reference and LZ4 compression startup tasks

wezell · claude · wezell · commit ac32518bc937 · 2026-04-03T08:24:21.000-04:00
Task260403SetPermissionReferenceUnlogged:
- Converts permission_reference to UNLOGGED via ALTER TABLE SET UNLOGGED
- Table is a regenerable permission cache; crash-safety is not required
- Eliminates WAL write cost on every permission rebuild INSERT/DELETE
- forceRun() checks pg_class.relpersistence to skip if already unlogged

Task260403SetLz4CompressionOnTextColumns:
- Sets LZ4 compression on all text/bytea/jsonb/json columns in public schema
- Queries pg_attribute dynamically — no hardcoded column list, covers plugins
- Skips columns already using LZ4 (attcompression='l') for idempotency
- Continues on per-column failure so one bad column does not block all others
- Gracefully skips on PostgreSQL &lt; 14 (attcompression column absent)
- LZ4 decompresses 3-5x faster than pglz; affects future writes only

postgres.sql:
- permission_reference CREATE TABLE now uses UNLOGGED
- LZ4 SET COMPRESSION block added for all eligible columns (fresh installs)

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/dotCMS/src/main/java/com/dotmarketing/startup/runonce/Task260403SetLz4CompressionOnTextColumns.java b/dotCMS/src/main/java/com/dotmarketing/startup/runonce/Task260403SetLz4CompressionOnTextColumns.java
@@ -0,0 +1,131 @@
+package com.dotmarketing.startup.runonce;
+
+import com.dotmarketing.common.db.DotConnect;
+import com.dotmarketing.db.DbConnectionFactory;
+import com.dotmarketing.exception.DotDataException;
+import com.dotmarketing.exception.DotRuntimeException;
+import com.dotmarketing.startup.StartupTask;
+import com.dotmarketing.util.Logger;
+
+import java.sql.SQLException;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Sets LZ4 compression on every {@code text}, {@code bytea}, {@code jsonb}, and {@code json}
+ * column in the {@code public} schema that uses TOAST storage.
+ *
+ * <h3>Why LZ4?</h3>
+ * PostgreSQL defaults to pglz for TOAST compression. LZ4 decompresses roughly 3–5× faster
+ * than pglz while achieving comparable (often slightly better) ratios on typical dotCMS data
+ * (HTML, JSON, workflow payloads). Read-heavy workloads — content delivery, page rendering,
+ * workflow evaluation — pay the decompression cost on every fetch of a TOASTed column, so
+ * faster decompression directly reduces latency.
+ *
+ * <h3>Scope</h3>
+ * Only columns with TOAST-eligible storage are targeted (extended / external / main).
+ * Plain-storage columns (e.g. short {@code varchar}) are excluded automatically via
+ * the {@code pg_attribute.attstorage} filter. Columns that already use LZ4
+ * ({@code attcompression = 'l'}) are skipped — the task is fully idempotent.
+ *
+ * <h3>Effect on existing data</h3>
+ * {@code SET COMPRESSION lz4} changes the compression method for <em>future</em> writes only.
+ * Existing TOASTed values are not rewritten immediately — they retain their original encoding
+ * until the row is next updated. This makes the migration instant and lock-free.
+ *
+ * <h3>PostgreSQL version requirement</h3>
+ * LZ4 compression ({@code attcompression} column in {@code pg_attribute}) requires
+ * PostgreSQL 14 or later. On older versions the task is skipped gracefully.
+ *
+ * @since Apr 3rd, 2026
+ */
+public class Task260403SetLz4CompressionOnTextColumns implements StartupTask {
+
+    /**
+     * Finds all TOAST-eligible text/bytea/jsonb/json columns in the public schema that do not
+     * yet use LZ4 compression. Used both for the {@link #forceRun()} check and the upgrade loop.
+     *
+     * <p>Storage codes: 'x' = extended (TOAST, compressed), 'e' = external (TOAST,
+     * uncompressed), 'm' = main (inline compressed). All three benefit from LZ4.
+     * 'p' = plain (never TOASTed) — excluded.
+     *
+     * <p>Compression codes: 'l' = lz4, 'p' = pglz, '\0' = default (pglz).
+     */
+    private static final String FIND_COLUMNS_SQL =
+            "SELECT c.relname AS tbl, a.attname AS col " +
+            "  FROM pg_attribute a " +
+            "  JOIN pg_class c ON c.oid = a.attrelid " +
+            "  JOIN pg_namespace n ON n.oid = c.relnamespace " +
+            "  JOIN pg_type t ON t.oid = a.atttypid " +
+            " WHERE n.nspname = 'public' " +
+            "   AND a.attnum > 0 " +
+            "   AND NOT a.attisdropped " +
+            "   AND t.typname IN ('text', 'bytea', 'jsonb', 'json') " +
+            "   AND a.attstorage IN ('x', 'e', 'm') " +
+            "   AND a.attcompression != 'l' " +
+            " ORDER BY c.relname, a.attname";
+
+    @Override
+    public boolean forceRun() {
+        if (!DbConnectionFactory.isPostgres()) {
+            return false;
+        }
+        try {
+            final List<Map<String, Object>> pending = new DotConnect()
+                    .setSQL(FIND_COLUMNS_SQL)
+                    .loadObjectResults();
+            return !pending.isEmpty();
+        } catch (final DotDataException e) {
+            // pg_attribute.attcompression does not exist on PG < 14 — skip gracefully
+            Logger.warn(this, "Could not query pg_attribute for compression status "
+                    + "(requires PostgreSQL 14+), skipping LZ4 migration: " + e.getMessage());
+            return false;
+        }
+    }
+
+    @Override
+    public void executeUpgrade() throws DotDataException {
+        if (!DbConnectionFactory.isPostgres()) {
+            Logger.info(this, "Skipping LZ4 compression migration (not PostgreSQL)");
+            return;
+        }
+
+        final List<Map<String, Object>> columns;
+        try {
+            columns = new DotConnect().setSQL(FIND_COLUMNS_SQL).loadObjectResults();
+        } catch (final DotDataException e) {
+            Logger.warn(this, "Could not query columns for LZ4 compression "
+                    + "(requires PostgreSQL 14+), skipping: " + e.getMessage());
+            return;
+        }
+
+        if (columns.isEmpty()) {
+            Logger.info(this, "All eligible columns already use LZ4 compression — nothing to do");
+            return;
+        }
+
+        Logger.info(this, "Setting LZ4 compression on " + columns.size() + " column(s)");
+        int updated = 0;
+        int failed = 0;
+
+        for (final Map<String, Object> row : columns) {
+            final String table = (String) row.get("tbl");
+            final String column = (String) row.get("col");
+            final String sql = "ALTER TABLE " + table
+                    + " ALTER COLUMN " + column + " SET COMPRESSION lz4";
+            try {
+                new DotConnect().executeStatement(sql);
+                updated++;
+            } catch (final SQLException e) {
+                // Log and continue — one bad column should not block all others
+                Logger.warn(this, "Failed to set LZ4 on " + table + "." + column
+                        + ": " + e.getMessage());
+                failed++;
+            }
+        }
+
+        Logger.info(this, "LZ4 compression migration complete — "
+                + updated + " column(s) updated, " + failed + " skipped due to errors");
+    }
+
+}
diff --git a/dotCMS/src/main/java/com/dotmarketing/startup/runonce/Task260403SetPermissionReferenceUnlogged.java b/dotCMS/src/main/java/com/dotmarketing/startup/runonce/Task260403SetPermissionReferenceUnlogged.java
@@ -0,0 +1,77 @@
+package com.dotmarketing.startup.runonce;
+
+import com.dotmarketing.common.db.DotConnect;
+import com.dotmarketing.db.DbConnectionFactory;
+import com.dotmarketing.exception.DotDataException;
+import com.dotmarketing.exception.DotRuntimeException;
+import com.dotmarketing.startup.StartupTask;
+import com.dotmarketing.util.Logger;
+
+import java.sql.SQLException;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Converts the {@code permission_reference} table to UNLOGGED.
+ *
+ * <p>UNLOGGED tables bypass WAL (Write-Ahead Logging), which eliminates the
+ * per-row WAL write cost on every INSERT/UPDATE/DELETE. This table is a pure
+ * denormalized cache — rows are rebuilt automatically by the permission system
+ * whenever they are invalidated. Losing this data on an unexpected crash is
+ * completely safe because the permission system rebuilds it on demand.
+ *
+ * <p>Expected benefits:
+ * <ul>
+ *   <li>~2–3× faster INSERT/DELETE throughput on permission rebuilds</li>
+ *   <li>Reduced WAL volume, lowering I/O pressure and replication lag</li>
+ *   <li>Smaller checkpoints during mass permission recalculation</li>
+ * </ul>
+ *
+ * <p>{@code ALTER TABLE ... SET UNLOGGED} rewrites the table (brief exclusive
+ * lock) and truncates the unlogged table on replica nodes — expected behaviour
+ * since permission_reference is never read-from replicas directly.
+ *
+ * @since Apr 3rd, 2026
+ */
+public class Task260403SetPermissionReferenceUnlogged implements StartupTask {
+
+    private static final String TABLE_NAME = "permission_reference";
+
+    @Override
+    public boolean forceRun() {
+        if (!DbConnectionFactory.isPostgres()) {
+            return false;
+        }
+        try {
+            // relpersistence = 'u' means UNLOGGED; 'p' means permanent (logged)
+            final List<Map<String, Object>> result = new DotConnect()
+                    .setSQL("SELECT 1 FROM pg_class WHERE relname = ? AND relpersistence = 'u'")
+                    .addParam(TABLE_NAME)
+                    .loadObjectResults();
+            return result.isEmpty(); // run if NOT already unlogged
+        } catch (final DotDataException e) {
+            // Fail open — idempotent DDL, safe to re-run
+            Logger.error(this, "Error in forceRun() for " + TABLE_NAME + ", defaulting to run: "
+                    + e.getMessage(), e);
+            return true;
+        }
+    }
+
+    @Override
+    public void executeUpgrade() throws DotDataException {
+        if (!DbConnectionFactory.isPostgres()) {
+            Logger.info(this, "Skipping SET UNLOGGED for " + TABLE_NAME + " (not PostgreSQL)");
+            return;
+        }
+        try {
+            Logger.info(this, "Converting " + TABLE_NAME + " to UNLOGGED");
+            new DotConnect().executeStatement(
+                    "ALTER TABLE " + TABLE_NAME + " SET UNLOGGED");
+            Logger.info(this, "Successfully converted " + TABLE_NAME + " to UNLOGGED");
+        } catch (final SQLException e) {
+            throw new DotDataException(
+                    "Failed to set " + TABLE_NAME + " UNLOGGED: " + e.getMessage(), e);
+        }
+    }
+
+}
diff --git a/dotCMS/src/main/java/com/dotmarketing/util/TaskLocatorUtil.java b/dotCMS/src/main/java/com/dotmarketing/util/TaskLocatorUtil.java
@@ -264,6 +264,8 @@
 import com.dotmarketing.startup.runonce.Task260320AddPluginsPortletToMenu;
 import com.dotmarketing.startup.runonce.Task260324AddIdentifierPathTriggerIndex;
 import com.dotmarketing.startup.runonce.Task260331AddBaseTypeColumnToIdentifier;
+import com.dotmarketing.startup.runonce.Task260403SetLz4CompressionOnTextColumns;
+import com.dotmarketing.startup.runonce.Task260403SetPermissionReferenceUnlogged;
 import com.google.common.collect.ImmutableList;
 
 import java.util.ArrayList;
@@ -602,6 +604,8 @@ public static List<Class<?>> getStartupRunOnceTaskClasses() {
         .add(Task260320AddPluginsPortletToMenu.class)
         .add(Task260324AddIdentifierPathTriggerIndex.class)
         .add(Task260331AddBaseTypeColumnToIdentifier.class)
+        .add(Task260403SetLz4CompressionOnTextColumns.class)
+        .add(Task260403SetPermissionReferenceUnlogged.class)
         .build();
 
         return ret.stream().sorted(classNameComparator).collect(Collectors.toList());
diff --git a/dotCMS/src/main/resources/postgres.sql b/dotCMS/src/main/resources/postgres.sql
@@ -535,7 +535,7 @@ create table user_comments (
    communication_id varchar(36),
    primary key (inode)
 );
-create table permission_reference (
+create unlogged table permission_reference (
    id int8 not null,
    asset_id varchar(36),
    reference_id varchar(36),
@@ -2599,3 +2599,105 @@ CREATE TABLE IF NOT EXISTS unique_fields
     unique_key_val VARCHAR PRIMARY KEY,
     supporting_values JSONB
 );
+
+-- ---------------------------------------------------------------------------
+-- LZ4 compression on variable-length (TOAST-eligible) columns
+-- Requires PostgreSQL 14+. SET COMPRESSION only affects future writes;
+-- existing TOASTed values are rewritten lazily on next UPDATE.
+-- For upgrades this is applied by Task260403SetLz4CompressionOnTextColumns.
+-- ---------------------------------------------------------------------------
+ALTER TABLE AdminConfig ALTER COLUMN config SET COMPRESSION lz4;
+ALTER TABLE Company ALTER COLUMN key_ SET COMPRESSION lz4;
+ALTER TABLE Image ALTER COLUMN text_ SET COMPRESSION lz4;
+ALTER TABLE PollsChoice ALTER COLUMN description SET COMPRESSION lz4;
+ALTER TABLE PollsQuestion ALTER COLUMN description SET COMPRESSION lz4;
+ALTER TABLE Portlet ALTER COLUMN defaultPreferences SET COMPRESSION lz4;
+ALTER TABLE Portlet ALTER COLUMN roles SET COMPRESSION lz4;
+ALTER TABLE PortletPreferences ALTER COLUMN preferences SET COMPRESSION lz4;
+ALTER TABLE User_ ALTER COLUMN password_ SET COMPRESSION lz4;
+ALTER TABLE User_ ALTER COLUMN comments SET COMPRESSION lz4;
+ALTER TABLE User_ ALTER COLUMN additional_info SET COMPRESSION lz4;
+ALTER TABLE UserTrackerPath ALTER COLUMN path SET COMPRESSION lz4;
+ALTER TABLE api_token_issued ALTER COLUMN claims SET COMPRESSION lz4;
+ALTER TABLE campaign ALTER COLUMN message SET COMPRESSION lz4;
+ALTER TABLE category ALTER COLUMN keywords SET COMPRESSION lz4;
+ALTER TABLE chain_link_code ALTER COLUMN code SET COMPRESSION lz4;
+ALTER TABLE clickstream_404 ALTER COLUMN query_string SET COMPRESSION lz4;
+ALTER TABLE clickstream_request ALTER COLUMN query_string SET COMPRESSION lz4;
+ALTER TABLE cms_role ALTER COLUMN description SET COMPRESSION lz4;
+ALTER TABLE communication ALTER COLUMN text_message SET COMPRESSION lz4;
+ALTER TABLE container_structures ALTER COLUMN code SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN contentlet_as_json SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area1 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area2 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area3 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area4 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area5 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area6 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area7 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area8 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area9 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area10 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area11 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area12 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area13 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area14 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area15 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area16 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area17 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area18 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area19 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area20 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area21 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area22 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area23 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area24 SET COMPRESSION lz4;
+ALTER TABLE contentlet ALTER COLUMN text_area25 SET COMPRESSION lz4;
+ALTER TABLE dot_containers ALTER COLUMN code SET COMPRESSION lz4;
+ALTER TABLE dot_containers ALTER COLUMN pre_loop SET COMPRESSION lz4;
+ALTER TABLE dot_containers ALTER COLUMN post_loop SET COMPRESSION lz4;
+ALTER TABLE dot_containers ALTER COLUMN lucene_query SET COMPRESSION lz4;
+ALTER TABLE experiment ALTER COLUMN traffic_proportion SET COMPRESSION lz4;
+ALTER TABLE experiment ALTER COLUMN scheduling SET COMPRESSION lz4;
+ALTER TABLE experiment ALTER COLUMN goals SET COMPRESSION lz4;
+ALTER TABLE experiment ALTER COLUMN running_ids SET COMPRESSION lz4;
+ALTER TABLE field ALTER COLUMN field_values SET COMPRESSION lz4;
+ALTER TABLE field_variable ALTER COLUMN variable_value SET COMPRESSION lz4;
+ALTER TABLE job ALTER COLUMN parameters SET COMPRESSION lz4;
+ALTER TABLE job ALTER COLUMN result SET COMPRESSION lz4;
+ALTER TABLE job_history ALTER COLUMN result SET COMPRESSION lz4;
+ALTER TABLE links ALTER COLUMN link_code SET COMPRESSION lz4;
+ALTER TABLE multi_tree ALTER COLUMN style_properties SET COMPRESSION lz4;
+ALTER TABLE notification ALTER COLUMN message SET COMPRESSION lz4;
+ALTER TABLE publishing_end_point ALTER COLUMN auth_key SET COMPRESSION lz4;
+ALTER TABLE publishing_pushed_assets ALTER COLUMN endpoint_ids SET COMPRESSION lz4;
+ALTER TABLE publishing_pushed_assets ALTER COLUMN publisher SET COMPRESSION lz4;
+ALTER TABLE publishing_queue_audit ALTER COLUMN status_pojo SET COMPRESSION lz4;
+ALTER TABLE QRTZ_EXCL_blob_triggers ALTER COLUMN BLOB_DATA SET COMPRESSION lz4;
+ALTER TABLE QRTZ_EXCL_calendars ALTER COLUMN CALENDAR SET COMPRESSION lz4;
+ALTER TABLE QRTZ_EXCL_job_details ALTER COLUMN JOB_DATA SET COMPRESSION lz4;
+ALTER TABLE QRTZ_EXCL_triggers ALTER COLUMN JOB_DATA SET COMPRESSION lz4;
+ALTER TABLE qrtz_blob_triggers ALTER COLUMN BLOB_DATA SET COMPRESSION lz4;
+ALTER TABLE qrtz_calendars ALTER COLUMN CALENDAR SET COMPRESSION lz4;
+ALTER TABLE qrtz_job_details ALTER COLUMN JOB_DATA SET COMPRESSION lz4;
+ALTER TABLE qrtz_triggers ALTER COLUMN JOB_DATA SET COMPRESSION lz4;
+ALTER TABLE storage_data ALTER COLUMN data SET COMPRESSION lz4;
+ALTER TABLE structure ALTER COLUMN metadata SET COMPRESSION lz4;
+ALTER TABLE system_event ALTER COLUMN payload SET COMPRESSION lz4;
+ALTER TABLE template ALTER COLUMN body SET COMPRESSION lz4;
+ALTER TABLE template ALTER COLUMN header SET COMPRESSION lz4;
+ALTER TABLE template ALTER COLUMN footer SET COMPRESSION lz4;
+ALTER TABLE template ALTER COLUMN drawed_body SET COMPRESSION lz4;
+ALTER TABLE template ALTER COLUMN head_code SET COMPRESSION lz4;
+ALTER TABLE unique_fields ALTER COLUMN supporting_values SET COMPRESSION lz4;
+ALTER TABLE user_comments ALTER COLUMN ucomment SET COMPRESSION lz4;
+ALTER TABLE user_preferences ALTER COLUMN pref_value SET COMPRESSION lz4;
+ALTER TABLE web_form ALTER COLUMN custom_fields SET COMPRESSION lz4;
+ALTER TABLE workflow_action ALTER COLUMN condition_to_progress SET COMPRESSION lz4;
+ALTER TABLE workflow_action ALTER COLUMN metadata SET COMPRESSION lz4;
+ALTER TABLE workflow_action_class ALTER COLUMN clazz SET COMPRESSION lz4;
+ALTER TABLE workflow_action_class_pars ALTER COLUMN value SET COMPRESSION lz4;
+ALTER TABLE workflow_comment ALTER COLUMN wf_comment SET COMPRESSION lz4;
+ALTER TABLE workflow_history ALTER COLUMN change_desc SET COMPRESSION lz4;
+ALTER TABLE workflow_scheme ALTER COLUMN description SET COMPRESSION lz4;
+ALTER TABLE workflow_task ALTER COLUMN description SET COMPRESSION lz4;
