企业官网建设流程全解析

• 文档
• 教程
• 知识库

PostgreSQL 中的 Schema（模式）是组织表、视图、函数等数据库对象的命名空间，但每次执行create table时数据库是如何知道对象该落到哪个 Schema 下的？答案就藏在会话级的search_path配置中。本文以 til 仓库中 postgres/default-schema.md 为核心，结合仓库内多个相关 PostgreSQL 笔记，完整讲解 Schema 的查看、默认 Schema 的裁决逻辑、$user与public的协作方式，以及搜索路径失效时的报错与排查方法。

一、Schema：数据库内的对象命名空间

PostgreSQL 使用 Schema 在同一个数据库中隔离和组织对象。库内的表、索引、函数、类型等对象都归属于某一个 Schema，两个不同 Schema 下可以存在同名对象而互不冲突。这也是多租户、多模块项目常见的一种组织方式——例如仓库中 postgres/list-all-columns-of-a-specific-type.md 就提到，应用的表通常都建在publicSchema 下，查询时通过table_schema = 'public'过滤。

查看当前数据库里究竟有哪些 Schema，可以直接查询标准视图information_schema.schemata：

> select schema_name from information_schema.schemata; schema_name -------------------- pg_toast pg_temp_1 pg_toast_temp_1 pg_catalog public information_schema (6 rows)

从结果可以看到，一个新建数据库中至少包含三类 Schema：

• 系统 Schema：pg_catalog（系统目录）、pg_toast（TOAST 辅助表）等，以pg_前缀开头，由 PostgreSQL 内部使用；
• 信息 Schema：information_schema，提供跨数据库兼容的标准元数据视图；
• 用户 Schema：public，即默认情况下用户对象的落脚点。

如果只想快速查看用户创建的 Schema，可以在 psql 会话中使用\dn元命令；加上S参数（\dnS）则会把系统 Schema 也一并列出，详见仓库中的 postgres/list-available-schemas.md。

补充：pg_前缀是系统保留的，用户不能创建以pg_开头的 Schema。尝试执行create schema pg_cannot_do_this;会得到unacceptable schema name错误，具体报错细节可参考仓库中的 postgres/pg-prefix-is-reserved-for-system-schemas.md。

二、核心问题：create table时对象建到哪里？

Schema 既然这么多，当你执行create table posts (...)时，PostgreSQL 如何决定把这张表放进哪个 Schema？答案是：检查会话的search_path（搜索路径）。

> show search_path; search_path ----------------- "$user", public (1 row)

默认情况下，search_path的值是"$user", public，由两个元素组成，逗号分隔、按顺序排列：

1. $user：一个占位符，会被替换为当前连接用户的用户名。如果存在与该用户名同名的 Schema，它就会被选中；
2. public：数据库自带的公共 Schema，作为兜底。

回到前面select schema_name from information_schema.schemata的输出——当前连接的数据库里并不存在与用户名同名的 Schema（列表中没有形如用户名命名的条目），因此第一个可用的元素是public，PostgreSQL 便会把未限定名称的表建在public下。

三、搜索路径的裁决逻辑

search_path本质上是一个按优先级排列的 Schema 名称列表。当 SQL 语句中出现了未限定（不带 Schema 前缀）的对象名时，PostgreSQL 会从左到右依次检查每个 Schema：

• 对于创建操作（如create table posts）：选择列表中第一个真实存在的 Schema 作为落点；
• 对于读取操作（如select * from posts）：在列表中依次查找能匹配到该名称对象的 Schema，找到即用。

所以默认组合"$user", public的实际效果是：如果你的用户名恰好是一个 Schema 名，优先使用它；否则退回public。对绝大多数开发环境而言，用户名与 Schema 名并不重合，最终对象都会落到public下。这也解释了为什么在仓库笔记 postgres/list-database-objects-with-disk-usage.md 中，用\dt+列出关系时每一行表都显示Schema = public。

四、当搜索路径无法解析时会发生什么

如果把search_path改成一组无法解析为任何真实 Schema 的值，创建对象就会直接失败。文档演示了最极端的场景——把搜索路径只设置为$user，而当前库中并没有与用户名同名的 Schema：

> set search_path = '$user'; SET > create table posts (...); ERROR: no schema has been selected to create in

ERROR: no schema has been selected to create in这条报错信息非常直白：搜索路径中没有任何一个条目能对应到真实存在的 Schema，PostgreSQL 无从决定新表的归属。此时：

• 已经SET成功的会话级search_path生效范围仅限当前会话，断开连接即恢复默认值；
• 排查时先执行show search_path;确认当前值，再对照select schema_name from information_schema.schemata;检查每个条目是否真实存在；
• 也可以执行select current_schema();查看当前会话实际使用的 Schema 是什么。

五、search_path的实用操作与常见坑

围绕search_path，实际开发中还有几个高频场景值得掌握：

1. 临时修改会话搜索路径

set search_path = public, app; set search_path = 'app, public'; -- 与上一行等价，逗号写法两种皆可 set search_path = app, public;

注意：若 Schema 名称中包含特殊字符，或想避免与关键字歧义，应使用引号包裹，例如set search_path = "MySchema", public;。

2. 修改数据库或角色的默认搜索路径

会话级set只对当前会话生效。若希望某数据库或某角色的所有新会话都默认使用特定搜索路径，可以持久化配置：

alter database my_db set search_path to app, public; alter role my_role set search_path to app, public;

3. 临时表与pg_temp的隐式优先级

PostgreSQL 有一个容易被忽略的细节：临时表所在的临时 Schema（如pg_temp_1）会被隐式插入到搜索路径的最前面，因此未限定名称的查询总是优先命中临时表。这正是仓库中 postgres/temporary-tables.md 所记录的临时表行为——create temp table posts建出的表只存在于会话期内的临时 Schema 中，会话结束即消失，并且不会被 autovacuum 自动清理。

4.pg_catalog总是被隐式优先搜索

无论search_path如何设置，系统目录pg_catalog都会先于列表中的元素被搜索（除非被显式放置在搜索路径更靠前的位置）。这意味着即使把search_path设为'$user'这种"残缺"值，系统函数与系统目录对象依然能被正常解析——真正无法解析的是你新建的业务对象，这正好与文档中的报错场景吻合。

5. 用\dt+确认对象的真实 Schema

当对象落点不确定时，用 psql 元命令\dt+查看所有表，输出会带出Schema列，一目了然；更多用法见仓库中的 postgres/list-database-objects-with-disk-usage.md。

6. 批量创建 Schema 的场景

在多 Schema 项目的初始化阶段，可以用\gexec批量执行create schema语句，再通过\dn验证结果，具体示例可参考仓库中的 postgres/create-and-execute-sql-statements-with-gexec.md。

六、小结

PostgreSQL 的"默认 Schema"并不是一个固定的库内常量，而是由search_path实时裁决的动态结果：

理解search_path的裁决顺序，不仅能解释"表为什么建到了 public"，更能帮助你在多 Schema 架构、临时表调试、以及alter database/alter role持久化配置时准确预判对象的最终归属。若需继续深入，可以在本仓库的 postgres 目录下查阅 Schema 列表查看、临时表、pg_前缀保留等系列笔记。

• 文档
• 教程
• 知识库