Coverage for src/local_deep_research/settings/env_definitions/db_config.py: 100%

1""" 

2Database configuration environment settings. 

3 

4These settings control SQLite and SQLCipher database parameters 

5that must be set before opening the database connection. 

6 

7Each setting has a canonical env var name (auto-generated from the key, 

8e.g. db_config.kdf_iterations -> LDR_DB_CONFIG_KDF_ITERATIONS) and an 

9optional deprecated alias for backward compatibility with older env var 

10names (e.g. LDR_DB_KDF_ITERATIONS). 

11""" 

12 

13from ..env_settings import ( 

14 IntegerSetting, 

15 EnumSetting, 

16) 

17 

18 

19# Database configuration settings 

20DB_CONFIG_SETTINGS = [ 

21 # Performance settings 

22 IntegerSetting( 

23 key="db_config.cache_size_mb", 

24 description="SQLite cache size in MB", 

25 min_value=1, 

26 max_value=10000, 

27 default=64, 

28 deprecated_env_var="LDR_DB_CACHE_SIZE_MB", 

29 ), 

30 EnumSetting( 

31 key="db_config.journal_mode", 

32 description="SQLite journal mode", 

33 allowed_values={ 

34 "DELETE", 

35 "TRUNCATE", 

36 "PERSIST", 

37 "MEMORY", 

38 "WAL", 

39 "OFF", 

40 }, 

41 default="WAL", 

42 case_sensitive=False, 

43 deprecated_env_var="LDR_DB_JOURNAL_MODE", 

44 ), 

45 EnumSetting( 

46 key="db_config.synchronous", 

47 description="SQLite synchronous mode", 

48 allowed_values={"OFF", "NORMAL", "FULL", "EXTRA"}, 

49 default="NORMAL", 

50 case_sensitive=False, 

51 deprecated_env_var="LDR_DB_SYNCHRONOUS", 

52 ), 

53 IntegerSetting( 

54 key="db_config.wal_autocheckpoint", 

55 description="WAL frames threshold for automatic PASSIVE checkpoint at commit. Lower = smaller WAL high-water-mark, faster recovery on open, slightly more frequent fsyncs.", 

56 min_value=10, 

57 max_value=10000, 

58 default=250, 

59 ), 

60 IntegerSetting( 

61 key="db_config.busy_timeout_ms", 

62 description=( 

63 "SQLite busy_timeout in milliseconds -- how long a writer waits " 

64 "for the database lock before giving up with 'database is locked'. " 

65 "Set above the p99 latency of in-flight transactions (the background " 

66 "document scheduler can hold a session across multi-second PDF " 

67 "downloads; 30s gives the rate-limit tracker and other short writers " 

68 "enough headroom to land their commit instead of swallowing the error)." 

69 ), 

70 # Lower bound 100 ms: anything below that is effectively a no-op 

71 # anyway (the holder's transaction has to release the lock in the 

72 # 100 ms window), and tests need to drop it further to keep the 

73 # negative-control timeout test fast. 

74 min_value=100, 

75 max_value=300000, 

76 default=30000, 

77 deprecated_env_var="LDR_DB_BUSY_TIMEOUT_MS", 

78 ), 

79 # Storage settings 

80 IntegerSetting( 

81 key="db_config.page_size", 

82 description="SQLite page size (must be power of 2)", 

83 min_value=512, 

84 max_value=65536, 

85 default=16384, 

86 deprecated_env_var="LDR_DB_PAGE_SIZE", 

87 ), 

88 # Encryption settings 

89 IntegerSetting( 

90 key="db_config.kdf_iterations", 

91 description="Number of KDF iterations for key derivation", 

92 min_value=1000, 

93 max_value=1000000, 

94 default=256000, 

95 deprecated_env_var="LDR_DB_KDF_ITERATIONS", 

96 ), 

97 EnumSetting( 

98 key="db_config.kdf_algorithm", 

99 description="Key derivation function algorithm", 

100 allowed_values={ 

101 "PBKDF2_HMAC_SHA512", 

102 "PBKDF2_HMAC_SHA256", 

103 "PBKDF2_HMAC_SHA1", # DevSkim: ignore DS126858 — backwards compat for existing databases; default is SHA512 

104 }, 

105 default="PBKDF2_HMAC_SHA512", 

106 case_sensitive=False, 

107 deprecated_env_var="LDR_DB_KDF_ALGORITHM", 

108 ), 

109 EnumSetting( 

110 key="db_config.hmac_algorithm", 

111 description="HMAC algorithm for database integrity", 

112 allowed_values={ 

113 "HMAC_SHA512", 

114 "HMAC_SHA256", 

115 "HMAC_SHA1", # DevSkim: ignore DS126858 — backwards compat for existing databases; default is SHA512 

116 }, 

117 default="HMAC_SHA512", 

118 case_sensitive=False, 

119 deprecated_env_var="LDR_DB_HMAC_ALGORITHM", 

120 ), 

121 # Runtime security settings 

122 EnumSetting( 

123 key="db_config.cipher_memory_security", 

124 description="SQLCipher memory security (ON=clear memory after use + mlock, OFF=faster). ON requires IPC_LOCK in Docker.", 

125 allowed_values={"ON", "OFF"}, 

126 default="OFF", 

127 case_sensitive=False, 

128 ), 

129]