Write-Ahead Log (WAL)

QuantumCacheDB ensures data reliability and consistency through a Write-Ahead Log (WAL). The WAL provides a mechanism for durable writes, ensuring that all changes made to the database are written to disk in a sequential manner before they are applied to the database itself. This ensures that the database can recover from crashes or unexpected failures without losing data.

What is a Write-Ahead Log (WAL)?

A Write-Ahead Log (WAL) is a log-based approach to database durability, where every change to the database is first written to a log file before being applied to the database storage. This allows the database to restore to its most recent consistent state in case of a failure by replaying the log entries.

In QuantumCacheDB, the WAL ensures the following:

• Data Durability: Changes to the database are persistent, even if the application crashes.
• Crash Recovery: If an unexpected shutdown occurs, WAL entries can be replayed to restore the database to its latest consistent state.
• Atomicity: Ensures that even if a write operation is interrupted, the database will not be left in an inconsistent state.

How WAL Works in QuantumCacheDB

In QuantumCacheDB, the WAL operates as follows:

1. Log Changes First: Every write operation (insert, update, delete) is first written to a WAL file. The WAL file is stored in a separate location from the main database data files.

2. Apply Changes to the Database: After the write is logged, the changes are then applied to the database. This ensures that the database is always in a consistent state, and no changes are lost.

3. Periodic Checkpoints: Periodically, a checkpoint is created in the database. A checkpoint indicates a point where the database is in a consistent state and can safely be restored from the WAL if needed.

4. Crash Recovery: In case of an unexpected crash, QuantumCacheDB will use the WAL to replay all operations that were logged but not yet applied to the database. This ensures that no data is lost and the database is restored to its most recent consistent state.

Configuring WAL in QuantumCacheDB

By default, QuantumCacheDB uses WAL to ensure data consistency. However, you can configure certain parameters of the WAL to suit your application’s needs.

Enabling and Disabling WAL

The WAL is enabled by default. To configure WAL settings, you can adjust parameters in your database initialization.

import 'package:quantum_cache_db/quantum_cache_db.dart';

void main() async {
  var db = QuantumCacheDB();

  // Configuring WAL settings (optional)
  await db.init(useWAL: true);  // Ensure WAL is enabled

  // You can disable WAL if you do not need it for testing purposes (not recommended in production)
  // await db.init(useWAL: false);
}

WAL File Location

By default, QuantumCacheDB stores the WAL in the same directory as the database file. However, you can specify a custom directory if needed.

await db.init(walDirectory: '/path/to/custom/wal/directory');

WAL Size Limit

To prevent the WAL file from growing indefinitely, you can set a size limit. When the limit is reached, the database will automatically create a new WAL file.

await db.init(walSizeLimit: 100 * 1024 * 1024);  // 100 MB limit

Benefits of WAL in QuantumCacheDB

1. Reliability: WAL ensures that all changes are logged before they are applied, guaranteeing that no data is lost.
2. Performance: WAL can improve write performance, especially for applications with high write throughput, by reducing the need for immediate disk I/O.
3. Recovery: In case of failure, WAL allows for fast recovery without the need to manually restore backups or perform extensive database repairs.
4. Consistency: WAL ensures that the database remains in a consistent state, even in the event of a crash or unexpected shutdown.

Example Usage

Here’s an example of using QuantumCacheDB with WAL enabled. In this example, we will perform a few operations and show how the WAL ensures that changes are written safely to the database.

import 'package:quantum_cache_db/quantum_cache_db.dart';

void main() async {
  var db = QuantumCacheDB();

  // Initialize the database with WAL enabled
  await db.init(useWAL: true);

  // Insert data into the database
  await db.collection('users').doc('user_123').set({
    'name': 'Jane Doe',
    'email': 'jane.doe@example.com',
  });

  // At this point, the write is safely recorded in the WAL
  print('Data written to WAL and database.');
}

If the application crashes before the data is fully committed to the database, the WAL file will allow the database to replay the changes and restore consistency when the application restarts.