1 /*- 2 * See the file LICENSE for redistribution information. 3 * 4 * Copyright (c) 2009, 2013 Oracle and/or its affiliates. All rights reserved. 5 * 6 */ 7 using System; 8 using System.Collections.Generic; 9 using System.Text; 10 11 namespace BerkeleyDB { 12 /// <summary> 13 /// A class representing configuration parameters for <see cref="Database"/> 14 /// </summary> 15 public class DatabaseConfig { 16 /// <summary> 17 /// The Berkeley DB environment within which to create a database. If 18 /// null, the database will be created stand-alone; that is, it is not 19 /// part of any Berkeley DB environment. 20 /// </summary> 21 /// <remarks> 22 /// The database access methods automatically make calls to the other 23 /// subsystems in Berkeley DB, based on the enclosing environment. For 24 /// example, if the environment has been configured to use locking, the 25 /// access methods will automatically acquire the correct locks when 26 /// reading and writing pages of the database. 27 /// </remarks> 28 public DatabaseEnvironment Env; 29 30 /// <summary> 31 /// The cache priority for pages referenced by the database. 32 /// </summary> 33 /// <remarks> 34 /// The priority of a page biases the replacement algorithm to be more 35 /// or less likely to discard a page when space is needed in the buffer 36 /// pool. The bias is temporary, and pages will eventually be discarded 37 /// if they are not referenced again. This priority is only advisory, 38 /// and does not guarantee pages will be treated in a specific way. 39 /// </remarks> 40 public CachePriority Priority; 41 42 /// <summary> 43 /// The size of the shared memory buffer pool -- that is, the cache. 44 /// </summary> 45 /// <remarks> 46 /// <para> 47 /// The cache should be the size of the normal working data set of the 48 /// application, with some small amount of additional memory for unusual 49 /// situations. (Note: the working set is not the same as the number of 50 /// pages accessed simultaneously, and is usually much larger.) 51 /// </para> 52 /// <para> 53 /// The default cache size is 256KB, and may not be specified as less 54 /// than 20KB. Any cache size less than 500MB is automatically increased 55 /// by 25% to account for buffer pool overhead; cache sizes larger than 56 /// 500MB are used as specified. The maximum size of a single cache is 57 /// 4GB on 32-bit systems and 10TB on 64-bit systems. (All sizes are in 58 /// powers-of-two, that is, 256KB is 2^18 not 256,000.) For information 59 /// on tuning the Berkeley DB cache size, see Selecting a cache size in 60 /// the Programmer's Reference Guide. 61 /// </para> 62 /// </remarks> 63 public CacheInfo CacheSize; 64 65 /// <summary> 66 /// The byte order for integers in the stored database metadata. The 67 /// host byte order of the machine where the Berkeley DB library was 68 /// compiled is the default value. 69 /// </summary> 70 /// <remarks> 71 /// <para> 72 /// The access methods provide no guarantees about the byte ordering of 73 /// the application data stored in the database, and applications are 74 /// responsible for maintaining any necessary ordering. 75 /// </para> 76 /// <para> 77 /// If creating additional databases in a single physical file, this 78 /// parameter will be ignored and the byte order of the existing 79 /// databases will be used. 80 /// </para> 81 /// </remarks> 82 public ByteOrder ByteOrder = ByteOrder.MACHINE; 83 84 internal bool pagesizeIsSet; 85 private uint pgsz; 86 /// <summary> 87 /// The size of the pages used to hold items in the database, in bytes. 88 /// </summary> 89 /// <remarks> 90 /// <para> 91 /// The minimum page size is 512 bytes, the maximum page size is 64K 92 /// bytes, and the page size must be a power-of-two. If the page size is 93 /// not explicitly set, one is selected based on the underlying 94 /// filesystem I/O block size. The automatically selected size has a 95 /// lower limit of 512 bytes and an upper limit of 16K bytes. 96 /// </para> 97 /// <para> 98 /// For information on tuning the Berkeley DB page size, see Selecting a 99 /// page size in the Programmer's Reference Guide. 100 /// </para> 101 /// <para> 102 /// If creating additional databases in a single physical file, this 103 /// parameter will be ignored and the page size of the existing 104 /// databases will be used. 105 /// </para> 106 /// </remarks> 107 public uint PageSize { 108 get { return pgsz; } 109 set { 110 pagesizeIsSet = true; 111 pgsz = value; 112 } 113 } 114 115 internal bool encryptionIsSet; 116 private String encryptPwd; 117 private bool doEncrypt; 118 private EncryptionAlgorithm encryptAlg; 119 /// <summary> 120 /// Set the password and algorithm used by the Berkeley DB library to 121 /// perform encryption and decryption. 122 /// </summary> 123 /// <param name="password"> 124 /// The password used to perform encryption and decryption. 125 /// </param> 126 /// <param name="alg"> 127 /// The algorithm used to perform encryption and decryption. 128 /// </param> SetEncryption(String password, EncryptionAlgorithm alg)129 public void SetEncryption(String password, EncryptionAlgorithm alg) { 130 doEncrypt = true; 131 encryptionIsSet = true; 132 encryptPwd = password; 133 encryptAlg = alg; 134 } 135 /// <summary> 136 /// The password used to perform encryption and decryption. 137 /// </summary> 138 public string EncryptionPassword { get { return encryptPwd; } } 139 /// <summary> 140 /// The algorithm used to perform encryption and decryption. 141 /// </summary> 142 public EncryptionAlgorithm EncryptAlgorithm { 143 get { return encryptAlg; } 144 } 145 /// <summary> 146 /// Encrypt the database using the cryptographic password specified by 147 /// <see cref="DatabaseConfig.SetEncryption">DatabaseConfig.SetEncryption</see> or 148 /// <see cref="DatabaseEnvironmentConfig.SetEncryption">DatabaseEnvironmentConfig.SetEncryption</see>. 149 /// </summary> 150 /// <remarks> 151 /// <para> 152 /// If the database already exists, the value of Encrypted must be the 153 /// same as the existing database or an error will be returned. 154 /// </para> 155 /// <para> 156 /// Encrypted databases are not portable between machines of different 157 /// byte orders, that is, encrypted databases created on big-endian 158 /// machines cannot be read on little-endian machines, and vice versa. 159 /// </para> 160 /// </remarks> 161 public bool Encrypted { 162 get { return doEncrypt; } 163 set { doEncrypt = value; } 164 } 165 166 /// <summary> 167 /// The prefix string that appears before error messages issued by 168 /// Berkeley DB. 169 /// </summary> 170 public String ErrorPrefix; 171 /// <summary> 172 /// The mechanism for reporting error messages to the application. 173 /// </summary> 174 /// <remarks> 175 /// <para> 176 /// In some cases, when an error occurs, Berkeley DB will call 177 /// ErrorFeedback with additional error information. It is up to the 178 /// delegate function to display the error message in an appropriate 179 /// manner. 180 /// </para> 181 /// <para> 182 /// This error-logging enhancement does not slow performance or 183 /// significantly increase application size, and may be run during 184 /// normal operation as well as during application debugging. 185 /// </para> 186 /// <para> 187 /// For databases opened inside of Berkeley DB environments, setting 188 /// ErrorFeedback affects the entire environment and is equivalent to 189 /// setting <see cref="DatabaseEnvironment.ErrorFeedback"/>. 190 /// </para> 191 /// </remarks> 192 public ErrorFeedbackDelegate ErrorFeedback; 193 194 /// <summary> 195 /// 196 /// </summary> 197 public DatabaseFeedbackDelegate Feedback; 198 199 /// <summary> 200 /// If true, do checksum verification of pages read into the cache from 201 /// the backing filestore. 202 /// </summary> 203 /// <remarks> 204 /// <para> 205 /// Berkeley DB uses the SHA1 Secure Hash Algorithm if encryption is 206 /// configured and a general hash algorithm if it is not. 207 /// </para> 208 /// <para> 209 /// If the database already exists, this setting will be ignored. 210 /// </para> 211 /// </remarks> 212 public bool DoChecksum; 213 214 /// <summary> 215 /// If true, Berkeley DB will not write log records for this database. 216 /// </summary> 217 /// <remarks> 218 /// If Berkeley DB does not write log records, updates of this database 219 /// will exhibit the ACI (atomicity, consistency, and isolation) 220 /// properties, but not D (durability); that is, database integrity will 221 /// be maintained, but if the application or system fails, integrity 222 /// will not persist. The database file must be verified and/or restored 223 /// from backup after a failure. In order to ensure integrity after 224 /// application shut down, the database must be synced when closed, or 225 /// all database changes must be flushed from the database environment 226 /// cache using either 227 /// <see cref="DatabaseEnvironment.Checkpoint"/> or 228 /// <see cref="DatabaseEnvironment.SyncMemPool"/>. All database objects 229 /// for a single physical file must set NonDurableTxns, including 230 /// database objects for different databases in a physical file. 231 /// </remarks> 232 public bool NonDurableTxns; 233 234 /// <summary> 235 /// Configuration of <see cref="BaseDatabase"/> handle to obtain a write 236 /// lock on the entire database. 237 /// </summary> 238 /// <remarks> 239 /// <para> 240 /// If true, configure the <see cref="BaseDatabase"/> handle to obtain a 241 /// write lock on the entire database. When the database is opened it 242 /// will immediately throw <see cref="LockNotGrantedException"/> if it 243 /// cannot obtain the exclusive lock immediately. If False, configure 244 /// the <see cref="BaseDatabase"/> handle to obtain a write lock on the 245 /// entire database. When the database is opened, it will block until it 246 /// can obtain the exclusive lock. If null, do not configure the 247 /// <see cref="BaseDatabase"/> handle to obtain a write lock on the 248 /// entire database. 249 /// </para> 250 /// </remarks> 251 public bool? NoWaitDbExclusiveLock; 252 253 internal uint flags { 254 get { 255 uint ret = 0; 256 ret |= DoChecksum ? Internal.DbConstants.DB_CHKSUM : 0; 257 ret |= Encrypted ? Internal.DbConstants.DB_ENCRYPT : 0; 258 ret |= NonDurableTxns ? Internal.DbConstants.DB_TXN_NOT_DURABLE : 0; 259 return ret; 260 } 261 } 262 263 /// <summary> 264 /// Enclose the open call within a transaction. If the call succeeds, 265 /// the open operation will be recoverable and all subsequent database 266 /// modification operations based on this handle will be transactionally 267 /// protected. If the call fails, no database will have been created. 268 /// </summary> 269 public bool AutoCommit; 270 /// <summary> 271 /// Cause the database object to be free-threaded; that is, concurrently 272 /// usable by multiple threads in the address space. 273 /// </summary> 274 public bool FreeThreaded; 275 /// <summary> 276 /// Do not map this database into process memory. 277 /// </summary> 278 public bool NoMMap; 279 /// <summary> 280 /// Open the database for reading only. Any attempt to modify items in 281 /// the database will fail, regardless of the actual permissions of any 282 /// underlying files. 283 /// </summary> 284 public bool ReadOnly; 285 /// <summary> 286 /// Support transactional read operations with degree 1 isolation. 287 /// </summary> 288 /// <remarks> 289 /// Read operations on the database may request the return of modified 290 /// but not yet committed data. This flag must be specified on all 291 /// database objects used to perform dirty reads or database updates, 292 /// otherwise requests for dirty reads may not be honored and the read 293 /// may block. 294 /// </remarks> 295 public bool ReadUncommitted; 296 /// <summary> 297 /// Physically truncate the underlying file, discarding all previous databases it might have held. 298 /// </summary> 299 /// <remarks> 300 /// <para> 301 /// Underlying filesystem primitives are used to implement this flag. 302 /// For this reason, it is applicable only to the file and cannot be 303 /// used to discard databases within a file. 304 /// </para> 305 /// <para> 306 /// This setting cannot be lock or transaction-protected, and it is an 307 /// error to specify it in a locking or transaction-protected 308 /// environment. 309 /// </para> 310 /// </remarks> 311 public bool Truncate; 312 /// <summary> 313 /// Open the database with support for multiversion concurrency control. 314 /// </summary> 315 /// <remarks> 316 /// This will cause updates to the database to follow a copy-on-write 317 /// protocol, which is required to support snapshot isolation. This 318 /// settting requires that the database be transactionally protected 319 /// during its open and is not supported by the queue format. 320 /// </remarks> 321 public bool UseMVCC; 322 internal uint openFlags { 323 get { 324 uint ret = 0; 325 ret |= AutoCommit ? Internal.DbConstants.DB_AUTO_COMMIT : 0; 326 ret |= FreeThreaded ? Internal.DbConstants.DB_THREAD : 0; 327 ret |= NoMMap ? Internal.DbConstants.DB_NOMMAP : 0; 328 ret |= ReadOnly ? Internal.DbConstants.DB_RDONLY : 0; 329 ret |= ReadUncommitted ? Internal.DbConstants.DB_READ_UNCOMMITTED : 0; 330 ret |= Truncate ? Internal.DbConstants.DB_TRUNCATE : 0; 331 ret |= UseMVCC ? Internal.DbConstants.DB_MULTIVERSION : 0; 332 return ret; 333 } 334 } 335 336 /// <summary> 337 /// Instantiate a new DatabaseConfig object 338 /// </summary> DatabaseConfig()339 public DatabaseConfig() { 340 Env = null; 341 Priority = CachePriority.DEFAULT; 342 pagesizeIsSet = false; 343 encryptionIsSet = false; 344 ErrorPrefix = null; 345 Feedback = null; 346 DoChecksum = false; 347 NonDurableTxns = false; 348 NoWaitDbExclusiveLock = null; 349 AutoCommit = false; 350 FreeThreaded = false; 351 NoMMap = false; 352 ReadOnly = false; 353 ReadUncommitted = false; 354 Truncate = false; 355 UseMVCC = false; 356 } 357 } 358 } 359