G9SyncData.Client 1.1.0

G9SyncData

Offline-first data sync for .NET: PostgreSQL on the server, SQLite on devices, SignalR in between — exact, resumable, observable and NativeAOT-compatible from the first line.

 PostgreSQL ──capture──▶ G9SyncData.Server ──SignalR (G9SignalRSuperNetCore)──▶ G9SyncData.Client ──▶ SQLite
 (triggers, snapshot                engine + hub                                 engine + queue          (triggers,
  cursor, notify)          ◀── pushes (idempotent, per-row results) ◀──                                 staging)

Status: 1.1.0. The engines, PostgreSQL and SQLite providers, SignalR transports, source generator, server-side change feed and OpenTelemetry instrumentation are implemented; 141 unit and 170 end-to-end tests pass against real PostgreSQL, SQLite and SignalR (the end-to-end suite in both capture modes), the client and 200k/500k-row sites pass on the Android emulator, and the NativeAOT client publishes without warnings. It is the sync engine in production use by a fleet field application, which replaced a Dotmim.Sync fork with it outright. Benchmarks are in AiGuides/19-Performance.md. Read AiGuides/17-Known-Limitations.md before adopting.

Every package in this family releases together and must not be mixed. The protocol frame layout is negotiated across Client/Server/Protocol, so a client from one version against a server from another is exactly the mismatch the version pins.

Packages

Pick by role. Each pulls what it needs, so a device app normally names only the two client packages and a server only the server ones.

dotnet add package G9SyncData.Client.Sqlite
dotnet add package G9SyncData.Client.SignalR

The client model source generator ships inside G9SyncData.Client (analyzers/dotnet/cs), so a client gets it with no extra reference. Do not also reference G9SyncData.SourceGenerators: the generator would load twice and every generated partial would collide. The standalone package exists for tooling that wants the analyzer alone.

⛔ All packages in the family carry one version and must be kept on it together.

Why

G9SyncData replaces a Dotmim.Sync fork. Its guarantees target the failures that fork produced in the field:

Packages

Infrastructure requirements

Server — PostgreSQL. Two change-capture backends, chosen by configuration:

⚠ Turning on WAL capture is an infrastructure change with production prerequisites — a restart, a slot that retains WAL when its consumer stalls, a role, pg_hba.conf, and monitoring that must exist BEFORE it ships. All of it, including a checklist written to be handed to an Ops team as-is and a runbook for slot loss and failover, is in AiGuides/20-Infrastructure-PostgreSQL.md. Read that chapter before enabling it in any environment.

Selecting WAL capture:

builder.Services.AddG9SyncDataServer(model)
    .UsePostgreSql(dataSource, postgres =>
    {
        postgres.CaptureMode = G9EPostgresCaptureMode.WriteAheadLog;
        postgres.Wal.SlotName = "g9sync";                 // one slot per deployment, unique in the cluster
        postgres.Wal.PublicationName = "g9sync";
        postgres.Wal.ReplicationConnectionString = replicationConnectionString;   // a role with REPLICATION
    });

On first start the provider creates the publication and the slot, then seeds each synced table once. Pushes never wait for the consumer; the consumer only affects how quickly other writers' changes reach devices.

Client — SQLite. The engine brings no native SQLite of its own: the application owns that choice, so there is exactly one SQLite provider in the process (an application that ships two has, in practice, taken a SIGSEGV for it). The store talks to SQLitePCLRaw.core directly — no Microsoft.Data.Sqlite — and runs on the 2.x or 3.x generation, whichever the app pins. A command can be recorded on the app's own connection (sqlite-net's Handle), so it commits with the app's writes.

Development environment on this machine. PostgreSQL 18.1 in Docker at D:\Postgress (docker compose up -d), published on localhost:5432, holding a ~3.9 GB copy of production as agriwise_production for realistic testing. wal_level=logical was enabled there on 2026-09-16; the compose file carries the settings and the reasoning inline, and the original was preserved beside it.

Quick start

Server (ASP.NET Core)

var dataSource = NpgsqlDataSource.Create(builder.Configuration.GetConnectionString("Sync"));

builder.Services.AddG9SyncDataServer(model => model
        .Table("Operation", "Pot", t => t
            .Key("Id")
            .Column("SiteId", G9ESyncColumnType.Guid, nullable: false)
            .Column("Code", G9ESyncColumnType.String, nullable: false)
            .Column("IsDeleted", G9ESyncColumnType.Boolean, nullable: false)
            .Conflicts(G9EConflictPolicy.ColumnMerge))
        .Subscription("site-pots", s => s
            .Parameter("SiteId", G9ESyncColumnType.Guid)
            .Include("Operation.Pot", "{row}.\"SiteId\" = @SiteId", "NOT {row}.\"IsDeleted\"")),
        options => options.TokenSigningKey = signingKeyBytes)   // required with more than one instance
    .UsePostgreSql(dataSource)
    .UseSignalR();

var app = builder.Build();
app.UseWebSockets();
app.MapG9SyncHub().RequireAuthorization();

The store installs its capture objects in the g9sync schema at startup (or generates a reviewable script: GenerateInstallScriptAsync). Domain tables only gain three statement-level triggers each.

Visibility can also be an EF Core query over the application's own DbContext (package G9SyncData.Server.EfCore):

.Subscription("farm-pots", s => s
    .Parameter("FarmId", G9ESyncColumnType.Guid)
    .ServerParameter("PermissionStamp", G9ESyncColumnType.String)   // a changed stamp makes devices reconcile
    .IncludeQuery<AppDbContext, Pot>("Operation.Pot", (db, scope) =>
    {
        var farm = scope.Get<Guid>("FarmId");
        return db.Pots.Where(p => p.Ridge.Block.Field.FarmId == farm);
    }, whenSql: "NOT {row}.\"IsDeleted\""))

The query is translated, never executed by the library; every such query is probed at startup, and a wrong one stops the server instead of failing devices (05, ADR-0029).

Device (MAUI, console, NativeAOT)

[G9AttrSyncTable("Operation.Pot", LocalName = "Pot")]
public sealed class Pot
{
    public Guid Id { get; set; }
    public Guid SiteId { get; set; }
    [G9AttrSyncColumn(Nullability = G9ESyncNullability.NotNull)] public string Code { get; set; } = "";
    public bool IsDeleted { get; set; }
}

SQLitePCL.Batteries_V2.Init();   // native SQLite from the bundle your app references

services.AddG9SyncDataClient(G9SyncGeneratedModel.Model, o => o.AppVersion = "1.0.0")
    .UseSqlite(o => o.DatabasePath = databasePath)
    .UseSignalR((sp, o) =>
    {
        o.Url = "https://sync.example.com/g9sync";
        o.AccessTokenProvider = () => sp.GetRequiredService<ITokenSource>().GetAccessTokenAsync();
    });

var engine = provider.GetRequiredService<G9CSyncEngine>();
await engine.InitializeAsync();
await engine.SubscribeAsync("site-pots", new G9CSyncParameters().Set("SiteId", siteId));

var run = engine.Run(new G9CSyncRequest { Priority = G9ESyncPriority.UserInteractive });
await foreach (var p in run.ReadProgressAsync()) overlay.Report(p.Overall, p.Phase);
var result = await run.Completion;

The app keeps writing its tables as it always did; capture triggers record what to upload.

Samples

# a disposable PostgreSQL 13+ is expected at localhost:15433 (or set G9SYNC_SAMPLE_PG)
dotnet run --project samples/G9SyncData.Samples.Server
dotnet run --project samples/G9SyncData.Samples.AotClient -- http://localhost:5210/g9sync --watch
Invoke-RestMethod -Method Post "http://localhost:5210/sample/pots?count=100"   # the client is poked and pulls

dotnet publish samples/G9SyncData.Samples.AotClient -c Release -r win-x64       # NativeAOT proof

Build and test

dotnet build G9SyncData.slnx
dotnet test tests/G9SyncData.Tests
# Point the tests at a disposable PostgreSQL. On this machine that is the Docker instance in
# D:\Postgress (password there too - it is deliberately not repeated in this repository):
$env:G9SYNC_TEST_PG = "Host=localhost;Port=5432;Username=iman;Password=<see D:\Postgress\docker-compose.yml>;Database=postgres"
dotnet test tests/G9SyncData.IntegrationTests
# Android device or emulator (opt-in): the client and large sites on a real Android runtime
$env:G9SYNC_ANDROID = "auto"; dotnet test tests/G9SyncData.IntegrationTests --filter "FullyQualifiedName~Android"

Details: AiGuides/03-Build-Test-Release.md and AiGuides/12-Testing.md.

Documentation

Start at AiGuides/00-AiGuide.md. The research and design plan this implementation follows is G9SyncData.md in the agriculture repository root (not part of this repository).

Repository

https://dev.azure.com/G9TM/G9SyncData/_git/G9SyncData (private). CI lives in azure-pipelines.yml and has not been run yet — create the pipeline in Azure DevOps and fix whatever the hosted agent disagrees with.

License

MIT