perf(wal): add cairo.wal.writer.madvise.mode configuration option (#6841)

jerrinot · web-flow · commit ea4ef52e5b38 · 2026-03-03T13:49:40.000Z
diff --git a/core/src/main/java/io/questdb/PropServerConfiguration.java b/core/src/main/java/io/questdb/PropServerConfiguration.java
@@ -566,6 +566,7 @@ public class PropServerConfiguration implements ServerConfiguration {
     private final int walTxnNotificationQueueCapacity;
     private final long walWriterDataAppendPageSize;
     private final long walWriterEventAppendPageSize;
+    private final int walWriterMadviseMode;
     private final int walWriterPoolMaxSegments;
     private final long workStealTimeoutNanos;
     private final long writerAsyncCommandBusyWaitTimeout;
@@ -1471,6 +1472,7 @@ public PropServerConfiguration(
             this.parallelIndexThreshold = getInt(properties, env, PropertyKey.CAIRO_PARALLEL_INDEX_THRESHOLD, 100000);
             this.readerPoolMaxSegments = getInt(properties, env, PropertyKey.CAIRO_READER_POOL_MAX_SEGMENTS, 10);
             this.poolSegmentSize = getIntSize(properties, env, PropertyKey.DEBUG_CAIRO_POOL_SEGMENT_SIZE, 32);
+            this.walWriterMadviseMode = getWalWriterMadviseMode(properties, env, PropertyKey.CAIRO_WAL_WRITER_MADVISE_MODE);
             this.walWriterPoolMaxSegments = getInt(properties, env, PropertyKey.CAIRO_WAL_WRITER_POOL_MAX_SEGMENTS, 10);
             this.viewWalWriterPoolMaxSegments = getInt(properties, env, PropertyKey.CAIRO_VIEW_WAL_WRITER_POOL_MAX_SEGMENTS, 4);
             this.spinLockTimeout = getMillis(properties, env, PropertyKey.CAIRO_SPIN_LOCK_TIMEOUT, 1_000);
@@ -2255,6 +2257,27 @@ private int getSqlJitMode(Properties properties, @Nullable Map<String, String> e
         return SqlJitMode.JIT_MODE_ENABLED;
     }
 
+    private int getWalWriterMadviseMode(Properties properties, @Nullable Map<String, String> env, ConfigPropertyKey key) throws ServerConfigurationException {
+        final String mode = getString(properties, env, key, "none");
+
+        // must not be null because we provided non-null default value
+        assert mode != null;
+
+        if (Chars.equalsLowerCaseAscii(mode, "none")) {
+            return -1;
+        }
+
+        if (Chars.equalsLowerCaseAscii(mode, "sequential")) {
+            return Files.POSIX_MADV_SEQUENTIAL;
+        }
+
+        if (Chars.equalsLowerCaseAscii(mode, "random")) {
+            return Files.POSIX_MADV_RANDOM;
+        }
+
+        throw ServerConfigurationException.forInvalidKey(key.getPropertyPath(), mode);
+    }
+
     // The enterprise version needs to add tcps and https
     private String initIlpTransport() {
         StringSink sink = Misc.getThreadLocalSink();
@@ -4468,6 +4491,11 @@ public int getWalTxnNotificationQueueCapacity() {
             return walTxnNotificationQueueCapacity;
         }
 
+        @Override
+        public int getWalWriterMadviseMode() {
+            return walWriterMadviseMode;
+        }
+
         @Override
         public int getWalWriterPoolMaxSegments() {
             return walWriterPoolMaxSegments;
diff --git a/core/src/main/java/io/questdb/PropertyKey.java b/core/src/main/java/io/questdb/PropertyKey.java
@@ -529,6 +529,7 @@ public enum PropertyKey implements ConfigPropertyKey {
     CAIRO_WAL_SEGMENT_ROLLOVER_SIZE("cairo.wal.segment.rollover.size"),
     CAIRO_WAL_WRITER_DATA_APPEND_PAGE_SIZE("cairo.wal.writer.data.append.page.size"),
     CAIRO_WAL_WRITER_EVENT_APPEND_PAGE_SIZE("cairo.wal.writer.event.append.page.size"),
+    CAIRO_WAL_WRITER_MADVISE_MODE("cairo.wal.writer.madvise.mode"),
     CAIRO_WAL_SEQUENCER_CHECK_INTERVAL("cairo.wal.sequencer.check.interval"),
     CAIRO_SYSTEM_WAL_WRITER_DATA_APPEND_PAGE_SIZE("cairo.system.wal.writer.data.append.page.size"),
     CAIRO_SYSTEM_WAL_WRITER_EVENT_APPEND_PAGE_SIZE("cairo.system.wal.writer.event.append.page.size"),
diff --git a/core/src/main/java/io/questdb/cairo/CairoConfiguration.java b/core/src/main/java/io/questdb/cairo/CairoConfiguration.java
@@ -776,6 +776,8 @@ default int getWalPurgeWaitBeforeDelete() {
 
     int getWalTxnNotificationQueueCapacity();
 
+    int getWalWriterMadviseMode();
+
     int getWalWriterPoolMaxSegments();
 
     int getWindowColumnPoolCapacity();
diff --git a/core/src/main/java/io/questdb/cairo/CairoConfigurationWrapper.java b/core/src/main/java/io/questdb/cairo/CairoConfigurationWrapper.java
@@ -1356,6 +1356,11 @@ public int getWalTxnNotificationQueueCapacity() {
         return getDelegate().getWalTxnNotificationQueueCapacity();
     }
 
+    @Override
+    public int getWalWriterMadviseMode() {
+        return getDelegate().getWalWriterMadviseMode();
+    }
+
     @Override
     public int getWalWriterPoolMaxSegments() {
         return getDelegate().getWalWriterPoolMaxSegments();
diff --git a/core/src/main/java/io/questdb/cairo/DefaultCairoConfiguration.java b/core/src/main/java/io/questdb/cairo/DefaultCairoConfiguration.java
@@ -1370,6 +1370,11 @@ public int getWalTxnNotificationQueueCapacity() {
         return 4096;
     }
 
+    @Override
+    public int getWalWriterMadviseMode() {
+        return -1;
+    }
+
     @Override
     public int getWalWriterPoolMaxSegments() {
         return 5;
diff --git a/core/src/main/java/io/questdb/cairo/wal/WalWriter.java b/core/src/main/java/io/questdb/cairo/wal/WalWriter.java
@@ -116,6 +116,7 @@ public class WalWriter extends WalWriterBase implements TableWriterAPI {
 
     private final AlterOperation alterOp = new AlterOperation();
     private final ObjList<MemoryMA> columns;
+    private final int columnsMadviseMode;
     private final DdlListener ddlListener;
     private final AtomicIntList initialSymbolCounts;
     private final IntList localSymbolIds;
@@ -174,6 +175,7 @@ public WalWriter(
         super(configuration, tableToken, tableSequencerAPI, walDirectoryPolicy, walLocker);
 
         LOG.info().$("open [table=").$(tableToken).I$();
+        this.columnsMadviseMode = configuration.getWalWriterMadviseMode();
         this.ddlListener = ddlListener;
         this.recentWriteTracker = recentWriteTracker;
         this.telemetryWal = telemetryWal;
@@ -1308,7 +1310,7 @@ private void openColumnFiles(CharSequence columnName, int columnType, int column
                     -1,
                     MemoryTag.MMAP_TABLE_WAL_WRITER,
                     configuration.getWriterFileOpenOpts(),
-                    Files.POSIX_MADV_RANDOM
+                    columnsMadviseMode
             );
 
             final MemoryMA auxMem = getAuxColumn(columnIndex);
@@ -1323,7 +1325,7 @@ private void openColumnFiles(CharSequence columnName, int columnType, int column
                         getDataAppendPageSize(),
                         MemoryTag.MMAP_TABLE_WAL_WRITER,
                         configuration.getWriterFileOpenOpts(),
-                        Files.POSIX_MADV_RANDOM
+                        columnsMadviseMode
                 );
             }
         } finally {
diff --git a/core/src/main/resources/io/questdb/site/conf/server.conf b/core/src/main/resources/io/questdb/site/conf/server.conf
@@ -1066,6 +1066,9 @@ cairo.sql.copy.root=import
 # this page size can be reduced. The optimal value should be established via ingestion benchmark.
 #cairo.wal.writer.event.append.page.size=128k
 
+# madvise mode for WalWriter memory-mapped files. Valid values: none, sequential, random.
+#cairo.wal.writer.madvise.mode=none
+
 # Multiplier to cairo.max.uncommitted.rows to calculate the limit of rows that can kept invisible when writing
 # to WAL table under heavy load, when multiple transactions are to be applied.
 # It is used to reduce the number Out Of Order commits when Out Of Order commits are unavoidable by squashing multiple commits together.
diff --git a/core/src/test/java/io/questdb/test/PropServerConfigurationTest.java b/core/src/test/java/io/questdb/test/PropServerConfigurationTest.java
@@ -500,6 +500,7 @@ public void testAllDefaults() throws Exception {
         Assert.assertEquals(1048576, configuration.getCairoConfiguration().getWalDataAppendPageSize());
         Assert.assertEquals(262144, configuration.getCairoConfiguration().getSystemWalDataAppendPageSize());
         Assert.assertTrue(configuration.getCairoConfiguration().isTableTypeConversionEnabled());
+        Assert.assertEquals(-1, configuration.getCairoConfiguration().getWalWriterMadviseMode());
         Assert.assertEquals(10, configuration.getCairoConfiguration().getWalWriterPoolMaxSegments());
         Assert.assertTrue(configuration.getCairoConfiguration().isWalApplyParallelSqlEnabled());
 
@@ -2098,6 +2099,7 @@ private void testSetAllFromFile(CairoConfiguration configuration) {
         Assert.assertFalse(configuration.isWalApplyEnabled());
         Assert.assertEquals(23, configuration.getWalApplyLookAheadTransactionCount());
         Assert.assertFalse(configuration.isTableTypeConversionEnabled());
+        Assert.assertEquals(Files.POSIX_MADV_RANDOM, configuration.getWalWriterMadviseMode());
         Assert.assertEquals(100, configuration.getWalWriterPoolMaxSegments());
         Assert.assertEquals(50, configuration.getViewWalWriterPoolMaxSegments());
         Assert.assertEquals(120, configuration.getO3LagCalculationWindowsSize());
diff --git a/core/src/test/java/io/questdb/test/ServerMainTest.java b/core/src/test/java/io/questdb/test/ServerMainTest.java
@@ -723,6 +723,7 @@ public void testShowParameters() throws Exception {
                                     "cairo.view.wal.writer.pool.max.segments\tQDB_CAIRO_VIEW_WAL_WRITER_POOL_MAX_SEGMENTS\t4\tdefault\tfalse\tfalse\n" +
                                     "cairo.wal.sequencer.check.interval\tQDB_CAIRO_WAL_SEQUENCER_CHECK_INTERVAL\t10000\tdefault\tfalse\tfalse\n" +
                                     "cairo.wal.writer.event.append.page.size\tQDB_CAIRO_WAL_WRITER_EVENT_APPEND_PAGE_SIZE\t131072\tdefault\tfalse\tfalse\n" +
+                                    "cairo.wal.writer.madvise.mode\tQDB_CAIRO_WAL_WRITER_MADVISE_MODE\tnone\tdefault\tfalse\tfalse\n" +
                                     "cairo.work.steal.timeout.nanos\tQDB_CAIRO_WORK_STEAL_TIMEOUT_NANOS\t10000\tdefault\tfalse\tfalse\n" +
                                     "cairo.writer.alter.busy.wait.timeout\tQDB_CAIRO_WRITER_ALTER_BUSY_WAIT_TIMEOUT\t500\tdefault\tfalse\tfalse\n" +
                                     "cairo.writer.alter.max.wait.timeout\tQDB_CAIRO_WRITER_ALTER_MAX_WAIT_TIMEOUT\t30000\tdefault\tfalse\tfalse\n" +
diff --git a/core/src/test/resources/server.conf b/core/src/test/resources/server.conf
@@ -340,6 +340,7 @@ cairo.wal.enabled.default=true
 cairo.wal.purge.interval=333
 cairo.wal.segment.rollover.row.count=100
 cairo.wal.writer.data.append.page.size=256k
+cairo.wal.writer.madvise.mode=random
 cairo.system.wal.writer.data.append.page.size=512k
 cairo.wal.apply.parallel.sql.enabled=false
 
diff --git a/pkg/ami/marketplace/assets/server.conf b/pkg/ami/marketplace/assets/server.conf
@@ -843,6 +843,9 @@ pg.user=admin
 # mmap sliding page size that WalWriter uses to append data for each column
 #cairo.wal.writer.data.append.page.size=1M
 
+# madvise mode for WalWriter memory-mapped files. Valid values: none, sequential, random.
+#cairo.wal.writer.madvise.mode=none
+
 # Multiplier to cairo.max.uncommitted.rows to calculate the limit of rows that can kept invisible when writing
 # to WAL table under heavy load, when multiple transactions are to be applied.
 # It is used to reduce the number Out Of Order commits when Out Of Order commits are unavoidable by squashing multiple commits together.
