Turso .NET 完整指南基于 ADO.NET 的本地、远程与嵌入式副本 SQLite 数据库开发【免费下载链接】tursoA SQL database in Rust: SQLite-compatible, now also speaking Postgres (experimental). The LLVM of databases.项目地址: https://gitcode.com/GitHub_Trending/tu/tursoTurso 是一个用 Rust 实现的 SQL 数据库引擎兼容 SQLite同时实验性支持 Postgres 协议。本文讲解其官方 .NET 绑定Turso.Data.Sqlite.Provider它提供 SQLite 兼容的Turso.Data.Sqlite门面facade底层由共享托管 ADO.NET 类型包Turso.Data.Common与原生运行时包Turso.Data.Native支撑可以连接本地数据库文件、远程 Turso/libSQL 数据库以及本地嵌入式副本。读完本文你将掌握从安装、连接字符串、ADO.NET 编程、嵌入式副本同步、DbBatch批处理到 NativeAOT 静态链接与 Entity Framework Core 集成的完整实战方案。包结构与安装Turso.Data.Sqlite.Provider是唯一需要业务代码直接引用的包它提供了 SQLite 兼容的Turso.Data.Sqlite门面并依赖两个实现包Turso.Data.Common共享的托管 ADO.NET 类型DbConnection、DbCommand、DbDataReader等基类之上的实现见 src/Turso.Data。Turso.Data.Native原生运行时资产覆盖 Windows、Linux、macOS、Androidandroid-arm64、android-arm、android-x64、android-x86以及以 XCFramework 形式发布的 iOS含真机与模拟器架构。安装命令dotnet add package Turso.Data.Sqlite.Provider从源码来看Turso.Data.Common的包元数据Turso.Data.csproj以 MIT 许可证发布TargetFramework 通过$(TursoTargetFrameworks)属性控制对应文档声明的net8.0、net9.0、net10.0目标。NativeAOT 静态链接对于 NativeAOT 应用默认的动态原生库会被发布为 sidecar 文件turso_sdk_kit.dll、.so或.dylib。若希望发布产物是单一可执行文件可额外引用与目标 RID 匹配的中性静态包ItemGroup PackageReference IncludeTurso.Data.Sqlite.Provider Version0.8.0-pre.2 / PackageReference IncludeTurso.Data.NativeAot.win-x64 Version0.8.0-pre.2 PrivateAssetsall / /ItemGroup然后开启静态链接属性PropertyGroup PublishAottrue/PublishAot SelfContainedtrue/SelfContained TursoUseStaticNativeLibrarytrue/TursoUseStaticNativeLibrary /PropertyGroup发布时指定受支持的 RID例如dotnet publish -c Release -r win-x64静态原生包已为win-x64、win-arm64、linux-x64、linux-arm64、osx-x64、osx-arm64发布动态原生资产仍是非 AOT 应用和移动端目标的默认选择。仓库中提供了完整的可运行示例 samples/NativeAot含NativeAotSample.csproj、Program.cs与独立 README可作为配置参考。快速开始内存数据库TursoConnection的用法与 ADO.NET 常规连接完全一致最小示例using Turso; using var connection new TursoConnection(Data Source:memory:); connection.Open(); connection.ExecuteNonQuery(CREATE TABLE t(a, b)); var rowsAffected connection.ExecuteNonQuery(INSERT INTO t(a, b) VALUES (1, 2), (3, 4)); Console.WriteLine($RowsAffected: {rowsAffected}); using var command connection.CreateCommand(); command.CommandText SELECT * FROM t; using var reader command.ExecuteReader(); while (reader.Read()) { var a reader.GetInt32(0); var b reader.GetInt32(1); Console.WriteLine($Value1: {a}, Value2: {b}); }Data Source:memory:表示纯内存数据库Data Sourceapp.db则是本地文件数据库。底层调用链中本地路径在 TursoConnection.Open() 内通过TursoBindings.OpenDatabase(filename)打开若配置了本地加密则走OpenDatabaseWithEncryption。ADO.NET 标准用法与远程连接面向DbConnection编写的既有代码可以直接使用TursoConnectionusing System.Data.Common; using Turso; await using DbConnection connection new TursoConnection(Data Sourceapp.db); connection.Open(); await using var command connection.CreateCommand(); command.CommandText SELECT $value; var parameter command.CreateParameter(); parameter.ParameterName $value; parameter.Value 42; command.Parameters.Add(parameter); var value command.ExecuteScalar();远程 Turso/libSQL 数据库使用同样的TursoConnection表面只需把Data Source换成远程 URL 并附带认证令牌await using var connection new TursoConnection( Data Sourcelibsql://example-org.turso.io;Auth TokeneyJ...); await connection.OpenAsync(); await using var command connection.CreateCommand(); command.CommandText SELECT name FROM customers WHERE id $id; command.Parameters.Add(new TursoParameter($id, 42)); var name await command.ExecuteScalarAsync();远程协议的传输细节远程模式使用 Hrana HTTP/v2/pipeline协议。从 TursoConnectionOptions.GetRemoteUri() 的源码可以看到 URL 方案的规范化规则libsql://默认映射为 HTTPSTlsFalse时映射为 HTTP便于本地开发。turso://与libsql://等价固定走 HTTPS。ws://和wss://也被接受分别映射到等价的 HTTP/HTTPS pipeline 端点。Auth Token要求 HTTPS除非主机是localhost或回环地址——该约束同时存在于连接选项校验TursoConnectionOptions.cs与同步选项校验TursoSyncDatabaseOptions.Validate()中。远程 URL 不允许携带查询串、片段或内嵌用户信息应改用Auth Token。Tls如果与显式的http:///https://方案冲突会在打开连接时提前失败。Read Your Writes关键字控制远程 Hrana 会话 baton 的保持方式默认True会在命令间保持会话以支持读己之写设为False则每个远程请求为无状态一次性请求见 TursoConnection.ExecuteRemoteAsync 中closeAfter的计算。嵌入式副本本地查询 后台同步在连接字符串中加入Replica Path即可用同一套 provider 表面维护一个本地嵌入式副本await using var replica new TursoConnection( Data Sourceturso://example-org.turso.io; Auth TokeneyJ...; Replica Path./replica.db; PoolingTrue; Sync Interval30); await replica.OpenAsync(); // Pull immediately in addition to the shared 30-second automatic schedule. await replica.SyncAsync();Pooling 与副本租约PoolingTrue会在使用相同路径与选项的连接之间共享同一个文件副本与一条自动同步调度PoolingFalse保持独占的路径租约:memory:副本始终私有。同一池化路径下的连接必须使用完全一致的同步设置与凭据——这一点在源码中由 TursoReplicaRegistry 的租约lease机制承载连接关闭时通过ReleaseSyncDatabase()归还租约TursoConnection.cs。自动同步与状态监控Sync Interval是自动拉取pull周期单位秒0表示禁用自动同步。注意其上限为 4,294,967 秒约 49.7 天越界会在解析时抛出异常TursoConnectionOptions.cs。AutomaticSyncStatus与AutomaticSyncStatusChanged暴露自动同步状态机包含Stopped、Waiting、Running、Retrying、Faulted五种状态TursoAutomaticSyncStatus.cs并携带尝试次数、最近尝试时间、最近一次拉取结果、下一次尝试时间与终结性失败信息。自动同步对瞬时传输、I/O 与超时类失败会重试两次其他失败为终结性失败并在调用Close()时一并抛出。连接字符串中可用的同步选项连接字符串复本还支持把以下关键字映射到TursoSyncDatabaseOptions完整关键字清单见 TursoConnectionStringBuilder.csSync Client Name同步客户端标识默认turso-sync-dotnet。Sync Long Poll Timeout长轮询超时毫秒。Bootstrap If Empty空库时是否自动引导默认True。Partial Bootstrap Prefix/Partial Bootstrap Query部分同步的前缀长度或查询引导策略二者只能选其一。Partial Sync Segment Size/Partial Sync Prefetch部分同步的分段大小与预取开关。Remote Encryption Cipher/Remote Encryption Key远程副本加密二者必须同时指定。Push Operations Threshold、Pull Bytes Threshold推送操作数与拉取字节数阈值。Force Logical MVCC Pull强制逻辑 MVCC 拉取。Sync Experimental Features实验特性开关例如views。注意本地的Encryption Cipher/Encryption Key只作用于本地数据库文件不会配置远程副本加密副本场景必须使用Remote Encryption Cipher/Remote Encryption Key混用会在打开连接时直接报错TursoConnection.CreateReplicaOptions()。DbBatch 批处理直接远程连接与已打开的嵌入式副本连接都支持 ADO.NETDbBatchawait using var batch connection.CreateBatch(); var insert batch.CreateBatchCommand(); insert.CommandText INSERT INTO customers(name) VALUES ($name); var name insert.CreateParameter(); name.ParameterName $name; name.Value Alice; insert.Parameters.Add(name); batch.BatchCommands.Add(insert); var select batch.CreateBatchCommand(); select.CommandText SELECT COUNT(*) FROM customers; batch.BatchCommands.Add(select); await using var reader await batch.ExecuteReaderAsync();两种模式在语义上有明确区别直接远程批处理所有命令在一次 Hrana 请求中发送到服务端。副本批处理每条命令在本地副本连接上顺序执行通过NextResult暴露每个结果不具备隐式原子性。因此当所有命令必须一起提交或一起回滚时应使用显式事务await using var transaction await replica.BeginTransactionAsync(); await using var batch replica.CreateBatch(); batch.Transaction transaction; var first batch.CreateBatchCommand(); first.CommandText INSERT INTO customers(name) VALUES (Alice); batch.BatchCommands.Add(first); var second batch.CreateBatchCommand(); second.CommandText INSERT INTO customers(name) VALUES (Bob); batch.BatchCommands.Add(second); await batch.ExecuteNonQueryAsync(); await transaction.CommitAsync();从 TursoConnection.CreateDbBatch() 的源码可见CanCreateBatch仅在直接远程非副本或已打开副本连接上为真本地文件连接不支持批处理。显式同步控制TursoSyncDatabase当应用需要显式控制同步时机与高级同步配置时使用TursoSyncDatabasevar options new TursoSyncDatabaseOptions( ./replica.db, new Uri(turso://example-org.turso.io)) { AuthToken authToken, PartialSync new TursoPartialSyncOptions { PrefixLength 4 * 1024 * 1024, SegmentSize 256 * 1024, Prefetch true, }, PushOperationsThreshold 1000, PullBytesThreshold 1024 * 1024, ForceLogicalMvccPull true, ExperimentalFeatures views, }; await using var database await TursoSyncDatabase.CreateAsync(options); await using var local await database.ConnectAsync(); var changed await database.PullAsync(); var stats await database.GetStatsAsync(); // Push is explicit. Do not call it for pull-only replicas. await database.PushAsync(); await database.CheckpointAsync();关键语义与 TursoSyncDatabase.cs 的实现一致PullAsync只拉取永不推送本地写入。PushAsync遵循同步引擎的 last-write-wins 冲突策略仅在该策略可接受时才使用。CheckpointAsync执行同步引擎的本地检查点操作。GetStatsAsync返回 WAL 大小、CDC 操作数、传输总量、revision 以及最近一次拉取/推送时间见 TursoSyncStats 记录类型。同步失败抛出TursoSyncException携带操作名、原生状态、脱敏后的端点、HTTP 方法/状态码与原始异常。远程加密与部分同步的约束远程加密通过RemoteEncryption new TursoRemoteEncryptionOptions { Key key, Cipher TursoRemoteEncryptionCipher.Aes256Gcm }配置。从 TursoSyncDatabaseOptions.cs 可以看到全部受支持的加密算法枚举Aes256Gcm、Aes128Gcm、ChaCha20Poly1305、Aegis128L、Aegis128X2、Aegis128X4、Aegis256、Aegis256X2、Aegis256X4不同算法的预留字节数不同GCM 族 28 字节、Aegis128 族 32 字节、Aegis256 族 48 字节。同时存在以下硬性校验Validate()远程加密不能与部分同步组合。基于查询query的部分同步不能设置PullBytesThreshold。所有部分同步策略都要求BootstrapIfEmptyTrue。Windows 上部分同步不可用因为原生稀疏文件空洞检测尚未实现会抛出PlatformNotSupportedException。部分同步的前缀与查询引导策略必须恰好指定其一且前缀长度、分段大小必须为正数。提供程序工厂需要基于工厂模式创建连接时使用TursoFactory.InstanceDbProviderFactory factory TursoFactory.Instance; using var connection factory.CreateConnection(); connection!.ConnectionString Data Source:memory:; connection.Open();从 Microsoft.Data.Sqlite 迁移对于常见的嵌入式 SQLite 用法Turso.Data.Sqlite.Provider通过Turso.Data.Sqlite门面提供 SQLite 兼容 API迁移只需替换命名空间- using Microsoft.Data.Sqlite; using Turso.Data.Sqlite; - using var connection new SqliteConnection(Data Sourceapp.db); using var connection new SqliteConnection(Data Sourceapp.db);同一个门面也可以直接连接远程数据库using Turso.Data.Sqlite; await using var connection new SqliteConnection( Data Sourcelibsql://example-org.turso.io;Auth TokeneyJ...); await connection.OpenAsync();加入Replica Path即可在保持本地查询的同时同步嵌入式副本await using var connection new SqliteConnection( Data Sourcelibsql://example-org.turso.io; Auth TokeneyJ...; Replica Path./replica.db; Sync Interval30); await connection.OpenAsync(); await connection.SyncAsync();三种连接形态的底层行为见 TursoConnection.Open() 与OpenRemote()本地路径使用原生 SQLite 兼容后端。远程 URL无Replica Path直接远程执行。远程 URL有Replica Path本地副本后端。由于客户端函数、聚合、排序规则collation、备份、blob 与扩展辅助方法都需要本地数据库句柄因此在直接远程连接上这些能力不可用。常见连接字符串关键字下表整理了官方支持的关键字默认值与别名依据 TursoConnectionStringBuilder.cs 源码确认关键字不区分大小写KeywordNotesData Source数据库路径或:memory:。别名包括DataSource、Filename。Mode解析并保留用于兼容。Cache解析并保留用于兼容。Foreign Keys解析并保留用于兼容。Recursive Triggers解析并保留用于兼容。Default Timeout默认命令超时默认值 30 秒。别名包括Command Timeout。Pooling解析并保留用于兼容。Vfs解析并保留用于兼容。Encryption CipherTurso 本地加密算法。Encryption Key与Encryption Cipher配合使用的十六进制加密密钥。Auth Token远程 Turso/libSQL URL 的 Bearer 令牌。别名包括AuthToken、Authentication Token。Replica Path远程Data Source的嵌入式副本本地路径。Read Your Writes跨命令保持远程 Hrana 会话 baton默认True设为False走无状态一次性远程请求。Sync Interval嵌入式副本自动拉取周期秒0禁用自动同步。Tls用于本地开发libsql://URL 的可选覆盖与显式http:///https://方案冲突时提前失败。本地加密算法通过Encryption Cipher配置支持的取值源码GetEncryptionCipher()确认aes128gcm、aes256gcm、aegis256、aegis256x2、aegis128l、aegis128x2、aegis128x4指定Encryption Cipher时Encryption Key必填。SQLite 兼容门面覆盖范围与已知限制Turso.Data.Sqlite门面面向迁移场景设计覆盖能力包括SQLite 风格的连接字符串、命令、读取器、schema 元数据、事务与保存点、备份、基于 SQL 的 blob 流、标量与聚合 UDF、自定义排序规则以及默认关闭的扩展加载。原始 SQLitePCLsqlite3*句柄互操作有意不支持SqliteConnection.Handle返回null不会暴露伪造的 SQLite 句柄。PRAGMA read_uncommitted仅作为连接本地状态追踪以保持 API 兼容Turso 当前不实现 SQLite 共享缓存脏读。SqliteBlob通过 SQL 读写保持定长 blob 流行为尚未由原生增量 blob 存储句柄支撑。SQLite 虚拟表模块如 FTS3/FTS5默认未内置除非由 Turso 扩展/模块提供。异步方法目前走 ADO.NET 基类默认行为而非专门的异步原生路径。Entity Framework Core 集成Turso.EntityFrameworkCore.Sqlite为本地、直接远程与嵌入式副本三种 Turso 数据库提供UseTursoprovider 钩子复用 EF Core SQLite 的 LINQ 翻译管线并通过Turso.Data.Sqlite门面执行生成的 SQLdotnet add package Turso.EntityFrameworkCore.Sqliteusing Microsoft.EntityFrameworkCore; public sealed class AppDbContext : DbContext { public DbSetCustomer Customers SetCustomer(); protected override void OnConfiguring(DbContextOptionsBuilder options) options.UseTurso(Data Sourceapp.db); }也可以传入一个已打开的 Turso SQLite 兼容连接using Microsoft.EntityFrameworkCore; using Turso.Data.Sqlite; await using var connection new SqliteConnection(Data Sourceapp.db); var options new DbContextOptionsBuilderAppDbContext() .UseTurso(connection) .Options;该 provider 支持常规 EF Core CRUD、生成的键、事务、迁移以及通过EnsureCreated/EnsureCreatedAsync创建 schema上述远程与副本连接字符串同样适用于UseTurso。需要注意的边界直接远程连接无法运行 EF 的客户端 SQLite 辅助函数包括REGEXP、decimal 的ef_*函数与EF_DECIMAL排序规则依赖这些能力的查询会在 SQL 发送前失败。EnsureDeleted无法删除直接远程数据库文档指引改用 Turso 平台 API。对嵌入式副本而言EnsureDeleted只删除本地副本及其 sidecar 文件绝不删除远程数据库。小结Turso .NET 绑定以一套统一的 ADO.NET 表面覆盖了三种部署形态本地 SQLite 兼容文件/内存库、通过 Hrana HTTP/v2/pipeline直连的远程库、以及本地查询加后台同步的嵌入式副本。Turso.Data.Sqlite门面让既有 Microsoft.Data.Sqlite 代码可以低成本迁移TursoSyncDatabase提供显式的 pull/push/checkpoint 控制与高级同步选项NativeAOT 静态链接则面向对发布产物尺寸敏感的场景。相关源码与样例均可从仓库继续深入bindings/dotnet/Readme.md、src/Turso.Data、src/Turso.Data.Sqlite、src/Turso.EntityFrameworkCore.Sqlite 以及 samples。【免费下载链接】tursoA SQL database in Rust: SQLite-compatible, now also speaking Postgres (experimental). The LLVM of databases.项目地址: https://gitcode.com/GitHub_Trending/tu/turso创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Turso .NET 完整指南：基于 ADO.NET 的本地、远程与嵌入式副本 SQLite 数据库开发
Turso .NET 完整指南基于 ADO.NET 的本地、远程与嵌入式副本 SQLite 数据库开发【免费下载链接】tursoA SQL database in Rust: SQLite-compatible, now also speaking Postgres (experimental). The LLVM of databases.项目地址: https://gitcode.com/GitHub_Trending/tu/tursoTurso 是一个用 Rust 实现的 SQL 数据库引擎兼容 SQLite同时实验性支持 Postgres 协议。本文讲解其官方 .NET 绑定Turso.Data.Sqlite.Provider它提供 SQLite 兼容的Turso.Data.Sqlite门面facade底层由共享托管 ADO.NET 类型包Turso.Data.Common与原生运行时包Turso.Data.Native支撑可以连接本地数据库文件、远程 Turso/libSQL 数据库以及本地嵌入式副本。读完本文你将掌握从安装、连接字符串、ADO.NET 编程、嵌入式副本同步、DbBatch批处理到 NativeAOT 静态链接与 Entity Framework Core 集成的完整实战方案。包结构与安装Turso.Data.Sqlite.Provider是唯一需要业务代码直接引用的包它提供了 SQLite 兼容的Turso.Data.Sqlite门面并依赖两个实现包Turso.Data.Common共享的托管 ADO.NET 类型DbConnection、DbCommand、DbDataReader等基类之上的实现见 src/Turso.Data。Turso.Data.Native原生运行时资产覆盖 Windows、Linux、macOS、Androidandroid-arm64、android-arm、android-x64、android-x86以及以 XCFramework 形式发布的 iOS含真机与模拟器架构。安装命令dotnet add package Turso.Data.Sqlite.Provider从源码来看Turso.Data.Common的包元数据Turso.Data.csproj以 MIT 许可证发布TargetFramework 通过$(TursoTargetFrameworks)属性控制对应文档声明的net8.0、net9.0、net10.0目标。NativeAOT 静态链接对于 NativeAOT 应用默认的动态原生库会被发布为 sidecar 文件turso_sdk_kit.dll、.so或.dylib。若希望发布产物是单一可执行文件可额外引用与目标 RID 匹配的中性静态包ItemGroup PackageReference IncludeTurso.Data.Sqlite.Provider Version0.8.0-pre.2 / PackageReference IncludeTurso.Data.NativeAot.win-x64 Version0.8.0-pre.2 PrivateAssetsall / /ItemGroup然后开启静态链接属性PropertyGroup PublishAottrue/PublishAot SelfContainedtrue/SelfContained TursoUseStaticNativeLibrarytrue/TursoUseStaticNativeLibrary /PropertyGroup发布时指定受支持的 RID例如dotnet publish -c Release -r win-x64静态原生包已为win-x64、win-arm64、linux-x64、linux-arm64、osx-x64、osx-arm64发布动态原生资产仍是非 AOT 应用和移动端目标的默认选择。仓库中提供了完整的可运行示例 samples/NativeAot含NativeAotSample.csproj、Program.cs与独立 README可作为配置参考。快速开始内存数据库TursoConnection的用法与 ADO.NET 常规连接完全一致最小示例using Turso; using var connection new TursoConnection(Data Source:memory:); connection.Open(); connection.ExecuteNonQuery(CREATE TABLE t(a, b)); var rowsAffected connection.ExecuteNonQuery(INSERT INTO t(a, b) VALUES (1, 2), (3, 4)); Console.WriteLine($RowsAffected: {rowsAffected}); using var command connection.CreateCommand(); command.CommandText SELECT * FROM t; using var reader command.ExecuteReader(); while (reader.Read()) { var a reader.GetInt32(0); var b reader.GetInt32(1); Console.WriteLine($Value1: {a}, Value2: {b}); }Data Source:memory:表示纯内存数据库Data Sourceapp.db则是本地文件数据库。底层调用链中本地路径在 TursoConnection.Open() 内通过TursoBindings.OpenDatabase(filename)打开若配置了本地加密则走OpenDatabaseWithEncryption。ADO.NET 标准用法与远程连接面向DbConnection编写的既有代码可以直接使用TursoConnectionusing System.Data.Common; using Turso; await using DbConnection connection new TursoConnection(Data Sourceapp.db); connection.Open(); await using var command connection.CreateCommand(); command.CommandText SELECT $value; var parameter command.CreateParameter(); parameter.ParameterName $value; parameter.Value 42; command.Parameters.Add(parameter); var value command.ExecuteScalar();远程 Turso/libSQL 数据库使用同样的TursoConnection表面只需把Data Source换成远程 URL 并附带认证令牌await using var connection new TursoConnection( Data Sourcelibsql://example-org.turso.io;Auth TokeneyJ...); await connection.OpenAsync(); await using var command connection.CreateCommand(); command.CommandText SELECT name FROM customers WHERE id $id; command.Parameters.Add(new TursoParameter($id, 42)); var name await command.ExecuteScalarAsync();远程协议的传输细节远程模式使用 Hrana HTTP/v2/pipeline协议。从 TursoConnectionOptions.GetRemoteUri() 的源码可以看到 URL 方案的规范化规则libsql://默认映射为 HTTPSTlsFalse时映射为 HTTP便于本地开发。turso://与libsql://等价固定走 HTTPS。ws://和wss://也被接受分别映射到等价的 HTTP/HTTPS pipeline 端点。Auth Token要求 HTTPS除非主机是localhost或回环地址——该约束同时存在于连接选项校验TursoConnectionOptions.cs与同步选项校验TursoSyncDatabaseOptions.Validate()中。远程 URL 不允许携带查询串、片段或内嵌用户信息应改用Auth Token。Tls如果与显式的http:///https://方案冲突会在打开连接时提前失败。Read Your Writes关键字控制远程 Hrana 会话 baton 的保持方式默认True会在命令间保持会话以支持读己之写设为False则每个远程请求为无状态一次性请求见 TursoConnection.ExecuteRemoteAsync 中closeAfter的计算。嵌入式副本本地查询 后台同步在连接字符串中加入Replica Path即可用同一套 provider 表面维护一个本地嵌入式副本await using var replica new TursoConnection( Data Sourceturso://example-org.turso.io; Auth TokeneyJ...; Replica Path./replica.db; PoolingTrue; Sync Interval30); await replica.OpenAsync(); // Pull immediately in addition to the shared 30-second automatic schedule. await replica.SyncAsync();Pooling 与副本租约PoolingTrue会在使用相同路径与选项的连接之间共享同一个文件副本与一条自动同步调度PoolingFalse保持独占的路径租约:memory:副本始终私有。同一池化路径下的连接必须使用完全一致的同步设置与凭据——这一点在源码中由 TursoReplicaRegistry 的租约lease机制承载连接关闭时通过ReleaseSyncDatabase()归还租约TursoConnection.cs。自动同步与状态监控Sync Interval是自动拉取pull周期单位秒0表示禁用自动同步。注意其上限为 4,294,967 秒约 49.7 天越界会在解析时抛出异常TursoConnectionOptions.cs。AutomaticSyncStatus与AutomaticSyncStatusChanged暴露自动同步状态机包含Stopped、Waiting、Running、Retrying、Faulted五种状态TursoAutomaticSyncStatus.cs并携带尝试次数、最近尝试时间、最近一次拉取结果、下一次尝试时间与终结性失败信息。自动同步对瞬时传输、I/O 与超时类失败会重试两次其他失败为终结性失败并在调用Close()时一并抛出。连接字符串中可用的同步选项连接字符串复本还支持把以下关键字映射到TursoSyncDatabaseOptions完整关键字清单见 TursoConnectionStringBuilder.csSync Client Name同步客户端标识默认turso-sync-dotnet。Sync Long Poll Timeout长轮询超时毫秒。Bootstrap If Empty空库时是否自动引导默认True。Partial Bootstrap Prefix/Partial Bootstrap Query部分同步的前缀长度或查询引导策略二者只能选其一。Partial Sync Segment Size/Partial Sync Prefetch部分同步的分段大小与预取开关。Remote Encryption Cipher/Remote Encryption Key远程副本加密二者必须同时指定。Push Operations Threshold、Pull Bytes Threshold推送操作数与拉取字节数阈值。Force Logical MVCC Pull强制逻辑 MVCC 拉取。Sync Experimental Features实验特性开关例如views。注意本地的Encryption Cipher/Encryption Key只作用于本地数据库文件不会配置远程副本加密副本场景必须使用Remote Encryption Cipher/Remote Encryption Key混用会在打开连接时直接报错TursoConnection.CreateReplicaOptions()。DbBatch 批处理直接远程连接与已打开的嵌入式副本连接都支持 ADO.NETDbBatchawait using var batch connection.CreateBatch(); var insert batch.CreateBatchCommand(); insert.CommandText INSERT INTO customers(name) VALUES ($name); var name insert.CreateParameter(); name.ParameterName $name; name.Value Alice; insert.Parameters.Add(name); batch.BatchCommands.Add(insert); var select batch.CreateBatchCommand(); select.CommandText SELECT COUNT(*) FROM customers; batch.BatchCommands.Add(select); await using var reader await batch.ExecuteReaderAsync();两种模式在语义上有明确区别直接远程批处理所有命令在一次 Hrana 请求中发送到服务端。副本批处理每条命令在本地副本连接上顺序执行通过NextResult暴露每个结果不具备隐式原子性。因此当所有命令必须一起提交或一起回滚时应使用显式事务await using var transaction await replica.BeginTransactionAsync(); await using var batch replica.CreateBatch(); batch.Transaction transaction; var first batch.CreateBatchCommand(); first.CommandText INSERT INTO customers(name) VALUES (Alice); batch.BatchCommands.Add(first); var second batch.CreateBatchCommand(); second.CommandText INSERT INTO customers(name) VALUES (Bob); batch.BatchCommands.Add(second); await batch.ExecuteNonQueryAsync(); await transaction.CommitAsync();从 TursoConnection.CreateDbBatch() 的源码可见CanCreateBatch仅在直接远程非副本或已打开副本连接上为真本地文件连接不支持批处理。显式同步控制TursoSyncDatabase当应用需要显式控制同步时机与高级同步配置时使用TursoSyncDatabasevar options new TursoSyncDatabaseOptions( ./replica.db, new Uri(turso://example-org.turso.io)) { AuthToken authToken, PartialSync new TursoPartialSyncOptions { PrefixLength 4 * 1024 * 1024, SegmentSize 256 * 1024, Prefetch true, }, PushOperationsThreshold 1000, PullBytesThreshold 1024 * 1024, ForceLogicalMvccPull true, ExperimentalFeatures views, }; await using var database await TursoSyncDatabase.CreateAsync(options); await using var local await database.ConnectAsync(); var changed await database.PullAsync(); var stats await database.GetStatsAsync(); // Push is explicit. Do not call it for pull-only replicas. await database.PushAsync(); await database.CheckpointAsync();关键语义与 TursoSyncDatabase.cs 的实现一致PullAsync只拉取永不推送本地写入。PushAsync遵循同步引擎的 last-write-wins 冲突策略仅在该策略可接受时才使用。CheckpointAsync执行同步引擎的本地检查点操作。GetStatsAsync返回 WAL 大小、CDC 操作数、传输总量、revision 以及最近一次拉取/推送时间见 TursoSyncStats 记录类型。同步失败抛出TursoSyncException携带操作名、原生状态、脱敏后的端点、HTTP 方法/状态码与原始异常。远程加密与部分同步的约束远程加密通过RemoteEncryption new TursoRemoteEncryptionOptions { Key key, Cipher TursoRemoteEncryptionCipher.Aes256Gcm }配置。从 TursoSyncDatabaseOptions.cs 可以看到全部受支持的加密算法枚举Aes256Gcm、Aes128Gcm、ChaCha20Poly1305、Aegis128L、Aegis128X2、Aegis128X4、Aegis256、Aegis256X2、Aegis256X4不同算法的预留字节数不同GCM 族 28 字节、Aegis128 族 32 字节、Aegis256 族 48 字节。同时存在以下硬性校验Validate()远程加密不能与部分同步组合。基于查询query的部分同步不能设置PullBytesThreshold。所有部分同步策略都要求BootstrapIfEmptyTrue。Windows 上部分同步不可用因为原生稀疏文件空洞检测尚未实现会抛出PlatformNotSupportedException。部分同步的前缀与查询引导策略必须恰好指定其一且前缀长度、分段大小必须为正数。提供程序工厂需要基于工厂模式创建连接时使用TursoFactory.InstanceDbProviderFactory factory TursoFactory.Instance; using var connection factory.CreateConnection(); connection!.ConnectionString Data Source:memory:; connection.Open();从 Microsoft.Data.Sqlite 迁移对于常见的嵌入式 SQLite 用法Turso.Data.Sqlite.Provider通过Turso.Data.Sqlite门面提供 SQLite 兼容 API迁移只需替换命名空间- using Microsoft.Data.Sqlite; using Turso.Data.Sqlite; - using var connection new SqliteConnection(Data Sourceapp.db); using var connection new SqliteConnection(Data Sourceapp.db);同一个门面也可以直接连接远程数据库using Turso.Data.Sqlite; await using var connection new SqliteConnection( Data Sourcelibsql://example-org.turso.io;Auth TokeneyJ...); await connection.OpenAsync();加入Replica Path即可在保持本地查询的同时同步嵌入式副本await using var connection new SqliteConnection( Data Sourcelibsql://example-org.turso.io; Auth TokeneyJ...; Replica Path./replica.db; Sync Interval30); await connection.OpenAsync(); await connection.SyncAsync();三种连接形态的底层行为见 TursoConnection.Open() 与OpenRemote()本地路径使用原生 SQLite 兼容后端。远程 URL无Replica Path直接远程执行。远程 URL有Replica Path本地副本后端。由于客户端函数、聚合、排序规则collation、备份、blob 与扩展辅助方法都需要本地数据库句柄因此在直接远程连接上这些能力不可用。常见连接字符串关键字下表整理了官方支持的关键字默认值与别名依据 TursoConnectionStringBuilder.cs 源码确认关键字不区分大小写KeywordNotesData Source数据库路径或:memory:。别名包括DataSource、Filename。Mode解析并保留用于兼容。Cache解析并保留用于兼容。Foreign Keys解析并保留用于兼容。Recursive Triggers解析并保留用于兼容。Default Timeout默认命令超时默认值 30 秒。别名包括Command Timeout。Pooling解析并保留用于兼容。Vfs解析并保留用于兼容。Encryption CipherTurso 本地加密算法。Encryption Key与Encryption Cipher配合使用的十六进制加密密钥。Auth Token远程 Turso/libSQL URL 的 Bearer 令牌。别名包括AuthToken、Authentication Token。Replica Path远程Data Source的嵌入式副本本地路径。Read Your Writes跨命令保持远程 Hrana 会话 baton默认True设为False走无状态一次性远程请求。Sync Interval嵌入式副本自动拉取周期秒0禁用自动同步。Tls用于本地开发libsql://URL 的可选覆盖与显式http:///https://方案冲突时提前失败。本地加密算法通过Encryption Cipher配置支持的取值源码GetEncryptionCipher()确认aes128gcm、aes256gcm、aegis256、aegis256x2、aegis128l、aegis128x2、aegis128x4指定Encryption Cipher时Encryption Key必填。SQLite 兼容门面覆盖范围与已知限制Turso.Data.Sqlite门面面向迁移场景设计覆盖能力包括SQLite 风格的连接字符串、命令、读取器、schema 元数据、事务与保存点、备份、基于 SQL 的 blob 流、标量与聚合 UDF、自定义排序规则以及默认关闭的扩展加载。原始 SQLitePCLsqlite3*句柄互操作有意不支持SqliteConnection.Handle返回null不会暴露伪造的 SQLite 句柄。PRAGMA read_uncommitted仅作为连接本地状态追踪以保持 API 兼容Turso 当前不实现 SQLite 共享缓存脏读。SqliteBlob通过 SQL 读写保持定长 blob 流行为尚未由原生增量 blob 存储句柄支撑。SQLite 虚拟表模块如 FTS3/FTS5默认未内置除非由 Turso 扩展/模块提供。异步方法目前走 ADO.NET 基类默认行为而非专门的异步原生路径。Entity Framework Core 集成Turso.EntityFrameworkCore.Sqlite为本地、直接远程与嵌入式副本三种 Turso 数据库提供UseTursoprovider 钩子复用 EF Core SQLite 的 LINQ 翻译管线并通过Turso.Data.Sqlite门面执行生成的 SQLdotnet add package Turso.EntityFrameworkCore.Sqliteusing Microsoft.EntityFrameworkCore; public sealed class AppDbContext : DbContext { public DbSetCustomer Customers SetCustomer(); protected override void OnConfiguring(DbContextOptionsBuilder options) options.UseTurso(Data Sourceapp.db); }也可以传入一个已打开的 Turso SQLite 兼容连接using Microsoft.EntityFrameworkCore; using Turso.Data.Sqlite; await using var connection new SqliteConnection(Data Sourceapp.db); var options new DbContextOptionsBuilderAppDbContext() .UseTurso(connection) .Options;该 provider 支持常规 EF Core CRUD、生成的键、事务、迁移以及通过EnsureCreated/EnsureCreatedAsync创建 schema上述远程与副本连接字符串同样适用于UseTurso。需要注意的边界直接远程连接无法运行 EF 的客户端 SQLite 辅助函数包括REGEXP、decimal 的ef_*函数与EF_DECIMAL排序规则依赖这些能力的查询会在 SQL 发送前失败。EnsureDeleted无法删除直接远程数据库文档指引改用 Turso 平台 API。对嵌入式副本而言EnsureDeleted只删除本地副本及其 sidecar 文件绝不删除远程数据库。小结Turso .NET 绑定以一套统一的 ADO.NET 表面覆盖了三种部署形态本地 SQLite 兼容文件/内存库、通过 Hrana HTTP/v2/pipeline直连的远程库、以及本地查询加后台同步的嵌入式副本。Turso.Data.Sqlite门面让既有 Microsoft.Data.Sqlite 代码可以低成本迁移TursoSyncDatabase提供显式的 pull/push/checkpoint 控制与高级同步选项NativeAOT 静态链接则面向对发布产物尺寸敏感的场景。相关源码与样例均可从仓库继续深入bindings/dotnet/Readme.md、src/Turso.Data、src/Turso.Data.Sqlite、src/Turso.EntityFrameworkCore.Sqlite 以及 samples。【免费下载链接】tursoA SQL database in Rust: SQLite-compatible, now also speaking Postgres (experimental). The LLVM of databases.项目地址: https://gitcode.com/GitHub_Trending/tu/turso创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考