Reference

UseSqlite

Package Trax.Effect.Data.SqliteNamespaces Trax.Effect.Data.Sqlite.Extensions, Trax.Effect.Data.Sqlite.UtilsSource ServiceExtensions.cs, DatabaseMigrator.cs

The SQLite data provider. Persists the trax tables in a SQLite database file, migrates its schema on startup and switches the database to WAL mode.

Signature

public static TraxEffectBuilderWithData UseSqlite(
    this TraxEffectBuilder configurationBuilder,
    string connectionString
)

Parameters

ParameterTypeDescription
connectionStringstringThe SQLite connection string, such as "Data Source=trax.db"

Returns

TraxEffectBuilderWithData, which carries the methods that need a data provider. See AddEffects.

Behavior

UseSqlite runs, in order, before it registers anything: the migration (unless SkipMigrations was called earlier in the chain), then PRAGMA journal_mode=WAL. A process started with --trax-export-client <path> skips both and opens no database, and registers a hosted service that refuses to start the host if it serves anyway (see Client manifest). It sets HasDataProvider and HasDatabaseProvider, so the scheduler runs its full, database-backed services on it, as on Postgres.

  • Enums are stored as their integers, EF Core's default for SQLite, and JSON as TEXT. Raw SQL compares an enum column to an integer, such as 0 for TrainState.Pending. TrainState, WorkQueueStatus and FailureClass, which Trax's own SQLite SQL depends on, pin their values.
  • Writes are serialized at the file. There are no advisory locks or FOR UPDATE SKIP LOCKED, so dispatch is not coordinated across processes sharing one file.
  • NUL characters are stored unchanged.

DatabaseMigrator

Trax.Effect.Data.Sqlite.Utils.DatabaseMigrator applies the embedded SQLite scripts.

MemberDescription
Migrate(connectionString)Applies every script not yet in the DbUp journal, in name order. Runs synchronously and returns a completed task. The failing script's exception is written to standard output and rethrown unchanged.
CreateEngineWithEmbeddedScripts(connectionString)The DbUp UpgradeEngine over the embedded scripts.

Each script runs in its own transaction together with its journal row, so a script that fails partway leaves nothing behind and runs again cleanly at the next start.

Registered services

ServiceLifetimeRole
IDbContextFactory<SqliteContext>SingletonCreates Trax's EF Core context over the file
IDataContextScopedA context from the factory
IDataContextProviderFactorySingletonThe SQLite data context provider factory, registered as a non-toggleable effect
ISqlDialectSingletonThe SQLite dialect
IQueuedWorkListenerSingletonAn in-process signal raised when a save through one of these contexts commits queued work
ICheckpointRowsSingleton, if none is registeredThe rows checkpoints are stored in
IHostedService (HostHeartbeatService)SingletonWrites this host's row in trax.host_heartbeat at start and every 15 seconds. See Host Tracking.
TimeProviderSingleton, if none is registeredTimeProvider.System, the heartbeat's clock
ITraxFeatureDbConfiguratorSingletonA DelegateFeatureDbConfigurator that points a feature's own DbContext at the same file (UseSqlite)

Example

services.AddTrax(trax => trax
    .AddEffects(effects => effects
        .UseSqlite("Data Source=trax.db")
        .AddDataContextLogging()
    )
    .AddMediator(typeof(IShipOrderTrain).Assembly)
    .AddScheduler()
);

See also