JCode.ORMX.DbProvider.SQLite 1.0.3

JCode.ORMX.DbProvider.SQLite

SQLite 数据库提供程序，用于 JCode.ORMX 框架。该提供程序使您能够使用 SQLite 作为 JCode.ORMX 的后端数据库。

功能特性

• 完整的 SQLite 支持：支持 SQLite 的所有基本操作
• 类型安全：使用强类型实体类，避免运行时错误
• LINQ 表达式树：使用 LINQ 表达式进行查询，编译时类型检查
• 表管理：自动创建和管理 SQLite 表
• 事务支持：支持 SQLite 事务操作
• 批量操作：支持批量插入、更新、删除
• 参数化查询：自动参数化查询，防止 SQL 注入
• 内存数据库：支持内存数据库模式
• 加密支持：支持 SQLite 数据库加密
• 轻量级：零配置，无需安装数据库服务器
• 跨平台：支持 Windows、Linux、macOS、iOS、Android

安装

NuGet 包

Install-Package JCode.ORMX.DbProvider.SQLite

依赖项

• System.Data.SQLite (1.0.118 或更高版本) 或 Microsoft.Data.Sqlite (7.x 或更高版本)
• JCode.ORMX (1.0.0 或更高版本)

快速开始

1. 定义实体类

[Table("Users")]
public class User
{
    [Column(IsPrimaryKey = true, IsIdentity = true)]
    public int Id { get; set; }

    [Column]
    public string Name { get; set; }

    [Column]
    public string Email { get; set; }

    [Column]
    public DateTime CreatedAt { get; set; }
}

2. 初始化 SQLite 提供程序

// 文件数据库
var provider = new SQLiteProvider("Data Source=mydb.db;");

// 内存数据库
var provider = new SQLiteProvider("Data Source=:memory:;");

// 带连接池的数据库
var connectionString = "Data Source=mydb.db;" +
    "Version=3;" +
    "Pooling=true;" +
    "Max Pool Size=100;" +
    "Journal Mode=WAL;" +
    "Synchronous=Normal";

var provider = new SQLiteProvider(connectionString);

3. 创建表

var tableManager = provider.GetTableManager();
tableManager.Create(typeof(User));

4. 基本操作

var table = tableManager.Table<User>();

// 插入
var user = new User 
{ 
    Name = "John", 
    Email = "john@example.com", 
    CreatedAt = DateTime.Now 
};
table.Insert(user);

// 查询
var users = table.Find()
    .Where(u => u.Name == "John")
    .OrderBy(u => u.Id)
    .Limit(10)
    .GetList();

// 更新
table.Update()
    .Set("Email", "newemail@example.com")
    .Where(u => u.Id == 1)
    .Execute();

// 删除
table.Delete()
    .Where(u => u.Id == 1)
    .Execute();

高级功能

事务操作

using (var transaction = provider.BeginTransaction())
{
    try
    {
        var table = transaction.Table<User>();
        
        table.Insert(user1);
        table.Insert(user2);
        
        transaction.Commit();
    }
    catch
    {
        transaction.Rollback();
        throw;
    }
}

内存数据库

// 创建内存数据库
var provider = new SQLiteProvider("Data Source=:memory:;");

// 内存数据库中的数据在连接关闭后会丢失
// 如果需要持久化，可以使用 ATTACH DATABASE 命令

加密数据库

// 使用加密的数据库
var connectionString = "Data Source=encrypted.db;" +
    "Password=your_password;" +
    "Version=3";

var provider = new SQLiteProvider(connectionString);

聚合查询

var result = table.Aggregate()
    .GroupBy("Department")
    .Count("EmployeeCount", "Id")
    .Avg("AvgSalary", "Salary")
    .GetList();

连接查询

var result = table.Find()
    .InnerJoin<Order>((u, o) => u.Id == o.UserId)
    .Where(u => u.Name == "John")
    .GetList();

批量操作

// 批量插入
var users = new List<User> { /* ... */ };
table.InsertAll(users);

// 批量更新
table.UpdateAll(users);

// 批量删除
table.DeleteAll(users);

全文搜索（FTS5）

// 创建 FTS5 虚拟表
var tableManager = provider.GetTableManager();
tableManager.ExecuteSql("CREATE VIRTUAL TABLE Users_fts USING fts5(Name, Email)");

// 插入数据到虚拟表
tableManager.ExecuteSql("INSERT INTO Users_fts(rowid, Name, Email) SELECT Id, Name, Email FROM Users");

// 全文搜索
var results = table.Find()
    .Where("Name MATCH 'John*'")
    .GetList();

配置选项

连接字符串选项

var connectionString = "Data Source=mydb.db;" +
    "Version=3;" +                           // SQLite 版本
    "Pooling=true;" +                          // 启用连接池
    "Max Pool Size=100;" +                     // 最大连接池大小
    "Journal Mode=WAL;" +                      // 日志模式：WAL、DELETE、TRUNCATE、PERSIST、MEMORY、OFF
    "Synchronous=Normal;" +                    // 同步模式：FULL、NORMAL、OFF
    "Cache Size=-10000;" +                     // 缓存大小（负值表示 KB）
    "Page Size=4096;" +                        // 页大小
    "Default Timeout=30;" +                    // 默认超时（秒）
    "FailIfMissing=False;" +                   // 如果数据库不存在是否失败
    "Read Only=False;" +                       // 只读模式
    "Password=your_password;" +                // 数据库密码
    "Foreign Keys=True;" +                     // 启用外键约束
    "Recursive Triggers=True;" +               // 递归触发器
    "Default IsolationLevel=Serializable;" +   // 默认隔离级别
    "NoSharedCache=True;" +                    // 禁用共享缓存
    "Open Mode=ReadWriteCreate;" +             // 打开模式
    "DateTimeFormat=ISO8601;" +                // 日期时间格式
    "DateTimeKind=Utc;" +                      // 日期时间种类
    "BinaryGUID=False;" +                      // GUID 存储格式

var provider = new SQLiteProvider(connectionString);

类型映射

SQLite 提供程序支持以下 .NET 类型到 SQLite 类型的映射：

性能建议

1. 使用 WAL 模式：启用 WAL 日志模式提高并发性能
2. 批量操作：使用 InsertAll、UpdateAll、DeleteAll 进行批量操作
3. 查询优化：只查询需要的字段，使用 LIMIT 限制结果集
4. 连接池：合理配置连接池大小
5. 事务范围：尽量缩小事务范围，减少锁持有时间
6. 避免 N+1 查询：使用连接查询代替多次查询
7. 使用索引：为常用查询字段创建索引
8. 内存数据库：对于临时数据使用内存数据库

故障排除

常见问题

Q: 数据库文件被锁定 A: 确保使用 WAL 模式，检查是否有其他进程正在访问数据库

Q: 查询性能慢 A: 使用 EXPLAIN QUERY PLAN 分析查询计划，添加适当的索引

Q: 内存不足 A: 调整 Cache Size 参数，增加缓存大小

Q: 批量操作失败 A: 减少批量操作的数据量，分批执行

Q: 日期时间格式问题 A: 设置 DateTimeFormat=ISO8601 和 DateTimeKind=Utc