PostgreSQL search_path 完全指南：从原理到多租户与安全避坑

1. search_path 是什么：一个被低估的"默认目录"机制

1.1 从一次误插数据的经历说起

先讲一个我早年间踩过的坑。当时我维护一个订单系统，数据库里有两个模式（Schema），一个是 public，存放着核心业务表 orders；另一个是 archive，用于存放历史归档数据，里面也有一张结构几乎相同的 orders 表。某天半夜在做数据归档脚本时，我执行了一段非常普通的 SQL：INSERT INTO orders SELECT * FROM temp_orders;。结果第二天发现，数据没有进到 public.orders，反而全部插进了 archive.orders。当时整个人都是懵的——SQL 语法完全没写错，连表名都没带前缀，怎么就插错地方了？

后来排查半天，发现原因就是会话的 search_path 被改成了 archive, public。执行插入时，PostgreSQL 按照 search_path 里的顺序找 orders 表，archive 排在前面，自然就命中了归档表。从那以后，我再也不敢小看这个默认路径配置。

简单来说，search_path（搜索路径）就是 PostgreSQL 解析未加模式名前缀的对象时，去哪些模式里依次查找的配置项。它决定了你写 SELECT * FROM users 时，系统最终查到的是 public.users 还是 app.users，也决定了 CREATE TABLE users 会把表建在哪个模式里。它是数据库对象解析的"默认目录"，看不见摸不着，却在每一次 SQL 执行背后默默起着决定性作用。

1.2 模式（Schema）与 search_path 的关系

要真正理解 search_path，先得理解模式（Schema）。如果用文件系统来类比，数据库实例（Instance）像一块硬盘，数据库（Database）像一个分区，而模式就像是分区里的目录。表、视图、函数、序列这些对象，全部存放在某个具体的模式下。 PostgreSQL 里访问一个对象的完整写法是 模式名.对象名，比如 public.users。如果你只写 users，数据库就需要通过 search_path 来确定它到底在哪个目录里。

这种设计在 MySQL 里是不存在的——MySQL 的逻辑结构是"实例-数据库-表"三层，USE database_name 切换的就是数据库本身。而 PostgreSQL 是"实例-数据库-模式-表"四层结构，连接建立时绑定的是某个数据库，真正决定表在哪的却是模式。所以 search_path 是 PostgreSQL 里绕不开的核心概念，无论你是开发者、DBA 还是数据工程师，只要在 PostgreSQL 上写过 SQL，就必然跟它打过交道，区别只是你有没有意识到而已。

2. search_path 的底层行为：命名解析规则与优先级

2.1 PostgreSQL 如何按 search_path 找对象

search_path 的值是一个逗号分隔的模式名列表。当你执行一条不带模式前缀的 SQL 语句时，PostgreSQL 会严格按照列表顺序去查找目标对象。

假设当前会话执行：

sql复制SET search_path = app, public, pg_catalog;
SELECT * FROM users;

解析过程大致是这样：

1. 先在 app 模式下查找是否有 users 这张表。有则直接复用，语句解析结束。
2. app 下找不到，再去 public 下查找。
3. public 下也找不到，去 pg_catalog 下查找。
4. 所有列出的模式都找遍了还是没有，抛出 relation "users" does not exist 错误。

这里有一个非常关键、也是很多人容易忽视的点：search_path 的解析过程对已经存在的对象是"惰性"的。也就是说，PostgreSQL 在第一次解析语句时，会根据当时的 search_path 把对象确定下来，并缓存执行计划。如果之后你改了 search_path，之前准备好的语句（特别是预编译语句 Prepared Statement）可能仍然绑定着旧的对象。

我再举个例子来说明这种"惰性"的影响。假如执行了：

sql复制PREPARE my_query AS SELECT * FROM users;
SET search_path = other_schema;
EXECUTE my_query;

EXECUTE 时用的是 PREPARE 时的解析结果，也就是旧路径下的 users 表，而不是新的 other_schema.users。这个问题在 ORM 框架使用连接池时尤其隐蔽，后面我们细说。

另一个核心行为是：pg_catalog 永远最先被隐式搜索。即使你的 search_path 是 app, public，系统也会先查 pg_catalog，再查 app，再查 public。这是为了保证系统目录对象（比如 pg_class 这种系统表）不会被用户自定义的同名对象遮蔽。如果你把 pg_catalog 手动放在最前面，PostgreSQL 会给出警告：WARNING: ignoring search_path "pg_catalog, public" because it contains "pg_catalog" before any user table。简单地说，pg_catalog 类似系统内置的"底层目录"，永远有最高优先级。

2.2 为什么"当前用户同名模式"