本文整理于 HOW 2026 演讲内容，演讲者：杨向博，PostgreSQL ACE。

一、问题现象：一条 SQL 的本地与远程执行差距​

这是一个来自真实生产环境的案例。一条 SQL 在本地 PostgreSQL 实例上执行只需 17 毫秒，但通过 Postgres_fdw 访问远程数据库时，耗时长达 200 秒。两者相差超过一万倍。

初步排查时，第一反应往往是怀疑网络问题。但通过 EXPLAIN ANALYZE 查看执行计划后，问题的根源逐渐浮出水面。

在远程端实际执行的 SQL 中，原本的 Join 条件（如 A.sid = B.id）并未被正确下推。取而代之的是，本地的 WHERE 过滤条件（如 xt = 1）被错误地当成了 Join 条件下推到了远程端。最终效果是：远程端返回了大量中间结果数据，真正的 Join 关联却在本地完成，性能自然急剧恶化。

二、根因分析：类型转换如何破坏下推逻辑​

2.1 Postgres_fdw 的 Join 下推机制​

Postgres_fdw 并非无条件地将 Join 操作下推到远程端。优化器会综合评估代价，在四种 Join 路径（Nestloop、Hash Join、Merge Join，以及 Foreign Join）中选择最优方案。即使使用了 Foreign Join，也未必一定下推——仍需要通过代价模型比较才能决定。

具体到下推的条件，核心校验在 is_foreign_expr 函数中完成，需同时满足以下要求：

• Join 类型支持：仅限 Inner Join、Left Join 等特定类型
• 外表安全性标记：外表必须被标记为 safety（安全）
• 表达式限制：内外表的 Join 条件不能包含不可下推的操作符或函数
• 最终校验：is_foreign_expr 必须返回 True

2.2 本次案例的故障链条​

本案例中的 SQL 存在一个看似无害的写法：A.sid 和 B.id 两个字段都被显式进行了类型转换（转为 text）。这个类型转换节点触发了以下连锁反应：

1. is_foreign_expr 函数检测到类型转换节点，将其归入 "未知或不安全表达式" 分支（default 分支），返回 False
2. 原本合法的 Join 条件（A.sid = B.id）被拒绝下推
3. FDW 的优化逻辑中，为了避免子查询等问题，会尝试将其他合法条件合并到 Join 子句中
4. 此时唯一合法的条件只剩下本地的 WHERE xt = 1，于是该条件被强行"伪装"成 Join 条件下推到远程端
5. 远程端使用 xt = 1 作为 Join 条件执行，返回大量中间行，真正的表关联留在了本地完成

这就是性能雪崩的根本原因。

三、解决方案：用 GUC 参数"兜住"性能​

3.1 为什么需要 GUC 方案​

直接修改 SQL 去除类型转换显然是最彻底的解决方式。但在实际场景中，这种写法往往涉及历史遗留系统或第三方封闭软件，SQL 不在应用方的可控范围内。修改 SQL 这条路走不通。

这时候需要从 FDW 内核层面寻找解决方案。

3.2 干预位置与实现思路​

优化的关键在于：在优化器生成 Foreign Join Path 的阶段进行干预。具体来说，在 add_foreign_join_paths 相关的路径生成逻辑中，嵌入一个 GUC 参数开关。

实现逻辑如下：

1. 新增 GUC 参数（例如 enable_fdw_join_pushdown），默认值为 on（允许 Join 下推）
2. 在 is_foreign_expr 校验之前，先检查该参数状态
3. 如果参数被设置为 off，则直接阻止 Foreign Join 路径的生成，强制 Join 在本地执行
4. 参数可在会话级别动态修改，无需重启数据库

3.3 优化效果​

当 GUC 参数关闭 Join 下推后，同样的 SQL 执行时间从 200 秒 骤降至 79 毫秒。执行计划显示，远程端仅执行了基础表的过滤扫描（SELECT ... WHERE xt = 1），将数据拉回本地后再完成 Join 关联——虽然放弃了远程 Join 的优化机会，但在这个特定场景下，网络传输的数据量远小于错误下推导致的中间结果集，整体性能反而大幅提升。

性能提升约 3000 倍。

四、经验总结​

第一，排查 FDW 性能问题时，首要步骤是查看远程端实际执行的 SQL。 仅看本地的执行计划是不够的。使用 EXPLAIN (VERBOSE, ANALYZE) 或者查看远程端的日志，确认下推到远端的 SQL 是否符合预期。

第二，Join 键上的类型转换是 FDW 下推的常见陷阱。 类型转换节点会被 is_foreign_expr 判定为不安全表达式，导致原本合法的 Join 条件被拒绝下推。在编写跨库 SQL 时，应尽量避免在 Join 键上做显式类型转换。

第三，GUC 参数是快速止损的有效手段。 当 SQL 层面无法修改时，通过内核参数控制优化器行为，可以在不改变应用代码的前提下解决问题。对于云服务或 DBA 运维团队来说，这种"兜底"能力尤为重要——能在第一时间恢复业务，再从容规划长期方案。

本案例中新增的 GUC 参数虽只是一个简单开关，但背后的思路值得推广：很多 FDW 相关的性能问题，都可以通过类似的"干预点"设计，为用户提供更多的运行时控制能力，而不是将所有的优化决策都固化在代码逻辑中。

本文整理于 HOW 2026 演讲内容，演讲者：刘智龙，平安科技PG数据库专家。

一、Cgroup内存管理概述​

1.1 Cgroup的基本原理​

Cgroup（Control Group）是Linux内核提供的进程组资源管理机制，可对一组进程的CPU时间、物理内存、IO、网络等资源进行配额限制、隔离与使用统计。在云环境中，同一物理主机上通常运行多个PG实例，每个实例通过Cgroup进行资源管理——这是各家云厂商的常见做法，容器技术同样基于Cgroup实现资源约束。

【图1】

1.2 CPU管理与内存管理的本质差异​

Cgroup对CPU和内存的管理逻辑有根本性的不同：

• CPU控制的核心是时间分配。CPU通过时间片轮转实现共享，即使某Cgroup的CPU上限达到，任务只是运行变慢，仍可继续执行。

• 内存控制的核心是Page计数。内存必须即时可用，一个任务占用的工作内存无法被其他任务复用（共享内存除外）。当内存达到上限时，不存在"降速运行"的选项，只能进行回收，若回收失败则进程被终止。

关键区别在于：CPU上限打满，任务还能跑，只是慢一些；内存上限打满，任务面临的是回收或死亡。

1.3 云环境下的超卖现象​

在共享云主机上，多个Cgroup实例并发运行。若将所有Cgroup的限额简单相加，可能远超主机的物理内存，即"超卖"。但对于PG来说，超卖并不必然意味着实际内存不足——因为内存中的Cache部分是可以回收的。

实际内存占用可分为三类：私有内存（不可回收）、共享内存（如PG的Shared Buffers，由多进程共享，不可回收）、Cache（文件缓存，可回收）。多个实例的Cache存在大量空闲或可回收空间时，即使限额之和超过物理内存，实际使用量可能并未超限。

但若进行扩容或新增实例，导致OS内存水位线超标，系统会频繁回收Cache。此时回收谁的内存成了"运气问题"，可能波及关键实例，引发性能抖动。

1.4 PG在OS上的内存层次​

PG进程的内存占用可分解为三层结构：

• RSS（常驻内存） ：分为私有内存和共享内存，通常无法回收
• Page Cache：文件缓存，可回收
• Kernel层：内核自身的内存开销

【2】

在Cgroup层面，各实例拥有独立的LRU列表，回收时仅影响本Cgroup，实现了资源隔离。

二、Pages的计算与统计口径辨析​

2.1 关键接口文件​

Cgroup内存管理涉及的核心文件包括：

• memory.stat：包含各类内存指标的详细统计，是观测内存使用的主要入口
• memory.usage_in_bytes：官方不推荐直接使用，准确用量需自行计算
• cgroup.procs：需确保所有PG进程（postmaster、checkpointer、bgwriter、walwriter、backend等）均加入此文件
• memory.limit_in_bytes：定义Cgroup的内存上限

2.2 memory.stat 的核心指标解读​

以一个实际案例为例：PG实例的shared_buffers=64GB，shared_memory_type=mmap，客户端约800个。memory.stat中的关键指标包括：

• cache：Page Cache的大小
• rss：匿名页和Swap内存，注意：这里的RSS与OS进程的RSS含义不同
• mapped_file：文件共享内存大小，PG的共享内存在此项中统计
• pgpgin / pgpgout：RSS+Cache的charge/uncharge页数
• inactive_anon / active_anon：匿名页和Swap缓存的LRU分布
• inactive_file / active_file：文件缓存的LRU分布

2.3 统计口径的核心偏差​

通过手动计算可以发现Cgroup v1中的统计混乱问题：

shared_mem_mapped = inactive_anon + active_anon - rss
cache - shared_mem_mapped = inactive_file + active_file
rss + mapped_file = inactive_anon + active_anon
inactive_file + active_file + rss + mapped_file = rss + cache

• Cgroup v1的RSS统计不包含file map类型的共享内存
• PG的共享内存（无论mmap还是sysv方式）均被归类到mapped_file下
• 大页场景下，共享内存甚至不出现在任何统计指标中（包括rss_huge）

2.4 进程RSS与Cgroup RSS的差异​

查看PG各进程的RSS排序，通常checkpointer和bgwriter的RSS最大（均达60GB级别），这是因为这些进程频繁操作Shared Buffers，实际占用了大量共享内存。postmaster的RSS则小得多，因为它只需开辟共享内存的虚拟地址空间，fork给子进程使用。

查看/proc/[pid]/smaps会发现：checkpointer、bgwriter和postmaster的共享内存虚拟地址完全一致，但RSS不同。fork出的子进程虽然继承了相同的虚拟地址映射，但只有实际访问了对应物理页面的进程，其RSS才会增长。

2.5 如何正确模拟Cgroup OOM​

由于PG采用Double Buffer架构（Shared Buffers + Page Cache），在shared_buffers = 1/4 × cg_mem的典型配置下，Page Cache最多可占3/4的Cgroup内存。正常业务中私有内存占用不会太多，即使Cgroup内存打满，系统也可从Page Cache中回收内存，因此实例未必会OOM。

想要有效触发Cgroup OOM，最直接的方法是创建大量占用私有内存的会话（如大量排序、Hash Join等），而非通过持续写入填满Page Cache。 后者只会触发Cache回收，不会导致真正的内存耗尽。

三、Cgroup OOM的行为与影响​

3.1 OOM触发机制​

Cgroup OOM可分为两种情况：

OOM Killer On：内核根据OOM Score选择得分最高的进程终止（通常是Backend用户进程），发送SIGKILL信号。PG的postmaster检测到子进程异常终止后，若共享内存未被破坏，会自动拉起新进程，业务可能短暂中断但实例整体可恢复。系统日志（dmesg）和PG日志中均有相关记录。

OOM Killer Off：不触发内核Kill，但PG进程可能因内存分配失败而Hang住（状态变为D，等待事件为mem_cgroup_oom）。关键进程如walwriter若无法获得内存，实例可能直接崩溃。这种情况下，即使OOM Killer关闭，实例仍然可能挂掉——不是因为被杀，而是跑死了。

3.2 关键区别​

• Cgroup OOM ≠ 系统级VM OOM。系统级VM OOM由vm.overcommit机制独立判断
• Cgroup v1的memory.oom_control关闭时，OOM Killer不启动，但进程仍可能因内存不足而Hang或崩溃

四、Cgroup v1的缺陷与v2的改进​

4.1 v1的统计盲区​

• 缺少Page Table统计：大量进程可导致Page Table占用数十GB，v1无法观测
• 缺少Slab统计：内核Slab内存开销未纳入统计
• 缺少HugePage统计：大页内存完全不被计入，形成统计黑洞
• 无法区分异步/同步回收：pgscan_kswapd与pgscan_direct在v1中无法按Cgroup粒度区分
• 共享内存统计混乱：shmem和file_mapped混在一起
• RSS统计口径不一致：Cgroup RSS与进程RSS含义不同

4.2 v2的改进​

Cgroup v2（Linux 4.5+正式发布）在内存管理上提供了显著增强：

管理层面：

• 层级结构更清晰，配置更直观
• 新增memory.min/low/high水位线参数，可更精细地控制回收行为
• 更好地应对突刺负载
• 移除直接关闭OOM Killer的接口，改用更柔和的控制方式
• 新增memory_hugetlb_accounting，终于将大页纳入统计

观测层面：

• 新增Slab、Page Table、pgscan_kswapd/pgscan_direct/pgsteal_kswapd等指标
• 新增Socket、Vmalloc、透明大页、Zswap、全零页交换等专项统计
• 共享内存（shmem）与文件映射（file_mapped）指标分离，不再混淆
• 大页信息终于可观测

五、大页（Huge Pages）的管理与挑战​

5.1 大页的优势​

大页对PG的稳定性和性能有多方面好处：

• 略微提升TPS
• 减少TLB（Translation Lookaside Buffer）刷新压力，降低CPU缓存竞争
• 显著减少Page Table在主内存中的大小。这不仅节约内存，还能在内存回收时加速通过物理地址查找虚拟地址的映射过程
• 大页的物理连续性带来更好的内存访问局部性
• 非大页的共享内存理论上可被OS回收，大页不会

对于内存碎片和Cgroup内直接内存回收问题，大页有非常好的缓解效果。

5.2 Shared Buffers与大页的配置建议​

将shared_buffers设置为Cgroup内存的1/4似乎是行业标准，但实际情况更为复杂。调小shared_buffers可略微增加Page Cache，即增大整体缓存容量；调大shared_buffers则略微减小整体缓存，但提升了Shared Buffers命中率。两种方向各有利弊。

若shared_buffers太小，PG自身可用的工作内存不足，相当于把内存管理责任推给OS，而OS回收Page Cache本身就有性能开销；若shared_buffers太大，不仅挤占Page Cache，还需同步调整bgwriter相关参数（如bgwriter_delay、bgwriter_lru_maxpages），否则刷脏效率跟不上写入负载。

基于实际压测与生产运维经验，一个更靠谱的建议值（至少比简单的1/4公式更可靠）：

• 不开大页：shared_buffers = min(1/4 × 总内存, 20GB)
• 开大页：shared_buffers = min(1/4 × 总内存, 60GB)

读多写少的场景可适当调大，但必须同步调整刷脏参数。

5.3 大页带来的管理难题​

统计黑洞：在Cgroup v1中，大页完全不进入任何统计指标。一个实例的Cgroup限额设为20GB，若使用大页，实际可能已占用30GB物理内存，但监控显示一切正常。RDS等监控系统的内存指标在大页场景下可能全面失真。

资源规划困难：大页需在主机启动时预先分配，无法按需动态扩展。问题在于：

• 同一主机可能混合部署PG、MySQL等多种数据库，不同数据库对大页的使用策略不同
• 不知道主机上要部署多少实例、什么规格的实例，大页大小难以预先确定
• 若大页分配过大，后续实例分配不到大页，只能退而使用普通页，违背了启用大页的初衷；若分配过小，则造成大量内存浪费

【3】

示例场景：第一个PG实例获得充足大页，第二个实例要上线时大页已耗尽，无法满足需求。若试图为一个大实例分配过多大页，则主机上只能运行这一个实例，资源利用率极低。

六、内存故障模型与排查思路​

6.1 故障分类​

内存问题大致可分为四个层面：

操作系统层面：内存碎片、Swap换入过高。注意：启用大页可缓解碎片问题，但可能略微加剧Swap换入问题，需权衡。

PG内核层面：元数据膨胀、版本Bug等。

Cgroup层面：Cgroup内内存回收引发的性能抖动，通常由Cgroup打满触发。启用大页对此有显著改善效果。

私有内存层面：个别Backend进程占用过多私有内存（如大结果集排序、Hash Join），导致Cgroup整体内存紧张。

6.2 监控要点​

• 系统层：/proc/buddyinfo查看碎片；/proc/meminfo的si/so（Swap In/Out）判断换入换出压力；/proc/vmstat中的pgscan_kswapd和pgscan_direct区分异步/同步回收
• Cgroup层：memory.stat中的各项指标，注意v1和v2的统计差异
• 进程层：ps查看各进程RSS/PSS，计算私有内存；关注进程等待事件（如mem_cgroup_oom）
• 数据库层：pg_stat_bgwriter的checkpoint和buffers分配；等待事件中的IPC类事件

Buffer命中率方面，Read次数比Hit Rate更值得关注。Hit Rate很高但Read也很高时，意味着即使命中率高，仍然产生了大量Buffer读取操作（可能因扫描范围太大），这是无效的缓存竞争，仅看命中率会被误导。

6.3 故障先导信号​

常见的前置信号包括：page allocation failure、kswapd长时间高CPU、direct reclaim频繁触发、进程状态频繁切换为D（不可中断睡眠）、malloc相关等待事件增多等。OOM则属于最终结果，往往伴随着明显的进程消失和日志记录。

总结​

云环境下PG的Cgroup内存管理比单机场景复杂得多。几个核心结论：

1. 迁移到Cgroup v2可解决v1中共享内存统计、大页统计、回收观测等多方面盲区
2. 大页能提升稳定性和性能，但需配合v2使用，否则形成统计黑洞，资源规划需谨慎
3. Cgroup OOM的on/off各有风险，on时Backend进程可能被杀但实例可恢复，off时关键进程可能Hang住导致实例不可用
4. Shared Buffers不宜超过60GB（开大页时），超过后刷脏压力和非大页内存管理成本急剧上升
5. 内存监控的核心是掌握真实使用量，尤其要理解Cgroup RSS与进程RSS的区别、共享内存的统计归属

本文整理于 HOW 2026 矫顺田演讲内容。

1. 背景与项目概况​

1.1 Oracle去O的需求与挑战​

Oracle长期作为企业核心业务系统的数据库基座，尤其在能源、电信、制造等行业占据主导地位。在“去O”迁移过程中，主要面临以下四类阻力，直接决定迁移项目的成败：

• 语法不兼容：导致应用代码需大量改动。
• 语义行为差异：导致程序虽能运行但结果错误。
• 资产难以复用：PL/SQL业务逻辑迁移成本高。
• 运维复杂度高：驱动、工具不统一增加协同难度。

1.2 IvorySQL项目概况​

IvorySQL于2021年由浪潮软件集团瀚高股份发起，2025年正式捐献给开放原子开源基金会，遵循Apache 2.0开源协议。其核心定位与特点包括：

• 定位：并非独立DBMS，而是基于PostgreSQL内核深度演进，避免重复造轮子。
• 使命：用开源连接世界，提供Oracle替代的开放方案。
• 目标：降低迁移门槛，保留PG生态与可持续升级路径。
• 版本节奏：紧跟PG内核发布，约40天跟随PG最新版本发版；小版本修复Bug，大版本发布重大兼容特性。
• 最新版本：IvorySQL 5.3（基于PostgreSQL 18.3）。

注：目前已发布 IvorySQL 5.4（基于 PostgreSQL 18.4）

1.3 核心特性与社区进展​

IvorySQL提供全面灵活的Oracle兼容功能，覆盖常见数据类型、字符/时间函数、NLS参数等内置能力。社区自2021年12月发布1.0版本以来，已持续更新至5.4版本。项目提供全平台介质包，支持x86、ARM、MIPS、LoongArch等主流环境，并通过Docker镜像、K8s Operator及浏览器在线体验等方式降低用户评估门槛。

2. 核心架构与设计理念​

2.1 双模式设计​

IvorySQL采用“双模式”架构，初始化时通过initdb -m pg/oracle指定两种模式：

• PG模式：保持与原生PostgreSQL完全兼容。
• Oracle模式（默认）：提供Oracle兼容语法及增强功能。
• 动态切换：可通过 SET ivorysql.compatible_mode 语句实时动态切换模式，互不牺牲稳定性。

2.2 双端口与双解析器设计​

IvorySQL提供双端口协同解析架构：

• 5432端口：原生PostgreSQL兼容，保障业务无缝迁移。
• 1521端口（Oracle模式默认端口）：企业级Oracle语法支持，开箱即用。

在此基础上，采用专利级隔离的双语法解析核心，通过新增Parser模块处理Oracle语法，最大限度降低PostgreSQL与Oracle语法间的相互干扰。

2.3 PL/iSQL的实现思路​

IvorySQL在系统表pg_language中新增plisql语言，用于承接Oracle风格过程语言。其设计思路是复用并演进PostgreSQL的plpgsql机制，而不是完全重写。Oracle模式初始化时自动注册相关插件与语言能力，通过插件式架构降低对主线内核的侵入度。

2.4 五层兼容体系​

IvorySQL的兼容体系分为五个层次，前两层解决“能否跑起来”，后三层解决“跑得对不对、好不好”：

1. SQL语法兼容：覆盖高频DDL/DML，如表创建、修改、查询及MERGE、q转义、LIKE等Oracle语法表达。
2. 对象与存储过程兼容：支持Package、系统视图及对象访问习惯。
3. 执行语义兼容：对齐NULL处理、空串转NULL、函数细节与关键边界条件。
4. 过程语言兼容：适配Oracle执行模型，支持Procedure、Function、Cursor、匿名块等核心能力，与PL/pgSQL共存。
5. 迁移与运维工具：工具生态的完整闭环。

3. 关键兼容特性详解​

3.1 SQL语法与对象兼容​

• 基础DDL/DML：覆盖建表、修改、查询、写入等典型迁移语句。
• Package兼容：支持Oracle自定义包的功能，包括包和包体的创建、修改和描述，并通过\dk等增强命令提升包管理体验。
• View等对象语法：降低对象层改造成本。

3.2 语义与行为兼容——真正的难点​

语义行为差异是迁移中最隐蔽的风险。Oracle与PostgreSQL在以下方面存在关键差异：

语句能解析，只是迁移的开始；结果是否一致，才决定业务是否敢切换。

3.3 高级功能兼容​

• 序列与系统视图：支持CACHE/NOCACHE、SCALE、SESSION、GLOBAL等选项，兼容NEXTVAL和CURRVAL伪列使用习惯，提供ALL_SEQUENCES、DBA_SEQUENCES、USER_SEQUENCES视图。
• Invisible Column（不可见列） ：默认不出现在SELECT *结果中，需显式引用，适合应用升级过程中平滑增加列。
• XML函数：新增11个XML函数，覆盖APPENDCHILDXML、UPDATEXML、EXISTSNODE等高频函数，增强企业对XML数据的处理能力。
• 系统视图与元数据：路线规划中包含ALL_TAB_COLUMNS、ALL_CONSTRAINTS、ALL_INDEXES等常用视图，兼容DBA_/USER_体系。

3.4 未来高级特性规划​

IvorySQL计划持续补齐以下高级特性：

• 自治事务（Autonomous Transaction）
• ROWNUM伪列
• Outer Join（+）语法
• Synonym（同义词）
• Reverse Key Index、CREATE INDEX ONLINE
• Pivot/Unpivot、Trigger语法、Bitmap Index、IOT等

3.5 测试框架与质量保障​

IvorySQL建立了双框架协同的测试体系：

• Oracle test framework：用Oracle侧测试保障关键兼容点行为对齐。
• pg test framework：复用PG侧成熟验证体系，保持内核稳定性。
• 通过工程化测试减少“能跑但不一致”的风险。

4. 迁移实践与方法论​

4.1 迁移工具链闭环​

IvorySQL将迁移过程划分为四个阶段：

1. 评估阶段：识别对象差异、风险点与改造范围。
2. 转换阶段：完成SQL、对象与过程逻辑的自动或半自动转换。
3. 接入阶段：适配JDBC、ODBC、libpq等驱动，验证PostGIS、FDW、pg_stat_statements等生态组件，适配Kylin、UOS、Anolis等国产环境。
4. 运维阶段：完成监控、备份、管理与日常交付闭环。

4.2 全平台交付与云原生能力​

IvorySQL提供开箱即用的全平台安装包，降低部署摩擦。在云原生方面，通过Docker镜像、K8s Operator等方式适配现代交付模式。同时提供完善的文档、迁移指南、FAQ及最佳实践，支撑规模化推广。

4.3 案例：金融核心系统迁移实践​

某金融系统涉及总账等多个核心系统的Oracle替换需求。项目中深度兼容Oracle Package、集合数据类型、系统视图和分区索引。经过严格测试，新平台性能指标与稳定性指标达到预期要求。实践证明，兼容能力能够直接转化为核心业务迁移成功率。

5. 社区治理与未来路线​

5.1 社区治理与开放协作​

IvorySQL于2025年捐赠给开放原子开源基金会，治理结构更公开透明。社区欢迎代码、测试、文档、Issue、PR等多类型贡献，GitHub Project与公开协作流程提升了全球开发者协同效率。文档、论坛、FAQ、最佳实践共同构成社区支撑体系。

5.2 生态合作与国际化​

IvorySQL与法国Data Bene签署为期两年的MOU（合作备忘录）。Data Bene看重的是PG高兼容接入能力以及Oracle兼容与云原生优势，将在Oracle迁移项目中推广IvorySQL并参与社区能力建设。这说明兼容体系正在从国内项目走向国际生态合作。

5.3 IvorySQL 6.0预览与版本规划​

2026年版本规划如下：

• 2026年3月：IvorySQL v5.3（PG 18.3）
• 2026年6月：IvorySQL v5.4（PG 18.4）
• 2026年9月：IvorySQL v5.5（PG 18.5）
• 2026年11月：IvorySQL v6.0（PG 19.0）
• 2026年12月：IvorySQL v6.1（PG 19.1）

IvorySQL 6.0重点功能包括：

• 自治事务：在主事务中独立开启的子事务，可独立提交或回滚。
• ROWNUM：Oracle伪列，用于返回查询结果集中每一行的行号。
• Rebuild index：重建索引以消除碎片、释放空间。
• DBMS_OUTPUT：用于在程序中输出调试信息。
• 组件适配：wal2json、pgbouncer、pg_ai_query、pg_textsearch等。

5.4 2026年产品与生态重点​

• AI生态打造：推动数据库能力与AI/Agent场景融合。
• 新增国产平台适配：继续扩展认证与适配覆盖面。
• 云及容器化完整生态：各版本持续提供云原生适配能力。
• 文档与解决方案：建设迁移指南、调优指南、最佳实践与行业方案。

5.5 IvorySQL创新试验田​

IvorySQL面向真实业务需求的功能孵化平台，汇聚国内客户痛点与前沿实践，将社区暂未接纳的优秀方案快速落地：

• 逻辑复制新增表无主键：自动添加identity属性，避免报错中断。
• 创建视图后修改表结构：允许在视图语义仍有效的前提下安全变更。
• 全局唯一索引：在分区表上创建跨所有分区的唯一约束。

📖 前言​

前段时间发了一篇 IvorySQL 国内镜像实测文章，不少读者私信问：仓库里能不能拉原生 PostgreSQL？

今天专门拿 openEuler 真机完整测一遍 PG 18.4-bookworm 镜像，把整套实操、踩坑点一次性说透。

之前用 Docker Hub 拉 PG 镜像，老毛病一堆：⏱️ 高峰几百 KB/s、下到 90% 直接断连，机房无外网代理时干脆完全拉不动。现在 IvorySQL 社区 registry.highgo 仓库同步了官方原生 PG 镜像，不用切换第三方加速源，一套仓库同时跑 IvorySQL、原生 PG，做迁移对比、兼容性测试特别省事。

全文没有套话，全部是真机复制可执行命令，把版本标签坑、磁盘爆满、宿主机无客户端、命令粘贴报错这些运维高频问题全部拆解，新手照着操作也能一次性部署成功。

🔥 写在前面：本文所有命令均基于 openEuler 真机实测，截图均为实际操作记录，非模拟演示。

一、前置环境说明​

本次实测机器配置：

[root@openeuler-server ~]# docker --version
Docker version 20.10.24, build 297e128
[root@openeuler-server ~]# docker-compose --version
Docker Compose version v2.20.0
[root@openeuler-server ~]#

1.1 🚨 先划重点：镜像标签致命大坑​

很多人会直接执行下面这条命令，百分百报错：

# ❌ 错误写法，纯数字tag仓库不存在,而且路径也是错的少了postgres/postgres
docker pull registry.highgo.com/postgres:18.4

1.1.1 报错现场​

[root@openeuler-server ~]# docker pull registry.highgo.com/postgres:18.4
Error response from daemon: unknown: bad request: invalid repository name: postgres
[root@openeuler-server ~]# 

1.1.2 原因 & 正确指令​

📌 根因：仓库内 PG 镜像必须携带系统发行后缀 -bookworm / -trixie，不能只写数字版本。

📌 正确：仓库内 PG 镜像的完整路径是 postgres/postgres，不是 postgres；且标签必须带 -bookworm 发行版后缀

✅ 正确拉取命令：

[root@openeuler-server ~]# docker pull registry.highgo.com/postgres/postgres:18.4-bookworm
18.4-bookworm: Pulling from postgres/postgres
dc4bf025fa70: Pull complete 
07800c4658aa: Pull complete 
d3b29a572ab1: Pull complete 
9c32480c36e2: Pull complete 
ab0222f6080d: Pull complete 
26068876c106: Pull complete 
204ea99b8184: Pull complete 
b9b7e4c43bc2: Pull complete 
d626a1ee2499: Pull complete 
df093a451bde: Pull complete 
4551c7621254: Pull complete 
b7cc028a2062: Pull complete 
4ea1c3550cc2: Pull complete 
Digest: sha256:d323ae4f611b8c41e2488693785b770d2797c10e859b259e4e7706246debb069
Status: Downloaded newer image for registry.highgo.com/postgres/postgres:18.4-bookworm
registry.highgo.com/postgres/postgres:18.4-bookworm
[root@openeuler-server ~]#

二、⚡ 极速拉取：从20分钟到30秒​

2.1 执行拉取​

[root@openeuler-server ~]# docker pull registry.highgo.com/postgres/postgres:18.4-bookworm
18.4-bookworm: Pulling from postgres/postgres
67cf8384fcca: Pull complete
047252d203fc: Pull complete
285c515ff12e: Pull complete
c04bac481cf: Pull complete
4d2f8983bdeb: Pull complete
928cbc530e9b: Pull complete
b7d7c0b1553c: Pull complete
ef11daf91965: Pull complete
5dab6177213d: Pull complete
b73f5647695f: Pull complete
9c1186127d05: Pull complete
c73bb36f2399: Pull complete
142af709c9ab: Pull complete
Digest: sha256:1fa4bccc8246ee2ba9592895d804dcf767119e632999ef22d2b3355a93b627c3
Status: Downloaded newer image for registry.highgo.com/postgres/postgres:18.4-bookworm
registry.highgo.com/postgres/postgres:18.4-bookworm

💡 实测效果：从敲下回车到下载完毕，大概只用了30秒左右。之前在 Docker Hub 上龟速爬行的日子一去不复返，下载速度直接飙到几十 MB/s。这效率，简直是质的飞跃。

2.2 镜像完整性校验​

拉完核对镜像 ID、文件大小，确认无损坏分层：

[root@openeuler-server ~]# docker images | grep postgres
registry.highgo.com/postgres/postgres               18.4-bookworm   dda003c01642   2 weeks ago    440MB
registry.highgo.com/postgres/postgres               18.3-bookworm   3c67953c3a90   7 weeks ago    440MB
[root@openeuler-server ~]#

三、🚀 启动容器：连环踩坑实录​

镜像拉下来了，接下来就是启动。这里我要特别提醒一句：PostgreSQL 的 Docker 镜像和 MySQL / IvorySQL 有点不一样，它默认不会暴露 1521 端口，而且对环境变量的要求比较"倔强"。

3.1 坑①：Shell 历史扩展 !! 引发的"鬼畜"报错​

我第一次启动时，习惯性地用了之前 IvorySQL 的命令风格，结果悲剧了：

[root@openeuler-server ~]# docker run --name pg184 -p 5432:5432 -e POSTGRES_PASSWORD=StrongPass456!! -v pgdata:/var/lib/postgresql/data -d registry.highgo.com/postgres/postgres:18.4-bookworm
Unable to find image 'run:latest' locally
docker: Error response from daemon: Get "https://registry-1.docker.io/v2/": dial tcp 202.160.130.66:443: connect: connection timed out.
See 'docker run --help'.
[root@openeuler-server ~]#

🔍 根因分析：你注意看密码：StrongPass456!!。在 Bash 等 Shell 中，!! 是一个特殊指令，意思是"重复执行上一条命令"。Shell 在执行前会把 !! 替换成上一条完整命令，结果就"展开"成了一条包含自身的超长命令，自然报错。

✅ 解决方案：用单引号或双引号把密码包起来：

[root@openeuler-server ~]# docker run --name pg184 -p 5432:5432 -e POSTGRES_PASSWORD='StrongPass456!!' -v pgdata:/var/lib/postgresql/data -d registry.highgo.com/postgres/postgres:18.4-bookworm
5867e8daa44e925e7818598013a1da62ad7dbdd685e6aa0fae68a94d590edbce
docker: Error response from daemon: driver failed programming external connectivity on endpoint pg184 (7e11a12a731fb44d5aea01d0363b015deadb223d87df0569a40c46a0698da70e): Bind for 0.0.0.0:5432 failed: port is already allocated.
[root@openeuler-server ~]#

3.2 坑②：端口 5432 已被 IvorySQL 占用​

报错信息：Bind for 0.0.0.0:5432 failed: port is already allocated。

看一眼 docker ps -a 的结果，真相大白：

[root@openeuler-server ~]# docker ps -a
CONTAINER ID   IMAGE                                                      COMMAND                  CREATED          STATUS                   PORTS                                                                                            NAMES
5867e8daa44e   registry.highgo.com/postgres/postgres:18.4-bookworm        "docker-entrypoint.s…"   31 seconds ago   Created                                                                                                                   pg184
90f5945502a0   registry.highgo.com/ivorysql/ivorysql:5.3-ubi8             "docker-entrypoint.s…"   9 days ago       Up 9 days                0.0.0.0:1521->1521/tcp, :::1521->1521/tcp, 0.0.0.0:5432->5432/tcp, :::5432->5432/tcp, 5866/tcp   ivorysql

那个叫 ivorysql 的容器已经占了 5432。一台服务器上，一个端口同一时间只能服务一个程序。

✅ 解决方案：换个端口映射。把宿主机的 5433 映射到容器的 5432：

[root@openeuler-server ~]# docker stop pg184
pg184
[root@openeuler-server ~]# docker rm pg184
pg184
[root@openeuler-server ~]# docker run --name pg184 -p 5433:5432 -e POSTGRES_PASSWORD='StrongPass456!!' -v pgdata:/var/lib/postgresql/data -d registry.highgo.com/postgres/postgres:18.4-bookworm
aa42ab39ec930934befb825efa15e7b646af0cd3b84560c3ff5aba73818af60b
[root@openeuler-server ~]#

3.3 坑③：PostgreSQL 18+ 数据路径 Breaking Change​

端口解决了，但容器还是没起来：

[root@openeuler-server ~]# docker ps | grep pg18
[root@openeuler-server ~]#

查看日志：

[root@openeuler-server ~]# docker logs pg184
Error: in 18+, these Docker images are configured to store database data in a
       format which is compatible with "pg_ctlcluster" (specifically, using
       major-version-specific directory names).

       Counter to that, there appears to be PostgreSQL data in:
         /var/lib/postgresql/data (unused mount/volume)

       The suggested container configuration for 18+ is to place a single mount
       at /var/lib/postgresql which will then place PostgreSQL data in a
       subdirectory...

🔍 根因分析：从 PostgreSQL 18 开始，官方 Docker 镜像**不再把数据存在 **/var/lib/postgresql/data，而是放在带版本号的新路径 /var/lib/postgresql/18/docker。你的挂载点 /var/lib/postgresql/data 是旧路径，PG 18 启动时发现路径对不上，直接报错退出。

✅ 解决方案：把挂载点从 /var/lib/postgresql/data 改为 /var/lib/postgresql：

[root@openeuler-server ~]# docker stop pg184
pg184
[root@openeuler-server ~]# docker rm pg184
pg184
[root@openeuler-server ~]# docker run --name pg184 -p 5433:5432 -e POSTGRES_PASSWORD='StrongPass456!!' -v pgdata:/var/lib/postgresql -d registry.highgo.com/postgres/postgres:18.4-bookworm
0ea9e62cd3d0f19a6a791914f2b946ca417ba7247556a4b8f56b3c851118e2ba
[root@openeuler-server ~]#

3.4 ✅ 终于启动成功​

[root@openeuler-server ~]# docker ps | grep pg18
0ea9e62cd3d0   registry.highgo.com/postgres/postgres:18.4-bookworm   "docker-entrypoint.s…"   2 minutes ago   Up 2 minutes   0.0.0.0:5433->5432/tcp, :::5433->5432/tcp                                                        pg184
[root@openeuler-server ~]#

查看日志确认就绪：

[root@openeuler-server ~]# docker logs pg184 | tail -10
2026-06-27 09:56:43.153 UTC [1] LOG:  starting PostgreSQL 18.4 (Debian 18.4-1.pgdg12+1) on x86_64-pc-linux-gnu
2026-06-27 09:56:43.153 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
2026-06-27 09:56:43.153 UTC [1] LOG:  listening on IPv6 address "::", port 5432
2026-06-27 09:56:43.155 UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
2026-06-27 09:56:43.161 UTC [73] LOG:  database system was shut down at 2026-06-27 09:56:43 UTC
2026-06-27 09:56:43.170 UTC [1] LOG:  database system is ready to accept connections

🎉 看到 ready to accept connections，成了！

四、📦 生产环境 Docker Compose 编排​

单机 run 命令适合临时测试，长期测试、准生产环境统一使用 Compose 管理，配置集中、扩容迁移更便捷。

4.1 新建编排工作目录​

[root@openeuler-server ~]# mkdir -p /data/pg-compose
[root@openeuler-server ~]# cd /data/pg-compose
[root@openeuler-server pg-compose]#

4.2 docker-compose.yml 完整配置（适配 PG18.4）​

[root@openeuler-server pg-compose]# vim docker-compose.yml

version: '3.8'
services:
  pg18:
    image: registry.highgo.com/postgres/postgres:18.4-bookworm
    container_name: pg18
    restart: always
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: PGtest@2026
      POSTGRES_DB: testdb
    # ⚠️ PG18+挂载根目录 /var/lib/postgresql，非 /data 子目录
    volumes:
      - ./pgdata:/var/lib/postgresql
    networks:
      pg_net:
networks:
  pg_net:
    driver: bridge

4.3 ⚠️ 启动报错又一个端口冲突​

[root@openeuler-server pg-compose]# docker-compose up -d
Error response from daemon: Bind for 0.0.0.0:5432 failed: port is already allocated
[root@openeuler-server pg-compose]#

🔍 根因：Compose 模板里写的是 "5432:5432"，直接和 IvorySQL 的 5432 端口冲突。调整为 "5435:5432" 即可。

4.4 修改 docker-compose.yml 完整配置（适配 PG18.4）​

[root@openeuler-server pg-compose]# vim docker-compose.yml

version: '3.8'
services:
  pg18:
    image: registry.highgo.com/postgres/postgres:18.4-bookworm
    container_name: pg18
    restart: always
    ports:
      - "5435:5432"          # 宿主机5435，避开5432/5433占用
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: PGtest@2026
      POSTGRES_DB: testdb
    # ⚠️ PG18+挂载根目录 /var/lib/postgresql，非 /data 子目录
    volumes:
      - ./pgdata:/var/lib/postgresql
    networks:
      pg_net:
networks:
  pg_net:
    driver: bridge

4.5 修正后重新启动​

[root@openeuler-server pg-compose]# docker-compose down
[+] Running 2/2
 ✔ Container pg18             Removed                                                0.0s 
 ✔ Network pg-compose_pg_net  Removed                                                0.2s 
[root@openeuler-server pg-compose]# vim docker-compose.yml   # 端口改为5435
[root@openeuler-server pg-compose]# docker-compose up -d
[+] Running 2/2
 ✔ Network pg-compose_pg_net  Created                                                0.2s 
 ✔ Container pg18             Started                                                0.4s 
[root@openeuler-server pg-compose]#

查看日志确认成功：

[root@openeuler-server pg-compose]# docker logs pg18 | grep "ready to accept"
2026-06-27 10:31:46.188 UTC [1] LOG:  database system is ready to accept connections

4.6 验证容器运行状态​

[root@openeuler-server pg-compose]# docker ps | grep pg18
1d53e4097a3d   registry.highgo.com/postgres/postgres:18.4-bookworm   "docker-entrypoint.s…"   30 seconds ago   Up 29 seconds   0.0.0.0:5435->5432/tcp, :::5435->5432/tcp                                                        pg18
0ea9e62cd3d0   registry.highgo.com/postgres/postgres:18.4-bookworm   "docker-entrypoint.s…"   35 minutes ago   Up 35 minutes   0.0.0.0:5433->5432/tcp, :::5433->5432/tcp                                                        pg184
[root@openeuler-server pg-compose]#

五、🔍 PostgreSQL 18.4 基础 CRUD 实操验证​

容器日志输出 database system is ready to accept connections 代表数据库完全初始化完毕，直接进入容器完成版本校验与增删改查全流程验证。

5.1 进入数据库终端 & 版本校验​

[root@openeuler-server pg-compose]# docker exec -it pg18 psql -U postgres
psql (18.4 (Debian 18.4-1.pgdg12+1))
Type "help" for help.

postgres=# select version();
                                                                 version                                                              
------------------------------------------------------------------------------------------------------------------------------------
 PostgreSQL 18.4 (Debian 18.4-1.pgdg12+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 12.2.0-14+deb12u1) 12.2.0, 64-bit
(1 row)

5.2 完整 CRUD 示例​

-- 1. 创建测试业务表
CREATE TABLE test_user (
    id BIGSERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL,
    age INT,
    create_time TIMESTAMP DEFAULT now()
);

postgres=# CREATE TABLE test_user (
    id BIGSERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL,
    age INT,
    create_time TIMESTAMP DEFAULT now()
);
CREATE TABLE
postgres=#

-- 2. 新增多条测试数据
INSERT INTO test_user (username,age) VALUES 
('zhangsan',24),
('lisi',28),
('wangwu',32);

postgres=# INSERT INTO test_user (username,age) VALUES 
('zhangsan',24),
('lisi',28),
('wangwu',32);
INSERT 0 3
postgres=#

-- 3. 全表查询
SELECT * FROM test_user;

postgres=# SELECT * FROM test_user;
 id | username | age |        create_time         
----+----------+-----+----------------------------
  1 | zhangsan |  24 | 2026-06-27 12:29:53.710586
  2 | lisi     |  28 | 2026-06-27 12:29:53.710586
  3 | wangwu   |  32 | 2026-06-27 12:29:53.710586
(3 rows)

-- 4. 条件更新数据
UPDATE test_user SET age=29 WHERE username='lisi';

postgres=# UPDATE test_user SET age=29 WHERE username='lisi';
UPDATE 1
postgres=#

-- 5. 确认更新结果
SELECT * FROM test_user;

postgres=# SELECT * FROM test_user;
 id | username | age |        create_time         
----+----------+-----+----------------------------
  1 | zhangsan |  24 | 2026-06-27 12:29:53.710586
  3 | wangwu   |  32 | 2026-06-27 12:29:53.710586
  2 | lisi     |  29 | 2026-06-27 12:29:53.710586
(3 rows)

-- 6. 删除指定行数据
DELETE FROM test_user WHERE username='wangwu';

postgres=# DELETE FROM test_user WHERE username='wangwu';
DELETE 1
postgres=#

-- 7. 最终结果验证
SELECT * FROM test_user;

postgres=# SELECT * FROM test_user;
 id | username | age |        create_time         
----+----------+-----+----------------------------
  1 | zhangsan |  24 | 2026-06-27 12:29:53.710586
  2 | lisi     |  29 | 2026-06-27 12:29:53.710586
(2 rows)

postgres=# \q
[root@openeuler-server pg-compose]#

六、📊 连接端口区分说明​

# Compose 容器内免密登录（不受宿主机端口影响）
[root@openeuler-server pg-compose]# docker exec -it pg18 psql -U postgres
psql (18.4 (Debian 18.4-1.pgdg12+1))
Type "help" for help.

postgres=#

七、🧾 实测高频踩坑汇总（翻车记录）​

坑 1：简写 Tag 直接拉取，提示镜像不存在​

• 现象：postgres:18.4 拉取失败
• 解决：仓库内 PG 镜像的完整路径是 postgres/postgres，不是 postgres；且标签必须带 -bookworm 发行版后缀

坑 2：Shell 历史扩展 !! 导致命令错乱​

• 现象：密码带 !! 后命令被"展开"，报 Unable to find image 'run:latest'
• 解决：密码用单引号包起来，或用不带 ! 的密码

坑 3：端口 5432 被 IvorySQL 占用​

• 现象：Bind for 0.0.0.0:5432 failed: port is already allocated
• 解决：换端口映射，如 5433:5432 或 5435:5432

坑 4：PG18+ 挂载路径变更​

• 现象：容器启动失败，日志提示 unused mount/volume
• 解决：挂载 /var/lib/postgresql，不是 /var/lib/postgresql/data

坑 5：宿主机无 psql 客户端​

• 现象：-bash: psql: 未找到命令
• 解决：统一用 docker exec -it pg18 psql -U postgres 进入容器

八、💭 实测体验客观点评​

很多人觉得国内镜像只是单纯提速工具，其实对 PG 迁移场景价值更大：

✅ 优势：

1. 一套仓库同时拥有 IvorySQL + 原生 PG 镜像，做 Oracle 语法兼容对比、数据库迁移评估不用切换镜像源，环境搭建效率翻倍；
2. PG 18.4 同步最新社区内核修复，同步速度和海外 Docker Hub 差距极小，中小企业不用搭建私有镜像仓库；
3. 镜像完全官方原生无二次修改，信创、政企测试环境合规，规避第三方镜像篡改风险。

总结​

这次完整实测 registry.highgo 仓库 PostgreSQL 18.4-bookworm 镜像，整套流程从拉取、单机部署、生产 Compose 编排到排坑全部落地。

核心优势总结： 国内节点高速拉取、原生官方镜像安全合规、搭配 IvorySQL 一站式完成迁移对比测试。

实操重点提醒： 拉取镜像务必携带 -bookworm 后缀，必须挂载宿主机数据目录防止磁盘爆满，复制命令优先单行避免参数错乱。

📋 作者注​

本文所有操作及测试均基于 openEuler 操作系统环境完成，核心围绕 IvorySQL 社区镜像仓库 registry.highgo.com 内 PostgreSQL 18.4-bookworm 兼容性验证展开。

请注意 IvorySQL 社区 PostgreSQL 镜像迭代较快，文中配置参数、命令行输出可能随新版本更新调整。生产部署前，请以 IvorySQL 官方文档、registry.highgo 仓库最新 Tag 清单为准。

以上仅为个人实践总结，不代表社区官方观点，文中命令、密码仅作演示，线上环境请自定义高强度密码。

👤 作者简介​

作者： ShunWah
公众号： "shunwah星辰数智社"主理人。

持有认证： OceanBase、MySQL、OpenGauss、崖山、金仓KingBase、KaiwuDB、亚信AntDBCA、翰高、GBase、Galaxybase、Neo4j、NebulaGraph、东方通TongTech、TiDB 等多项权威认证。

获奖经历： 崖山YashanDB YVP、浪潮KaiwuDB MVP、墨天轮 MVP、金仓社区KVA、TiDB社区MVA、NebulaGraph社区之星、IFClub星珩联盟·智库星系技术专家、ITPUB 技术专家、GBase 8a开发者联盟成员 社区版主及布道师。在OceanBase&墨天轮征文大赛、OpenGauss、TiDB、YashanDB、Kingbase、KWDB、Navicat 征文等赛事中多次斩获一、二、三等奖，原创技术文章常年被墨天轮、CSDN、ITPUB 等平台首页推荐。

本文基于 HOW 2026 Oreo Yang 的演讲内容整理。 视频回放：https://www.bilibili.com/video/BV1CFLB6DEHV/

一、项目背景​

1.1 什么是 IvorySQL​

IvorySQL 是一个基于 PostgreSQL 并兼容 Oracle 的开源关系型数据库项目，致力于提供灵活、高性能的数据管理解决方案。其核心特性包括：

• Oracle 兼容：支持 Oracle 数据类型、PL/SQL 语法、内置函数及 Package 包，显著降低从 Oracle 迁移或混合部署的技术门槛与成本。
• 社区生态：拥有活跃的开源社区，通过社区协作持续推动产品迭代与技术创新。
• 部署灵活性：支持传统部署、容器化、云服务、在线体验、沙盒环境等多种部署方式。

1.2 项目背景与目标​

数据库运维面临多重挑战：指标分散、诊断困难、人力成本高、文档查找繁琐。IvorySQL Agent 的核心理念是利用大模型技术实现智能对话与自动化分析，构建一站式监控、诊断、运维辅助平台。项目要解决的六大核心问题包括：智能文档检索、数据库运维、性能调优、SQL 编写效率提升、企业知识管理，最终通过 AI 技术实现从"被动检索"到"主动服务"的转型。

1.3 什么是 Agent​

Agent = 大模型 + 工具 + 推理。智能体将语言模型与工具能力结合，能够对任务进行推理、决定使用哪些工具，并通过迭代寻求解决方案。

IvorySQL Agent 的技术选型：

• 模型层：支持 OpenAI GPT 系列、Anthropic Claude 系列、智谱 AI 等多模型后端
• 工具层：21 个数据库工具，覆盖 7 大领域专家
• 框架层：基于 LangGraph 工作流编排，实现 ReAct 循环迭代
• 知识层：矩阵式知识库，覆盖多版本、多模式

二、系统架构​

2.1 整体架构​

系统采用四层架构设计：

2.2 核心数据流​

监控采集流：通过 Collector 设计，覆盖 50+ 监控指标（连接、缓存、锁、事务、查询、表膨胀等）。针对 IvorySQL 的 Oracle 兼容模式，动态注册自定义类型编解码器。采集数据以 JSONB 格式存储于 PostgreSQL，后台采用 APScheduler 每 30 秒执行一次采集任务，并通过 Delta 增量计算减少开销。

智能对话流：用户输入经路由分发至对应 Agent，构建上下文后调用工具链执行推理，最终生成回答并返回用户。

2.3 异常检测：规则引擎 + LLM 协同​

异常检测采用规则引擎与 LLM 协同工作的双轨机制：

• 规则引擎：预定义阈值规则，命中后自动触发 LLM 分析
• LLM 分析：支持 Claude/OpenAI/智谱 AI 等多模型，对异常进行智能解读
• 向量化存储：512 维本地向量（支持 256~2048 维自定义），配合 pgvector 索引加速检索
• 历史学习：通过相似案例检索复用诊断经验

三、关键技术实现​

3.1 两阶段智能路由​

• Phase 1（确定性路由）：基于关键词与正则表达式匹配，响应时间约 0ms，覆盖约 70% 的场景
• Phase 2（LLM 分类）：规则匹配失败时调用大模型进行意图识别，响应时间约 300ms
• Post-Confirm：短路复用机制，0ms 完成缓存命中

关键设计决策：关键词互斥防止跨域冲突、中英双语正则、渐进降级（关键词 → LLM → general 三层兜底）、模式感知根据 compat_mode 动态裁剪工具表、LLM 容错（指数退避重试 ×2，超时降级 general）、域隔离防污染。

3.2 本地向量检索（零外部依赖）​

采用 BAAI/bge-small-zh-v1.5 嵌入模型，512 维，完全离线运行。pgvector 扩展 + IVFFlat 索引加速。知识库来源包括 IvorySQL 官方文档、PostgreSQL 官方文档和历史分析结果。RAG 检索采用"加权向量搜索 + BM25 重排 + MMR 多样化"组合方案。切片管理按文档章节划分，包含版本和模式标记防止跨版本知识污染。

3.3 上下文管理与智能压缩​

• Schema 缓存：1 小时 TTL，DDL 后自动失效
• 包定义缓存：IvorySQL Oracle 模式包信息
• 实时指标：动态加载当前会话、锁、慢查询
• 历史异常：RAG 检索相关案例，top-K=5

智能压缩机制应对 15+ 轮长对话：DDL 判断 → 选择性保留（DDL + 最近 6 轮）→ Token 检查 → LLM 摘要生成 → 注入优化上下文。

3.4 工具系统与安全控制​

21 个内置工具，分领域管理。SQL 验证四层防护：Prompt 预过滤（拦截 80% 无效 SQL）→ 语法缓存校验 → 预确认验证 → 错误反馈重试（最多 3 次）。安全认证采用 API Token + SHA256 + 配置热重载。审计系统记录操作日志与错误追踪。IvorySQL Oracle/PG 模式工具差异化。

3.5 Chat 流程：规划 · 生成 · 验证 · 流式输出​

Plan 规划由 LLM 生成 JSON 格式步骤计划。SSE 流式输出实时推送 token、tool_start、tool_end 事件。状态往返保证多步计划跨轮次连贯性，无需重建上下文。

3.6 部署架构​

Docker 容器化设计：服务拆分（存储 PostgreSQL + Agent 服务 + Grafana 可视化 + knowledge 批量导入）、settings.json 运行时配置热更新、多目标支持监控多个实例、环境隔离、docker-compose 一键启动。

四、技术特色​

• 纯离线本地运行，无需外部 API
• 多 RAG 领域扩展（当前 7 个 Agent，可继续扩展）
• 智能上下文缓存与压缩机制
• 多层次安全校验与审计日志
• 模块化可扩展设计，支持自定义工具与知识库

五、应用场景​

六、未来规划​

6.1 短期规划​

• 完善智能 Agent 框架，支持多 Model 后端与流式输出
• 实现 IvorySQL 与 PostgreSQL 双模式兼容
• 多模态输入支持：文件分析、截图识别、语音输入
• 知识库管理：在线新增、编辑、删除知识条目与切片

6.2 长期规划​

功能扩展：多模式多版本支持、自动化修复、多实例管理、安全与访问控制、告警通知集成、自学习能力、更多领域 Agent。

愿景：原生集成 pgvector 成为 Agent 首选向量存储、多语言 SDK 开箱即用、Agent 开发套件、一键 Docker Compose 部署完整环境。核心能力：3 行代码实现 RAG 应用，无需配置外部向量服务。

七、总结​

IvorySQL Agent 是 IvorySQL 社区在 AI 赋能数据库管理领域的一次系统性探索。项目基于 ReAct 框架与 LangGraph 工作流编排，构建了覆盖路由、检索、上下文管理、工具调用和安全审计的完整技术体系，实现了从自然语言到数据库运维动作的端到端自动化。未来，项目将持续向多模态交互、自动化修复、SDK 生态等方向演进，降低数据库的使用门槛，提升运维效率，让 IvorySQL 不仅是优秀的数据库，更成为智能数据管理的基础设施。

一个老系统里，Oracle 通常不只是存表。大量业务逻辑写在存储过程、函数、触发器和 Package 里；SQL 里到处是 ROWNUM、SYSDATE、DUAL、NUMBER、VARCHAR2；应用和报表工具会查 ALL_TAB_COLUMNS、DBA_PROCEDURES 这类数据字典；还有空字符串等于 NULL、隐式类型转换、大小写规则、NLS 参数这些平时不显眼但十分影响结果的细节。

这就是企业从 Oracle 迁到 PG 时最痛苦的地方：如果完全按 PostgreSQL 语法进行改造，应用改造量会很大，测试周期会被拉长，业务风险也难控制；如果只在外层做 SQL 改写，又很难覆盖存储过程、包、数据字典。

IvorySQL 的出现完美解决了这个问题，它是 PG 生态中高度兼容 Oracle 的内核，并且紧跟社区最新版本，最重要的是，它开源免费。

一、IvorySQL 是什么​

IvorySQL 是基于 PostgreSQL 的开源数据库项目，目标是在保留 PG 内核能力和生态兼容性的基础上，提供更深入的 Oracle 兼容能力。它不是重新写一个数据库，也不是在应用层做 SQL 字符串替换，而是在 PostgreSQL 内核、扩展和系统对象层面补齐 Oracle 应用迁移时经常依赖的行为。

从项目结构看，IvorySQL 的兼容范围不只在 SQL 语法。它包括 Oracle 模式入口、独立 Oracle parser、Oracle 数据类型、隐式转换、PL/iSQL、Package、内置函数、内置包、系统视图、ROWNUM、ROWID、FORCE VIEW、MERGE 语义、序列行为，以及 NLS、空字符串、标识符大小写等会话级差异。

这也是它和普通兼容层最大的区别。IvorySQL 更关注"你的应用能不能按原来的业务代码运行"。企业迁移 Oracle 时，表数据迁移通常不是最难的那部分，难的是数据库里那些多年积累的存储过程、包、隐式转换和数据字典依赖。IvorySQL 正是把这些问题统统归纳到数据库内核中进行处理，让业务层尽量少动刀子。

二、从源码看 IvorySQL 是怎么兼容 Oracle 的​

IvorySQL 的兼容入口，首先在模式隔离上。

src/include/utils/ora_compatible.h 定义了数据库类型和 parser 类型。数据库模式有 DB_PG 和 DB_ORACLE，解析模式有 PG_PARSER 和 ORA_PARSER。Oracle 模式下还定义了专门的搜索路径：

#define ORA_SEARCH_PATH "sys,\"$user\", public"

sys 放在前面，是为了让 Oracle 兼容对象优先被找到。比如 NUMBER、SYSDATE、DBMS_OUTPUT、ALL_TAB_COLUMNS 这些对象，在迁移应用里往往会直接出现。如果搜索路径不对，后面的类型、函数、包和数据字典视图就会变成零散补丁。

模式切换的核心在 src/backend/utils/misc/ivy_guc.c。这里有两个重要变量：

int database_mode = DB_PG;
int compatible_db = PG_PARSER;

ivorysql.database_mode 记录当前数据库按 PG 还是 Oracle 使用，ivorysql.compatible_mode 决定当前会话用 PG parser 还是 Oracle parser。check_compatible_mode() 会阻止不合法切换。比如普通 PG 数据库不能随意打开 Oracle parser；进入 Oracle 模式之前，还要确认 ivorysql_ora 兼容库已经加载，并且能找到 ora_raw_parser。

真正切换 parser 的动作在 assign_compatible_mode()。进入 Oracle 模式时，它把 sql_raw_parser 指向 ora_raw_parser；切回 PG 模式时，再恢复到 standard_raw_parser。同一段逻辑还会切换 MERGE 相关 hook，并调整 search_path。

连接层也配合了这套设计。src/backend/main/main.c 的帮助信息里有两类端口：-p PORT 对应 PostgreSQL 模式，-o PORT 对应 Oracle 模式。postmaster.c 解析 -o 参数，backend_startup.c 根据连接端口设置 connmode，postgres.c 里的 InitIvorysql() 再根据连接模式设置 ivorysql.compatible_mode。同一个内核可以接 PG 客户端，也可以接 Oracle 迁移客户端，但两边从会话入口就已经分开。

第二个核心点是双 parser。src/backend/parser/parser.c 里有这两个指针：

raw_parser_hook_type sql_raw_parser = standard_raw_parser;
raw_parser_hook_type ora_raw_parser = NULL;

raw_parser() 不再固定调用 PostgreSQL parser，而是调用 (*sql_raw_parser)。默认情况下，它指向 standard_raw_parser；进入 Oracle 模式后，指针切到 ora_raw_parser。Oracle parser 的注册在 src/backend/oracle_parser/liboracle_parser.c，模块初始化时 _PG_init() 会把 ora_raw_parser 设置为 oracle_raw_parser。oracle_raw_parser() 使用 Oracle 自己的 scanner、关键字表和 grammar。

这个选择很重要。Oracle SQL 和 PostgreSQL SQL 差别不小，尤其是匿名块、PL/SQL、Package、过程调用、类型声明这些地方。如果把 Oracle 语法全部硬塞进 PG 原来的 grammar，短期可能能快速堆功能，长期维护会非常痛苦。IvorySQL 让两套 parser 在 raw parse 阶段分流，后面再进入 PostgreSQL 的分析、重写、优化和执行框架。它没有重写一个数据库内核，而是把 Oracle 语法接到 PG 内核的后半段继续处理。

语义分析阶段，IvorySQL 开始处理那些不能只靠 parser 解决的问题。ROWNUM 是很典型的例子。Oracle 里的 ROWNUM 不是普通列，也不是 PostgreSQL 的窗口函数。它什么时候赋值，和 scan、qual、排序、limit 的时机有关。写一个 rownum() 函数解决不了这个问题。

IvorySQL 在 src/backend/parser/parse_expr.c 中处理未限定的 rownum。Oracle 模式下，表达式里出现 rownum 会生成 RownumExpr，而不是按普通列名解析。执行阶段则在 src/backend/executor/execExprInterp.c 和 src/include/executor/execScan.h 里配合处理：ExecEvalRownum() 从 executor state 读取 es_rownum，scan 时在合适的位置递增；如果 qual 没通过，还要回退计数。包含 rownum 的投影也要特殊处理，否则值的时机会错。

优化器也做了有限改写。src/backend/optimizer/plan/planner.c 会把一部分简单的 ROWNUM <= N、ROWNUM = 1、ROWNUM < N 转成 LIMIT。但代码没有把所有 rownum 条件都改掉，因为复杂查询里 Oracle ROWNUM 和 PostgreSQL LIMIT 的生效时机并不完全等价。这里的原则很实在：能保证语义一致才优化，不能保证就保留原行为。

类型系统是另一块重头戏。IvorySQL 在 src/include/catalog/pg_type.dat 中加入了多种 Oracle 兼容类型，主要放在 sys 命名空间下，例如 number、binary_float、binary_double、blob、clob、raw、long、long_raw、rowid、urowid、yminterval、dsinterval。这些类型不是只有名字。contrib/ivorysql_ora/src/datatype/datatype--1.0.sql 里还补了输入输出函数、typmod、cast、operator、btree/hash/brin opclass、比较函数和排序支持。

类型兼容必须做到这一层才有意义。一个类型如果不能建表、建索引、参与比较、参与排序、作为函数参数传递，在业务里很快就会露馅。Oracle 应用里大量字段和过程参数依赖 NUMBER、RAW、LOB、日期间隔类型，单纯把名字映射成 PG 类型远远不够。

隐式转换也必须处理。contrib/ivorysql_ora/src/datatype/compatible_oracle_precedence.c 实现了 Oracle 数据类型优先级 hook。src/backend/parser/parse_oper.c 在找不到合适操作符时，会在 Oracle 模式下调用这段逻辑。比如字符串参与数值运算时，Oracle 会按自己的规则尝试转成 NUMBER，而 PostgreSQL 原生规则更严格。IvorySQL 只在 Oracle 模式下介入，让迁移 SQL 更接近 Oracle 行为，同时不改变 PG 模式的类型解析习惯。

再往上，是空字符串、大小写和 NLS 这类看起来小但很容易改坏业务结果的差异。Oracle 把空字符串当成 NULL，PostgreSQL 不这么做。IvorySQL 在 ivy_guc.c 里提供了 ivorysql.enable_emptystring_to_NULL。Oracle 未引用标识符通常转大写，PG 则转小写，所以 IvorySQL 又提供 ivorysql.identifier_case_switch，并在 Oracle parser 和标识符引用逻辑里配合。NLS 参数也在 ivy_guc.c 中，包括日期语言、日期格式、时间戳格式、数值字符和长度语义。

PL/iSQL 和 Package 是 Oracle 兼容里最硬的一块。IvorySQL 在 src/pl/plisql/src 下实现 PL/iSQL。系统语言定义在 src/include/catalog/pg_language.dat，plisql 有自己的 call handler、inline handler 和 validator。

Package 没有被当成普通文本存起来。IvorySQL 新增了 pg_package 和 pg_package_body 两张系统 catalog。pg_package 记录包规格，pg_package_body 记录包体，它们有自己的索引和 syscache。这意味着 Package 被纳入 PostgreSQL 的系统对象体系，可以参与对象查找、权限检查、依赖记录和缓存失效。

src/backend/parser/parse_package.c 负责 package 里的类型、变量和函数查找。代码里会先判断当前是不是 ORA_PARSER，不是 Oracle 模式时，很多 package 查找不会继续跑。缓存处理在 src/backend/utils/cache/packagecache.c，PackageCache 放在 CacheMemoryContext，并通过 syscache callback 在 package 或 package body 变化时失效，同时联动 plan cache。

兼容对象层面，IvorySQL 通过 ivorysql_ora 扩展和 sys schema 提供了大量 Oracle 函数、包和系统视图。contrib/ivorysql_ora/src/builtin_functions/builtin_functions--1.0.sql 里有 sysdate、systimestamp、add_months、last_day、months_between、next_day、to_date、to_timestamp，也包括正则函数和 substrb、instrb 这类按字节处理的字符串函数。contrib/ivorysql_ora/src/builtin_packages 下有 dbms_output、dbms_lock、dbms_utility、utl_file 等内置包。contrib/ivorysql_ora/src/sysview/sysview--1.0.sql 则提供 SYS.DBA_PROCEDURES、SYS.ALL_TAB_COLUMNS 等 Oracle 风格数据字典视图。

还有一些兼容点分布在更具体的位置。FORCE VIEW 在 src/backend/commands/view.c、parse_relation.c、ruleutils.c 中配合处理，支持先创建暂时无法编译通过的视图，等依赖对象出现后再编译。MERGE 通过 contrib/ivorysql_ora/src/ivorysql_ora.c 注册相关 hook，只在 Oracle 模式下接管部分 transform 和执行逻辑。序列差异在 src/backend/commands/sequence.c 中处理。ROWID 和 UROWID 更底层，还涉及 relhasrowid、tuple descriptor 里的 tdhasrowid，以及执行器和 junk filter。

把这些点连起来看，IvorySQL 的兼容路径不是"在外面糊一层 Oracle 方言"。它把 Oracle 应用真正依赖的行为，放进 PostgreSQL 内核里相对合适的位置：语法交给 parser，类型交给 catalog 和类型推导，Package 交给系统目录和缓存，ROWNUM 交给执行器，数据字典交给系统视图，函数和包交给扩展对象。这种做法工作量大，但边界比简单字符串改写可靠得多。

三、兼容 Oracle 为什么不会对性能产生影响​

严格说，任何功能只要被使用，就一定有它自己的执行成本。Oracle 模式下使用 Oracle 类型、Oracle 函数、PL/iSQL、Package、LOB、复杂日期格式解析，这些功能不可能完全没有代价。这里说"不会对性能产生影响"，更准确的意思是：IvorySQL 的 Oracle 兼容设计不会让普通 PG 查询平白多跑一层 Oracle 逻辑，也不会把 Oracle 兼容变成所有会话共享的系统性负担。

第一，parser 在会话开始时已经分流。 普通 PG 会话使用 PG_PARSER，sql_raw_parser 指向 standard_raw_parser；Oracle 会话才会切到 ora_raw_parser。SQL parser 是每条语句都会经过的入口，如果每条 SQL 都先尝试 Oracle 语法，再尝试 PG 语法，成本会非常直接。IvorySQL 没有这么做。它在会话级别确定 parser，PG 语句仍然按 PG parser 解析，Oracle 语句才进入 Oracle parser。

第二，Oracle hook 多数有明确触发条件。 比如类型优先级 hook 不是每次操作符解析都完整跑一遍 Oracle 规则，而是在找不到合适操作符，并且当前处于 Oracle 模式时才介入。Package 查找也类似，parse_package.c 会先判断 parser 类型，不是 ORA_PARSER 就不继续走 Oracle Package 查找。hook 在代码里存在，不等于所有查询都承担完整兼容逻辑。

第三，Oracle 类型和函数进入 PostgreSQL 原生对象体系以后，执行阶段可以复用 PG 的函数调用、表达式求值、排序、索引访问和缓存机制。 NUMBER、LOB、RAW、ROWID 等类型被放进 catalog，配套 operator、cast、opclass 后，优化器和执行器可以按 PG 熟悉的方式处理它们。Oracle 函数自身有成本，但那是使用功能时的成本，不会转嫁给不使用这些对象的普通 PG 查询。

第四，Package 通过缓存避免重复解析。 Package 如果每次调用都重新读 catalog、解析包体、构造执行上下文，性能会很差。IvorySQL 的 PackageCache 放在 CacheMemoryContext，通过 syscache callback 管理失效。package 或 package body 发生 DDL 变化后，相关缓存和 plan cache 会被清理；没有变化时，调用可以复用缓存对象。它比临时拼装式实现更适合长期运行的业务系统。

第五，ROWNUM 优化只在能保证等价时发生。 简单的 ROWNUM <= N、ROWNUM = 1、ROWNUM < N 可以改写成 LIMIT。复杂查询里，如果 Oracle ROWNUM 和 PostgreSQL LIMIT 的生效时机不一致，IvorySQL 就不强行改写。兼容数据库不能为了让某些 SQL 看起来更快，就让复杂场景结果悄悄变错。

第六，sys schema 和扩展对象减少了名字解析干扰。 Oracle 函数、类型、系统视图和内置包主要由 ivorysql_ora 扩展和 sys schema 提供。Oracle 模式下 search_path 优先查 sys，PG 模式下不需要把这些对象放进普通 SQL 的默认查找路径。

第七，PG 和 Oracle 测试目标是分开的。 项目里可以看到 oracle-check、oracle-installcheck、oracle-pg-check 等测试目标。这说明 IvorySQL 不只是验证 Oracle SQL 能不能跑，也在验证 Oracle 兼容改动有没有影响 PG 侧行为。兼容功能越多，越需要持续证明 PG 模式没有被误伤。

所以，IvorySQL 的性能逻辑可以概括成一句话：Oracle 兼容不是摆在所有 SQL 前面的一层解析器，而是通过模式、parser 指针、hook 条件、schema、扩展、catalog 和 cache 被放在特定路径上。PG 模式下，绝大多数 Oracle 逻辑不会进入热路径；Oracle 模式下，额外成本主要来自用户确实使用了 Oracle 语义。这种成本是功能成本，不是架构上的无差别打击。

这也是为什么 IvorySQL 的设计比"统一拦截所有 SQL 再判断方言"的方案更健康。它让 PG 继续像 PG 一样运行，让 Oracle 兼容在需要的时候生效。对于企业数据库来说，这种边界比单点优化更重要。边界清楚，性能才有讨论空间；边界不清楚，再多微优化也容易被全局分支和语义污染抵消。

四、总结：IvorySQL 对 PG 生态的业务贡献​

IvorySQL 对 PG 生态的贡献，在于给 PostgreSQL 生态加上了一条面向 Oracle 存量系统迁移的内核级路径。

企业系统里，Oracle 往往不是一个单纯的数据存储。大量业务逻辑、权限习惯、报表工具、运维脚本、数据字典查询、存储过程和包都围绕 Oracle 建了很多年。IvorySQL 把 parser、类型、Package、PL/iSQL、系统视图、内置函数、会话语义这些迁移难点放到数据库侧处理，本质上是在降低企业拥抱 PG 生态的门槛。

对业务方来说，这意味着迁移项目没必要一开始就大规模重写。存储过程、包、隐式转换、Oracle 数据字典依赖这些历史包袱，可以先由数据库兼容能力承载一部分。应用团队可以把精力放在真正需要改造的业务逻辑上，而不是把大量时间花在低层语法和对象差异上，这无疑让项目的启动和验证变得更加低成本无负担。

对 PG 生态来说，IvorySQL 的意义就更不言而喻。PostgreSQL 原本就有稳定的内核、成熟的优化器、活跃的扩展生态和开放的社区基础，但在 Oracle 存量市场里，兼容深度一直是企业决策时绕不开的问题。IvorySQL 用内核增强的方式补齐了这块短板，让 PG 生态在金融、电信、政企、传统制造这些 Oracle 深度用户的场景里，多了一个更现实的落地选择。

更难得的是，IvorySQL 没有用牺牲 PG 原生体验来换 Oracle 兼容。它通过模式隔离、双 parser、hook 条件、sys schema、扩展对象和缓存机制，把 Oracle 兼容放在该出现的位置。PG 应用可以继续按 PG 的方式运行，Oracle 迁移应用也能获得更接近原系统的语义。这种路线对生态很友好：它扩大了 PostgreSQL 的适用范围，却没有把 PG 本身改成一个不可辨认的混合体。

本文章整理于 HOW 2026 中陶郑（IvorySQL 核心贡献者）演讲内容。 视频回放：https://www.bilibili.com/video/BV1KdLq6sEV3/

一、数据架构的演进历程​

1.1 传统数据架构的局限​

业务数据从产生到被分析使用，中间需要经过多个系统的流转。当前行业主要存在两种架构模式：

• 线性架构：业务数据产生后进入事务数据库，经过 ETL 数据迁徙进入数据湖，再经处理进入数据仓库，最终由 AI 调用数据仓库接口进行分析。这一链路冗长，数据处理环节众多。
• 变形架构：数据同时写入事务数据库和分析型数据库（即数据库与数据仓库并存），但本质上仍是多个数据库系统，AI 查询仍需跨系统访问。

这两类架构共同面临的困境是：数据处理流程复杂导致分钟级甚至小时级的延迟，且多次查询间原始数据可能已经发生变化，造成数据割裂。与此同时，多套系统的运维成本也居高不下。

1.2 架构演进的三代路径​

• 第一代（2000年代——数据仓库）：随着数据量增长，企业开始按业务需求设计数据结构并存入数据仓库。但后期业务扩展时，新增数据分析需求往往面临数据仓库改造的高昂成本。
• 第二代（2010年代——数据湖）：为降低成本，企业开始将全量增量数据保存至廉价的数据湖中，仅在需要时提取至数据仓库。这虽降低了存储成本，却使分析链路更加复杂，维护难度加大。
• 第三代（2020年前后——湖仓一体）：融合数据仓库与数据湖的优势，但本质上仍是两个系统的组合。

1.3 HTAP 原生化：下一代架构​

当前最新趋势是从"湖仓一体"向"HTAP 原生化"演进——让事务数据与分析数据存储在同一数据库中，彻底消除数据迁徙与 ETL 环节。

两代架构的核心差异：

这意味着多个数据库整合为一个，AI 可通过单一 API 调用，无需跨库查询，运维成本显著降低，数据实时性大幅提升。

二、AI 时代传统架构的三大痛点​

• 痛点一：查询模式不可预测——Agent 生成的查询是随机的，传统架构无法同时高效应对点查和聚合分析。
• 痛点二：数据新鲜度敏感——ETL 延迟意味着 Agent 查询时数据可能已变化，在风控、推荐、金融等场景中不可接受。
• 痛点三：跨系统延迟叠加——当单次任务同时涉及点查和聚合分析时，跨系统的延迟相互叠加。

三、HTAP 原生架构：行业动向与 IvorySQL 的定位​

3.1 行业风向标：Databricks 的两笔关键并购​

• 2025年5月——收购 Neon：无服务器 PostgreSQL 服务提供商，意味着 OLAP 巨头主动进入 OLTP 领域。
• 2025年10月——收购 Mooncake Labs：核心项目 pg_mooncake——在 PostgreSQL 内嵌入 DuckDB 列存引擎，使同一份数据同时支持事务查询与分析查询，彻底无需 ETL。IvorySQL 的方案正是基于 pg_mooncake 构建。

3.2 pg_mooncake 留下的两个空白​

• 空白一：开源生态的维护缺口——被收购后更新频率明显放缓，开源社区需要一个独立维护的实现。
• 空白二：Oracle 迁移场景的能力缺口——pg_mooncake 从未考虑过 Oracle 兼容场景，而中国大量企业的核心数据仍运行在 Oracle 上。

3.3 IvorySQL 的定位与填补​

IvorySQL 是一个开源的 PostgreSQL 分支，由社区独立维护，完整兼容 PostgreSQL 生态，同时支持 Oracle 语法、数据类型和函数行为。基于这一基础，IvorySQL 的 HTAP 引擎做到：

• 填补空白一：社区独立维护的 pg_mooncake 持续演进版本，迭代方向不受商业公司绑定
• 填补空白二：全面支持 Oracle 迁移场景的 HTAP 能力
• 实时湖仓接入引擎：同一份数据同时支持事务与分析两条路径，实时可查

四、技术路径与架构原理​

4.1 行存与列存：理解 HTAP 的技术基础​

PostgreSQL 是行存数据库，数据按整行连续存储，适合事务型操作。列存则按列独立排列，查询时可直接提取目标列，无需整行扫描，在大数据量聚合分析场景下性能优势显著。HTAP 的核心思路是：在同一数据库中同时拥有行存与列存两种存储形态，根据查询特征自动选择最优执行路径。

4.2 整体架构​

IvorySQL HTAP 引擎基于 pg_mooncake 构建，核心机制如下：

智能路由：通过 Hooks 方式嵌入 PostgreSQL 内核（不侵入内核代码），Planner 自动识别查询特征，判断走行存（点查/事务）还是列存（聚合/分析）效率更高，自动路由至最优执行路径。

双存储引擎：行存采用 PG Heap 文件（OLTP），列存采用 DuckDB 引擎 + Parquet 列存格式（OLAP）。

内存共享与自动同步：在内存中，同一份数据既可通过 PG 行存访问，也可转化为列存供 DuckDB 查询。持久化层面，数据通过 Parquet 等列存格式保存，行存与列存之间自动实时同步，应用层完全无感知。

4.3 为什么不需要 ETL​

传统方案中，数据库 → ETL → 数仓，延迟达分钟级甚至小时级。HTAP 原生方案中，数据始终只有一份，行存和列存是同一份数据的两种访问路径——ETL 消失了，延迟也消失了。

4.4 写入路径与查询路由​

1. 应用层 SQL：标准 SQL 语句，无需任何改造
2. PostgreSQL 查询层：Parser → Planner → Executor，pg_mooncake 以 Hook 方式嵌入
3. 自动路由：Planner 识别查询特征，自动决定行存或列存
4. 双存储引擎执行：行存走 PG Heap，列存走 DuckDB + Parquet
5. 自动同步：两种存储之间自动同步，数据始终只有一份

五、应用场景​

场景一：Oracle 数仓迁移​

迁移后，Oracle 类型、语法、函数行为全面兼容，HTAP 能力随迁移一并到位，分析链路不需要重建。

场景二：AI Agent 混合查询​

点查走行存，聚合走列存，一个连接搞定所有查询。数据实时一致，Agent 响应速度与决策质量同步提升。

场景三：实时风控​

交易写入的同时，列存即可查询。风控规则实时触发，从分钟级降到秒级以内。

六、开源发布计划​

• 发布时间：计划伴随 IvorySQL 6.0 版本正式发布
• 开源内容：代码完全开源，包含三个核心模块——ivy_mooncake、ivy_duckdb、ivy_moonlink

注：现在已经发布了预览版 1.0 beta1

七、总结​

IvorySQL HTAP 实时湖仓接入引擎，是 IvorySQL 社区在数据库架构演进方向上的重要布局。项目紧跟 Databricks 等行业巨头验证的技术方向，基于 pg_mooncake 构建，同时填补了开源独立维护与 Oracle 迁移场景两大空白。通过行存与列存的融合、智能路由与自动同步机制，实现了事务与分析在同一数据库中的实时统一，为 AI Agent 时代的数据查询、实时风控、Oracle 迁移等场景提供了切实可行的解决方案。随着 6.0 版本的开源发布，IvorySQL 社区将为企业用户提供一套真正开放、可独立演进、兼容 Oracle 生态的 HTAP 基础设施。

作者：杨宇，PG ACE，第八届 PG 数据库生态大会 2025 年度金牌讲师，PG 分会哈尔滨用户组核心成员，负责本公司数据库、云计算等相关运维工作。曾主持对公司 PostgreSQL 数据库进行架构设计、容灾系统搭建及报表优化工作，发表多篇架构、优化相关的原创文章。目前拥有 ORACLE 11G/12C OCM、MYSQL 5.7/8.0 OCP、TIDB PCTP、OBCP V4、电科金仓 KCP 等资质认证。

引言：数据库领域的 "最佳桥梁"​

在当今多元化的数据库技术栈中，企业常常面临一个两难选择：是拥抱开源、生态丰富、性能卓越的 PostgreSQL，还是沿用商业强大、生态成熟但成本高昂的 Oracle 数据库？迁移的复杂性、高昂的许可费用以及对现有应用的兼容性担忧，往往让企业在技术选型和迁移上举步维艰。

IvorySQL 正是在这一背景下应运而生。它并非一个简单的数据库，而是一个旨在架起 PostgreSQL 与 Oracle 之间桥梁的革新性开源项目。它基于 PostgreSQL 开发，在保持与原版数据库 100% 语法兼容的同时，深度兼容 Oracle 语法，为企业提供了一条平滑、低成本的迁移与融合路径。

核心定位：生于 PostgreSQL，优于 Oracle 兼容​

IvorySQL 的核心哲学可以概括为：以 PostgreSQL 为基石，以 Oracle 兼容性为核心。

坚守开源与 PostgreSQL 生态​

IvorySQL 社区明确承诺，始终与 PostgreSQL 数据库保持 100% 兼容，并可直接替换最新版本的 PostgreSQL。这意味着 PostgreSQL 强大的扩展生态系统（如 PostGIS、pgvector、pg_cron 等）在 IvorySQL 中得以完整保留。

强大的 Oracle 兼容性​

这是 IvorySQL 区别于其他基于 PostgreSQL 的分支的核心竞争力。其关键在于 ivorysql.compatible_mode 这个 GUC 参数。通过将其设置为 oracle 或 pg，用户可以在同一套数据库系统内无缝切换 Oracle 兼容模式和原生 PostgreSQL 模式，这在数据库产品中是极为创新的设计。

深度技术解析：如何实现 "无缝兼容"？​

1. GUC 参数驱动的双模式与初始化​

初始化时指定模式​

初始化为纯 PostgreSQL 模式：initdb -D /usr/ivory-5/data -m pg，使用 -m pg 模式后 ivorysql.compatible_mode 参数将失效，系统行为与原生 PostgreSQL 完全一致。

初始化为 Oracle 兼容模式（默认）：initdb -D /usr/ivory-5/data -m oracle

运行时动态切换​

SHOW ivorysql.compatible_mode;
-- 输出: oracle

SET ivorysql.compatible_mode TO pg;
SHOW ivorysql.compatible_mode;
-- 输出: pg

2. PL/iSQL：Oracle PL/SQL 的无缝兼容​

匿名块兼容

DECLARE
    i integer := 10;
    grade CHAR(1) := 'B';
BEGIN
    CASE grade
        WHEN 'A' THEN RAISE NOTICE 'Excellent';
        WHEN 'B' THEN RAISE NOTICE 'Very Good';
    END CASE;
EXCEPTION
    WHEN CASE_NOT_FOUND THEN
        RAISE NOTICE 'No such grade';
END;
/

函数兼容

CREATE OR REPLACE FUNCTION add_numbers(p_a NUMBER, p_b NUMBER) RETURN NUMBER IS
BEGIN
    RETURN p_a + p_b;
END;
/

SELECT add_numbers(10, 20) FROM dual;

包（PACKAGE）兼容

CREATE OR REPLACE PACKAGE my_pkg IS
    var1 INTEGER;
    FUNCTION get_double(p_id INTEGER) RETURN INTEGER;
    PROCEDURE print_message(p_msg VARCHAR2);
END my_pkg;
/

CREATE OR REPLACE PACKAGE BODY my_pkg IS
    FUNCTION get_double(p_id INTEGER) RETURN INTEGER IS
    BEGIN
        RETURN p_id * 2;
    END;
    PROCEDURE print_message(p_msg VARCHAR2) IS
    BEGIN
        DBMS_OUTPUT.PUT_LINE(p_msg);
    END;
BEGIN
    var1 := 100;
END my_pkg;
/

3. 数据类型与函数​

IvorySQL 支持大量 Oracle 独有的数据类型和函数：

CREATE TABLE customers (
    cust_id NUMBER PRIMARY KEY,
    cust_name VARCHAR2(100)  -- 非标准PG类型，IvorySQL兼容
);

常用内置函数：SYSDATE、ADD_MONTHS、NVL、DECODE、INSTRB、SUBSTRB 等。

SELECT SYSDATE FROM dual;
SELECT NVL(NULL, 'Default Value') FROM dual;
SELECT DECODE(1, 1, 'One', 2, 'Two', 'Other') FROM dual;

RowID 伪列：SET ivorysql.default_with_rowids TO on;

4. 其他关键特性​

支持 Sequence 序列、不可见列（INVISIBLE COLUMN）、%TYPE 和 %ROWTYPE 属性、CALL INTO 子句等。通过 identifier_case_switch 参数解决 Oracle 与 PG 标识符大小写差异问题，提供 normal、interchange、lowercase 三种模式。

安装部署：从单机到云原生的全景图​

Yum 一键安装​

sudo tee /etc/yum.repos.d/ivorysql.repo <<EOF
[ivorysql5]
name=IvorySQL Server 5
baseurl=https://yum.highgo.com/dists/ivorysql-rpms/5/redhat/rhel-\$releasever-\$basearch
enabled=1
gpgcheck=0
EOF

sudo dnf install -y ivorysql5-5.3

Docker 部署​

docker pull ivorysql/ivorysql:5.3-ubi8
docker run --name ivorysql -p 5432:5432 -p 1521:1521 \
  -e IVORYSQL_PASSWORD=mysecretpassword -d ivorysql/ivorysql:5.3-ubi8

K8s/Harbor Operator 云原生部署​

apiVersion: ivory-operator.ivorysql.org/v1beta1
kind: IvoryCluster
metadata:
  name: hippo
spec:
  image: ivorysql/ivorysql:5.3-ubi8
  instances:
    - name: instance1
      replicas: 2
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 1Gi

运维生态：让管理更简单，让性能更卓越​

高可用集群基于流复制搭建主备集群。结合 pgMonitor + Grafana 搭建监控大屏。提供常用诊断 SQL：

-- 查看执行计划
EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM large_table WHERE id = 100;

-- 查看当前活跃会话
SELECT pid, state, query, wait_event_type FROM pg_stat_activity WHERE state = 'active';

使用 pg_dump 完成同架构数据迁移。

结论：面向未来的数据基础设施​

IvorySQL 不是一个简单的 PostgreSQL 再发行版，而是一个思考深、设计巧、价值高的开源数据库项目。它成功解决了 Oracle 用户向开源和云原生生态迁移的核心障碍——兼容性。它将 Oracle 的强大与 PostgreSQL 的灵活结合在了一起，为用户在未来的数据结构、混合多模态数据处理上提供了无限的想象空间。

IvorySQL 的出现，标志着数据库领域 "融合" 趋势的进一步发展。它不是去颠覆谁，而是在做一件更有意义的事：让历史与未来，在一个高效、可靠的平台上共存共生。

我有。

去年底想在一台测试机上跑 IvorySQL 5.0，执行 docker pull ivorysql/ivorysql:5.0-ubi8，然后就去泡了杯咖啡。咖啡喝完，进度条走了 30%。又刷了会儿手机，还是 50%。最后干脆去开了个会，回来总算拉完了——前前后后快二十分钟。

你说这算技术问题吗？不算。但这就是劝退很多人的"第一公里"。

所以当我听说 IvorySQL 社区在 registry.highgo.com 上线了国内镜像源，第一反应是：终于来了。

这篇文章我不会跟你念产品文档。咱们就像平时在技术群里闲聊那样，聊聊这个镜像源到底好不好用、怎么用、以及我踩到的那些坑。

一、镜像仓库地址​

先放地址：https://registry.highgo.com/

这个镜像服务面向国内网络环境做了优化，适合开发测试、演示验证、CI 构建以及容器化部署场景。说白了就是——在国内拉镜像，不用再绕道 Docker Hub 了。

二、快速体验 IvorySQL 镜像​

2.1 拉取镜像​

如果你之前看过 IvorySQL 的 Docker 安装文档，操作方式几乎一样，只需要把镜像地址替换成国内的就行。

以 IvorySQL 5.3 的 UBI8 镜像为例：

docker pull registry.highgo.com/ivorysql/ivorysql:5.3-ubi8

我在 openEuler 服务器上实际跑了一下，效果是这样的：

[root@openeuler-server ~]# docker pull registry.highgo.com/ivorysql/ivorysql:5.3-ubi8
5.3-ubi8: Pulling from ivorysql/ivorysql
4fba3effa6b3: Pull complete 
4cc358cba85f: Pull complete 
c4453bb8971d: Pull complete 
d396d38d02c2: Pull complete 
4406b6bc22b7: Pull complete 
52bcb2e0d3b6: Pull complete 
bc3a2a4b7a5d: Pull complete 
addd7eda355c: Pull complete 
c566c56fc71d: Pull complete 
5354ee8271dc: Pull complete 
6adc3134ae3c: Pull complete 
4f4fb700ef54: Pull complete 
Digest: sha256:c877f3d50eb7d5edb96da5d1f939890ba6f9b031b83faee893403b8de0622c82
Status: Downloaded newer image for registry.highgo.com/ivorysql/ivorysql:5.3-ubi8
registry.highgo.com/ivorysql/ivorysql:5.3-ubi8
[root@openeuler-server ~]#

实测效果：我本地用 Docker Hub 拉取同一个镜像，平均速度几百 KB/s，有时候还会断连重试。换成国内镜像源之后，速度直接飙到几十 MB/s。从"泡杯咖啡等它拉完"变成"刚起身水还没倒好就结束了"。

拉完之后校验一下：

docker images | grep ivorysql

我在服务器上执行的结果：

[root@openeuler-server ~]# docker images | grep ivorysql
registry.highgo.com/ivorysql/ivorysql               5.3-ubi8   2af458997451   3 months ago   417MB
[root@openeuler-server ~]#

能看到 IMAGE ID 和 SIZE，说明镜像下载完整、没有损坏。

2.2 启动容器（附带踩坑实录）​

拉取完成后，用下面的命令启动 IvorySQL 容器：

docker run --name ivorysql -p 5432:5432 -p 1521:1521 \
  -e IVORYSQL_PASSWORD=PKsjj@112!! -d \
  registry.highgo.com/ivorysql/ivorysql:5.3-ubi8

⚠️ 第一个坑：命令被"截断"了

我第一次执行的时候，因为多行复制时不小心混入了别的命令，结果报了这个错：

[root@openeuler-server ~]# docker run --name ivorysql -p 5432:5432 -p 1521:1521 \
>   -e IVORYSQL_PASSWORD=PKsjj@112!! -d \
  -e IVORYSQL_PASSWORD=PKsjj@112docker images | grep ivorysql -d \
>   registry.highgo.com/ivorysql/ivorysql:5.3-ubi8
grep: '--directories' 的参数 'registry.highgo.com/ivorysql/ivorysql:5.3-ubi8' 无效
有效参数是:
  - 'read'
  - 'recurse'
  - 'skip'
用法: grep [选项]... 模式 [文件]...
尝试使用 'grep --help' 来获得更多信息。
Unable to find image 'images:latest' locally
^C
[root@openeuler-server ~]#

仔细一看，原来是 -e IVORYSQL_PASSWORD=PKsjj@112docker ps 这一串出了问题——Docker 把 PKsjj@112docker ps 当成了完整的密码值，后面的 -d 被当成了镜像名，然后它跑去 Docker Hub 找了一个叫 ps 的镜像，当然找不到。

解决办法：要么用单行命令，要么用 \ 换行时确保每行末尾没有多余空格。最简单的是直接单行执行：

docker run --name ivorysql -p 5432:5432 -p 1521:1521 -e IVORYSQL_PASSWORD=PKsjj@112!! -d registry.highgo.com/ivorysql/ivorysql:5.3-ubi8

但换了单行之后，又出幺蛾子了：

[root@openeuler-server ~]# docker run --name ivorysql -p 5432:5432 -p 1521:1521 -e IVORYSQL_PASSWORD=PKsjj@112!! -d registry.highgo.com/ivorysql/ivorysql:5.3-ubi8
docker run --name ivorysql -p 5432:5432 -p 1521:1521 -e IVORYSQL_PASSWORD=PKsjj@112docker ps -d registry.highgo.com/ivorysql/ivorysql:5.3-ubi8
Unable to find image 'ps:latest' locally
docker: Error response from daemon: Get "https://registry-1.docker.io/v2/": dial tcp 103.39.76.66:443: connect: connection timed out.
See 'docker run --help'.

问题还是同一个——-e IVORYSQL_PASSWORD=PKsjj@112docker ps 这串命令里，密码和参数之间没有空格，Docker 直接懵了。

最终正确姿势：确保密码和 -d 之间有一个明确的空格分隔。

docker run --name ivorysql -p 5432:5432 -p 1521:1521 -e IVORYSQL_PASSWORD=g4Bw#QPY4^t%87xTy -d registry.highgo.com/ivorysql/ivorysql:5.3-ubi8

这次终于成功了：

[root@openeuler-server ~]# docker run --name ivorysql -p 5432:5432 -p 1521:1521 -e IVORYSQL_PASSWORD=g4Bw#QPY4^t%87xTy -d registry.highgo.com/ivorysql/ivorysql:5.3-ubi8
5856d79e1f85a51945e31e68ae21161d2e6dc2806697fffa9e0485e02df32f48
[root@openeuler-server ~]#

用 docker ps 确认一下容器状态：

[root@openeuler-server ~]# docker ps
CONTAINER ID   IMAGE                                            COMMAND                  CREATED              STATUS              PORTS                                                                                            NAMES
5856d79e1f85   registry.highgo.com/ivorysql/ivorysql:5.3-ubi8   "docker-entrypoint.s…"   About a minute ago   Up About a minute   0.0.0.0:1521->1521/tcp, :::1521->1521/tcp, 0.0.0.0:5432->5432/tcp, :::5432->5432/tcp, 5866/tcp   ivorysql
[root@openeuler-server ~]#

💡 一点小建议：这种因为复制粘贴、不小心多按了几个键导致的"乌龙"报错，在运维里太常见了。以后遇到 Unable to find image 'xxx:latest' locally 这种报错，第一反应先检查命令里是不是多了什么奇怪的字符，往往比排查网络、镜像源要快得多。

2.3 双端口的意义​

这里有两个端口需要留意一下：

• 5432 端口：兼容 PostgreSQL 原生语法
• 1521 端口：对标 Oracle 访问端口，适配 Oracle 语法

为什么要同时暴露两个端口？因为 IvorySQL 的核心定位就是 Oracle 兼容。你在 1521 端口上连接，可以体验到 IvorySQL 针对 Oracle 语法做的兼容适配；在 5432 端口上连接，又像在用标准 PostgreSQL。同一个容器，两套语法，方便你在迁移评估阶段做对比测试。

2.4 连接数据库的波折​

容器启动后，我想通过 1521 端口连接数据库：

psql -d ivorysql -U ivorysql -h 127.0.0.1 -p 1521

结果：

[root@openeuler-server ~]# psql -d ivorysql -U ivorysql -h 127.0.0.1 -p 1521
-bash: psql：未找到命令
[root@openeuler-server ~]#

⚠️ 第二个坑：宿主机没有 psql 客户端

psql 是 PostgreSQL 自带的命令行客户端工具，不会随 Docker 自动安装到宿主机上。在 openEuler 系统里直接敲 psql，系统当然找不到。

解决方法：直接用 docker exec 进入容器内部执行：

docker exec -it ivorysql psql -d ivorysql -U ivorysql

结果又报错了：

[root@openeuler-server ~]# docker exec -it ivorysql psql -d ivorysql -U ivorysql
psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: FATAL:  the database system is not yet accepting connections
DETAIL:  Consistent recovery state has not been yet reached.
[root@openeuler-server ~]#

2.5 排查过程：日志暴露真凶​

容器状态显示 Up 只代表容器进程跑起来了，不代表数据库内核加载完毕。这时候需要看日志：

docker logs ivorysql --tail 50

我看到的日志是这样的：

[root@openeuler-server ~]# docker logs ivorysql --tail 50
2026-06-17 09:06:57.008 UTC [1] LOG:  checkpointer process (PID 4442) was terminated by signal 6: Aborted
2026-06-17 09:06:57.008 UTC [1] LOG:  terminating any other active server processes
2026-06-17 09:06:57.009 UTC [1] LOG:  all server processes terminated; reinitializing
2026-06-17 09:06:57.043 UTC [4447] LOG:  database system shutdown was interrupted; last known up at 2026-06-17 09:06:56 UTC
2026-06-17 09:06:57.067 UTC [4447] LOG:  database system was not properly shut down; automatic recovery in progress
2026-06-17 09:06:57.068 UTC [4447] LOG:  redo starts at 0/1ED9BC0
2026-06-17 09:06:57.068 UTC [4447] LOG:  invalid record length at 0/1ED9BF8: expected at least 24, got 0
2026-06-17 09:06:57.068 UTC [4447] LOG:  redo done at 0/1ED9BC0 system usage: CPU: user: 0.00 s, system: 0.00 s, elapsed: 0.00 s
2026-06-17 09:06:57.071 UTC [4448] LOG:  checkpoint starting: end-of-recovery immediate wait
2026-06-17 09:06:57.071 UTC [4448] PANIC:  could not write to file "pg_logical/replorigin_checkpoint.tmp": No space left on device
...（省略部分重复日志）
2026-06-17 09:06:58.752 UTC [4472] PANIC:  could not write to file "pg_logical/replorigin_checkpoint.tmp": No space left on device
[root@openeuler-server ~]#

⚠️ 第三个坑：磁盘空间满了

关键报错是 No space left on device。数据库启动时需要写临时文件做 checkpoint，但磁盘已经满了。

用 df -Th 确认一下：

[root@openeuler-server ~]# df -Th
文件系统                                     类型      容量  已用  可用 已用% 挂载点
devtmpfs                                     devtmpfs  4.0M     0  4.0M    0% /dev
tmpfs                                        tmpfs      16G  8.0K   16G    1% /dev/shm
tmpfs                                        tmpfs     6.2G  636M  5.6G   11% /run
tmpfs                                        tmpfs     4.0M     0  4.0M    0% /sys/fs/cgroup
/dev/mapper/openeuler_openeuler--server-root ext4       41G   39G     0  100% /
tmpfs                                        tmpfs      16G  4.0K   16G    1% /tmp
/dev/sda2                                    ext4      920M  312M  545M   37% /boot
overlay                                      overlay    41G   39G     0  100% /var/lib/docker/overlay2/cbcb4ac63b0ff3f5953c8cda779af0d2b530eae3aeeebc76ebb09e0c3b36083a/merged
[root@openeuler-server ~]#

根分区 / 可用空间为 0，已用 100%。这就是 IvorySQL 容器反复崩溃的根源。

2.6 解决方案：迁移 Docker 数据目录​

好消息是服务器上还有一块 100G 的空闲磁盘 /dev/sdb1。我把 Docker 的数据目录整个迁过去：

# 停止 Docker 服务
systemctl stop docker

# 把 Docker 数据目录迁移到新盘
mv /var/lib/docker /data/

# 创建软链接指向新位置
ln -s /data/docker /var/lib/docker

# 重启 Docker
systemctl start docker

实际执行记录：

[root@openeuler-server ~]# systemctl stop docker
[root@openeuler-server ~]# mv /var/lib/docker /data/
[root@openeuler-server ~]# ln -s /data/docker /var/lib/docker
[root@openeuler-server ~]# systemctl start docker

迁移完成后，磁盘空间正常了：

[root@openeuler-server ~]# df -Th
文件系统                                     类型      容量  已用  可用 已用% 挂载点
devtmpfs                                     devtmpfs  4.0M     0  4.0M    0% /dev
tmpfs                                        tmpfs      16G  8.0K   16G    1% /dev/shm
tmpfs                                        tmpfs     6.2G  660M  5.6G   11% /run
tmpfs                                        tmpfs     4.0M     0  4.0M    0% /sys/fs/cgroup
/dev/mapper/openeuler_openeuler--server-root ext4       41G   36G  2.9G   93% /
tmpfs                                        tmpfs      16G  4.0K   16G    1% /tmp
/dev/sda2                                    ext4      920M  312M  545M   37% /boot
/dev/sdb1                                    ext4       98G  7.0G   86G    8% /data

2.7 重新部署，终于成功​

删除旧容器，重新启动：

[root@openeuler-server ~]# docker rm -f ivorysql
ivorysql
[root@openeuler-server ~]# docker run --name ivorysql -p 5432:5432 -p 1521:1521 \
>   -e IVORYSQL_PASSWORD=g4Bw#QPY4^t%87xTy -d \
>   registry.highgo.com/ivorysql/ivorysql:5.3-ubi8
90f5945502a072af760a738d2f962c73bcaadd91351fcbe0a5e80a03d14fceb5
[root@openeuler-server ~]#

等几秒后查看日志，这次终于看到 ready to accept connections 了：

[root@openeuler-server ~]# docker logs ivorysql --tail 20
2026-06-17 09:38:35.117 UTC [51] LOG:  shutting down
2026-06-17 09:38:35.118 UTC [51] LOG:  checkpoint starting: shutdown immediate
2026-06-17 09:38:35.125 UTC [51] LOG:  checkpoint complete: wrote 0 buffers (0.0%), wrote 3 SLRU buffers; 0 WAL file(s) added, 0 removed, 0 recycled; write=0.004 s, sync=0.001 s, total=0.009 s; sync files=2, longest=0.001 s, average=0.001 s; distance=0 kB, estimate=0 kB; lsn=0/1ED9B48, redo lsn=0/1ED9B48
2026-06-17 09:38:35.141 UTC [47] LOG:  database system is shut down
 done
server stopped

PostgreSQL init process complete; ready for start up.

2026-06-17 09:38:35.258 UTC [1] LOG:  starting PostgreSQL 18.3 (IvorySQL 5.3) on x86_64-pc-linux-gnu, compiled by gcc (GCC) 8.5.0 20210514 (Red Hat 8.5.0-28), 64-bit
2026-06-17 09:38:35.258 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
2026-06-17 09:38:35.258 UTC [1] LOG:  listening on IPv6 address "::", port 5432
2026-06-17 09:38:35.259 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 1521
2026-06-17 09:38:35.259 UTC [1] LOG:  listening on IPv6 address "::", port 1521
2026-06-17 09:38:35.260 UTC [1] LOG:  listening on Unix socket "/tmp/.s.PGSQL.5432"
2026-06-17 09:38:35.262 UTC [1] LOG:  listening on Unix socket "/tmp/.s.PGSQL.1521"
2026-06-17 09:38:35.270 UTC [67] LOG:  database system was shut down at 2026-06-17 09:38:35 UTC
2026-06-17 09:38:35.276 UTC [1] LOG:  database system is ready to accept connections
2026-06-17 09:43:35.369 UTC [65] LOG:  checkpoint starting: time
2026-06-17 09:43:40.796 UTC [65] LOG:  checkpoint complete: wrote 54 buffers (0.3%), wrote 3 SLRU buffers; 0 WAL file(s) added, 0 removed, 0 recycled; write=5.419 s, sync=0.003 s, total=5.428 s; sync files=11, longest=0.002 s, average=0.001 s; distance=432 kB, estimate=432 kB; lsn=0/1F45EF0, redo lsn=0/1F45E98
[root@openeuler-server ~]#

docker ps 确认容器正常运行：

[root@openeuler-server ~]# docker ps
CONTAINER ID   IMAGE                                            COMMAND                  CREATED          STATUS          PORTS                                                                                            NAMES
90f5945502a0   registry.highgo.com/ivorysql/ivorysql:5.3-ubi8   "docker-entrypoint.s…"   12 minutes ago   Up 12 minutes   0.0.0.0:1521->1521/tcp, :::1521->1521/tcp, 0.0.0.0:5432->5432/tcp, :::5432->5432/tcp, 5866/tcp   ivorysql
[root@openeuler-server ~]#

再次测试连接：

[root@openeuler-server ~]# docker exec -it ivorysql psql -d ivorysql -U ivorysql
psql (18.3)
Type "help" for help.

ivorysql=#

查看版本确认：

ivorysql=# select version();
                                                        version                          
                               
-----------------------------------------------------------------------------------------
-------------------------------
 PostgreSQL 18.3 (IvorySQL 5.3) on x86_64-pc-linux-gnu, compiled by gcc (GCC) 8.5.0 20210
514 (Red Hat 8.5.0-28), 64-bit
(1 row)

ivorysql=#

💡 小提示：如果你用 Navicat 或 DBeaver 等外部工具连接，也需要等初始化完成。刚启动立刻连会报连接失败，建议等待 1-2 分钟再测试。

三、PostgreSQL 镜像也能拉​

除了 IvorySQL，这个镜像仓库里也同步了 PostgreSQL 官方镜像。如果你需要在原生 PG 和 IvorySQL 之间做对比测试或者迁移评估，可以统一从这里拉：

docker pull registry.highgo.com/postgres/postgres:18.3-bookworm
docker pull registry.highgo.com/postgres/postgres:18.3-trixie

我在服务器上实测拉取 18.3-bookworm：

[root@openeuler-server ~]# docker pull registry.highgo.com/postgres/postgres:18.3-bookworm
18.3-bookworm: Pulling from postgres/postgres
67cf8384fcca: Pull complete 
047252d203fc: Pull complete 
285c515ff12e: Pull complete 
c04bac481cf9: Pull complete 
4d2f8983bdeb: Pull complete 
928cbc530e9b: Pull complete 
b7d7c0b1553c: Pull complete 
ef11daf91965: Pull complete 
5dab6177213d: Pull complete 
b73f5647695f: Pull complete 
9c1186127d05: Pull complete 
c73bb36f2399: Pull complete 
142af709c9ab: Pull complete 
Digest: sha256:1fa4bccc8246ee2ba9592895d804dcf767119e632999ef22d2b3355a93b627c3
Status: Downloaded newer image for registry.highgo.com/postgres/postgres:18.3-bookworm
registry.highgo.com/postgres/postgres:18.3-bookworm
[root@openeuler-server ~]#

目前可用的主要是带发行版后缀的标签，比如 18.3-bookworm、18.3-trixie 这些。

⚠️ 第四个坑：别凭感觉猜版本号

我一开始想当然地以为能拉 postgres:18.4 或者 postgres:15.18 这种纯数字标签，结果：

[root@openeuler-server ~]# docker pull registry.highgo.com/postgres/postgres:18.4
Error response from daemon: unknown: artifact postgres/postgres:18.4 not found
[root@openeuler-server ~]# docker pull registry.highgo.com/postgres/postgres:15.18
Error response from daemon: unknown: artifact postgres/postgres:15.18 not found

所以拉之前最好去 registry.highgo.com 网页上确认一下有哪些 tag 可用，别凭感觉猜。

另外顺便提一句，如果你执行 docker search postgres 报错，那是 Docker 客户端默认去 Docker Hub 搜索被墙了，跟国内镜像仓库没关系。国内仓库本身不提供 docker search 功能。

四、不止是数据库内核​

IvorySQL 的国内镜像仓库不只是提供了数据库内核镜像。围绕容器化部署场景，社区还在持续完善更多生态镜像：

这意味着你可以用一套镜像源，完成从"单机体验"到"生产级部署"的全链路支撑。不用在 Docker Hub、GitHub、各个官网之间来回跳转找资源。

如果你在实际使用中有其他镜像需求，也可以反馈给 IvorySQL 社区。

五、一点个人看法​

镜像源上线这件事，单独看就是个基础设施优化。但放在 IvorySQL 的发展路径上来看，信号不太一样。

IvorySQL 5.3 是基于 PostgreSQL 18.3 构建的，2026 年 3 月 12 日正式发布。从版本迭代节奏来看，社区在同步 PG 最新内核方面跟得挺紧。而国内镜像源的上线，补上的是"用户触达"这一环——让想试的人能真正试起来，而不是卡在第一公里的网络问题上。

但镜像源只是起点。后续值得关注的点至少还有两个：

第一，版本同步的时效性。 镜像源能不能做到跟 Docker Hub 几乎同步更新？尤其像 PG 18.3 这种小版本修复，如果在镜像源里滞后几天，对于依赖最新安全补丁的用户来说就是隐患。

第二，国产操作系统的原生支持。 目前镜像基于 UBI8，在 x86 和 ARM 上跑都没问题。但如果在麒麟、统信这些国产 OS 上跑，会不会有依赖兼容性问题？这是很多政企用户真正关心的。

毕竟，技术文章最大的价值不是告诉别人"这么做是对的"，而是告诉别人"别像我那样做"。

作者： ShunWah
公众号： "shunwah星辰数智社"主理人。

持有认证： OceanBase、MySQL、OpenGauss、崖山、金仓 KingBase、KaiwuDB、亚信 AntDBCA、翰高、GBase、Galaxybase、Neo4j、NebulaGraph、东方通 TongTech、TiDB 等多项权威认证。

获奖经历： 崖山 YashanDB YVP、浪潮 KaiwuDB MVP、墨天轮 MVP、金仓社区 KVA、TiDB 社区 MVA、NebulaGraph 社区之星、IFClub 星珩联盟·智库星系技术专家、ITPUB 技术专家，社区版主及布道师。在 OceanBase&墨天轮征文大赛、OpenGauss、TiDB、YashanDB、Kingbase、KWDB、Navicat 征文等赛事中多次斩获一、二、三等奖，原创技术文章常年被墨天轮、CSDN、ITPUB 等平台首页推荐。

📋 作者注：

本文围绕 IvorySQL 5.3 容器化部署展开的安装过程、问题分析与排查方案，均基于 openEuler 服务器 + Docker 容器环境实测整理。文中涉及的 docker run 命令截断报错、psql 客户端缺失、数据库连接拒绝、磁盘空间不足导致的 PANIC 崩溃等问题，均为本次部署过程中真实踩坑记录。

数据库运行环境复杂多样，操作系统版本、Docker 版本、磁盘分区方案、网络环境都会影响最终表现。本文方案仅作技术参考，不代表唯一标准解法。文中使用的密码示例 PKsjj@112!! 和 g4Bw#QPY4^t%87xTy 均为演示用途，实际生产环境请使用强密码并妥善保管。

以上内容为个人经验总结，不构成线上生产环境落地建议。

有问题欢迎在评论区留言，或者去 GitHub 上给 IvorySQL 社区提 issue。咱们下篇见。

本文整理自 HOW 2026 中国数据库开源发展峰会暨 PostgreSQL 高峰论坛的演讲分享，演讲嘉宾：唐成，资深数据库架构师，中启乘数科技创始人及 CTO，《PostgreSQL修炼之道：从小工到专家》作者。

HOW 2026 演讲 PPT 下载方式

该演讲录屏：https://www.bilibili.com/video/BV1jaLx63EZw/

过去几年，"全面上云"一度成为数据库建设的主流方向。但随着核心业务规模不断扩大，越来越多企业开始重新关注私有云架构。尤其在金融、政企、运营商等场景下，数据库不仅需要云化能力，同时还要兼顾数据安全、资源可控、成本优化、国产化适配、高可用与稳定性。数据库私有云，也逐渐从"资源虚拟化平台"演变为完整的数据基础设施平台。

为何选择 PostgreSQL / IvorySQL 构建私有云​

业务发展的挑战​

伴随业务场景复杂化、数据体量爆发式增长，传统数据库架构在业务快速增长过程中，逐渐暴露出多个问题：

1. 弹性能力不足：传统数据库架构扩容周期长，资源利用率低，难以适配业务高峰与低谷之间的动态变化。
2. 运维复杂度持续提升：随着数据库实例规模扩大，人工部署、人工扩容、人工切换等传统运维方式已经难以支撑大规模数据库集群管理。
3. 安全与合规压力增加：核心业务数据对数据主权、访问控制、审计监管提出更高要求，越来越多行业开始强调数据本地化与资源可控。
4. 数据库成本持续增长：商业数据库授权费用、高端存储成本以及 DBA 运维成本不断增加，企业开始更加关注数据库总体拥有成本（TCO）。

私有云的优势与数据库选型考量​

相比传统数据库部署模式，私有云更强调资源统一管理与平台化能力建设。在这一背景下，PostgreSQL 与 IvorySQL 成为了数据库私有云的重要选择。PostgreSQL 依靠成熟稳定的开源生态、丰富扩展能力以及企业级可靠性，已经成为当前最主流的开源数据库之一。而 IvorySQL 则在兼容 PostgreSQL 生态基础上，进一步增强 Oracle 兼容能力，更适合国产化替代与数据库迁移场景。

IvorySQL 的优势​

作为基于 PG 的开源数据库，100% 兼容 PG 并高度兼容 Oracle，为云原生而生，是企业构建私有云数据库的理想选择：

1. 100% 兼容 PostgreSQL：IvorySQL 基于最新的 PostgreSQL 版本进行研发，继承了 PG 的所有核心功能与优势。
2. 高度兼容 Oracle：提供包括 PL/iSQL 语法、数据类型、函数及存储过程等的 Oracle 兼容性，大幅降低企业从 Oracle 迁移的成本与风险。
3. 遵循 Apache 2.0 协议：采用宽松的开源协议，允许用户自由使用、修改和分发，提供了最大的技术自主权。
4. 丰富的云原生生态：提供全套云原生工具链，支持在 K8s 等容器平台上快速部署、弹性伸缩和自动化运维。
5. 全面的 Oracle 兼容性：新增对 ROWID、%ROWTYPE、%TYPE、NLS 参数、大小写敏感等 21 个 Oracle 关键特性的支持。
6. 性能与稳定性提升：基于 PG 18.0 的异步 IO、跳跃扫描等新特性，提供卓越的性能和高并发处理能力。

私有云架构设计​

数据库私有云的核心，本质上是基础设施能力的构建。

基础设施规划——裸金属服务器​

对于高并发、高 IO 的核心业务，裸金属依然是数据库部署的重要方案。数据库直接运行在物理机上，可以绕过虚拟化层，获得更低的性能损耗。

在实际部署中，通常会重点关注 NVMe SSD、本地高性能存储、万兆 / 25G 网络、RDMA 网络。

尤其是在 PostgreSQL 主备复制场景中，网络时延会直接影响同步效率。

基础设施规划——容器​

对于要求极致资源利用率的系统，采用 Kubernetes（K8S）作为容器编排平台，为 IvorySQL 实例提供一个弹性的运行基座。

其中 Operator 是实现数据库高可用部署的核心组件。IvorySQL 适配自身数据库特性：

• Operator：https://github.com/IvorySQL/ivory-operator/
• IvorySQL Cloud 前端：https://github.com/IvorySQL/ivory-cloud-web
• IvorySQL Cloud 后端：https://github.com/IvorySQL/ivory-cloud

高可用体系​

PostgreSQL 的高可用体系主要建立在流复制基础之上。在生产环境中，通常采用一主多备、同步复制、自动故障切换等方式保障数据库稳定运行。

数据库性能优化​

数据库性能优化并不是简单"调几个参数"。真正影响数据库性能的，通常包括操作系统、数据库参数、连接池管理、SQL 执行效率、存储 IO。

存储 IO 是数据库性能短板高发区，从 RAID 选型、文件系统、内核调度、磁盘分区四个维度落地优化：

• RAID 配置：机械盘配缓存 RAID 卡，优选 RAID10；NVMe 采用软 RAID
• 文件系统：生产环境统一使用 XFS，适配高并发与大文件 IO 场景
• I/O 调度器：NVMe 配置 noop，普通磁盘选用 deadline，压低 IO 延迟
• 预读与对齐：分区对齐物理扇区，合理调控预读参数，削减冗余 IO 损耗

智能监控与运维​

实时监控与告警​

数据库私有云环境中，监控体系的核心目标是快速发现问题、定位问题。

构建智能监控​

依托开源工具实现监控从被动告警到主动预判的升级：

• Metrics 采集与告警：使用 Prometheus Operator 部署 Prometheus 和 Alertmanager，通过 node_exporter 和 pg_exporter 采集指标
• 日志平台化管理：利用 EFK 或 Loki 等日志系统，集中收集和存储所有数据库实例的日志
• 链路追踪一体化：将数据库监控与 APM 系统打通，实现从应用端到数据库端的全链路追踪
• 异常检测与预测：利用机器学习算法对历史监控指标建模，实现基线预测和异常点检测

关键指标监控​

全面精准地采集数据库各项指标，重点关注：

• 主机层指标：CPU、内存、磁盘 IO、网络吞吐量
• 实例层指标：活跃连接数、缓存命中率、TPS、QPS、锁等待数量
• 对象层指标：表的增删改查频次、索引使用率、表索引膨胀率、WAL 日志产生速度
• 会话与 SQL 指标：慢查询数量、长事务数量、空闲事务数量

获取数据库指标​

PostgreSQL 依靠内置系统视图采集细分性能指标：

• 会话等待：pg_wait_events、pg_stat_activity
• WAL 运行：pg_stat_wal
• 检查点：pg_stat_checkpointer
• 异步 IO：pg_aios
• 内存与 NUMA：pg_stat_memory_usage、pg_shmem_allocations_numa
• 向量运算：pg_stat_vector_ops
• 并行查询：pg_stat_parallel_queries

自动化运维实践​

随着数据库规模不断扩大，自动化运维已经成为数据库私有云的重要组成部分。目前常见实践包括基础设施即代码、配置管理自动化、CI/CD 流水线。

总结​

随着企业核心业务持续向云化演进，数据库私有云建设已经不再只是简单的"数据库上云"。从基础设施规划到高可用体系建设，从性能优化到监控与自动化运维，数据库平台正在逐渐向云原生化、平台化、智能化方向发展。

PostgreSQL 凭借稳定性、扩展能力与成熟开源生态，已经成为数据库私有云的重要技术底座。而 IvorySQL 在兼容 PostgreSQL 生态的基础上，进一步增强 Oracle 兼容能力与云原生适配能力，也为企业数据库国产化与平滑迁移提供了更多可能。

从人工运维转向自动化运维，从被动告警转向智能预警，从单实例管理转向统一平台化管理，数据库运维体系正在发生深刻变化。

未来，随着 AI 运维、自助式数据库服务以及多模数据能力持续发展，数据库私有云也将逐渐演变为完整的数据基础设施平台。

本文作者严少安，PostgreSQL ACE, IvorySQL 贡献者，IvorySQL 专家顾问委员。持有 PGCM, PGCE, PGCA, HGCP, HGCA 等认证。主笔公众号「少安事务所」，专注于数据 & AI 领域技术传播。本文为 HOW 2026 严少安老师的演讲内容，首发于公众号【少安事务所】。

4 月 27 日，HOW 2026 大会在济南山东大厦召开。上午主论坛的内容回顾戳这里:

HOW2026 大会：PostgreSQL 与 AI 在泉城济南的硬核碰撞

笔者作为 IvorySQL 专家顾问委员，在当天下午分论坛进行了一次分享，期间首次介绍了 IvorySQL Skills。这是我把自己日常工作中沉淀的 IvorySQL 运维和开发技巧做了一次梳理，并开源出来分享给大家。下面来具体聊聊这套 IvorySQL-Skills 是什么，为什么需要它。

01. Agentic AI 时代，"告诉我怎么做"比"告诉我原理"更值钱​

我在 PPT 里放了三句话，这也是我做这个项目的初衷。

第一，AI 适合做探索，不适合做决策。 让 AI 帮你写初稿、生成测试用例、解释执行计划都可以，但最终上生产的决策必须人把关。可问题是，如果你连"正确的做法"都不知道，你怎么判断 AI 给的建议好不好？

第二，AI 是放大器，不是替身。 你本身能力越强，AI 放大效果越好。你对 SQL 优化理解不深，AI 的建议你也判断不了好坏。所以基础技能库必须先行。

第三，选对工具比用多少重要。 不是所有 AI 工具都值得尝试，但一套经过生产环境验证的、即插即用的技术"菜谱"，绝对值得放在手边。

IvorySQL Skills 的定位就是这个"技术菜谱"。它不是官方文档的重复，而是我在过去两年从 Oracle 19c 迁移到 IvorySQL、在信创环境（龙芯 LoongArch + 麒麟 OS）做部署、给团队做内部培训过程中，反复打磨验证过的实操脚本和配置模板。

项目地址：https://github.com/shawn0915/ivorysql-skills

欢迎大家点点 Star ⭐

如果访问速度慢，可以访问国内镜像：

https://gitcode.com/mydb/ivorysql-skills

02. IvorySQL-Skills 里都有什么​

目前整个套件按照使用场景拆成了四大模块，共 22 个技能。每个 skill 都是一个独立文件，包含场景描述、适用版本、操作步骤和验证命令。

核心技能​

开发技能​

功能技能​

辅助技能​

示例：Oracle 兼容函数速查（迁移适配类）

IvorySQL 5.0 基于 PostgreSQL 18.0 内核，新增了 21 个 Oracle 兼容特性。但开发者在实际迁移时，经常卡在一些具体函数上。这个 skill 不是罗列所有兼容函数，而是只放"最容易踩坑"的 Top 20 对照表。

-- 场景：从Oracle 19c迁移到IvorySQL 5.3，快速验证常用函数兼容性
-- 适用版本：IvorySQL 5.0+ / PG 18.x

-- 1. 日期处理：Oracle的ADD_MONTHS
SELECT ADD_MONTHS('2026-04-27'::timestamp, 3);  -- IvorySQL直接支持

-- 2. 字符串拼接：Oracle的||
SELECT 'HOW' || '2026' || 'Jinan';  -- 兼容，无需改写

-- 3. 空值处理：Oracle的NVL
SELECT NVL(NULL, 'default_value');  -- 兼容

-- 4. 行号：Oracle的ROWNUM
SELECT * FROM (SELECT *, ROWNUM() OVER() AS rn FROM pg_tables) t WHERE rn <= 5;

-- 验证命令：查看当前IvorySQL兼容级别
SHOW ivorysql.compatible_mode;  -- 返回 oracle 或 pg

03. 一个好的 Skill 应该是什么样子​

在 HOW 2026 现场，我也分享了 IvorySQL Skills 的设计规范。这不是什么高大上的方法论，就是四个硬性要求，确保每个 skill 都是"拿到就能用"的水平。

04. 怎么安装使用：三种姿势，30 秒上手​

除了下面介绍的三种常规方法外，还有更简单的方式。直接告诉你的 AI 编程助手：

帮我安装这个 skills：shawn0915/ivorysql-skills

方式一：npx 一键安装（推荐，适合快速体验）

# 全局安装skills管理器后，一键拉取IvorySQL技能包
npx skills add shawn0915/ivorysql-skills

# 安装完成后，查看可用skill列表
skills list | grep ivorysql

方式二：npm 一键安装

npm i ivorysql-skills

方式三：Git 克隆（适合二次开发和团队内部定制）

git clone https://github.com/shawn0915/ivorysql-skills.git

目录结构：

ivorysql-skills/
├── SKILL.md                      # 包级入口（路由中心）
├── README.md                     # 说明文档
│
├── ivorysql/                    # 主技能（产品概览）
│   └── references/              # 参考文档
├── ivorysql-app-builder/        # 端到端应用开发
│   └── references/              # 参考文档
├── ivorysql-architecture/        # 架构设计
│   └── references/              # 参考文档
...

在内部环境可以这样用：把 Git 仓库 fork 到公司内网 GitLab，DBA 和开发各自贡献自己验证过的 skill，形成团队级的"私有技能库"。新人入职第一天，或者当一个新的 Agent 上线，先装这个技能包，基本能覆盖大部分日常操作。

05. 结语​

在分享的最后，我聊了一个观点：Agentic AI 时代，Skills 不是被 AI 替代的东西，而是给 AI 提供"事实基准"的锚点。

什么意思呢？你让 AI 直接生成一条 IvorySQL 的备份脚本，它可能给你一条 pg_basebackup 的命令，参数可能适用于 PG 15 但不适用于 PG 18，或者没考虑国密 SSL 环境。但如果你已经让 Agent 安装了 IvorySQL Skills，那么大模型生成的内容就有了边界。

一上午听完 HOW 2026 主论坛，下午又和各位同行交流，最大的感受是：中国 PG 生态正在从"追逐开源"走向"贡献开源"。 IvorySQL Skills 这个项目很小，没有复杂代码，就是一堆 Markdown 文档，但它本质上是为了让大家在使用 AI 编程助手时，更加容易上手，让 Agent 更懂你，让 Agent 更懂 IvorySQL。

Skills 是经验的"蒸馏"品，是 Agent 的行动指南，也是你提升工作效率的"硬菜"。

2026-05-02 批注

本文是在 HOW 2026 第二天写的，也就是 4 月 28 日，但是我在 4 月 30 日看到了 Oracle Skills 开源了，然后意识到 IvorySQL-Skills 还有很多需要改进的地方。比如，IvorySQL 和 PostgreSQL 的差异点，是否需要再梳理一下。再如，IvorySQL 在 Oracle 兼容性上，以及从 Oracle 迁移到 IvorySQL 还有哪些案例、脚本、流程、工具等都需要补充优化。

未完待续。

同时，这款引擎也是我们团队将各类外部 SQL 语句及应用适配至 PostgreSQL 时的首选工具！我们秉持平滑过渡、而非整体迁移的理念 —— 让旧数据库引擎向新引擎逐步切换，核心为降低迁移风险、优化实施效果。借助这类方案，能为实现这两大目标带来关键助力。

尽管 IvorySQL 最新主版本发布已有一段时间，但其中的全新特性依旧让我们倍感振奋，特此为大家分享。

新特性概览​

IvorySQL 5.0 版本（5.0 发布说明）于 2025 年 11 月 25 日发布，随后在 2025 年 12 月 18 日推出 5.1 版本（5.1 发布说明）。这两个版本凝聚了 IvorySQL 团队的大量投入，不仅带来了多项高品质的功能优化，还完成了对 PostgreSQL 18 的兼容性适配。

IvorySQL v5 带来了一系列关键能力，包括：

• PLiSQL —— 兼容 Oracle PL/SQL 的子集
• Oracle 兼容包支持
• Oracle 风格序列支持
• v5.0 增强能力包括：ROWID、%TYPE、%ROWTYPE 以及嵌套子函数

我们尤其喜欢很多功能升级。

例如，IvorySQL 现在改进了 NULL 值处理逻辑，在兼容模式下（与 Oracle 的行为一致），NULL 值现在被视为空字符串，以避免迁移过程中出现错误。以 SELECT CONCAT ('a' || NULL) 语句为例，IvorySQL 将返回结果 'a'，而非沿用 PostgreSQL 默认的 NULL 值返回逻辑。

我们非常喜欢的一项增强功能是：你现在可以嵌套函数和存储过程。函数能够嵌入到其他函数内部（类似于 Oracle 的包，但更简单，仅使用私有方法）。这让你能够在一个地方集中组织复杂的逻辑。

与之类似，系统还增加了对 DO [ LANGUAGE lang_name ] 代码块 [USING IN | OUT | IN OUT, ...] 语法的支持。

实测验证​

目前，我们已基于该版本完成多类应用的迁移适配测试，适配对象规模跨度极大：既有仅包含少量包、存储过程及函数的轻量应用（约 10-50 个数据库对象），也有包含海量数据库对象的大型业务系统（约 5 万个对象，其中存储过程超 1 万个、数据库包达数百个）。

尽管后续仍需持续迭代、补充更多功能特性，但当前版本已能大幅降低从 Oracle 向 PostgreSQL 平滑过渡的实施成本，助力迁移工作高效落地。

若你计划亲自体验测试，IvorySQL 提供了丰富的快速上手方式，包括源码编译、容器部署等，甚至还支持 WASM 构建！WASM 的独特优势在于，无需在本地完成完整安装，即可在浏览器中直接运行 IvorySQL，便于快速验证语法兼容性并开展 PostgreSQL 体系的初步探索。

你可参照 IvorySQL 官方发布的相关文章，通过简单几步完成 IvorySQL-WASM 项目的本地部署。也可直接访问 IvorySQL 官网，体验在线托管的 WASM 版本。

后续规划​

我们团队很高兴聘用 IvorySQL 项目的贡献者，目前我们团队已有多位贡献者加入 IvorySQL 的核心研发工作。其中 Cédric Villemain、Yasir Hussain Shah 等成员的贡献，已在 5.0 和 5.1 版本的发布说明中专门致谢 —— 未来我们还将吸纳更多优秀开发者参与项目建设。

针对下一个版本，我们已规划了多项重磅新特性开发工作，具体包括：

• ENABLE / DISABLE 约束语法支持
• UTL_FILE 包新增适配
• Oracle 风格的 CREATE TRIGGER 触发器体（无需预先创建函数）
• 支持 Oracle 旧式连接运算符 (+)

我们同样期待社区为下一个版本持续贡献的研发成果落地。目前已有多项优质功能正处于积极开发与合入阶段，例如项目新晋贡献者 Rophy Tsai 近期新增了 DBMS_OUTPUT 和 DBMS_UTILITY 包的适配支持 —— 这两个包是 Oracle 生态 SQL 代码库中应用极为广泛的工具包。该特性现已合入 IvorySQL 主分支，预计将随下一个小版本或主版本正式发布。

对于希望在无需对现有数据库逻辑和应用程序进行大量改造的前提下，完成向 PostgreSQL 迁移或探索 PostgreSQL 生态的开发者而言，IvorySQL（尤其是 5.x 系列版本）提供了一套切实可行的解决方案。直接迁移至 PostgreSQL 在部分场景下，可能需要对数据库对象和应用代码做出大量调整，而 IvorySQL 能够有效填补这一适配鸿沟，凭借更高的兼容性，助力开发者更平滑地完成 PostgreSQL 生态的落地与适配。

您还可以通过以下渠道深入了解 IvorySQL：

• 官网 blog：https://www.ivorysql.org/zh-CN/blog
• 社区活动：https://www.ivorysql.org/zh-cn/events
• HOW 2025 相关会议录像：https://www.youtube.com/@ivorysql

值得一提的是，2026 年的 HOW 大会已确定于 4 月 26 日至 28 日举行，议题征集截止日期为 2026 年 2 月 27 日。

更多参考​

• PostgreSQL.org 发布的 IvorySQL 5.0 公告
• GitHub 上的 IvorySQL 5.0 路线图

一、PG 异步 I/O（AIO）框架：迈出打破同步阻塞瓶颈的第一步​

PostgreSQL 18 全新引入异步 I/O 子系统。新机制允许特定场景下并行执行多个异步预读操作，CPU 无需等待数据返回即可继续推进查询，一定程度上降低了等待损耗。此框架为 PG 未来更深入更彻底的异步 I/O 性能优化奠定基础，迈出了第一步。

核心提升场景​

【当前仅实现异步读，没有实现异步写】 所有 Seq Scan 场景下通过适配过异步 I/O 的 ReadStream 设施可实现并行化顺序预读，提升 Seq Scan 的性能，效果好于原有 posix_fadvice 的建议性预读。尤其在云存储场景下单次阻塞读 I/O 相比本地 I/O 所需时间更长，异步 I/O 加持下的并行化预读的优势更加明显。目前异步 I/O 已支持顺序扫描、位图堆扫描和 VACUUM 操作的异步读取，早期测试显示，读取密集型查询性能可提升 2-3 倍。

如图所示：

使用了异步 I/O 的 ReadStream 机制可以在收到读请求后异步地预读后续可能使用的 buffer。而在使用同步 I/O 方式在每次请求读取 buffer 时，都要等待 I/O 操作完成，这样降低了系统吞吐量。

使用方法​

# - I/O -

#backend_flush_after = 0		# measured in pages, 0 disables
effective_io_concurrency = 300		# 1-1000; 0 disables issuing multiple simultaneous IO requests
maintenance_io_concurrency = 300	# 1-1000; same as effective_io_concurrency
io_max_combine_limit = 256kB		# usually 1-128 blocks (depends on OS)
                    # (change requires restart)
io_combine_limit = 256kB		# usually 1-128 blocks (depends on OS)

io_method = io_uring # worker, io_uring, sync
                    # (change requires restart)
io_max_concurrency = 128		# Max number of IOs that one process
                    # can execute simultaneously
                    # -1 sets based on shared_buffers
                    # (change requires restart)
#io_workers = 3				# 1-32;

用户可选择三种不同的 io_method 启用异步 I/O，分别是：

• worker 若干后台 I/O workers 接收处理后端进程的 I/O 请求。
• io_uring Linux 系统中 io_uring 子系统通过操作系统内核线程处理 PG 的 I/O 请求。
• sync 满足异步 I/O 框架接口要求的同步 I/O。

要启用异步 I/O，用户需要根据自身情况设定上述 GUC 参数。其中每个进程能够拥有的最大异步 I/O 句柄为 io_max_concurrency，用户可以将其置 -1，使数据库自行选择合适的值。若自行选择的值太大，则可能因为异步 I/O 所占空间太大而无法启动数据库；若自行选择的值太小则无法完全发挥出异步 I/O 性能。

启动数据库后，用户可通过 pg_aios 视图实时地获取当前系统异步 I/O 执行状况:

postgres=# select * from pg_aios;
-[ RECORD 1 ]---+-------------------------------------------
pid             | 85834
io_id           | 14208
io_generation   | 204
state           | SUBMITTED
operation       | readv
off             | 116252672
length          | 8192
target          | smgr
handle_data_len | 1
raw_result      |
result          | UNKNOWN
target_desc     | block 14191 in file "base/5/16427"
f_sync          | f
f_localmem      | f
f_buffered      | t
...

各列含义详见官方文档。

框架设计​

PG 18 引入异步 I/O 框架，支持通过 GUC 参数灵活配置异步 I/O：包括实现方式（io_method，可选 worker、io_uring 或 sync）、并发规模（如 *_io_concurrency、io_max_concurrency）及实现相关参数（如 io_workers）。

该框架对 I/O 目标（当前支持 smgr，未来计划支持 WAL）和不同阶段、不同数据源(shared buffer/local buffer)的行为进行了抽象（通过 PgAioHandleCallbacks 结构），以支持后续扩展。相关内存于启动时在共享内存中分配，后续不再缩放。进程按编号访问所属异步 I/O 资源，句柄通过 generation 号标记复用。

目前该版本异步 I/O 主要提供对 smgr 的异步读支持，尚不支持 WAL 异步读写，smgr 的异步写入功能仍在开发中。

对原有设施的修改​

1. 扩展 smgr 接口：新增 smgr_startreadv 方法以支持异步读取。
2. 实现回调结构：smgr 需实现 PgAioTargetInfo 和 PgAioHandleCallBacks 回调结构。
3. 适配现有模块：smgr 和 buffer manager 等模块需填充异步 I/O 抽象结构以兼容框架。
4. PG 临界区处理：同步 I/O 可在 PG 临界区内发起；异步 I/O 因分段执行且带回调，需移除回调中可能失败的操作（临界区内一切操作不能失败，如用RelPathStr替代 palloc 的char*字符串）以确保安全。
5. 优化上层接口：利用异步 I/O 改造 ReadStream 等接口，实现真预读，大幅提升顺序扫描、pg_prewarm 及 ANALYZE 等操作的 I/O 性能，效果优于原有 posix_fadvise 方案。

使用注意及未来展望​

1. **io_uring 需要较新内核：**旧版 Linux Kernel 不支持 io_uring。某些早期版本内核虽然支持 io_uring，但功能和性能表现与新内核有一定差距。
2. 架构限制并发粒度：受多进程架构所限，PG 异步 I/O 期间可并行运行的计算任务较少，难以实现更细粒度的任务级异步。当前主要性能收益集中于ReadStream 顺序预读及等并行 I/O 操作。
3. 未来可能的性能提升：Linux io_uring 支持直接 I/O（DIO）特性，为在 PG 中启用 DIO 奠定基础。未来启用直接 I/O 可免除双重 buffer(OS 层面对 I/O 数据进行 buffer，PG 层面对 I/O 进行 buffer)以减少不必要的数据复制。在高速 NVMe 上还配合 DIO 启用IORING_SETUP_IOPOLL选项使用轮训方式检查 I/O 完成情况，还可以进一步提升性能。
4. 未来更多的异步 I/O 后端：除了sync模式，正式版的 PostgreSQL 18 仅支持 worker 和 io_uring 两种异步 I/O 后端。目前异步 I/O 框架设计已基本完备，未来版本有望支持 Windows IORing，IOCP，以及 Posix 异步 I/O 等 I/O 后端，为用户提供更多选择。

小结​

PostgreSQL 18 异步 I/O 框架提升数据库系统 I/O 能力，同时也增强了 PostgreSQL 架构的可扩展性，用户只需要根据自身情况修改 GUC 参数即可获取到异步 I/O 带来的好处。目前异步 I/O 框架设计基本完备，后期支持其他异步 I/O 后端也将非常方便。任意平台 Postgres 用户可以尝试 io_method = worker或者sync 若要在非官方适配 io_uring 的旧 Linux 内核发行版上使用 io_uring 后端，需要进行充分测试后再使用。

二、 跳跃式扫描：让 B 树索引 “提速换挡”​

在 PostgreSQL 18 之前的版本中，多列 B 树索引可用于包含该索引中任意子集列的查询条件，在对起始（最左侧）列施加约束时最为高效。对前导列的等式约束，加上对第一个不带有等式约束的列的任何不等式约束，用于限制要扫描的索引部分。

例如，给定一个基于（a，b，c）非空字段的升序索引和查询条件 WHERE a = 5 AND b >= 42 AND c < 77，该索引将从具有 a = 5 和 b = 42 的第一个条目开始扫描，一直扫描到最后具有 a = 5 的条目。 具有 c >= 77 的索引条目将被跳过，但它们仍需扫描。

原则上，这种索引可以用于对 b 和/或 c 有约束条件而对 a 没有约束条件的查询——但必须扫描整个索引，所以在大多数情况下优化器更倾向于对表进行顺序扫描表，而非利用索引扫描。

核心提升场景​

从 PostgreSQL 18 开始：

如果 B 树索引扫描能够应用跳跃式扫描（SKIP SCAN），在遍历索引时应用每个列的约束，可以减少索引的读取。跳跃式扫描的工作原理是内部生成一个动态等式约束，该约束与索引列中的每个可能值相匹配。

效果测试​

对比版本：

PostgreSQL 17 vs PostgreSQL 18

表结构与索引​

CREATE TABLE t1
(
c1 int
c2 int,
c3 float
)
WITH (fillfactor=80);


CREATE INDEX idx_t1_c1c2 ON t1(c1, c2);

数据生成​

INSERT INTO t1
SELECT (random()*1000)::int, (random()*10000)::int, random()
FROM generate_series(1,1000000) g;

通过 COPY 导入数据​

COPY t1 FROM '/.../t1.csv' WITH (FORMAT csv);

查询语句 使用复合索引的第二个列​

EXPLAIN ANALYZE SELECT * FROM t1 WHERE c2=100;

PostgreSQL 17 执行计划 选择使用并行顺序扫描​

                                                    QUERY PLAN
-------------------------------------------------------------------------------------------------------------------
 Gather  (cost=1000.00..12986.33 rows=100 width=16) (actual time=1.125..76.076 rows=90 loops=1)
   Workers Planned: 2
   Workers Launched: 2
   ->  Parallel Seq Scan on t1  (cost=0.00..11976.33 rows=42 width=16) (actual time=1.414..68.624 rows=30 loops=3)
         Filter: (c2 = 100)
         Rows Removed by Filter: 333303
 Planning Time: 0.792 ms
 Execution Time: 76.165 ms
(8 rows)

关闭顺序扫描强制选择索引扫描，并非最优计划，执行更慢。

                                                        QUERY PLAN
--------------------------------------------------------------------------------------------------------------------------
 Index Scan using idx_t1_c1c2 on t1  (cost=0.42..18773.42 rows=100 width=16) (actual time=1.846..100.758 rows=90 loops=1)
   Index Cond: (c2 = 100)
 Planning Time: 0.147 ms
 Execution Time: 100.806 ms
(4 rows)

PostgreSQL 18 执行计划选择使用索引扫描，可以看出跳跃式扫描执行效率提升幅度非常大​

                                                        QUERY PLAN
---------------------------------------------------------------------------------------------------------------------------
 Index Scan using idx_t1_c1c2 on t1  (cost=0.42..3900.84 rows=100 width=16) (actual time=0.225..11.464 rows=90.00 loops=1)
   Index Cond: (c2 = 100)
   Index Searches: 1002
   Buffers: shared hit=3096
 Planning Time: 0.141 ms
 Execution Time: 11.522 ms
(6 rows)

关闭索引扫描和位图扫描强制选择顺序扫描。

postgres=# EXPLAIN ANALYZE SELECT * FROM t1 WHERE c2=100;
                                                      QUERY PLAN
----------------------------------------------------------------------------------------------------------------------
 Gather  (cost=1000.00..12986.33 rows=100 width=16) (actual time=1.486..86.881 rows=90.00 loops=1)
   Workers Planned: 2
   Workers Launched: 2
   Buffers: shared hit=6768
   ->  Parallel Seq Scan on t1  (cost=0.00..11976.33 rows=42 width=16) (actual time=2.758..78.712 rows=30.00 loops=3)
         Filter: (c2 = 100)
         Rows Removed by Filter: 333303
         Buffers: shared hit=6768
 Planning Time: 0.141 ms
 Execution Time: 86.926 ms
(10 rows)

使用注意​

跳跃式扫描目前只能支持等值比较条件。

小结​

PostgreSQL 18 的索引跳跃式扫描，使得多列 BTREE 索引能够被那些仅对第二个或之后的索引列进行等值引用的查询使用，大幅减少索引扫描需要访问的条目，使其效率得到明显提升。

三、 虚拟生成列：存储与计算的 “灵活平衡”​

PostgreSQL 18 开发体验相关的特性，聚焦于简化开发流程、提升代码灵活性，让开发者更高效地利用 PostgreSQL 能力。

IvorySQL 数据库长期致力于 Oracle 特性兼容，其中包含了一项虚拟列的语法兼容：

column [datatype][generated always] AS (column_expression)[VIRTUAL]

这次 PostgreSQL 18 终于也带来了虚拟列功能。虚拟列是一种不存储数据的表列，其值在查询时通过动态计算得出。与存储列相比，虚拟列节省了列存储空间，查询虚拟列值时通过计算虚拟列表达式的值作为该列的值。

基本语法​

PostgreSQL 18 中虚拟列的语法和存储列的语法相似，新增加关键字VIRTUAL，当省略 STORED 和 VIRTUAL 关键字时默认为虚拟列。其语法如下所示：

GENERATED ALWAYS AS ( generation_expr ) [ STORED | VIRTUAL ]

虚拟列用例​

虚拟列的标识是在列的限制条件中表示的，通过虚拟列的限制语法标识列为虚拟列，以下为虚拟列表的创建、查询和新增虚拟列：

-- 创建包含虚拟列的表，其中price_with_tax为虚拟列
CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    price NUMERIC(10,2) NOT NULL,
    tax_rate NUMERIC(5,2) DEFAULT 0.20,
    price_with_tax NUMERIC(10,2) GENERATED ALWAYS AS (price * (1 + tax_rate)) VIRTUAL
);

-- 插入数据
INSERT INTO products (name, price, tax_rate)
VALUES ('Laptop', 1000.00, 0.20);

-- 查询数据（虚拟列自动计算）
SELECT name, price, tax_rate, price_with_tax FROM products;
  name  |  price  | tax_rate | price_with_tax
--------+---------+----------+----------------
 Laptop | 1000.00 |     0.20 |        1200.00
(1 row)

--为表添加虚拟列
ALTER TABLE products ADD COLUMN selling_price NUMERIC(10,2)
GENERATED ALWAYS AS (
    price * (1 - 0.2) * (1 + tax_rate)
) virtual;

实现原理浅析​

虚拟列的创建​

创建的表中虚拟列的存储方式和普通列的存储方式类似，其列信息都存储在 pg_attribute 系统表中，其中 attgenerated 列存储生成列信息，如果该列的值为's'，表示该列为存储列。PostgreSQL 18 新增的虚拟列在该字段中的标识符为'v'，并且将虚拟列的表达式存储于 pg_attrdef 系统表中。

--查看虚拟列信息，其attgenerated为v表示该列为虚拟列
postgres=# select * from pg_attribute where attname='price_with_tax';
-[ RECORD 1 ]--+---------------
attrelid       | 16388
attname        | price_with_tax
atttypid       | 1700
attlen         | -1
attnum         | 5
atttypmod      | 655366
attndims       | 0
attbyval       | f
attalign       | i
attstorage     | m
attcompression |
attnotnull     | f
atthasdef      | t
atthasmissing  | f
attidentity    |
attgenerated   | v
attisdropped   | f
attislocal     | t
attinhcount    | 0
attcollation   | 0
attstattarget  |
attacl         |
attoptions     |
attfdwoptions  |
attmissingval  |

--查看虚拟列表达式存储，可以看到以下表达式为虚拟列表达式
postgres=# select pg_get_expr(adbin, adrelid) from pg_attrdef where adnum = 5;
             pg_get_expr
-------------------------------------
 (price * ((1)::numeric + tax_rate))
(1 row)

虚拟列的插入或更新​

由于虚拟列的数据不占据存储空间，所以任何指定更新或插入虚拟列的操作都将被限制。

--指定插入虚拟列
INSERT INTO products (name, price, tax_rate, price_with_tax) VALUES ('Laptop', 1000.00, 0.20, 1);
ERROR:  cannot insert a non-DEFAULT value into column "price_with_tax"
DETAIL:  Column "price_with_tax" is a generated column.

--指定更新虚拟列
update products set price_with_tax = 1 where name = 'Laptop';
ERROR:  column "price_with_tax" can only be updated to DEFAULT
DETAIL:  Column "price_with_tax" is a generated column.

虚拟列的查询​

PostgreSQL 18 中查询虚拟列的实现是在生成执行计划阶段完成。在逻辑重写优化阶段，判断查询的范围表中是否包含虚拟列，如果包含虚拟列，则将该虚拟列的表达式从 pg_attrdef 中获取出来并替换原虚拟列名。这样查询虚拟列的值就相当于计算其表达式的值，即 select price_with_tax 相当于 select (price \* ('1'::numeric + tax_rate)) as price_with_tax。可以看到以下虚拟列被替换成了其表达式：

postgres=# explain verbose SELECT name, price, tax_rate, price_with_tax
FROM products;
                              QUERY PLAN
----------------------------------------------------------------------
 Seq Scan on public.products  (cost=0.00..23.12 rows=750 width=76)
   Output: name, price, tax_rate, (price * ('1'::numeric + tax_rate))
(2 rows)

适用场景​

• 当考虑存储空间时，可以使用虚拟列，因为虚拟列不占用磁盘空间。
• 当列的值需要根据依赖的列变化而变化时，需要使用虚拟列。因为虚拟列的值是动态获取的。
• 当虚拟列表达式简单时，可以使用虚拟列。因为查询虚拟列需消耗 CPU 资源，表达式复杂会消耗太多 CPU 资源。
• 因为 Oracle 中有虚拟列功能，更加方便 Oracle 的虚拟列迁移至 PostgreSQL 中。

待完善部分​

一些功能目前尚不支持，但可能会作为增量功能在后续的版本中添加：

• 在虚拟列上创建索引或使用虚拟列。
• 虚拟列上也没有唯一约束。
• 虚拟列上的扩展统计信息。
• 虚拟列上的外键约束。
• 虚拟列上的非空约束（支持检查约束）。
• ALTER TABLE / DROP EXPRESSION。
• 虚拟列不能具有域类型。
• 逻辑复制不支持虚拟列。

小结​

虚拟列与普通列和存储列有着本质的不同，因为虚拟列的值不占磁盘空间，其获取值的方式也与普通列和存储列不同，普通列或存储列需要从磁盘获取数据，而虚拟列是通过动态计算获取虚拟列的值。

四、UUID 功能增强：有序性与易用性提升​

传统 UUID 的无序性是其用作主键的主要痛点：​

传统 UUID（尤其是 v4）的完全随机性是其作为数据库主键的痛点：

• UUID 随机生成，插入位置不确定，导致索引树频繁分裂和重组，大幅降低写入性能。
• 破坏聚簇索引（如 InnoDB）的物理存储顺序，增加磁盘 I/O。
• 范围查询和排序效率低下，性能低下。

UUIDv7 的关键突破：时间有序性架构设计​

UUIDv7 通过在 UUID 的高位部分引入时间戳来解决生成 UUID 完全随机的问题，使新生成的 UUID 能够按照创建时间自然排序。这样，B 树索引可以像自增整数一样进行顺序插入，同时仍然保持 UUID 的全局唯一性和分布式生成优势。

该特性使 UUIDv7 作为主键具备以下突出优势：

• 严格按照创建时间先后顺序递增。
• 减少索引碎片。
• 提高缓存命中率。
• 适合高并发插入和高效查询的场景。

UUIDv7 的结构设计​

设计关键点解析：

• 高精度时间前缀(48 位): 精确到毫秒的 Unix 时间戳，确保 ID 严格按时间递增（需 NTP 时钟同步）。
• 尾部随机位(62 位): 保证分布式唯一性，避免 v1 版本的 MAC 地址泄漏风险。

有序性如何解决性能问题？

• B-Tree 索引优化: 新生成的 UUIDv7 总是大于之前的值，因此被追加到索引尾部，避免中间节点分裂。
• 缓冲池友好: 顺序写入使新记录集中在少数数据页。当页写满时，数据库只需分配新页追加，减少旧页淘汰与磁盘 I/O。
• 范围查询加速: 时间有序性使 WHERE id > '2025-06-01' 可转化为时间戳范围过滤，大幅降低扫描范围。

如何在 PostgreSQL18 中应用 UUIDv7​

PostgreSQL 18 引入了多个新函数来支持 UUIDv7，方便生成、操作和提取 UUID 信息。

1. uuidv7()函数：用于生成新的 UUIDv7 值

-- 使用当前时间戳生成 UUIDv7
SELECT uuidv7();
-- 输出示例: 0197f96c-b278-7f64-a32f-dae3cabe1ff0

-- 生成 1 小时前的 UUIDv7
SELECT uuidv7(INTERVAL '-1 hour');
-- 生成 30 分钟后的 UUIDv7
SELECT uuidv7(INTERVAL '30 minutes');

2. uuidv4()函数：作为已有函数 gen_random_uuid() 的别名 ，便于和 uuidv7 一起使用

-- 两者等价
SELECT gen_random_uuid();
SELECT uuidv4();

3. uuid_extract_timestamp()函数 : 该函数现在支持 UUIDv7（原本只支持 UUIDv1）

-- 从 UUIDv7 提取时间戳
SELECT uuid_extract_timestamp(uuidv7());
-- 示例输出: 2025-09-18 12:20:49.409+00

4. uuid_extract_version()函数：用于检测 UUID 的版本：

-- 检查 UUID 版本
SELECT uuid_extract_version(uuidv7());  -- 返回 7
SELECT uuid_extract_version(uuidv4());  -- 返回 4

PostgreSQL 数据库中使用 UUIDv7 作为主键：

--创建带 UUIDv7 主键的表
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT uuidv7(),
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(100) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

这样，每条新记录的 id 都会自动分配一个按时间戳排序的 UUID。

--插入数据
INSERT INTO users (username, email)
VALUES ('alice', 'alice@example.com');
INSERT INTO users (username, email)
VALUES ('bob', 'bob@example.com');

-- 按 UUID 时间顺序查看
SELECT id, username, uuid_extract_timestamp(id) as uuid_timestamp
FROM users
ORDER BY id;

性能优势：​

1. UUIDv7 的时间戳顺序能显著减少页分裂和缓存失效，有效提升 B 树索引效率。

--创建性能测试表
CREATE TABLE performance_test (
    id_v4 UUID DEFAULT uuidv4(),
    id_v7 UUID DEFAULT uuidv7(),
    data TEXT DEFAULT 'sample data'
);
--使用UUIDv7作为索引
CREATE INDEX idx_v4 ON performance_test (id_v4);
CREATE INDEX idx_v7 ON performance_test (id_v7);

批量插入后，你可以用 pg_statio_user_indexes 查看索引命中情况，UUIDv7 通常表现更优。

2. UUIDv7 自带时间排序，大部分场景下显著提升排序性能。

-- 利用 UUIDv7 自然排序
SELECT id_v7, data
FROM performance_test
ORDER BY id_v7
LIMIT 10;

相比 UUIDv4 的随机顺序，UUIDv7 查询结果按创建顺序返回，更直观。

UUIDv7 最佳实践​

适合使用 UUIDv7 的场景：

• 多租户应用：可用 UUIDv7 做主键，并为 (tenant_id, id) 创建复合索引，既保持唯一性又能按时间排序。

• 分布式系统：多个服务可独立生成 UUIDv7，并且在全局范围内仍能保持时间顺序。

限制与注意事项​

• 依赖系统时钟：需启用 NTP 等时间同步机制，避免时钟漂移。
• 时间戳精度：UUIDv7 以毫秒为单位，在同一毫秒内生成多个 UUID，顺序可能无法完全反映真实创建顺序，但仍保持唯一性。
• 迁移规划：从 UUIDv4 迁移到 UUIDv7 时，需要检查应用逻辑、索引和外部依赖。

小结​

PostgreSQL 18 对 UUIDv7 的支持，解决了 UUID 作为主键的性能瓶颈。UUIDv7 在保持全局唯一性的同时，具备类似自增整数的顺序性，使 B 树插入更高效，查询更快。

对于需要分布式、高并发和高性能的现代应用，UUIDv7 提供了一种兼顾唯一性和性能的实用解决方案。

五、EXPLAIN 增强：直观呈现执行细节​

PostgreSQL 18 对 EXPLAIN 命令进行了重大升级，通过提供更丰富、更直观的执行计划信息，让数据库开发者和 DBA 能够更加轻松地进行查询性能分析与优化。

自动缓冲区分析​

EXPLAIN ANALYZE 现在默认包含 BUFFER 统计信息，无需手动添加 BUFFERS 选项：

• 共享命中(Shared Hits)：显示从缓存中读取的数据块数量，反映内存使用效率。
• 共享读取(Shared Reads)：标识必须从磁盘读取的数据块，帮助识别 I/O 瓶颈。
• 共享脏块(Shared Dirtied)：针对数据修改操作，显示被更改的块数量。

精细化索引监控​

新增索引扫描次数统计，让开发者能够精确了解索引使用效率：

-- 示例输出显示索引使用情况
Index Scan using orders_pkey on orders
Index Searches: 1  -- 明确显示索引查找次数
Buffers: shared hit=2 read=2

增强的统计信息​

• 支持小数行（ fractional row counts），提供更精确的行数估计。
• 为 Material、Window Aggregate、CTE 节点输出内存和磁盘使用详情。
• 在窗口函数中显示详细的参数信息。
• 为 Parallel Bitmap Heap Scan 显示 worker 缓存统计。
• 输出禁用节点。
• 输出 WAL 缓冲区信息。

基础查询分析​

-- 创建测试表
CREATE TABLE orders (
    order_id SERIAL PRIMARY KEY,
    customer_id INTEGER NOT NULL,
    order_date DATE NOT NULL,
    total_amount DECIMAL(10, 2) NOT NULL
);
CREATE INDEX idx_orders_customer_id ON orders(customer_id);

-- 插入测试数据
INSERT INTO orders (customer_id, order_date, total_amount)
SELECT
    (n % 10) + 1,
    CURRENT_DATE - (n % 365),
    (50 + (random() * 950))::decimal(10,2)
FROM generate_series(1, 50000) n;

-- 查看增强的执行计划
EXPLAIN ANALYZE
SELECT *,sum(total_amount) OVER (PARTITION BY customer_id)
FROM orders WHERE order_id>49900;

执行计划：

QUERY PLAN
----------------------------------------------------------------------------------------------------------------------------------------
 WindowAgg  (cost=13.46..15.04 rows=99 width=50) (actual time=0.630..0.745 rows=100.00 loops=1)
   Window: w1 AS (PARTITION BY customer_id)
   Storage: Memory  Maximum Storage: 17kB
   Buffers: shared hit=5 read=2
   ->  Sort  (cost=13.30..13.55 rows=99 width=18) (actual time=0.307..0.333 rows=100.00 loops=1)
         Sort Key: customer_id
         Sort Method: quicksort  Memory: 28kB
         Buffers: shared hit=5 read=2
         ->  Index Scan using orders_pkey on orders  (cost=0.29..10.02 rows=99 width=18) (actual time=0.089..0.174 rows=100.00 loops=1)
               Index Cond: (order_id > 49900)
               Index Searches: 1
               Buffers: shared hit=2 read=2
 Planning:
   Buffers: shared hit=64 read=22
 Planning Time: 2.080 ms
 Execution Time: 1.343 ms

执行计划输出洞察：

• 缓冲区使用情况（缓存命中 vs 磁盘读取）：生成执行计划时从缓存中访问了 64 个共享缓冲区，从磁盘中读取了 22 个缓冲区，执行时从缓冲区访问了 5 个共享缓冲区，从磁盘读取了 2 个缓冲区。
• 索引效率统计：执行了 1 次 orders_pkey 索引扫描，并从缓存中访问了 2 个共享缓冲区，清晰地显示了索引的使用效率。
• 窗口函数内存使用详情：使用的 17kB 磁盘空间。
• 精确的行统计信息。
• 窗口函数的详细参数。

WAL 日志分析​

EXPLAIN (ANALYZE, WAL)
INSERT INTO orders (customer_id, order_date, total_amount)
SELECT
    (n % 10) + 1,
    CURRENT_DATE - (n % 365),
    (50 + (random() * 950))::decimal(10,2)
FROM generate_series(1, 50000) n;

执行计划：

QUERY PLAN
---------------------------------------------------------------------------------------------------------------------------------------------
 Insert on orders  (cost=0.00..2000.00 rows=0 width=0) (actual time=767.116..767.118 rows=0.00 loops=1)
   Buffers: shared hit=299156 read=2 dirtied=500 written=501
   WAL: records=152158 bytes=10427828 buffers full=139
   ->  Subquery Scan on "*SELECT*"  (cost=0.00..2000.00 rows=50000 width=28) (actual time=5.742..336.699 rows=50000.00 loops=1)
         Buffers: shared hit=50013
         WAL: records=1516 bytes=150084 buffers full=2
         ->  Function Scan on generate_series n  (cost=0.00..1750.00 rows=50000 width=24) (actual time=5.460..227.650 rows=50000.00 loops=1)
 Planning Time: 0.114 ms
 Execution Time: 767.179 ms

WAL 统计：

• 监控写入负载的日志生成量：WAL 缓冲区生成 1516 条日志，共 150084 个字节的数据。
• 诊断写入性能瓶颈：缓冲区被写满了 2 次。

并行查询优化​

EXPLAIN (ANALYZE)
SELECT * FROM orders WHERE customer_id IN (1, 2, 3, 4, 5, 6);

执行计划：

QUERY PLAN
-------------------------------------------------------------------------------------------------------------------------------------------------------
 Gather  (cost=2752.40..10357.99 rows=327855 width=18) (actual time=22.375..121.296 rows=330000.00 loops=1)
   Workers Planned: 2
   Workers Launched: 2
   Buffers: shared hit=3810
   ->  Parallel Bitmap Heap Scan on orders  (cost=2751.40..10029.13 rows=136606 width=18) (actual time=12.868..88.329 rows=110000.00 loops=3)
         Recheck Cond: (customer_id = ANY ('{1,2,3,4,5,6}'::integer[]))
         Rows Removed by Index Recheck: 53967
         Heap Blocks: exact=170 lossy=566
         Buffers: shared hit=3810
         Worker 0:  Heap Blocks: exact=387 lossy=957
         Worker 1:  Heap Blocks: exact=369 lossy=1055
         ->  Bitmap Index Scan on idx_orders_customer_id  (cost=0.00..2669.44 rows=327855 width=0) (actual time=21.219..21.220 rows=330000.00 loops=1)
               Index Cond: (customer_id = ANY ('{1,2,3,4,5,6}'::integer[]))
               Index Searches: 1
               Buffers: shared hit=266
 Planning:
   Buffers: shared hit=30
 Planning Time: 0.510 ms
 Execution Time: 158.523 ms

并行执行效率洞察：

• 每个工作进程的缓存统计详情：worker 0 命中 387 个精确块和 957 个有损块，worker 1 命中 369 个精确块和 1055 个有损块。
• 精确块与有损块分析：出现有损块说明可能 work_mem 太小导致 bitmap 无法精准定位元组。

技术优势与价值​

即时性能诊断​

• 降低门槛：自动化的缓冲区统计让初学者快速识别 I/O 问题。
• 深度洞察：为专家级用户提供更细粒度的性能数据。
• 全面覆盖：单条命令获取执行计划、缓存使用、索引效率等多维信息。

优化指导​

• 索引优化：通过精确的索引使用统计，避免过度索引或索引不足。
• 内存调优：根据有损块出现频率指导 work_mem 参数调整
• 查询重写：基于详细的执行成本数据优化 SQL 语句结构

功能未来展望​

尽管 PostgreSQL 18 的 EXPLAIN 增强带来了显著改进，但仍有一些方面可以进一步完善：

1. 输出可读性：随着信息量的增加，输出变得更加复杂，可能需要更好的格式化或可视化工具支持
2. 历史对比：缺乏直接与历史执行计划对比的内置机制，使得性能回归分析仍需依赖外部工具
3. 阈值警报：没有内置机制对异常值（如异常高的缓冲区读取）发出警告，需要手动分析
4. 执行计划可视化：文本形式的输出在复杂查询中仍难以直观理解，需要第三方工具补充

小结​

PostgreSQL 18 的 EXPLAIN 增强代表了数据库可观测性的重大进步。通过自动化收集关键性能指标并提供更深入的执行洞察，它显著降低了查询优化的门槛，同时为经验丰富的 DBA 提供了更强大的分析能力。

六、OAuth 2.0 认证支持：筑牢数据防护壁垒​

在安全方面，IvorySQL 致力于加入多种国密认证功能来保障数据安全。而这次 PostgreSQL18 在身份认证方面继续加强，引入对 OAuth 2 的支持。这是一种开放标准的授权协议，用于授权一个应用程序或服务访问用户在另一个应用程序中的资源，而无需提供用户名和密码。

该特性主要包含以下几个核心要素：

• OAuth2 验证器框架：提供了一个可扩展的框架，使 PostgreSQL 能够与 OAuth 2.0 提供程序集成。PostgreSQL 本身不实现具体的令牌验证算法（如 JWT 验证），而是将这项工作委托给一个外部共享库 (*.so 文件)。
• 客户端认证支持：libpq（PostgreSQL 的 C 客户端库）现在支持 OAuth 2.0 认证流程。
• 自定义验证逻辑：通过回调机制允许实现自定义的令牌验证和用户映射逻辑。