saipackage postgresql adaptation

SaiPackage PostgreSQL 适配

SandPackage PostgreSQL 适配的权威实现由独立 Composer 包 supdger/sand-package 维护， 在宿主发布到 plugin/sandpackage/，并保留必要的上游兼容命名空间。不要直接修改运行副本或 vendor/。 本页描述驱动与历史恢复边界；所选版本以版本范围及消费方锁文件为准。 早期实现基线来自 saithink/saipackage 6.0.2 revision 82043f83df45a6186ea872eef3bce388e0ad87e2。

正常流程

上传包 → 检查元数据和路径 → 等待安装 → 执行对应 SQL → 上游依赖处理 → 上游文件部署 → 依赖完成回调 → 返回最终状态。

• 新装只执行 install.sql，升级只执行 update.sql，卸载执行 uninstall.sql。
• PostgreSQL 执行集中在 PostgresLifecycleSqlExecutor。不转换 MySQL SQL、不建库。
• 隐式事务脚本由执行器包裹事务。显式多事务脚本保留其边界：后段失败不会撤销前段已提交内容。 执行前扫描到任一显式 BEGIN/START TRANSACTION 时，整份脚本从第一句起遵循自身事务边界； 块外语句按 PostgreSQL 原生行为逐句提交，失败只回滚当前活动事务，不承诺全文件回滚。 ROLLBACK、ABORT 和未支持的事务结束形式提前拒绝，不能回滚后报告安装成功。
• 正常候选标记为 lifecycle_driver=saipackage-pg-v1。这个字段区分旧恢复记录， 不引入新状态编号；仍使用上游 0–5 状态，失败阻断保留已有状态 8。
• 前端源码复制不等于激活。仍须按宿主的依赖安装、构建及访问验证步骤完成前端部署。

与上游的差异

范围	保留的差异及原因
SQL 执行	PostgreSQL 连接、函数体分号识别及事务错误传播
生命周期选择	上游 WAIT_INSTALL 升级会依次执行两个 SQL，改为安装／升级二选一
命名与路径	SandAdmin 命名空间、runtime/sandpackage、sandadmin-artd
上传	先校验完整候选再替换旧包；旧登记目录保留普通备份；拒绝越界、重复 ZIP 路径及符号链接
宿主文件保护	保留目录名拒绝、目标路径和目录树符号链接检查；复制或删除失败不得报告成功
状态	操作中断或失败阻断重试；旧日志不自动清理；上传升级及执行升级时核对静态运行版本
返回值	返回操作后的 getInfo，避免前端仍收到安装前状态
INI	引号化字符串，避免分号截断元数据或换行注入记录
终端	保留现有鉴权、命令白名单和进程退出检查；以持有的宿主锁和一次性回调标识串行操作，不做租约恢复或文件补偿

正常 InstallLogic 不继承、不调用 LegacyInstallLogic 或 FailedUpgrade* 协调器。 文件、依赖、SQL 不是跨资源原子事务；出错时明确停止，不能宣称全部恢复。

旧记录兼容

LegacyInstallLogic 保存切换前的恢复实现及已有未提交修复，仅由旧恢复 API、 登记/撤回入口和 sandpackage:recover 的旧操作分支调用。构造器拒绝处理新 driver， 普通上传、安装、卸载和终端不转入该类。旧恢复测试已显式指向这个兼容类。

新 driver 的 sandpackage:recover inspect <app> 进入独立的新装恢复检查， 区分未提交、提交未知和已提交待部署。写操作仍需现场指纹确认；未知旧现场不能自动重跑。

正常路径拒绝状态 6/7/8、未知状态、未完成旧候选、旧操作日志和宿主依赖进程记录。 正常旧 installed 记录只有运行配置版本与登记版本一致时才允许升级； 无法静态确认版本时保留原锁定宿主处理。不得改 state 绕过检查。

包含 sand_platform 自动依赖安装或服务目录登记扩展的包，当前正常路径明确拒绝， 不能静默忽略这些约定。此类消费方继续使用原锁定宿主，须在独立验证完成并确认包兼容后 才切换。

2026-09-15 的独立宿主验证中，SandIAM 0.7.2 修复候选完成全新安装、 管理总览加载和客户主体创建。插件侧仅修复索引结构校验，历史迁移文件和 账本校验和保持不变。该候选不含上述扩展；结果不覆盖旧失败现场直接升级， 也不代表所有 SandIAM 业务功能或生产部署已验收。

旧恢复代码尚未物理删除，因此本次减少的是正常安装链复杂度，不是仓库总行数。

候选切换与回退

1. 保存当前宿主 revision、包版本、安装状态、代码及数据库备份；消费方主动拉取固定候选。
2. 在独立宿主先验证零插件基础运行和中立包安装、升级、卸载、页面访问，再验证业务包。
3. 有旧失败状态或未核清依赖记录时不切换；先在原锁定版本处置。
4. 未执行 SQL 时可回退代码。已执行 SQL 时，仅回退代码不足以恢复数据库； 使用验证过的备份恢复程序，不直接重跑安装或升级脚本。

真实数据库操作、建库、宿主同步、服务启停、删除及发布仍须对应任务授权。 离线检查及独立宿主结果按对应宿主请求和回归证据记录，不在公开源码根保留过程台账。