本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：WWW/sqlite版本核查报告.md。
SQLite 3.26 兼容性核查报告
- 核查日期：2026-09-15
- 核查对象：FlintHub（SplitDB 纯 SQLite 分片引擎）
- 核查范围：前台、后台（管理端）、CLI 维护脚本、plugins、update 升级包
- 目标：评估工程能否在 SQLite 3.26（2018-12-01）上运行，基线为 3.33（2020-08-14）
一、结论摘要
可以兼容，改动很小。 全工程实际使用的 SQL 特性下限为 SQLite 3.24（UPSERT），3.26 完全满足。
真正被 3.26 挡住的只有两处：
| # | 位置 | 问题 | 影响 |
|---|---|---|---|
| 1 | install.php 环境检测硬门槛 SQLite ≥ 3.33 | 版本判断写死 3.33 | 3.26 直接安装失败 |
| 2 | cli/archive.php 的 VACUUM INTO（需 ≥ 3.27） | 3.26 下每轮抛错 | 冷数据归档功能每次运行全部跳过（不丢数据，但功能失效） |
其余代码注释中提到的版本要求均为误导性注释，实际不构成依赖（见第五节）。
二、3.26 → 3.33 版本差异逐项核对（官方 changelog）
2.1 用户列出的 7 项 3.33 特性
| # | 特性 | 引入版本 | 代码是否使用 | 证据 |
|---|---|---|---|---|
| 1 | 最大数据库文件提升至 281 TB | 3.33 | ❌ | 引擎容量上限，非 SQL 特性；小型分片库，无任何 page_size/容量逻辑 |
| 2 | WAL 崩溃恢复增强（shm 自动恢复） | 3.33 | ❌ | 引擎行为改进，代码不感知；仅做标准 PRAGMA 设置 |
| 3 | UPDATE FROM | 3.33 | ❌ | 全库无此语法；所有 UPDATE 均为 WHERE ... IN (SELECT ...) / 相关子查询传统写法 |
| 4 | SQLITE_DETERMINISTIC 求值策略调整（3.32） | 3.32 | ❌ | 只影响自定义 SQL 函数；工程未注册任何自定义函数（无 PDO::sqliteCreateFunction，无扩展加载） |
| 5 | CLI 输出模式（box/json/markdown/table） | 3.33 | ❌ | 仅影响 sqlite3 命令行工具 dot-command；工程为 PHP 应用，不依赖 sqlite3 CLI |
| 6 | decimal.c 扩展 | 3.33 | ❌ | 未加载任何扩展 |
| 7 | PRAGMA integrity_check 单表检查 | 3.33 | ❌ | 全库无 integrity_check 调用；后台"数据库一致性检查"为应用层自研 SQL 对账 |
2.2 3.24 ~ 3.33 之间新增的关键语法特性（对照）
| 特性 | 引入版本 | 代码是否使用 |
|---|---|---|
UPSERT INSERT ... ON CONFLICT DO UPDATE | 3.24.0 | ✅ 大量使用（兼容 3.26） |
窗口函数 OVER | 3.25.0 | ❌ 未使用 |
ALTER TABLE ... RENAME COLUMN | 3.25.0 | ❌ 未使用 |
VACUUM INTO | 3.27.0 | ⚠️ 仅 cli/archive.php 使用（3.26 不兼容） |
NULLS FIRST/LAST、聚合 FILTER | 3.30.0 | ❌ 未使用 |
生成列 GENERATED、ADD COLUMN 非恒定默认值 | 3.31.0 | ❌ 未使用（补列全为恒定默认值） |
UPDATE FROM | 3.33.0 | ❌ 未使用 |
结论：工程实际使用的 SQL 特性下限是 3.24（UPSERT）；唯一超过 3.26 的依赖是 VACUUM INTO（3.27）。
三、工程实际使用的 SQLite 特性清单（均 ≤ 3.26）
| 特性 | 最低版本 | 使用位置 |
|---|---|---|
UPSERT ON CONFLICT ... DO UPDATE（单冲突目标，无 WHERE） | 3.24.0 | app/Helpers/Settings.php、app/Helpers/Vote.php、SessionHandler、Permission、plugins/third_party_login 等 |
INSERT OR IGNORE / INSERT OR REPLACE | 3.0 | 全工程 |
WAL（PRAGMA journal_mode = WAL） | 3.7.0 | app/SplitDB/DBFactory.php |
PRAGMA wal_checkpoint(TRUNCATE) | 3.8.x | app/Controllers/Admin/DatabaseController.php:669/782 |
PRAGMA query_only = true | 3.8.0 | DatabaseController.php:474/540/627 |
普通 VACUUM | 3.0 | DatabaseController.php:783、cli/shrink_business.php |
strftime 日期函数 | 远古 | app/Helpers/Blog.php 等 |
| DESC 复合索引 | 3.3.0 | app/SplitDB/Schema.php |
| 子查询驱动 UPDATE/DELETE | 远古 | cli/archive_mark.php:70-72、plugins/qa/Plugin.php:179 等 |
四、后台（管理端）专项核查
对 app/Controllers/Admin/ 与 plugins//AdminController.php 做了专项扫描，结果：
- 未命中：
UPDATE FROM、NULLS FIRST/LAST、FILTER、窗口函数OVER、RETURNING、GENERATED、STRICT、integrity_check、CREATE TRIGGER/VIRTUAL TABLE。 - 仅使用的 PRAGMA：
query_only、wal_checkpoint(TRUNCATE)、普通VACUUM—— 均为 3.8 时代特性，3.26 可用。 DatabaseController.php:5文档注释提到"备份 → 逐库VACUUM INTO"，但实际备份实现（handleBackup，约 659-686 行）已是「WAL checkpoint + 整目录打包 zip」，不依赖 3.27，仅注释过时。- 插件管理控制器：全部干净，无任何版本敏感 SQL。
五、误导性注释清单（不构成阻塞，建议后续顺手清理）
| 位置 | 原文 | 实际情况 |
|---|---|---|
install.php:78 | "兼容基线 3.33：ON CONFLICT/WAL/无 RETURNING 兼容均依赖版本" | UPSERT 3.24+ 即可；WAL 3.7+；RETURNING 是被刻意规避（3.35+） |
app/Controllers/Admin/DatabaseController.php:5 | "备份 → 逐库 VACUUM INTO 生成一致性快照" | 实际为 checkpoint + zip，无 VACUUM INTO 依赖 |
app/SplitDB/IDGenerator.php 头部注释 | 规避 RETURNING 以兼容 3.33 | RETURNING 需 3.35，规避正确，但与 3.33 基线无关 |
六、文件格式兼容
- 全部表为普通 rowid 表（
INTEGER PRIMARY KEY），无 WITHOUT ROWID、无生成列、无 STRICT、无表达式索引 → 文件格式未升级，3.33 建的库文件 3.26 可直接打开读写。 - WAL 文件（-wal/-shm）自 3.11 起同为 version 2，双向兼容。
七、兼容方案与实施状态
已实施：install2.php（本仓库根目录）
将 install.php 复制并修改版本门槛后命名 install2.php，供 3.26 环境使用：
- 门槛由
>= 3.33.0放宽至>= 3.24.0（工程真实 SQL 下限）； - 检测文案同步更新为「SQLite 版本 ≥ 3.24（推荐 ≥ 3.33）」；
- 注释修正为真实依赖说明。
注意：
install.php本身（3.33 基线）保持不变，install2.php为独立副本，两者可并存。
待确认：cli/archive.php 版本回退（方案 B，未实施）
cli/archive.php:122 的 VACUUM INTO 需 3.27+。若需 3.26 环境下归档功能可用，建议加运行时版本判断：
sqlite_version() >= 3.27：保持VACUUM INTO原逻辑（快照 + 压缩）；< 3.27：回退为「PRAGMA wal_checkpoint(TRUNCATE)+ 直接复制 .sqlite 文件」——归档为 CLI 低并发场景，checkpoint 后复制即一致性快照。
该改动涉及 cli/archive.php（根目录 + flinthub1.0.0 两处拷贝），是否实施待用户确认。
未实施（不推荐做）
- 降低
update/1/install.php、flinthub1.0.0/install.php的同款门槛 —— 属历史发布包，仅当前根目录install2.php已满足交付需求，如需同步另行确认。
八、核验证据索引
| 证据 | 位置 |
|---|---|
| 版本硬门槛（3.33） | install.php:78-91（install2.php 已放宽为 3.24） |
VACUUM INTO（3.27+） | cli/archive.php:122 |
| 备份实际实现（checkpoint+zip，无 VACUUM INTO） | app/Controllers/Admin/DatabaseController.php:659-686 |
| 标准 PRAGMA 初始化 | app/SplitDB/DBFactory.php:27-36 |
| UPSERT 用法 | app/Helpers/Settings.php 等 |
| 归档标记（子查询 UPDATE） | cli/archive_mark.php:70-72 |
