PocketBase数据库锁问题分析与解决方案

问题背景

在使用PocketBase构建的生产系统中，开发者在处理OAuth2认证流程时遇到了数据库锁定的问题。具体表现为在调用/api/collections/users/auth-with-oauth2接口时，系统返回"database is locked (517)"错误，导致认证失败。虽然重试通常能解决问题，但约5%的失败率影响了用户体验。

问题分析

经过深入调查，发现问题根源在于数据库并发访问控制不当。系统中有大量使用原始SQL语句的写入操作，特别是统计数据的增量更新操作：

INSERT INTO statistic (name, user_id, value)
VALUES ({:name}, {:user_id}, {:value})
ON CONFLICT (name, user_id)
DO UPDATE SET value = statistic.value + EXCLUDED.value

这些操作使用了并发数据库连接池，而PocketBase为写入操作专门提供了非并发数据库连接池(app.Dao().NonconcurrentDB())。当高并发写入(约5QPS)与认证请求同时发生时，就容易出现数据库锁冲突。

解决方案

1. 使用正确的数据库连接池

PocketBase提供了两种数据库连接池：

• 并发数据库连接池：适合读取操作
• 非并发数据库连接池(NonconcurrentDB)：专为写入操作设计

应将所有写入操作迁移到非并发连接池：

// 错误方式 - 使用并发连接池
db := app.Dao().DB()

// 正确方式 - 使用非并发连接池
db := app.Dao().NonconcurrentDB()

2. 重构数据访问层

建议采用分层设计，明确区分读写操作：

type UserStatisticRepository struct {
    readDB  dbx.Builder  // 并发连接池用于读取
    writeDB dbx.Builder  // 非并发连接池用于写入
}

3. 避免过度使用原始SQL

虽然原始SQL提供了灵活性，但存在以下风险：

• 数据类型不匹配(PocketBase字段不支持BigInt/int64)
• 绕过字段验证机制
• 不触发应用事件钩子(如OnModelBeforeCreate)
• 缺少实时事件通知

建议尽可能使用PocketBase提供的Record模型API，它们内置了数据验证和事件触发机制。

最佳实践建议

1. 写入操作隔离：所有写入操作都应使用非并发数据库连接池
2. 避免事务滥用：在不需要严格事务保证的场景下，避免使用事务
3. 合理使用ORM：优先使用PocketBase的Record API而非原始SQL
4. 监控与告警：建立数据库锁监控机制，及时发现潜在问题
5. 重试机制：对于关键操作实现适当的重试逻辑

总结

数据库锁问题在PocketBase应用中通常源于不恰当的并发控制。通过正确使用非并发数据库连接池、优化数据访问模式以及减少原始SQL的使用，可以有效避免此类问题。对于已经大量使用原始SQL的系统，建议逐步重构，优先处理高频写入路径，最终实现系统的稳定性和可靠性提升。

对于新项目，建议从一开始就遵循PocketBase的最佳实践，充分利用其内置的数据访问层功能，而不是过度依赖原始SQL，这样不仅能避免锁问题，还能确保数据完整性和系统可维护性。