简介这是一份面向C#初学者的SQLite3增删改查完整Demo可用于桌面或移动应用开发中本地数据库操作的学习与实际项目参考。Demo基于System.Data.SQLite提供程序围绕数据库连接、建表、插入、查询、更新、删除等核心操作展开同时演示参数化查询与事务控制帮助开发者写出更安全、更稳定的数据库访问代码。压缩包共175个文件以dll运行库、cs源代码、xml配置文件、pdb调试信息及nupkg包文件为主大小32.56MB附带完整的Visual Studio解决方案和项目文件方便直接打开运行。目前已有2256人学习下载。示例中将常用操作封装为辅助类提供InsertUser、GetUsers、UpdateUser、DeleteUser等静态方法并处理好连接开关与异常逻辑读者可将这些类直接迁移至自身项目按需扩展即可快速实现SQLite数据持久化。通过该Demo既能掌握C#操作SQLite3的标准流程也能理解面向对象封装思想适合需要快速上手的.NET开发者。1. 选 SQLite3 做 C# 数据库 Demo一个文件就把增删改查讲清楚写 C# 桌面工具的人迟早会撞上一个需求程序要存配置、存历史记录、存采集数据。装 SQL Server 觉得太重用 Access 又怕客户机器上缺驱动而 SQLite3 是那个不需要安装服务、一个文件就是完整数据库、能跑标准 SQL 增删改查的轻量方案。这篇文字要解决的问题只有一件——把 C# 里操作 SQLite3 的增删改查全流程拆开讲引入哪个包、连接串怎么写、增删改查分几步、参数怎么设、坑在哪。适合两类人准备在 WinForm、WPF 或上位机工具里加本地库的 C# 开发者以及刚入门想找一个最小可运行案例的数据库初学者。2. 搭建 SQLite3 环境NuGet 选包、连接字符串与文件路径的关键点C# 本身没有内置 SQLite 驱动第一步是去 NuGet 挑包。我在不同项目里换过两轮早期用 System.Data.SQLite后来切到 Microsoft.Data.Sqlite。不是后者功能更全而是新项目里更省心。下面把选型、安装和路径问题一次说清。2.1 Microsoft.Data.Sqlite 还是 System.Data.SQLite新项目这样选这一选择题网上答案很多真正有价值的判断标准只有三条谁在维护、原生库怎么带、API 是否贴近现代 .NET。两个包的定位差异比较直接对比项Microsoft.Data.SqliteSystem.Data.SQLite维护方微软官方维护第三方社区维护原生库依赖通过 SQLitePCLRaw 自动加载安装包内自带 SQLite 原生库跨平台表现Linux / macOS / Windows 一致偏重 Windows跨平台要额外配置API 风格与 System.Data 一致命名干净功能齐全但老式 API 偏多适合场景新项目、轻量嵌入、.NET Core/.NET 5老项目升级、.NET Framework 场景Microsoft.Data.Sqlite 在 .NET 8/9 时代的新项目里基本是首选。它底层通过 SQLitePCLRaw 动态加载原生库发布时会自动带上对应平台的原生文件不需要手动把 sqlite3.dll 拷到输出目录。它的 API 用起来和 System.Data.SqlClient 很像连接、建命令、执行、读数据一套肌肉记忆直接迁移。System.Data.SQLite 打包更“厚”自带 SQLite 原生库还额外提供了 Visual Studio 设计器支持老项目里可以可视化建表。代价是包体积大跨平台时常常要单独处理 native 依赖新项目不建议从零开始选。如果你手上的老工程已经在用且跑得稳不必强行换包——技术选型最忌讳为了换而换。创建项目并添加包我一般用命令行dotnet new console -n SqliteDemo cd SqliteDemo dotnet add package Microsoft.Data.Sqlite第一行创建控制台项目第二行进入项目目录第三行把 NuGet 包写进项目依赖。如果你在 Visual Studio 里操作就在“管理 NuGet 程序包”界面搜同一个包名安装效果完全一样。装完之后.csproj 文件里会出现一行 PackageReference。提示如果项目还是 .NET Framework 4.x建议优先评估 System.Data.SQLite它对老框架的兼容性和遇到问题时搜到的资料都更多。2.2 最小连接字符串Data Source 的路径坑SQLite 的连接字符串比 SQL Server 简单得多一行 Data Source 就够using Microsoft.Data.Sqlite; string dbPath Path.Combine(AppContext.BaseDirectory, demo.db); string connectionString $Data Source{dbPath}; using var connection new SqliteConnection(connectionString); connection.Open(); Console.WriteLine(数据库已打开);Data Source 后面跟的就是数据库文件路径。这里用 AppContext.BaseDirectory 拼出程序运行目录的完整路径是为了避免“当前工作目录”在不同启动方式下不一致。Mode 参数默认是 ReadWriteCreate意思是文件不存在就自动创建如果你只是想只读打开历史数据文件可以显式写成ModeReadOnly防止误写。新手最容易在这里翻车只写Data Sourcedemo.db然后用 Visual Studio 的 F5 调试数据库文件不会出现在项目文件夹而是跑到 bin\Debug\net8.0\ 下面。在项目目录里翻不到文件就开始怀疑驱动装坏了。用绝对路径就没这个困惑想把文件放到指定目录先 Directory.CreateDirectory 再拼路径。2.3 验证数据库文件连接打开后确认 db 文件真的生成了打开连接之后我习惯性加一段自检代码if (File.Exists(dbPath)) { var info new FileInfo(dbPath); Console.WriteLine($数据库文件位置{info.FullName}); Console.WriteLine($当前文件大小{info.Length} 字节); } else { Console.WriteLine(数据库文件未生成请检查目录写入权限); }这里有个细节值得记住SQLite 在连接建立但还没执行任何建表语句之前文件大小很可能还是 0 字节。文件大小为 0 不代表连接失败只是还没有写入表结构。后续执行了 CREATE TABLE 再回来检查文件一般就是几千字节起步了。自检代码放在建表之后跑最能说明问题。另一个容易被忽略的点是只读目录。如果程序部署在 Program Files 下普通用户没有写权限SQLite 打开连接时会直接抛“unable to open database file”。解决方案是把数据库文件放到用户目录或程序数据目录而不是和 exe 放在一起。2.4 连接字符串里的其他参数Mode、Cache 与 Pooling 什么时候用除了 Data Source连接字符串还支持几个参数Demo 阶段用不上但实现真实功能时迟早要碰string connectionString $Data Source{dbPath};ModeReadWriteCreate;CachePrivate;PoolingTrue;DefaultTimeout5;Mode 上面说过CachePrivate 是默认值表示每个连接独立使用缓存。CacheShared 允许多个连接共享页面缓存能减少磁盘读但也更容易在并发场景产生锁耦合桌面小工具一般不主动开。Pooling 默认开启效果和 SQL Server 连接池类似但 SQLite 打开文件的成本本来就低池化收益并不明显。如果你的程序大量短连接、又遇到文件句柄不释放的现象可以关掉 Pooling 单独排查。DefaultTimeout 值得调它控制 SQLite 等待文件锁的最长时间默认值是 30 秒遇到锁竞争时用户体感就是卡死 30 秒不如调成 5 秒让程序快速失败。3. C# 写 SQLite3 增删改查四段代码覆盖全部基础操作环境准备好之后核心就是增删改查。我习惯把数据库操作封装成一个 Helper 类但 Demo 阶段先不引入这一层复杂度。直接拿连接对象跑四个基本操作搞清楚每一步在底层干了什么后面封装才不会踩空。3.1 建表与插入ExecuteNonQuery 执行无返回结果集语句建表和 INSERT 都返回“影响行数”而不是数据行统一用 ExecuteNonQueryusing var connection new SqliteConnection(connectionString); connection.Open(); var createTableSql CREATE TABLE IF NOT EXISTS user_profile ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, age INTEGER, email TEXT, created_at TEXT DEFAULT (datetime(now)) );; using (var cmd connection.CreateCommand()) { cmd.CommandText createTableSql; cmd.ExecuteNonQuery(); } var insertSql INSERT INTO user_profile (name, age, email) VALUES ($name, $age, $email); ; using (var cmd connection.CreateCommand()) { cmd.CommandText insertSql; cmd.Parameters.AddWithValue($name, 张三); cmd.Parameters.AddWithValue($age, 28); cmd.Parameters.AddWithValue($email, zhangsanexample.com); var affected cmd.ExecuteNonQuery(); Console.WriteLine($插入影响行数{affected}); }参数前缀用的是$name这是 Microsoft.Data.Sqlite 允许的三种占位符写法之一另有 和 : 两种风格。用 AddWithValue 时参数名必须写全包括前缀。参数类型由 C# 值自动推断string 存成 TEXT、int 存成 INTEGER、double 存成 REAL、byte[] 存成 BLOB。a bool 没有对应的原生类型这一条留到避坑章节细说。CREATE TABLE 里 IF NOT EXISTS 是一个后悔药重复执行不会报错Demo 跑十遍也不会把表建坏。id 用 INTEGER PRIMARY KEY AUTOINCREMENT这是 SQLite 自增主键的固定写法。created_at 用 TEXT 存 datetime(now) 的结果SQLite 没有真正的日期类型这是它最常用的记录时间方式。3.2 查询ExecuteReader 逐行读还是 DataTable 一把查查询有两种常见写法用途不同二选一// 方式一ExecuteReader 逐行读取适合边读边处理 var querySql SELECT id, name, age, email FROM user_profile;; using (var cmd connection.CreateCommand()) { cmd.CommandText querySql; using var reader cmd.ExecuteReader(); while (reader.Read()) { var id reader.GetInt32(0); var name reader.GetString(1); var age reader.GetInt32(2); var email reader.GetString(3); Console.WriteLine(${id} | {name} | {age} | {email}); } } // 方式二SqliteDataAdapter 填充 DataTable适合绑定表格控件 var adapter new SqliteDataAdapter(querySql, connection); var table new DataTable(); adapter.Fill(table); foreach (DataRow row in table.Rows) { Console.WriteLine(${row[id]} | {row[name]} | {row[age]}); }方式一里reader 的 GetInt32 / GetString 是按列索引取值的强类型方法比 GetValue 再类型转换少一层装箱。有一件事必须注意reader 没关闭之前同一个连接不能再执行新的命令否则会报“连接忙”。想要边查边写要么先把结果读进内存要么另开一个连接。方式二适合把结果直接丢给 DataGridView 或 ComboBox。SqliteDataAdapter 底层同样执行 SQL只是额外帮你做了结果集缓存数据量小的时候开发效率更高。两者的选择标准很简单需要逐行处理就 reader要绑定 UI 就直接 DataTable。3.3 更新与删除WHERE 参数化是底线影响行数是镜子// 更新把 id1 的用户的 age 改成 30 var updateSql UPDATE user_profile SET age $newAge WHERE id $id;; using (var cmd connection.CreateCommand()) { cmd.CommandText updateSql; cmd.Parameters.AddWithValue($newAge, 30); cmd.Parameters.AddWithValue($id, 1); var affected cmd.ExecuteNonQuery(); Console.WriteLine($更新影响行数{affected}); } // 删除把 id1 的记录删掉 var deleteSql DELETE FROM user_profile WHERE id $id;; using (var cmd connection.CreateCommand()) { cmd.CommandText deleteSql; cmd.Parameters.AddWithValue($id, 1); var affected cmd.ExecuteNonQuery(); Console.WriteLine($删除影响行数{affected}); }更新和删除都返回影响行数这是最容易被忽略的调试信号。affected 等于 0说明 WHERE 条件没有匹配到任何行affected 远大于预期说明 WHERE 写得不够严。很多人写 UPDATE 时忘了 WHERE跑了全表更新之后还在程序里找逻辑问题——先看影响行数比盯日志快得多。WHERE 组件里的值必须走参数化不管它是用户输入还是程序内部变量。字符串拼接 SQL 在 Demo 里勉强能跑在真实输入面前就是黑匣子这一点避坑章节再展开。4. SQLite3 避坑指南五个增删改查高频异常与排查这一章是我愿意多写的地方。SQLite 的坑多半不是语法层面的而是行为边界锁、路径、类型映射、连接生命周期。下面五条按“现象 → 原因 → 解决”的顺序整理。4.1 database is locked事务没提交与多连接写入现象程序里两个窗口或两个线程同时写库其中一个抛异常SQLite Error 5: database is locked。有时不是立刻抛而是等连接超时后才抛。原因SQLite 的锁粒度是“整个数据库文件”同一时刻只允许一个写事务。常见导火索是事务没提交就释放连接或另一个连接持锁时间过长。解决先把事务范围压到最小插入循环里不要开长事务再设置DefaultTimeout5让等待锁的卡顿快速暴露最后在写操作外层加重试。public static void ExecuteWithRetry(SqliteConnection connection, Action action, int retryCount 3) { for (int i 0; i retryCount; i) { try { action(); return; } catch (SqliteException ex) when (ex.SqliteErrorCode 5) { Thread.Sleep(200 * (i 1)); } } }重试时每次等待时间递增避免两个连接同时重试又同时碰撞。这个辅助方法不只在多线程场景有用数据库文件放在网络磁盘上时偶发锁也会被它吸收掉。4.2 中文路径与相对路径打开就失败报错却很笼统现象同样的代码开发机上连接成功部署到别的机器就报“unable to open database file”路径里含中文时偶尔连接直接失败错误信息却看不出原因。原因两个独立问题叠加。相对路径依赖“当前工作目录”服务方式启动和工作目录不同中文路径在部分老版本驱动和跨平台运行时编码处理不干净就会打不开。解决统一拼绝对路径并在打开前显式创建目录string dbPath Path.Combine(AppContext.BaseDirectory, data, app.db); Directory.CreateDirectory(Path.GetDirectoryName(dbPath) ?? .); string connectionString $Data Source{dbPath};用 Path.Combine 而不是字符串加号是为了避免斜杠方向在跨平台时出岔子。Directory.CreateDirectory 用幂等设计目录存在也不会报错。写完这一句百分之八十的“找不到库文件”问题直接消失。4.3 日期与 bool 类型看着对存进去就变了现象DateTime.Now存进 TEXT 列读出来是字符串bool 变量存进去读出来是 0 或 1。绑定到界面上显示“False/True”还好写到 JSON 里就不对味了。原因SQLite 的存储类型只有 INTEGER、REAL、TEXT、BLOB、NULL没有真正的日期类型和布尔类型。Microsoft.Data.Sqlite 会按值类型做存储DateTime 变成 ISO 格式的 TEXTbool 变成 INTEGER 的 0/1。解决日期统一按 ISO 格式字符串存储即yyyy-MM-dd HH:mm:ss便于排序和外部工具查看布尔字段存 0/1读取时写强制转换var isActive reader.GetInt32(4) ! 0; DateTime createdAt DateTime.Parse(reader.GetString(5));如果你大量使用 EF Core 操作 SQLite它内部也按这套规则映射不要指望 SQLite 给你返回一个原生 DateTime。理解这一点能帮你少看半天乱码。4.4 字符串拼接 SQL增删改查变成黑匣子现象初学写法常是这样的——$SELECT * FROM user_profile WHERE name {name}。自测时输入正常数据没问题直到名字里出现一个英文单引号程序报语法错误再往后输入 OR 11 --之类的内容整表被查了出来。原因SQL 注入不是 Web 项目专属桌面软件接收用户输入后拼接 SQL等于把增删改查变成了一个黑匣子你根本不知道什么输入会触发什么结果。解决所有条件值一律参数化四种语句都一样cmd.CommandText SELECT * FROM user_profile WHERE name $name; cmd.Parameters.AddWithValue($name, name);参数化之后单引号会被当作普通字符处理不再是 SQL 语法的一部分。这句话值得贴在工位旁边任何拼进 SQL 的字符串都是不安全的除非它是一个完整的 SQL 关键词或表名。4.5 using 漏写数据库文件被占用删除和备份都会失败现象程序跑完退出demo.db 文件却删不掉提示“正在被另一个进程使用”。想用 File.Copy 做备份同样报错。原因连接对象没有被释放。连接池把文件句柄占着进程退出后也要等池子回收才能释放。解决连接、命令、reader 全部按 using 写using var connection new SqliteConnection(connectionString); connection.Open(); using var cmd connection.CreateCommand(); using var reader cmd.ExecuteReader();如果代码已经全部 using 还是被占用把连接字符串里的PoolingFalse打开隔离连接池的影响做排查。文件型数据库打开成本低很多场景下直接关掉连接池反而更清爽。5. 让 Demo 撑住真实数据量事务批量写入与索引优化Demo 往往只有几条数据但真实需求一来就是几万条。增删改查的流程不变真正变化的是数据写入方式和你对索引的态度。5.1 用事务包住一万次插入耗时从分钟级降到秒级我在一个采集工具里踩过这条单条 INSERT 循环一万次跑了半分多钟一开始以为是电脑慢后来用事务包起来变成几百毫秒。差距来自 SQLite 的自动提交模式——每一条 INSERT 都打开并提交一个事务写一次磁盘日志一万条就是一万次磁盘同步。显式事务只在 Commit 时写一次using var connection new SqliteConnection(connectionString); connection.Open(); using var transaction connection.BeginTransaction(); const int total 10000; using (var cmd connection.CreateCommand()) { cmd.CommandText INSERT INTO user_profile (name, age, email) VALUES ($name, $age, $email);; cmd.Transaction transaction; for (int i 0; i total; i) { cmd.Parameters.Clear(); cmd.Parameters.AddWithValue($name, $用户{i}); cmd.Parameters.AddWithValue($age, 20 i % 50); cmd.Parameters.AddWithValue($email, $user{i}example.com); cmd.ExecuteNonQuery(); } } transaction.Commit(); Console.WriteLine($批量插入完成共 {total} 条);注意两点批量插入命令必须把 Transaction 属性赋成当前事务对象否则命令会自己开隐式事务包不住循环事务范围内的异常要记得 Rollback 或直接让 using 释放连接回滚。一万条是可视化对比最明显的量级超过百万条就要考虑分批次提交每批 500 到 2000 条避免单个事务把内存日志撑大。5.2 Prepare 与参数复用同一条 SQL 的下一步优化上面循环里每次 AddWithValueSQLite 都要重新解析 SQL。commit 之前先 Prepare 一次后面只改参数值可以省掉解析开销using var cmd connection.CreateCommand(); cmd.CommandText INSERT INTO user_profile (name, age, email) VALUES ($name, $age, $email);; cmd.Transaction transaction; cmd.Parameters.AddWithValue($name, ); cmd.Parameters.AddWithValue($age, 0); cmd.Parameters.AddWithValue($email, ); cmd.Prepare(); for (int i 0; i total; i) { cmd.Parameters[$name].Value $用户{i}; cmd.Parameters[$age].Value 20 i % 50; cmd.Parameters[$email].Value $user{i}example.com; cmd.ExecuteNonQuery(); }Prepare 的含义是让驱动提前编译并缓存执行计划。第一次传入的参数值只是占位后续修改 Value 不会再触发重新解析。这个优化在单表高频写入时比较明显在复杂查询上更是如此。注意 Prepare 之后不要让参数的数量或类型发生变化否则需要重新 Prepare。5.3 索引建在 WHERE 和 ORDER BY 出现的字段上增删改查跑通后查询变慢的第一反应不应该是优化 SQL 写法而是看 WHERE 条件有没有索引。以 age 字段为例CREATE INDEX IF NOT EXISTS idx_user_profile_age ON user_profile(age);索引不是随手加满。update 和 delete 需要维护索引写入会有额外开销。真实经验是几千条以下的表基本不用建索引全表扫描比索引跳转还快几千到几万条看查询频率一条查询跑了上百毫秒才值得考虑索引真正要警惕的是 WHERE 字段的选择度比如性别字段只有两个值建了索引也帮不上忙。5.4 PRAGMA 调优journal_mode 与 synchronous 的真实影响桌面程序里多窗口同时打开数据库建议在连接打开后执行一条 PRAGMA 把日志模式切成 WALPRAGMA journal_modeWAL; PRAGMA synchronousNORMAL;WAL 模式允许读连接和写连接并存写操作不再阻塞读操作能明显减少 database is locked 的出现频率。synchronousNORMAL 配合 WAL 使用把磁盘同步频率降下来批量写入会更快但代价是系统掉电时可能丢失最近几笔提交。Demo 阶段可以开着试试手感生产环境要评估数据丢失的后果。6. 验证增删改查结果三条命令对账不靠猜6.1 用 sqlite3 命令行连到同一个 db 文件数据库操作类 bug 的共性特征是“程序看着没报错数据不对”。要验证增删改查是不是真的符合预期最直接的办法是不通过程序、用 SQLite3 命令行工具打开同一个库文件sqlite3 demo.db进入交互模式后先看表再统计行数.tables SELECT COUNT(*) FROM user_profile;.tables 告诉我们表有没有建成功COUNT(*) 告诉我们增删改查之后剩下的记录数。如果程序里明明插入了 5 条这里 COUNT 是 0要么插入没提交要么连接的不是同一个文件。把程序输出里的连接串路径和当前目录对比一下就知道了。6.2 程序内自查插入加一、删除减一、更新后行数不变我最后的一个习惯是在 Demo 的末尾加一段对账代码把程序里的业务结果和数据库实际状态放一起打印using var cmd connection.CreateCommand(); cmd.CommandText SELECT COUNT(*) FROM user_profile;; var total (long)cmd.ExecuteScalar(); Console.WriteLine($数据库实际总行数{total});如果程序里逻辑计算的结果是 100数据库查出来也是 100说明增删改查这个链条是通的。如果程序说删了 1 条、数据库却少了 2 条那问题不在 SQLite而在你的业务逻辑把 WHERE 写宽了。遇到这种对不上账的情况不要对着日志猜直接去命令行里把整表 print 出来一眼就能定位是哪条记录不该被删。这个“程序结果 库内实际值”双重确认的习惯帮我省掉了很多次自我怀疑。希望帮到你。本文还有配套的精品资源点击获取