Encore 预装 PostgreSQL 扩展全指南：开箱即用的 pgvector、PostGIS 与完整扩展清单

Encore 预装 PostgreSQL 扩展全指南：开箱即用的 pgvector、PostGIS 与完整扩展清单

【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore

Encore 平台为 TypeScript/Go 应用内置了 PostgreSQL 数据库支持，其本地开发、CI/CD 以及 Encore Cloud 托管的数据库统一基于encoredotdev/postgresDocker 镜像运行，该镜像预装了 60+ 个 PostgreSQL 扩展，包括 pgvector、PostGIS 等。本文以 docs/ts/primitives/database-extensions.md 为主线，为你完整梳理这份扩展清单、如何通过CREATE EXTENSION启用它们，并结合仓库源码解释镜像的管理机制与权限模型，帮助你在 Encore 应用中直接使用向量检索、地理空间、全文搜索等能力，而无需自行编译或安装任何扩展。

一、背景：Encore 的数据库镜像从何而来

Encore 将 SQL 数据库视为逻辑资源，原生支持 PostgreSQL。无论你是在本地执行encore run进行开发，还是在 CI/CD 流水线中运行测试，抑或是部署到 Encore Cloud，底层数据库都来自同一个 Docker 镜像：encoredotdev/postgres。

这个镜像决定了你手头数据库"与生俱来"的能力。镜像本身预装了大量 PostgreSQL 官方贡献扩展（contrib modules）与第三方知名扩展，安装完成后即可通过标准的CREATE EXTENSION语句直接启用，无需下载源码、编译或手动放入pg_extension目录。

从当前仓库源码可以确认该镜像的具体版本：cli/daemon/sqldb/docker/docker.go 中定义了常量：

const Image = "encoredotdev/postgres:18"

即当前使用的镜像标签为encoredotdev/postgres:18（PostgreSQL 18 内核）。同一文件中还实现了镜像的本地管理逻辑：

• ImageExists(ctx)：通过docker image inspect检查镜像是否已存在于本地，并对 Podman 的差异错误信息做了兼容（cli/daemon/sqldb/docker/docker.go）；
• PullImage(ctx)：在镜像缺失时执行docker pull encoredotdev/postgres:18（cli/daemon/sqldb/docker/docker.go）。

也就是说，当你第一次运行encore run时，Encore 守护进程会自动检查并拉取该镜像，随后基于它创建本地数据库集群——这些扩展也随之就绪。

二、完整预装扩展清单

以下为encoredotdev/postgres镜像预装并可用的全部扩展（数据源自 docs/ts/primitives/database-extensions.md 的官方清单）：

注意：镜像中 PostGIS 系列同时以带-3后缀（如postgis-3）和标准名（如postgis）两种形式提供，两者版本一致（3.4.2）。这与 PostgreSQL 的扩展命名规范有关——PostGIS 的扩展包名中嵌入了主版本号。你只需要CREATE EXTENSION postgis;即可获得完整的地理空间能力。

三、如何启用扩展：从CREATE EXTENSION到迁移文件

3.1 标准的启用方式

镜像中的扩展都是"预安装"的，意味着扩展的控制文件（.control）、SQL 脚本和动态库均已就位，你只需要在目标数据库中执行：

CREATE EXTENSION IF NOT EXISTS vector; -- 启用 pgvector CREATE EXTENSION IF NOT EXISTS postgis; -- 启用 PostGIS CREATE EXTENSION IF NOT EXISTS pg_trgm; -- 启用三元组模糊搜索

IF NOT EXISTS用于保证幂等性，这在迁移文件被重复执行时尤其重要。

3.2 在 Encore 迁移文件中启用

Encore 使用纯 SQL 迁移文件（<number>_<name>.up.sql）定义数据库结构，扩展启用自然也是迁移的一部分。在 docs/ts/primitives/databases.md 中可以看到标准做法：在服务目录下创建migrations目录，迁移文件按序号递增命名，例如：

/my-app └── todo └── migrations ├── 1_enable_extensions.up.sql └── 2_create_table.up.sql

其中1_enable_extensions.up.sql可以这样写：

-- 启用 pgvector，用于向量相似度检索 CREATE EXTENSION IF NOT EXISTS vector; -- 启用 pg_trgm，用于模糊文本匹配 CREATE EXTENSION IF NOT EXISTS pg_trgm;

Encore 会自动按顺序应用所有up迁移（down迁移需要手动执行）。一旦迁移成功应用，扩展的数据类型、函数与操作符便对应用可用——例如你可以在随后的迁移或运行时查询中使用vector类型创建带 HNSW/IVFFlat 索引的表：

CREATE TABLE IF NOT EXISTS embeddings ( id BIGSERIAL PRIMARY KEY, content TEXT, embedding vector(1536) -- pgvector 向量列 ); CREATE INDEX ON embeddings USING hnsw (embedding vector_cosine_ops);

在仓库中也可以找到类似的迁移实践证据：docs/ts/migration/express-migration.md 中展示了在迁移初始化脚本里执行CREATE EXTENSION IF NOT EXISTS postgis;的示例。

3.3 权限模型：谁有资格执行CREATE EXTENSION

扩展启用通常需要较高的数据库权限，这一点在 Encore 的运行时源码中有明确体现。runtimes/go/storage/sqldb/test_db.go 中定义了本地代理映射的三类角色：

// migratorUser is the username the local dbproxy maps to the migrator // role. We use it for CREATE/DROP DATABASE in test setup/teardown ... const migratorUser = "encore-migrator" // superuserUser is the username the local dbproxy maps to the superuser // role. Used for statements that require privileges beyond the migrator // role (e.g. CREATE EXTENSION). const superuserUser = "encore-superuser"

从源码注释可以读出两层信息：

1. encore-superuser角色专门用于执行CREATE EXTENSION这类超出 migrator 权限的语句——印证了扩展启用属于超级用户级别操作；
2. 本地开发环境中，Encore 通过dbproxy将不同用户名映射到不同权限角色，应用运行时的常规查询走服务用户连接池，而管理类操作使用更高权限的通道。

因此在实际使用中：把CREATE EXTENSION写在迁移文件里是最稳妥的方式，因为迁移由 Encore 以足够的权限执行；而运行时服务角色默认并不具备创建扩展的权限。若你通过encore db shell手工连接数据库操作，也应留意会话权限。

四、重点扩展深度解读

4.1 vector（pgvector 0.7.0）：AI 时代的向量检索

vector扩展是当前智能应用（RAG、语义搜索、推荐系统）的核心依赖，版本 0.7.0，提供：

• vector数据类型（固定/可变维度浮点向量）；
• ivfflat与hnsw两种近似最近邻（ANN）访问方法；
• 配套的向量距离操作符（<->欧氏距离、<=>余弦距离、<#>负内积）与索引操作符类（vector_l2_ops、vector_cosine_ops、vector_ip_ops）。

这意味着你在 Encore 应用里做"AI 应用"时，无需任何外部向量数据库——直接在 PostgreSQL 表中存储 embedding 并执行ORDER BY embedding <=> $1 LIMIT 10即可完成语义检索。docs/ts/primitives/databases.md 也专门指出 pgvector 与 PostGIS 是镜像中特别强调的两大能力。

4.2 PostGIS 3.4.2：完整的地理空间能力

PostGIS 系列在镜像中以 8 个扩展名出现，覆盖：

• 核心空间类型：postgis/postgis-3（geometry、geography 类型及全套空间函数）；
• 拓扑：postgis_topology（拓扑空间类型与函数）；
• 栅格：postgis_raster（栅格数据类型与函数）；
• 地理编码：postgis_tiger_geocoder（美国 TIGER 地理编码与逆地理编码）；
• 地址标准化：address_standardizer及address_standardizer_data_us（地址解析与 US 数据集示例）；
• 3D 扩展：postgis_sfcgal（SFCGAL 三维函数）。

对国内开发者而言，最常用的是CREATE EXTENSION postgis;获得 geometry/geography 与距离、缓冲区等基础空间计算；earthdistance（1.1，地表大圆距离计算）与cube（1.5，多维立方体）可作为轻量补充。

4.3 文本搜索与模糊匹配

• pg_trgm1.6：基于三元组（trigram）的文本相似度度量与索引检索，支持similarity()、%操作符，可加速LIKE '%xxx%'与模糊搜索；
• unaccent1.1：去除重音符号的文本搜索字典，适合多语言场景的规范化；
• fuzzystrmatch1.1：提供levenshtein()、soundex()、metaphone()等字符串相似度与距离函数；
• dict_int1.0、dict_xsyn1.0：整数与扩展同义词处理文本搜索字典模板；
• ltree1.2：层级树状结构数据类型，适合组织架构、分类树等场景。

4.4 性能监控与诊断

• pg_stat_statements1.10：跟踪所有 SQL 语句的规划与执行统计，是性能分析的首选扩展；
• pg_buffercache1.3：检查共享缓冲区缓存内容；
• pg_freespacemap1.2：检查空闲空间映射（FSM）；
• pg_visibility1.2：检查可见性映射（VM）与页级可见性信息；
• pgstattuple1.5：展示元组级统计，用于评估表/索引膨胀；
• pageinspect1.11：底层检查数据库页面内容；
• pg_walinspect1.0：检查 PostgreSQL 预写日志（WAL）内容；
• pgrowlocks1.2：显示行级锁信息；
• pg_prewarm1.2：预加载关系数据到缓存；
• old_snapshot1.0：old_snapshot_threshold支持工具；
• amcheck1.3：校验关系完整性，用于一致性巡检。

4.5 数据类型与索引扩展

• citext1.6：大小写不敏感字符串类型，替代LOWER()函数的便捷方案；
• hstore1.8：键值对集合类型，半结构化数据存储利器；
• uuid-ossp1.1：UUID 生成函数（uuid_generate_v4()等）；
• pgcrypto1.3：密码学函数（哈希、加密、随机数），如crypt()/gen_salt()用于口令哈希；
• btree_gist1.7 /btree_gin1.3：为常见数据类型提供 GiST/GIN 索引支持，可显著加速tsvector之外的范围、数组等查询；
• intarray1.5：一维整数数组的函数、操作符与索引支持；
• bloom1.0：基于签名文件的布隆过滤索引访问方法；
• seg1.4：线段/浮点区间数据类型；
• isn1.2：国际产品编号标准（ISBN/ISSN 等）数据类型；
• lo1.1：大对象维护；
• sslinfo1.2：SSL 证书信息查询。

4.6 跨库访问与数据集成

• dblink1.2：在数据库内连接其他 PostgreSQL 数据库；
• postgres_fdw1.1：远程 PostgreSQL 服务器的外部数据包装器（FDW），适合跨库联邦查询；
• file_fdw1.0：扁平文件访问的外部数据包装器，可直接对 CSV 等文件执行 SQL；
• tablefunc1.0：整表操作函数，包括经典的crosstab()行转列透视查询；
• xml21.1：XPath 查询与 XSLT 转换。

4.7 触发器与审计辅助

• moddatetime1.0：追踪最后修改时间（自动更新modified_at列）；
• insert_username1.0：追踪"谁修改了表"；
• tcn1.0：触发式变更通知；
• autoinc1.0：字段自增函数；
• refint1.0/intagg1.1：两者在清单中标注为 obsolete（已过时），仅作兼容保留。

五、结合 Encore 数据库使用流程的实操

5.1 定义数据库

扩展只有在数据库存在时才有意义。在 Encore（TypeScript）中，数据库通过 runtimes/js/encore.dev/storage/sqldb/database.ts 暴露的SQLDatabase类声明：

import { SQLDatabase } from "encore.dev/storage/sqldb"; const db = new SQLDatabase("todo", { migrations: "./migrations", });

源码中SQLDatabase构造函数调用runtime.RT.sqlDatabase(name)完成资源注册，static named()用于引用已存在的数据库。声明后，encore run会基于encoredotdev/postgres:18镜像自动创建本地数据库并应用迁移。

5.2 迁移与扩展启用的先后顺序

由于扩展本质上是数据库对象（类型、函数、操作符、索引方法），它们必须在任何使用这些对象的对象（表、索引、函数体）之前创建。因此请遵守：

1. 将CREATE EXTENSION IF NOT EXISTS ...放在最靠前的迁移文件中；
2. 后续迁移再创建依赖扩展的类型、表与索引；
3. 迁移中避免使用扩展相关权限之外的操作，保持文件幂等（IF NOT EXISTS）。

5.3 用 CLI 验证扩展是否生效

你可以通过 Encore CLI 提供的数据库命令检查扩展状态：

# 打开本地数据库的 psql shell（默认只读权限） encore db shell todo # 查看当前数据库已安装的扩展 \dx

encore db shell默认以只读权限连接本地开发环境数据库（详见 docs/ts/primitives/databases.md 的 "Using the Encore CLI" 小节）；如需写权限，可追加--write、--admin、--superuser等标志。在\dx输出中，你可以确认vector、postgis等扩展已随迁移被正确启用。

六、注意事项与边界

1. "预安装"不等于"已启用"：镜像只是把扩展文件放入 PostgreSQL 的共享目录，每个数据库仍需单独执行CREATE EXTENSION才能真正使用对应扩展。这是 PostgreSQL 的既有语义——扩展是按数据库隔离启用的。
2. 版本与内核：以上清单的扩展版本（如 pgvector 0.7.0、PostGIS 3.4.2）以当前仓库引用的镜像encoredotdev/postgres:18为准（cli/daemon/sqldb/docker/docker.go）。镜像更新时，扩展版本可能随之变化，应以实际环境查询结果为准。
3. 权限边界：CREATE EXTENSION属于超级用户级操作（runtimes/go/storage/sqldb/test_db.go 中encore-superuser的注释明确以CREATE EXTENSION为例），运行时服务角色无法执行，请把扩展启用放在迁移文件中完成。
4. 本地与云端一致性：由于本地开发、CI/CD 与 Encore Cloud 使用同一镜像，你在本地迁移中启用扩展后，部署到云端同样可用，无需额外配置。
5. 过时扩展：清单中的refint、intagg已标记为 obsolete，仅作向后兼容保留，新项目不建议使用。

总而言之，Encore 通过统一的encoredotdev/postgres镜像把 PostgreSQL 生态中最常用的扩展能力"零成本"交到了开发者手中——从 pgvector 的向量检索、PostGIS 的空间计算，到pg_trgm的模糊搜索与pg_stat_statements的性能诊断，全部通过迁移文件里的一行CREATE EXTENSION即可启用，让数据库能力与 Encore 的自动化部署、托管流程无缝衔接。

【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore