Encore 预装 PostgreSQL 扩展全指南开箱即用的 pgvector、PostGIS 与完整扩展清单【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encoreEncore 平台为 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:18PostgreSQL 18 内核。同一文件中还实现了镜像的本地管理逻辑ImageExists(ctx)通过docker image inspect检查镜像是否已存在于本地并对 Podman 的差异错误信息做了兼容cli/daemon/sqldb/docker/docker.goPullImage(ctx)在镜像缺失时执行docker pull encoredotdev/postgres:18cli/daemon/sqldb/docker/docker.go。也就是说当你第一次运行encore run时Encore 守护进程会自动检查并拉取该镜像随后基于它创建本地数据库集群——这些扩展也随之就绪。二、完整预装扩展清单以下为encoredotdev/postgres镜像预装并可用的全部扩展数据源自 docs/ts/primitives/database-extensions.md 的官方清单ExtensionVersionDescriptionrefint1.0functions for implementing referential integrity (obsolete)pg_buffercache1.3examine the shared buffer cachepg_freespacemap1.2examine the free space map (FSM)plpgsql1.0PL/pgSQL procedural languagecitext1.6data type for case-insensitive character stringsadminpack2.1administrative functions for PostgreSQLmoddatetime1.0functions for tracking last modification timeamcheck1.3functions for verifying relation integrityseg1.4data type for representing line segments or floating-point intervalspg_stat_statements1.10track planning and execution statistics of all SQL statements executedpg_trgm1.6text similarity measurement and index searching based on trigramsisn1.2data types for international product numbering standardsbtree_gist1.7support for indexing common datatypes in GiSTintarray1.5functions, operators, and index support for 1-D arrays of integerspg_surgery1.0extension to perform surgery on a damaged relationuuid-ossp1.1generate universally unique identifiers (UUIDs)insert_username1.0functions for tracking who changed a tablebloom1.0bloom access method - signature file based indexpgcrypto1.3cryptographic functionsdblink1.2connect to other PostgreSQL databases from within a databasetsm_system_rows1.0TABLESAMPLE method which accepts number of rows as a limitpg_prewarm1.2prewarm relation dataold_snapshot1.0utilities in support of old_snapshot_thresholdpageinspect1.11inspect the contents of database pages at a low levelintagg1.1integer aggregator and enumerator (obsolete)pg_visibility1.2examine the visibility map (VM) and page-level visibility infocube1.5data type for multidimensional cubestablefunc1.0functions that manipulate whole tables, including crosstabxml21.1XPath querying and XSLTfuzzystrmatch1.1determine similarities and distance between stringspg_walinspect1.0functions to inspect contents of PostgreSQL Write-Ahead Logbtree_gin1.3support for indexing common datatypes in GINsslinfo1.2information about SSL certificatestcn1.0Triggered change notificationshstore1.8data type for storing sets of (key, value) pairsdict_int1.0text search dictionary template for integersearthdistance1.1calculate great-circle distances on the surface of the Earthfile_fdw1.0foreign-data wrapper for flat file accessautoinc1.0functions for autoincrementing fieldsltree1.2data type for hierarchical tree-like structuresunaccent1.1text search dictionary that removes accentspgrowlocks1.2show row-level locking informationtsm_system_time1.0TABLESAMPLE method which accepts time in milliseconds as a limitdict_xsyn1.0text search dictionary template for extended synonym processingpgstattuple1.5show tuple-level statisticspostgres_fdw1.1foreign-data wrapper for remote PostgreSQL serverslo1.1Large Object maintenancepostgis_sfcgal-33.4.2PostGIS SFCGAL functionsaddress_standardizer_data_us-33.4.2Address Standardizer US dataset exampleaddress_standardizer-33.4.2Used to parse an address into constituent elements. Generally used to support geocoding address normalization step.postgis_topology-33.4.2PostGIS topology spatial types and functionspostgis-33.4.2PostGIS geometry and geography spatial types and functionspostgis_raster-33.4.2PostGIS raster types and functionspostgis_tiger_geocoder-33.4.2PostGIS tiger geocoder and reverse geocodervector0.7.0vector data type and ivfflat and hnsw access methodspostgis3.4.2PostGIS geometry and geography spatial types and functionsaddress_standardizer3.4.2Used to parse an address into constituent elements. Generally used to support geocoding address normalization step.postgis_topology3.4.2PostGIS topology spatial types and functionspostgis_tiger_geocoder3.4.2PostGIS tiger geocoder and reverse geocoderaddress_standardizer_data_us3.4.2Address Standardizer US dataset examplepostgis_sfcgal3.4.2PostGIS SFCGAL functionspostgis_raster3.4.2PostGIS raster types and functions注意镜像中 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从源码注释可以读出两层信息encore-superuser角色专门用于执行CREATE EXTENSION这类超出 migrator 权限的语句——印证了扩展启用属于超级用户级别操作本地开发环境中Encore 通过dbproxy将不同用户名映射到不同权限角色应用运行时的常规查询走服务用户连接池而管理类操作使用更高权限的通道。因此在实际使用中把CREATE EXTENSION写在迁移文件里是最稳妥的方式因为迁移由 Encore 以足够的权限执行而运行时服务角色默认并不具备创建扩展的权限。若你通过encore db shell手工连接数据库操作也应留意会话权限。四、重点扩展深度解读4.1 vectorpgvector 0.7.0AI 时代的向量检索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-3geometry、geography 类型及全套空间函数拓扑postgis_topology拓扑空间类型与函数栅格postgis_raster栅格数据类型与函数地理编码postgis_tiger_geocoder美国 TIGER 地理编码与逆地理编码地址标准化address_standardizer及address_standardizer_data_us地址解析与 US 数据集示例3D 扩展postgis_sfcgalSFCGAL 三维函数。对国内开发者而言最常用的是CREATE EXTENSION postgis;获得 geometry/geography 与距离、缓冲区等基础空间计算earthdistance1.1地表大圆距离计算与cube1.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检查空闲空间映射FSMpg_visibility1.2检查可见性映射VM与页级可见性信息pgstattuple1.5展示元组级统计用于评估表/索引膨胀pageinspect1.11底层检查数据库页面内容pg_walinspect1.0检查 PostgreSQL 预写日志WAL内容pgrowlocks1.2显示行级锁信息pg_prewarm1.2预加载关系数据到缓存old_snapshot1.0old_snapshot_threshold支持工具amcheck1.3校验关系完整性用于一致性巡检。4.5 数据类型与索引扩展citext1.6大小写不敏感字符串类型替代LOWER()函数的便捷方案hstore1.8键值对集合类型半结构化数据存储利器uuid-ossp1.1UUID 生成函数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.2SSL 证书信息查询。4.6 跨库访问与数据集成dblink1.2在数据库内连接其他 PostgreSQL 数据库postgres_fdw1.1远程 PostgreSQL 服务器的外部数据包装器FDW适合跨库联邦查询file_fdw1.0扁平文件访问的外部数据包装器可直接对 CSV 等文件执行 SQLtablefunc1.0整表操作函数包括经典的crosstab()行转列透视查询xml21.1XPath 查询与 XSLT 转换。4.7 触发器与审计辅助moddatetime1.0追踪最后修改时间自动更新modified_at列insert_username1.0追踪谁修改了表tcn1.0触发式变更通知autoinc1.0字段自增函数refint1.0/intagg1.1两者在清单中标注为 obsolete已过时仅作兼容保留。五、结合 Encore 数据库使用流程的实操5.1 定义数据库扩展只有在数据库存在时才有意义。在 EncoreTypeScript中数据库通过 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 迁移与扩展启用的先后顺序由于扩展本质上是数据库对象类型、函数、操作符、索引方法它们必须在任何使用这些对象的对象表、索引、函数体之前创建。因此请遵守将CREATE EXTENSION IF NOT EXISTS ...放在最靠前的迁移文件中后续迁移再创建依赖扩展的类型、表与索引迁移中避免使用扩展相关权限之外的操作保持文件幂等IF NOT EXISTS。5.3 用 CLI 验证扩展是否生效你可以通过 Encore CLI 提供的数据库命令检查扩展状态# 打开本地数据库的 psql shell默认只读权限 encore db shell todo # 查看当前数据库已安装的扩展 \dxencore db shell默认以只读权限连接本地开发环境数据库详见 docs/ts/primitives/databases.md 的 Using the Encore CLI 小节如需写权限可追加--write、--admin、--superuser等标志。在\dx输出中你可以确认vector、postgis等扩展已随迁移被正确启用。六、注意事项与边界预安装不等于已启用镜像只是把扩展文件放入 PostgreSQL 的共享目录每个数据库仍需单独执行CREATE EXTENSION才能真正使用对应扩展。这是 PostgreSQL 的既有语义——扩展是按数据库隔离启用的。版本与内核以上清单的扩展版本如 pgvector 0.7.0、PostGIS 3.4.2以当前仓库引用的镜像encoredotdev/postgres:18为准cli/daemon/sqldb/docker/docker.go。镜像更新时扩展版本可能随之变化应以实际环境查询结果为准。权限边界CREATE EXTENSION属于超级用户级操作runtimes/go/storage/sqldb/test_db.go 中encore-superuser的注释明确以CREATE EXTENSION为例运行时服务角色无法执行请把扩展启用放在迁移文件中完成。本地与云端一致性由于本地开发、CI/CD 与 Encore Cloud 使用同一镜像你在本地迁移中启用扩展后部署到云端同样可用无需额外配置。过时扩展清单中的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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考