Skip to content

05 PLAN

Brian Lehnen edited this page Apr 8, 2026 · 1 revision

phase: 03-transports plan: "5" wave: 2 dependencies: ["1"] must_haves:

  • SQLiteTransport.md consumer code uses ILogger pattern
  • SQLiteTransport.md links to ConsumerMethod (not ConsumerLinq)
  • SQLiteTransport.md includes one-liner link to MessageHistory
  • SQLiteTransport.md links to samples repo
  • SQLiteOptions.md documents ALL properties from SqLiteMessageQueueTransportOptions including EnableWalMode
  • SQLiteOptions.md notes that EnableHoldTransactionUntilMessageCommitted is permanently disabled
  • SQLiteQueueCreationOptions.md documents EnableHistory, EnableHoldTransactionUntilMessageCommitted, and EnableRoute
  • SQLiteInMemoryDB.md clarifies Version=3 meaning files_touched:
  • SQLiteTransport.md
  • SQLiteOptions.md
  • SQLiteQueueCreationOptions.md
  • SQLiteInMemoryDB.md tdd: false

Plan 5 -- SQLite Transport Family

Wave 2 -- Transport pages. Depends on Plan 1 (Transports overview). Can run in parallel with Plans 2-4, 6-7.


Task 1: Update SQLiteTransport.md with features and cross-references

Update `SQLiteTransport.md` with these changes:
  1. Consumer HandleMessages method (lines 70-73): The current code already uses notifications.Log.LogDebug(...) which is the correct MEL ILogger pattern. Verify this is retained.

  2. Feature list (lines 3-9): Add missing features. Current list says "Status based queues or a FIFO Queue with no rollback" but is missing Routing and History. Update to:

    • Delayed messages
    • Message expiration
    • Message priority
    • Routing
    • History tracking
    • User-defined metadata columns
    • Status-based or FIFO processing
    • WAL mode for improved concurrent throughput
  3. Cross-references: Add after the consumer code sample:

    For more consumer patterns, see [ConsumerMethod](https://github.com/blehnen/DotNetWorkQueue/wiki/ConsumerMethod) and [ConsumerAsync](https://github.com/blehnen/DotNetWorkQueue/wiki/ConsumerAsync).
    
    If history tracking is enabled, see [MessageHistory](https://github.com/blehnen/DotNetWorkQueue/wiki/MessageHistory) for retention and query options.
    
    For in-memory databases, see [SQLiteInMemoryDB](https://github.com/blehnen/DotNetWorkQueue/wiki/SQLiteInMemoryDB).
  4. Samples link: Add at the bottom:

    ###### Full samples
    
    See the [SQLite samples](https://github.com/blehnen/DotNetWorkQueue.Samples/tree/main/Source/Samples/SQLite) in the DotNetWorkQueue.Samples repository.

Do NOT change: Queue creation code, producer code, connection string examples.

grep -i "DotNetWorkQueue.Logging.LogLevel|Log.Log(|ConsumerLinq" /mnt/f/git/dotnetworkqueue.wiki/SQLiteTransport.md; echo "exit: $?" grep returns no matches (exit code 1). SQLiteTransport.md contains links to ConsumerMethod, MessageHistory, SQLiteInMemoryDB, and the samples repo.

Task 2: Expand SQLiteOptions.md with full property documentation

Replace the content of `SQLiteOptions.md` with complete documentation of `SqLiteMessageQueueTransportOptions`. The current page has time source and EnableWalMode but is missing the full property table.

New content for SQLiteOptions.md:

#### SQLite Options

**NuGet package:** `DotNetWorkQueue.Transport.SQLite`

**Options class:** `SqLiteMessageQueueTransportOptions`

**Namespace:** `DotNetWorkQueue.Transport.SQLite.Basic`

##### Time source

The SQLite transport uses the local machine's clock for all time-dependent operations (delayed processing, expiration, heartbeat). If consumers run on multiple machines, their clocks should be synchronized.

##### EnableWalMode

SQLite has an `EnableWalMode` option (default: `true`) that turns on WAL (Write-Ahead Logging) journal mode. In WAL mode, readers do not block the writer and the writer does not block readers, improving throughput.

This setting only applies to file-based databases. In-memory databases ignore it.

```csharp
createQueue.Options.EnableWalMode = false;
Queue creation options

All feature flags below are set at queue creation time via the creation class and cannot be changed after the queue exists. See SQLiteQueueCreationOptions for usage examples.

Property Type Default Notes
EnablePriority bool false Adds a priority column
EnableStatus bool true Required when EnableHeartBeat is true
EnableHeartBeat bool true Enables dead message recovery
EnableDelayedProcessing bool false Required for retry delays
EnableStatusTable bool false Auto-set to true if AdditionalColumns are present
EnableRoute bool false Tag messages with a route string
EnableMessageExpiration bool false RPC queues force this to true
EnableWalMode bool true SQLite-specific. Ignored for in-memory databases
EnableHoldTransactionUntilMessageCommitted bool always false Present in the interface but permanently disabled. SQLite does not support this feature. The setter is a no-op.
EnableHistory bool false Creates a history table for message lifecycle tracking
QueueType QueueTypes Normal Normal, RpcSend, or RpcReceive
AdditionalColumns ColumnList empty Custom columns on the status or metadata table
AdditionalConstraints ConstraintList empty Custom indexes on user columns
AdditionalColumnsOnMetaData bool false If true, user columns go on the metadata table

When EnableHistory is true, the HistoryOptions property (type HistoryTransportOptions) controls retention:

Property Type Default
RetentionDays int 30
MaxExceptionLength int 4000
StoreBody bool false
TrackEnqueue bool true
TrackProcessing bool true
TrackComplete bool true
TrackError bool true
TrackDelete bool true
TrackExpire bool true
MonitorTime TimeSpan 1 day

See MessageHistory for details on history tracking behavior.

See SQLiteInMemoryDB for in-memory database usage.


Key differences from SQL Server/PostgreSQL options:
- `EnableWalMode` is SQLite-unique
- `EnableHoldTransactionUntilMessageCommitted` is permanently `false` (getter returns false, setter is no-op)
</action>
<verify>grep -c "EnableWalMode\|EnableHistory\|HistoryOptions\|RetentionDays\|EnableHoldTransactionUntilMessageCommitted.*always\|AdditionalColumns" /mnt/f/git/dotnetworkqueue.wiki/SQLiteOptions.md</verify>
<done>grep returns 6 or more matches. SQLiteOptions.md documents every property including EnableWalMode, the permanently-disabled HoldTransaction note, and HistoryTransportOptions.</done>
</task>

---

## Task 3: Update `SQLiteQueueCreationOptions.md` and `SQLiteInMemoryDB.md`

<task id="3" files="SQLiteQueueCreationOptions.md, SQLiteInMemoryDB.md" tdd="false">
<action>
**SQLiteQueueCreationOptions.md changes:**

1. **EnableRoute:** Add this missing option after the EnablePriority section:
   ```markdown
   - Enable Route

   Tag messages with a route string. Consumers can filter to process only messages with a specific route.

   ```csharp
   createQueue.Options.EnableRoute = true;
   ```
   ```

2. **EnableHistory and EnableHoldTransactionUntilMessageCommitted:** These sections already exist on the page (lines 100-114). Verify they are present and correctly documented. The EnableHoldTransactionUntilMessageCommitted code sample should use the correct double-t spelling. The page already has this correct.

3. **Cross-references:** Add at the bottom of the page:
   ```markdown
   See [SQLiteOptions](https://github.com/blehnen/DotNetWorkQueue/wiki/SQLiteOptions) for the complete property reference.

   See [MessageHistory](https://github.com/blehnen/DotNetWorkQueue/wiki/MessageHistory) for history retention configuration.

   See [UserDequeueColumns](https://github.com/blehnen/DotNetWorkQueue/wiki/UserDequeueColumns) for using additional columns in dequeue queries.
   ```

4. **Typo fixes:** Fix "seperate" to "separate" and "automaticly" to "automatically" in the EnableStatusTable section.

**SQLiteInMemoryDB.md changes:**

1. **Version=3 clarification (line 10):** Add a note after the connection string code block:
   ```markdown
   The `Version=3` in the connection string is the System.Data.SQLite protocol version indicator, not a SQLite runtime version selector. It is required by the System.Data.SQLite.Core driver.
   ```

2. **Serilog reference (lines 48-52):** The sample code uses Serilog (`LoggerConfiguration`, `WriteTo.ColoredConsole`). Add a note that this is just one logging option:
   ```markdown
   > **Note:** This sample uses Serilog for logging. Any `ILoggerFactory` implementation works -- Serilog, NLog, the built-in `Microsoft.Extensions.Logging` console provider, etc.
   ```

3. **HandleMessages logging (line 121):** The sample uses `notifications.Log.LogInformation(...)` which is the correct MEL ILogger pattern. No change needed.

**Do NOT change:** The queue creation code, producer/consumer wiring, or scope management pattern in SQLiteInMemoryDB.md -- these are correct and demonstrate an important concept.
</action>
<verify>grep -i "seperate\|automaticly" /mnt/f/git/dotnetworkqueue.wiki/SQLiteQueueCreationOptions.md; echo "exit: $?"</verify>
<done>grep returns no matches (exit code 1). SQLiteQueueCreationOptions.md has EnableRoute, cross-references, and no typos. SQLiteInMemoryDB.md has Version=3 clarification.</done>
</task>

Clone this wiki locally