configurable DB seed for consistency

sarthakaggarwal97 · sarthakaggarwal97 · commit 491c7bd85217 · 2025-09-24T13:57:03.000-07:00
Signed-off-by: Sarthak Aggarwal &lt;sarthagg@amazon.com&gt;
diff --git a/src/config.c b/src/config.c
@@ -3177,6 +3177,19 @@ static int applyClientMaxMemoryUsage(const char **err) {
     return 1;
 }
 
+#define DB_HASH_SEED_MAX_LEN 256
+static int isValidDbHashSeed(char *val, const char **err) {
+    if (val[0] == '\0') {
+        *err = "db-hash-seed can't be empty";
+        return 0;
+    }
+    if (strlen(val) > DB_HASH_SEED_MAX_LEN) {
+        *err = "db-hash-seed must be less than or equal to " STRINGIFY(DB_HASH_SEED_MAX_LEN) " characters";
+        return 0;
+    }
+    return 1;
+}
+
 standardConfig static_configs[] = {
     /* Bool configs */
     createBoolConfig("rdbchecksum", NULL, IMMUTABLE_CONFIG, server.rdb_checksum, 1, NULL, NULL),
@@ -3254,6 +3267,7 @@ standardConfig static_configs[] = {
     createStringConfig("bgsave-cpulist", "bgsave_cpulist", IMMUTABLE_CONFIG, EMPTY_STRING_IS_NULL, server.bgsave_cpulist, NULL, NULL, NULL),
     createStringConfig("ignore-warnings", NULL, MODIFIABLE_CONFIG, ALLOW_EMPTY_STRING, server.ignore_warnings, "", NULL, NULL),
     createStringConfig("proc-title-template", NULL, MODIFIABLE_CONFIG, ALLOW_EMPTY_STRING, server.proc_title_template, CONFIG_DEFAULT_PROC_TITLE_TEMPLATE, isValidProcTitleTemplate, updateProcTitleTemplate),
+    createStringConfig("db-hash-seed", NULL, IMMUTABLE_CONFIG, EMPTY_STRING_IS_NULL, server.db_hash_seed, NULL, isValidDbHashSeed, NULL),
     createStringConfig("bind-source-addr", NULL, MODIFIABLE_CONFIG, EMPTY_STRING_IS_NULL, server.bind_source_addr, NULL, NULL, NULL),
     createStringConfig("logfile", NULL, IMMUTABLE_CONFIG, ALLOW_EMPTY_STRING, server.logfile, "", NULL, NULL),
 #ifdef LOG_REQ_RES
diff --git a/src/hashtable.c b/src/hashtable.c
@@ -72,6 +72,7 @@ uint64_t siphash_nocase(const uint8_t *in, const size_t inlen, const uint8_t *k)
 /* --- Global variables --- */
 
 static uint8_t hash_function_seed[16];
+static uint8_t db_hash_function_seed[16];
 static hashtableResizePolicy resize_policy = HASHTABLE_RESIZE_ALLOW;
 
 /* --- Fill factor --- */
@@ -112,6 +113,14 @@ uint64_t hashtableGenCaseHashFunction(const char *buf, size_t len) {
     return siphash_nocase((const uint8_t *)buf, len, hash_function_seed);
 }
 
+void dbHashtableSetHashFunctionSeed(uint8_t *seed) {
+    memcpy(db_hash_function_seed, seed, sizeof(db_hash_function_seed));
+}
+
+uint64_t dbHashtableGenHashFunction(const void *key, size_t len) {
+    return siphash(key, len, db_hash_function_seed);
+}
+
 /* --- Global resize policy API --- */
 
 /* The global resize policy is one of
diff --git a/src/hashtable.h b/src/hashtable.h
@@ -110,6 +110,8 @@ void hashtableSetHashFunctionSeed(const uint8_t *seed);
 uint8_t *hashtableGetHashFunctionSeed(void);
 uint64_t hashtableGenHashFunction(const char *buf, size_t len);
 uint64_t hashtableGenCaseHashFunction(const char *buf, size_t len);
+void dbHashtableSetHashFunctionSeed(uint8_t *seed);
+uint64_t dbHashtableGenHashFunction(const void *key, size_t len);
 
 /* Global resize policy */
 void hashtableSetResizePolicy(hashtableResizePolicy policy);
diff --git a/src/server.c b/src/server.c
@@ -573,7 +573,7 @@ hashtableType zsetHashtableType = {
 };
 
 uint64_t hashtableSdsHash(const void *key) {
-    return hashtableGenHashFunction((const char *)key, sdslen((char *)key));
+    return dbHashtableGenHashFunction((const char *)key, sdslen((char *)key));
 }
 
 const void *hashtableObjectGetKey(const void *entry) {
@@ -7136,6 +7136,10 @@ __attribute__((weak)) int main(int argc, char **argv) {
     getRandomBytes(hashseed, sizeof(hashseed));
     dictSetHashFunctionSeed(hashseed);
     hashtableSetHashFunctionSeed(hashseed);
+    if (server.db_hash_seed != NULL) {
+        getHashSeedFromValue(hashseed, sizeof(hashseed), server.db_hash_seed);
+    }
+    dbHashtableSetHashFunctionSeed(hashseed);
 
     char *exec_name = strrchr(argv[0], '/');
     if (exec_name == NULL) exec_name = argv[0];
diff --git a/src/server.h b/src/server.h
@@ -2213,6 +2213,7 @@ struct valkeyServer {
                                                             * dropping packets of a specific type */
     unsigned long cluster_blacklist_ttl;                   /* Duration in seconds that a node is denied re-entry into
                                                             * the cluster after it is forgotten with CLUSTER FORGET. */
+    char *db_hash_seed;                                    /* Configurable DB hash seed */
     int cluster_slot_stats_enabled;                        /* Cluster slot usage statistics tracking enabled. */
     mstime_t cluster_mf_timeout;                           /* Milliseconds to do a manual failover. */
     unsigned long cluster_slot_migration_log_max_len;      /* Maximum count of migrations to display in the
diff --git a/src/unit/test_files.h b/src/unit/test_files.h
@@ -202,6 +202,7 @@ int test_ld2string(int argc, char **argv, int flags);
 int test_fixedpoint_d2string(int argc, char **argv, int flags);
 int test_version2num(int argc, char **argv, int flags);
 int test_reclaimFilePageCache(int argc, char **argv, int flags);
+int test_getHashSeedFromValue(int argc, char **argv, int flags);
 int test_writePointerWithPadding(int argc, char **argv, int flags);
 int test_valkey_strtod(int argc, char **argv, int flags);
 int test_vector(int argc, char **argv, int flags);
@@ -272,7 +273,7 @@ unitTest __test_rax_c[] = {{"test_raxRandomWalk", test_raxRandomWalk}, {"test_ra
 unitTest __test_sds_c[] = {{"test_sds", test_sds}, {"test_typesAndAllocSize", test_typesAndAllocSize}, {"test_sdsHeaderSizes", test_sdsHeaderSizes}, {"test_sdssplitargs", test_sdssplitargs}, {NULL, NULL}};
 unitTest __test_sha1_c[] = {{"test_sha1", test_sha1}, {NULL, NULL}};
 unitTest __test_sha256_c[] = {{"test_sha256_abc", test_sha256_abc}, {"test_sha256_large", test_sha256_large}, {"test_sha256_million_a", test_sha256_million_a}, {NULL, NULL}};
-unitTest __test_util_c[] = {{"test_string2ll", test_string2ll}, {"test_string2l", test_string2l}, {"test_ll2string", test_ll2string}, {"test_ld2string", test_ld2string}, {"test_fixedpoint_d2string", test_fixedpoint_d2string}, {"test_version2num", test_version2num}, {"test_reclaimFilePageCache", test_reclaimFilePageCache}, {"test_writePointerWithPadding", test_writePointerWithPadding}, {NULL, NULL}};
+unitTest __test_util_c[] = {{"test_string2ll", test_string2ll}, {"test_string2l", test_string2l}, {"test_ll2string", test_ll2string}, {"test_ld2string", test_ld2string}, {"test_fixedpoint_d2string", test_fixedpoint_d2string}, {"test_version2num", test_version2num}, {"test_reclaimFilePageCache", test_reclaimFilePageCache}, {"test_getHashSeedFromValue", test_getHashSeedFromValue}, {"test_writePointerWithPadding", test_writePointerWithPadding}, {NULL, NULL}};
 unitTest __test_valkey_strtod_c[] = {{"test_valkey_strtod", test_valkey_strtod}, {NULL, NULL}};
 unitTest __test_vector_c[] = {{"test_vector", test_vector}, {NULL, NULL}};
 unitTest __test_vset_c[] = {{"test_vset_add_and_iterate", test_vset_add_and_iterate}, {"test_vset_large_batch_same_expiry", test_vset_large_batch_same_expiry}, {"test_vset_large_batch_update_entry_same_expiry", test_vset_large_batch_update_entry_same_expiry}, {"test_vset_large_batch_update_entry_multiple_expiries", test_vset_large_batch_update_entry_multiple_expiries}, {"test_vset_iterate_multiple_expiries", test_vset_iterate_multiple_expiries}, {"test_vset_add_and_remove_all", test_vset_add_and_remove_all}, {"test_vset_remove_expire_shrink", test_vset_remove_expire_shrink}, {"test_vset_defrag", test_vset_defrag}, {"test_vset_fuzzer", test_vset_fuzzer}, {NULL, NULL}};
diff --git a/src/unit/test_util.c b/src/unit/test_util.c
@@ -331,6 +331,32 @@ int test_reclaimFilePageCache(int argc, char **argv, int flags) {
     return 0;
 }
 
+int test_getHashSeedFromValue(int argc, char **argv, int flags) {
+    UNUSED(argc);
+    UNUSED(argv);
+    UNUSED(flags);
+
+    unsigned char seed[4];
+    getHashSeedFromValue(seed, sizeof(seed), "abcdefgh");
+    TEST_ASSERT(seed[0] == ('a' ^ 'e'));
+    TEST_ASSERT(seed[1] == ('b' ^ 'f'));
+    TEST_ASSERT(seed[2] == ('c' ^ 'g'));
+    TEST_ASSERT(seed[3] == ('d' ^ 'h'));
+
+    unsigned char seed2[8];
+    unsigned char expected2[8] = {'a', 'b', 'c', 'a', 'b', 'c', 'a', 'b'};
+    getHashSeedFromValue(seed2, sizeof(seed2), "abc");
+    TEST_ASSERT(memcmp(seed2, expected2, sizeof(seed2)) == 0);
+
+    unsigned char seed3[4];
+    getHashSeedFromValue(seed3, sizeof(seed3), "");
+    for (size_t i = 0; i < sizeof(seed3); i++) {
+        TEST_ASSERT(seed3[i] == 0);
+    }
+
+    return 0;
+}
+
 int test_writePointerWithPadding(int argc, char **argv, int flags) {
     UNUSED(argc);
     UNUSED(argv);
diff --git a/src/util.c b/src/util.c
@@ -1037,6 +1037,16 @@ int ld2string(char *buf, size_t len, long double value, ld2string_mode mode) {
     return 0;
 }
 
+void getHashSeedFromValue(unsigned char *seed_array, size_t len, const char *value) {
+    size_t input_len = strlen(value);
+    memset(seed_array, 0, len);
+    if (input_len == 0) return;
+    size_t max_len = len > input_len ? len : input_len;
+    for (size_t i = 0; i < max_len; i++) {
+        seed_array[i % len] = value[i % input_len] ^ seed_array[i % len];
+    }
+}
+
 /* Parses a version string on the form "major.minor.patch" and returns an
  * integer on the form 0xMMmmpp. Returns -1 on parse error. */
 int version2num(const char *version) {
diff --git a/src/util.h b/src/util.h
@@ -91,6 +91,7 @@ int trimDoubleString(char *buf, size_t len);
 int d2string(char *buf, size_t len, double value);
 int fixedpoint_d2string(char *dst, size_t dstlen, double dvalue, int fractional_digits);
 int ld2string(char *buf, size_t len, long double value, ld2string_mode mode);
+void getHashSeedFromValue(unsigned char *seed_array, size_t len, const char *value);
 int double2ll(double d, long long *out);
 int version2num(const char *version);
 int yesnotoi(char *s);
diff --git a/tests/integration/scan-consistency-on-failover.tcl b/tests/integration/scan-consistency-on-failover.tcl
@@ -0,0 +1,69 @@
+start_server {tags {"scan-consistency-on-failover external:skip"}} {
+    proc full_scan_keys {c prefix} {
+        set cur 0
+        set out {}
+        while {1} {
+            # count 1 to make the ordering fully observable
+            set res [$c scan $cur count 1]
+            set cur  [lindex $res 0]
+            set keys [lindex $res 1]
+            foreach k $keys {
+                if {[string match "${prefix}*" $k]} {
+                    lappend out $k
+                }
+            }
+            if {$cur eq "0"} break
+        }
+        return $out
+    }
+
+    set fixed_seed "00112233445566778899aabbccddeeff"
+    set shared_overrides [list appendonly no save "" db-hash-seed $fixed_seed]
+
+    start_server [list overrides $shared_overrides] {
+        set primary_host [srv 0 host]
+        set primary_port [srv 0 port]
+
+        start_server [list overrides $shared_overrides] {
+            set replica_host [srv 0 host]
+            set replica_port [srv 0 port]
+
+            set primary [srv -1 client]
+            set replica [srv 0 client]
+
+            $primary flushall
+            $replica replicaof $primary_host $primary_port
+            wait_for_sync $replica
+
+            set n 100
+            for {set i 0} {$i < $n} {incr i} {
+                $primary set "k:$i" x
+            }
+
+            wait_for_condition 200 50 {
+                [$replica dbsize] == [$primary dbsize]
+            } else {
+                fail "replica did not catch up dbsize (primary=[$primary dbsize], replica=[$replica dbsize])"
+            }
+
+            wait_for_condition 200 50 {
+                ![string match {Hash table 1 stats*} [$primary debug htstats 9]] &&
+                ![string match {Hash table 1 stats*} [$replica debug htstats 9]]
+            } else {
+                fail "hash tables still rehashing on primary/replica"
+            }
+
+            set pseed [$primary config get db-hash-seed]
+            set rseed [$replica config get db-hash-seed]
+            assert_equal $pseed $rseed
+
+            set pkeys [full_scan_keys $primary "k:"]
+            set rkeys [full_scan_keys $replica "k:"]
+
+            assert_equal [$primary dbsize] [llength $pkeys]
+            assert_equal [$replica  dbsize] [llength $rkeys]
+            assert_equal [llength $pkeys] [llength $rkeys]
+            assert_equal $pkeys $rkeys
+        }
+    }
+}
diff --git a/tests/unit/introspection.tcl b/tests/unit/introspection.tcl
@@ -1190,6 +1190,7 @@ start_server {tags {"introspection"}} {
             disable-thp
             aclfile
             unixsocket
+            db-hash-seed
             pidfile
             syslog-ident
             appendfilename
@@ -1884,3 +1885,11 @@ test {CONFIG REWRITE handles alias config properly} {
         assert_equal [r config get hash-max-listpack-entries] {hash-max-listpack-entries 100}
     }
 } {} {external:skip}
+
+test {CONFIG db-hash-seed is immutable and settable at startup} {
+    start_server {tags {"introspection"} overrides {db-hash-seed myseed}} {
+        assert_error "ERR CONFIG SET failed (possibly related to argument 'db-hash-seed') - can't set immutable config*" {
+            r config set db-hash-seed newseed
+        }
+    }
+} {} {external:skip}
diff --git a/valkey.conf b/valkey.conf
@@ -2633,3 +2633,10 @@ jemalloc-bg-thread yes
 # the empty string.
 #
 # availability-zone "zone-name"
+
+# Use a fixed hash seed for key dictionaries instead of a random one.
+# Setting this option makes commands like SCAN return keys in a consistent
+# order across restarts and failovers. The seed can be any string up to 256 characters.
+# The value is immutable and must be provided only at server startup.
+#
+# db-hash-seed example-seed-value
