简介System.Data.SQLite 是 SQLite 在 .NET 平台的增强实现自带 ADO.NET 2.0 引擎开发者无需额外依赖 .NET Framework 即可在应用程序中直接使用特别适合中小型系统、移动设备及不便安装数据库服务的受限环境。文档系统梳理了 SQLite 单文件存储、SQL92 支持、跨平台特性并重点讲解 System.Data.SQLite 的 ADO.NET 集成、VS2008 设计器操作、唯一 DLL 部署方式以及通用数据库操作类的封装思路。资源体积小巧压缩包内共有 1 个 PDF 文件总大小约 300KB便于离线阅读或随项目归档。这份 PDF 还结合真实 Excel 数据分析案例说明如何将数据导入 SQLite 后用 SQL 完成连接查询与统计同时给出创建数据库、返回 DataTable/DataReader、执行增删改查、获取表清单等通用方法并强调参数化 SQL 防注入可直接借鉴到 .NET 数据访问层设计中。目前已有 209 人学习下载适合 .NET 开发人员快速掌握轻量级数据库集成方案。1. System.Data.SQLite 数据库详细介绍在 .NET 里把数据库当成一个文件来用System.Data.SQLite用一句话概括它是一个让 .NET 程序直接使用 SQLite 引擎的 ADO.NET 提供程序。和 SQL Server、MySQL 那种“装服务、开端口、配账号”的思路完全不同它把整个数据库引擎封装进动态库你的程序只需要引用一个 DLL数据落盘就是一个独立的 .db 文件。这类嵌入式数据库特别适合桌面工具、边缘设备、本地缓存这类场景。我第一次接触它是在某个离线环境中做一个单机数据采集工具没有服务器没有网络却要有完整的 SQL 查询能力那时才意识到这种“数据库即文件”的方案有多省事。这篇文章会从底层结构讲起给你一套能直接落地的安装和 CRUD 代码把连接串、事务、并发这些真实项目里绕不开的参数一次说透最后集中讲部署时最容易踩的几个坑。2. System.Data.SQLite 为什么能塞进一个程序文件底层原理与选型对照2.1 托管层加原生层SQLite 引擎并不是 .NET 重写很多人误以为 System.Data.SQLite 是一套用 C# 重写的 SQLite代码里见到的 SQLiteConnection、SQLiteCommand 就是全部真相。实际上它是两层结构一层是 C 语言编译的 SQLite 原生引擎通常以 SQLite.Interop.dll 的形式存在另一层是用 C# 写的 ADO.NET 适配层负责把托管代码里的调用翻译成原生 C API 调用。你在 C# 里写 conn.Open()最终经过平台调用进入 sqlite3_open你执行 ExecuteReader()底层对应的是 sqlite3_prepare_v2 和 sqlite3_step 这一套函数。这个分工直接决定了部署行为。程序运行时必须根据进程位数加载对应架构的 SQLite.Interop.dll32 位进程找 x86 目录64 位进程找 x64 目录。只要原生库缺失、被精简掉、或者位数不匹配就会抛出“无法加载 DLL”异常。这个问题我在后面专门开了一节讲因为它能排进 System.Data.SQLite 部署事故的前三名。也正因为适配层严格实现了 ADO.NET 的抽象基类上层才能接入 DataAdapter、DataSet、Entity Framework 6、各种第三方 ORM。如果代码里到处都是 DataTable、DataSet 这套离线模型System.Data.SQLite 几乎是老式 .NET Framework 项目里最平滑的选择这也是它到今天仍被大量使用的根本原因。2.2 动态版、静态版与 Core 版三个 NuGet 选型怎么区分System.Data.SQLite 在长期维护中演化出了几种常见分发形态新人不仔细看很容易拿错。以我现在的习惯新项目优先用 System.Data.SQLite.Core 这个包。它只包含托管适配层构建时会通过 targets 文件自动把 x86 和 x64 两个原生目录复制到输出路径集成成本最低也不带多余的设计时组件。第二种是完整的 System.Data.SQLite 包。它在 Core 的基础上额外带了一些设计时组件、LINQ 到 SQLite 的适配程序集、以及 EF6 支持。某个老项目如果依赖 IDE 里的 SQLite 设计器或者旧代码直接引用了那些扩展命名空间就需要走这个完整包。缺点是引用的程序集变多发布目录变大。我一般只在旧项目升级时才用新项目不会拿它做默认。第三种是静态合并版。这类构建把原生代码和托管代码打包成一个程序集部署时只需要一个文件看起来非常省事适合做绿色小工具。代价是体积变大而且一些静态合并版的历史包袱较重对较新运行时的跟进速度不稳定。如果要长期持续迭代我更倾向于守住 Core 这种标准加载方式让构建工具按平台自动选择原生库。三个形态的差异可以简化成一张表分发形态主要文件特点适用场景System.Data.SQLite.Core托管 DLL x86/x64 两个 Interop DLL标准加载按平台自动选原生库新项目、长期维护System.Data.SQLite 完整包Core 加附加设计时/EF/LINQ 程序集兼容旧式工具链存量 .NET Framework 项目静态合并版单个程序集部署最简体积较大单文件工具软件2.3 System.Data.SQLite 与 Microsoft.Data.Sqlite 的边界很多刚转到 .NET Core 的开发者会问为什么不能直接用另一个更轻量的 Sqlite 提供程序这两者的定位是有差异的。System.Data.SQLite 是完整的 ADO.NET 实现支持 DataAdapter、DataSet、命令生成器这些经典组件而另一个轻量级 provider 只提供最基础的对象和参数化访问设计目标是把 SQL 翻译交给 EF Core 这类上层框架去处理。项目选型时我一般就分两条路走如果这是新项目没有历史包袱目标框架是 .NET 6 以上用轻量级 provider 会更顺手如果这项目已经有大量 DataTable 逻辑或者还停留在 .NET Framework 4.x 并且要兼容 EF6System.Data.SQLite 依然是最合理的选项。混用两套 provider 也不是不行但连接对象、参数类型、命令对象都不一样代码里会持续出现分支判断后面维护的人会很难受。这里经常有个认知偏差看到新框架里推荐另一个包就急着把存量代码全部迁过去。实际上 System.Data.SQLite 并不等于旧代码它只是面向另一类场景的成熟实现。选型真正要看的是手上的代码结构和你需要支持的 ADO.NET 能力边界而不是单纯追新。3. 用 System.Data.SQLite 跑通第一个数据库安装、连接串、CRUD3.1 安装 System.Data.SQLite.Core 并设置平台目标在 .NET 项目里引入 System.Data.SQLite最直接的方式是安装 NuGet 包。命令行执行dotnet add package System.Data.SQLite.Core传统 .NET Framework 项目可以打开 IDE 的 NuGet 包管理器搜索 System.Data.SQLite.Core 后点击安装。无论哪种方式安装完成后输出目录里都会出现 x86 和 x64 两个子目录或者 runtimes 文件夹下的 native 目录里面放着对应架构的 SQLite.Interop.dll。看到这个目录结构不要手动删减它就是运行时按位数加载原生库的依据。接下来我强烈建议到项目属性里把平台目标从“任何 CPU”改成一个明确的 x64 或 x86。原因在上一章说过“任何 CPU”下进程位数可能随系统变化而你在输出里准备的 Interop 库如果只有一套很容易在运行时出现找不到 DLL 的错。若业务必须保持“任何 CPU”就要把 NuGet 生成的两套原生目录完整保留不能只留其中一个。这一步属于典型的“没道理但很费时间”的问题。开发机上一切正常发布到别的电脑就崩排查了一下午最后发现就是发布目录少了一套原生文件。先检查输出结构再怀疑代码逻辑能省掉大量无效调试。3.2 最小连接字符串与路径处理System.Data.SQLite 的连接字符串和传统数据库完全不同。它不需要服务器地址、端口、账号密码核心参数只有几个键值对。最基本的写法是这样string cs Data Sourceapp.db;Version3;;Data Source 是数据库文件路径Version3 表示使用 SQLite 3 的数据库格式这两个是最低要求。如果文件不存在首次 Open 时会自动创建。还有个容易被忽略的参数叫 Pooling默认是开启的表示连接对象可能被内部缓存复用。我几乎不在真实项目里用相对路径因为它依赖“当前工作目录”。IDE 运行时工作目录通常指向项目根目录但程序被计划任务、开机自启、系统服务启动时工作目录往往会变成别的路径结果就是数据库文件突然找不到了。更稳的写法是拼一个绝对路径string dbPath Path.Combine(AppContext.BaseDirectory, app.db); string cs $Data Source{dbPath};Version3;;AppContext.BaseDirectory 是程序集所在目录不会因为启动方式不同而变。如果你的程序要写数据到安装目录还要先确认目录有写权限。很多“明明装了程序却无法创建数据库”的报错本质都是权限问题。连接对象的生命周期也要养成好习惯。SQLite 的 Open 并不像网络数据库那样建立远程连接它只是打开文件并初始化状态但这不代表你可以一直持有不释放。连接池机制下未释放的连接会占住池里的名额长期写代码不释放最终会出现打开连接超时的假象。3.3 用 SQLiteConnection、SQLiteCommand 完成建库、增删改查现在给出一套能直接复制的完整逻辑从建表到查改删一次性走完。以一张学生成绩表为例using System; using System.Data.SQLite; class SqliteDemo { static void Main() { string cs Data Sourcedemo.db;Version3;; using (var conn new SQLiteConnection(cs)) { conn.Open(); // 建表IF NOT EXISTS 保证重复执行不报错 using (var cmd conn.CreateCommand()) { cmd.CommandText CREATE TABLE IF NOT EXISTS student( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, score INTEGER DEFAULT 0, created_at TEXT DEFAULT (datetime(now)) );; cmd.ExecuteNonQuery(); } // 插入参数化写法避免拼接 SQL using (var cmd conn.CreateCommand()) { cmd.CommandText INSERT INTO student(name, score) VALUES(n, s);; cmd.Parameters.AddWithValue(n, zhang); cmd.Parameters.AddWithValue(s, 86); int affected cmd.ExecuteNonQuery(); } // 查询ExecuteReader 返回前向只读结果集 using (var cmd conn.CreateCommand()) { cmd.CommandText SELECT id, name, score FROM student WHERE score min;; cmd.Parameters.AddWithValue(min, 60); using (var reader cmd.ExecuteReader()) { while (reader.Read()) { int id reader.GetInt32(0); string name reader.GetString(1); int score reader.GetInt32(2); Console.WriteLine(${id} {name} {score}); } } } } } }这段代码里值得注意的细节有几个。CreateCommand 是基于同一个连接创建的不需要手动传入连接字符串。参数名用 开头AddWithValue 会把值和类型一起绑定给命令。ExecuteNonQuery 用于建表、插入、更新、删除这类不返回结果集的语句ExecuteReader 则用于查询。读取时尽量用 GetInt32、GetString 这类强类型方法不要直接 reader[0].ToString()。后者会让类型转换变得隐蔽尤其在 SQLite 这种弱类型数据库上明明插进去的是字符串读出来可能已经变成了数字。如果你只需要查一个单值可以用 ExecuteScalar比如 SELECT COUNT(*)。3.4 用 DataAdapter 和 DataSet 做离线编辑一套另一个经典用法是离线读一批数据进内存用户修改后一次性提交给数据库。这是 System.Data.SQLite 相比轻量级 provider 的优势所在string cs Data Sourcedemo.db;Version3;; var adapter new SQLiteDataAdapter(SELECT id, name, score FROM student;, cs); var builder new SQLiteCommandBuilder(adapter); var dataSet new DataSet(); adapter.Fill(dataSet, student); DataTable table dataSet.Tables[student]; table.Rows[0][score] 100; adapter.Update(dataSet, student);这里的逻辑是Fill 把查询结果装入 DataSetSQLiteCommandBuilder 根据 SELECT 语句里的主键信息自动生成 INSERT、UPDATE、DELETE 命令之后调用 Update适配器会逐行检查 DataRow 的状态并执行对应操作。这个机制对 Grid 编辑类界面非常友好。但有两个前提必须记住。第一SELECT 语句里必须包含主键列否则 CommandBuilder 无法生成有效的更新语句。第二这里的 Update 依然是逐行执行 SQL不是真正意义上的批量写入。如果目的是大批量插入数据速度仍然不如显式事务加循环提交这个话题放到下一章。4. 真实项目里的 System.Data.SQLite事务提速、连接池与并发写入4.1 用显式事务做批量写入性能差距非常明显SQLite 在默认的自动提交模式下每一条 INSERT 都算一个独立事务执行完就要把日志同步到磁盘。磁盘同步越频繁耗时越明显。如果你在循环里逐条插入几千行程序会明显卡顿。解决办法是手动把这一批插入包进同一个事务using (var conn new SQLiteConnection(cs)) { conn.Open(); using (var tx conn.BeginTransaction()) { using (var cmd conn.CreateCommand()) { cmd.Transaction tx; for (int i 0; i 5000; i) { cmd.CommandText INSERT INTO log(content) VALUES(c);; cmd.Parameters.Clear(); cmd.Parameters.AddWithValue(c, entry_ i); cmd.ExecuteNonQuery(); } } tx.Commit(); } }关键在 cmd.Transaction tx 这一行。如果不给它赋值命令会使用自己的隐式事务循环里的每次 ExecuteNonQuery 又退化回自动提交。事务提交前所有写入处在一个逻辑单元里要么全部生效要么全部回滚。控制事务大小的经验是一两万行以内可以一口气提交量再大就要分批比如每五千行提交一次。SQLite 在事务期间会持有写锁事务越长其他连接等待的时间越久。开头好听的“批量提速”到了并发场景就会变成别人眼中的“长时间锁表”。4.2 连接池参数与连接泄漏的排查System.Data.SQLite 默认启用连接池。池的键是连接字符串也就是说如果你代码里一会写 app.db一会写 ./app.db池会被拆成两组复用效率下降还容易踩到连接数上限。实际项目里应该把连接字符串固定在一个地方统一组装再让各处引用同一个逻辑string cs $Data Source{dbPath};Version3;PoolingTrue;MaxPoolSize32;DefaultTimeout30;;PoolingTrue 是默认行为写出来是为了让维护者明确这里有意启用了连接池。MaxPoolSize32 表示池内最多复用 32 个连接超过这个数的新 Open 调用会等待复用直到超时抛异常。DefaultTimeout30 是锁等待超时单位秒。连接池常见的坑是连接泄漏。典型表现在程序运行一段时间后某个数据库操作突然卡住再等一会报超时。根本原因大多是某个连接没有释放池里的连接被耗尽。排查思路很直接看代码里所有 SQLiteConnection 是否都走了 using或者是否在 finally 里保证 Close/Dispose。别以为垃圾回收会帮你收原生句柄和连接池的清理往往没那么及时。4.3 并发写入的现实边界读多写少才是 SQLite 的主场SQLite 不是高并发写入的数据库。同一时刻只允许一个写者持有写锁其他写入必须等待。它也没有行级锁数据库级别的锁粒度决定了写冲突的概率较高。这不是 System.Data.SQLite 的问题是 SQLite 引擎本身的设计边界。如果你的应用是桌面软件、单机缓存、本地配置库这个边界完全够用。但如果想让多个客户端远程连同一个 db 文件或者把一个程序的多线程都直接往同一个文件里写就要谨慎。所谓并发更准确的说法是多进程可以同时读写的时候需要串行。我在这类项目里的通用设计是只保留一个数据库写入队列所有写操作排进队列顺序执行读操作可以开独立连接在 WAL 模式下与写并行。这样既利用 SQLite 的能力又不让它落在不擅长的并发写场景里。下一章讲的是最常见的坑其中很多恰好都跟这个并发模型有关。5. System.Data.SQLite 常见问题与避坑排查5.1 部署时不带原生 DLLUnable to load SQLite.Interop.dll现象程序在开发机运行正常复制到另一台机器后启动即崩异常信息是“Unable to load DLL SQLite.Interop.dll找不到指定的模块”。有些情况下异常不会直接出现而是某次 Open 数据库时才抛出。原因发布目录里少了原生引擎文件。最常见的是手动精简了输出目录只拷贝了 exe 和 System.Data.SQLite.dll丢掉了 x86 和 x64 两个子目录其次是平台目标设置混乱进程是 64 位发布的原生库却是 32 位版本。解决从 NuGet 包构建出的完整发布目录里复制所有内容保留 x86 和 x64 两个子目录。如果项目发布成单文件要确认原生库已经被打包器正确处理而不是简单地把 DLL 塞进打包工具路径列表就完事。排查时先用 ProcMon 类的文件监控工具看进程到底去哪个路径加载了 SQLite.Interop.dll通常一眼就能定位问题。5.2 相对路径与权限unable to open database file现象程序在 IDE 里运行正常改成开机自启或者以服务方式启动后创建数据库时报“unable to open database file”。这个错误让很多人误判为磁盘损坏其实是路径根本不存在或者当前账号没有写权限。原因连接字符串用的是相对路径程序的工作目录随启动方式变化。IDE 启动时工作目录是项目目录自启动服务的工作目录可能是 system32相对路径自然找不到。另一种情况是路径存在但没有写权限比如把数据库写进 Program Files 或系统目录。解决不要在连接字符串里写相对路径用绝对路径拼接并确保目录存在。以桌面应用为例可以把数据目录放在用户本地应用数据目录下string root Path.Combine( Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), MyApp); Directory.CreateDirectory(root); string dbPath Path.Combine(root, app.db);代码里的 Environment.GetFolderPath 会解析成当前系统给用户预留的数据目录不同版本 Windows 都能正确映射。先 CreateDirectory 再拼连接串能避免“目录不存在但 SQLite 不会自动创建多级目录”的尴尬。5.3 database is locked 的多发原因与排查顺序现象多线程或多进程访问同一个 db 文件时某条 SQL 抛 “database is locked”。这个异常本身不是玄学它就是锁等待超时。SQLite 提供的 busy handler 等待了一段时间后仍然拿不到锁于是放弃并抛错。原因最常见的是读连接没有关闭。一个未被释放的 SQLiteDataReader 会一直持有读事务读事务不结束写操作就无法获得写锁。其次某些 BeginTransaction 开启后没有正确提交或回滚事务长期占着写锁不放。第三个是连接字符串里 DefaultTimeout 设得太小甚至没设稍微有一点竞争就直接超时。解决先检查所有 DataReader 是否都在 using 块中再检查事务是否在异常路径上有回滚。然后给连接串加上 DefaultTimeout30让短时间竞争能自动等待。如果并发读写确实存在开启 WAL 模式能让读写并行显著降低锁冲突概率。WAL 模式下写写互斥依然存在但大多数桌面场景的卡顿都是读阻塞写导致的所以效果会非常明显。5.4 类型亲和性导致的“数据变形”问题现象把字符串“00123”插入建好的表里再读出来变成了数字 123前面的零不见了。或者把“2024-01-01”读成日期类型再格式化发现时区不对。这就是 SQLite 类型亲和性在起作用。原因SQLite 列类型只是亲和性声明不是强约束。如果把列声明成 NUMERIC 或不声明类型存入一个形似数字的字符串时引擎会把它转换成数字存储。手机号、编号、IMEI 这类文本一旦被转成数字前面的零就会丢失格式也被破坏。解决建表时明确用 TEXT 声明文本列CREATE TABLE user( id INTEGER PRIMARY KEY AUTOINCREMENT, mobile TEXT NOT NULL );mobile 用 TEXT 类型就能保证“00123”原样存、原样读。读取时也尽量按列定义选择 GetString 还是 GetInt32不要把转换交给运行时。还有一点参数绑定用 AddWithValue 时如果不指定 DbType引擎会按 .NET 类型的默认行为处理遇到边界情况应该显式构造 SQLiteParameter 再指定 DbType。把列类型设计清楚这类看似诡异的数据变形问题从源头就能避免。6. 进阶技巧把 WAL、热备份和短事务组合起来6.1 WAL 模式与 BackupDatabase 的组合用法如果 System.Data.SQLite 是你的主力本地存储方案最值得养成的习惯是把数据库切成 WAL 模式再用 BackupDatabase 做不停机备份。WAL 模式全称 Write-Ahead Logging写入先追加到 .wal 文件读端继续读主文件。这样读和写不再互斥只有写和写需要排队。连接字符串常见写法是加一段参数string cs $Data Source{dbPath};Version3;Journal ModeWal;SynchronousNormal;;也可以在代码里执行 PRAGMA journal_modeWAL; 让数据库持久记录这个模式。SynchronousNormal 是 WAL 下的推荐值平衡了安全性和速度如果业务要求断电时也不能丢最近的提交就改成 FULL代价是写入变慢。备份方面System.Data.SQLite 提供了一个比直接拷贝文件可靠得多的接口using (var source new SQLiteConnection(Data Sourceapp.db;Version3;)) using (var target new SQLiteConnection(Data Sourcebackup.db;Version3;)) { source.Open(); target.Open(); source.BackupDatabase(target, main, main, -1, null, 2000); }这段代码把源库的 main 数据库在线备份到另一个文件备份过程中源库仍然可以正常读写。参数里的 -1 表示页大小沿用默认值2000 是每次备份操作间隔的毫秒数。我通常会在应用空闲时段做一次定时备份然后保留最近若干份文件用来应对异常情况下的数据恢复。这套组合的好处是写入路径保持短事务读操作不背锁备份过程不打断业务。我在某次维护本地缓存工具时遇到过频繁的锁冲突切换 WAL 并控制事务大小后问题就不再出现了。如果你也把 System.Data.SQLite 用在进程内的本地数据层这些习惯能帮你少走不少弯路。希望这篇文字能让你对这个库的选型、参数和坑都心里有数真正需要时能直接上手。本文还有配套的精品资源点击获取
