TursoSync 1.0.0

TursoSync

The offline-sync + full-text-search layer for Turso on .NET. It adds local↔cloud replication (push/pull/checkpoint against the Turso sync engine) and tantivy full-text search — the pieces the official Turso.Data.Sqlite binding doesn't ship. It carries a familiar ADO.NET surface (modeled on Turso.Data) so Dapper, DbUp and the DbProviderFactory pattern work, but in its own Turso.Sync namespace so it coexists with the official package rather than colliding with it.

Reach for the official Turso.Data.Sqlite for base local/remote access, the SQLite-compat facade, EF Core, and NativeAOT. Reach for TursoSync when you need offline replication or FTS — the two are complementary.

using Turso.Sync;

// Local-only (offline fast path — plain engine, no sync overhead)
await using var conn = new TursoConnection("Data Source=app.db");
await conn.OpenAsync();

// …or synced against Turso Cloud
await using var synced = new TursoConnection(
    "Data Source=app.db;Remote Url=libsql://my-db.turso.io;Auth Token=…");
await synced.OpenAsync();
synced.SyncDatabase!.Push();   // push local changes
synced.SyncDatabase!.Pull();   // pull + apply remote changes

Packages

dotnet add package TursoSync
dotnet add package TursoSync.DbUp     # optional: migrations
dotnet add package TursoSync.Dapper   # optional: Dapper type handlers

Highlights

• Two lanes, one API. No Remote Url → the plain local engine (AsyncIO=0, no IO pump); a remote (or Sync=true) → the sync engine. In release builds, local performance is on par with SQLite.
• Familiar surface, own namespace. Public types live in namespace Turso.Sync (TursoConnection, TursoCommand, …), modeled on Turso.Data so Dapper, DbUp and the DbProviderFactory pattern work — and namespaced so a project can reference both this and the official Turso.Data.Sqlite without clashing.
• Connection pooling on by default (Pooling=false to disable) — opening Turso is expensive, the pool makes the open-per-op pattern ~50× cheaper.
• Extensibility: CreateFunction / CreateAggregate / CreateCollation / EnableExtensions / LoadExtension.
• Local at-rest encryption: …;Encryption Cipher=aes256gcm;Encryption Key=<hex>.

Connection string keys

Data Source (required) · Remote Url · Auth Token · Namespace · Bootstrap · Sync · Pooling · Busy Timeout · Long Poll Timeout · Encryption Cipher · Encryption Key.

Native library

The provider P/Invokes the turso_sync_sdk_kit native (the Turso sync engine + tantivy FTS). Released packages carry it under runtimes/<rid>/native/. For local development against a self-built engine, point TURSOSYNC_NATIVE_DIR at the folder containing the built turso_sync_sdk_kit library. Build the native in release — debug builds are ~25× slower.

Engine version

The Turso engine (the turso_sync_sdk_kit native) is not vendored — CI builds it from tursodatabase/turso at the commit pinned in turso-engine.json, currently the stable v0.7.0 release. The pin keeps builds reproducible and lets us validate each engine bump before adopting it.

• Bump it with scripts/bump-turso.sh <tag|latest> (resolves the tag → commit SHA).
• A weekly Engine bump workflow opens a PR when a newer release appears in the pinned series; CI builds
  • tests against it on the PR, so an ABI change is caught in review before merge.

Examples

// Migrations (TursoSync.DbUp)
using DbUp;
var result = DeployChanges.To.TursoDatabase("Data Source=app.db")
    .WithScriptsEmbeddedInAssembly(typeof(Program).Assembly)
    .Build()
    .PerformUpgrade();

// Dapper type handlers (TursoSync.Dapper)
Turso.TursoTypeHandlers.Register();

// A scalar UDF
conn.CreateFunction("times_two", 1, args => Convert.ToInt64(args[0]) * 2);

Status

TursoSync is the sync + FTS complement to the official Turso.Data.Sqlite binding, not a replacement for it. Base local/remote access, the SQLite-compat facade, EF Core and NativeAOT are official's domain — use that package directly for those. TursoSync owns the offline sync engine (push/pull/checkpoint) and tantivy FTS, and carries just enough of an ADO.NET surface (modeled on Turso.Data, see TURSO-PARITY.md) to query a synced database and support Dapper/DbUp. One known gap is sync-lane at-rest encryption (base-lane encryption is supported).

Testing

rig test (or dotnet test) runs the unit suite. The live sync suites are gated on environment variables and report Inconclusive (skip) when unset:

• LiveSyncIntegrationTests — needs TURSOSYNC_SYNC_SERVER pointing at a tursodb binary; the harness starts a tursodb --sync-server on a free port per test.
• TursoSyncBehaviorTests — needs TURSOSYNC_SYNC_URL (+ TURSOSYNC_SYNC_TOKEN) for a real Turso Cloud round-trip.

Copy .env.example to .env at the repo root and fill in what you have — the test project loads it automatically. Real environment variables (and CI, which exports these) always take precedence.

Releasing

Releases are driven by shipRig (changesets) — config in .changeset/.

1. Record intent: shiprig add (pick the bump + summary; the three packages are fixed, so they version together; TursoSync.Tests is ignored).
2. Ship: shiprig release → versions + changelog → commit → tags TursoSync@x.y.z → push.

The pushed tag triggers the Release workflow, which builds all six RID natives (release + FTS, stripped), packs, and publishes to NuGet via trusted publishing (OIDC — no API key). shipRig only versions/tags/pushes; the cross-arch native build + publish stay in CI (.changeset/release.jsonc).

Day-to-day dev uses rig (.rig.json): rig build / rig test / rig coverage, plus rig engine <tag|latest> (pin the engine) and rig pack (local Tier-0 pack + consume test).

License

MIT.