尧图网页设计 
Postgres Language Server基于 libpg_query 的 Postgres 语言工具链与 LSP 实现【免费下载链接】postgres_lspA Language Server for Postgres项目地址: https://gitcode.com/GitHub_Trending/po/postgres_lspPostgres Language Serverpostgres_lsp是一套面向 Postgres 开发的完整语言工具链它基于 Postgres 官方解析器libpg_query构建通过 Language Server ProtocolLSP、CLI、HTTP API 与 WebAssembly 多种通道提供服务涵盖自动补全、Hover、语法诊断、类型检查、格式化、迁移 lint 与数据库 lint 等能力。本文将以仓库 README.md 为主线结合 docs/ 下的功能文档与crates/源码实现讲解项目架构、安装方式、配置文件、CLI 用法与各核心功能帮助你在编辑器与 CI 中落地这套 SQL 工具链。项目概览一个 Server-Client 架构的 Postgres 工具链README 对项目的定位非常明确A collection of language tools and a Language Server Protocol (LSP) implementation for Postgres即一组 Postgres 语言工具 一份 LSP 实现核心目标是提升开发者体验并提供可靠的 SQL 工具。项目在设计上有两个关键决策构建在 Postgres 官方解析器之上项目直接复用libpg_query由 pganalyze 维护的 Postgres 解析器提取版确保对 SQL 语法的100% 兼容——不会出现自定义解析器跟不上 PG 语法演进的问题。这一点在根目录 Cargo.toml 中有直接证据workspace 依赖声明了pg_query 6.1.0对应 Postgres 17 的解析能力pgls_pretty_print_codegen/postgres/17-6.1.0 目录下存放着对应的.proto与.h解析定义。Server-Client 架构、传输层无关所有能力既可以通过 LSP 暴露给编辑器也可以通过 CLI 暴露给终端与 CI。README 还提到未来所有功能都会通过CLI、HTTP API 和 WebAssembly 模块访问——仓库中 pgls_wasm crate 以及packages/postgres-language-server/下的 npm 包正是这一方向的实现。从工作区结构看Cargo.toml 声明了members [crates/*, xtask/codegen, xtask/rules_check, docs/codegen]整个项目由约 30 个pgls_*crate 组成职责分层清晰解析与语法层pgls_query、pgls_lexer、pgls_treesitter编辑器能力层pgls_completions、pgls_hover分析层pgls_analyser迁移 lint、pgls_pglinter、pgls_splinter数据库 lint、pgls_typecheck格式化pgls_pretty_print交互层pgls_cli、pgls_lsp、pgls_workspace。核心功能矩阵README 列出当前可用的功能每项都有对应的功能文档与实现 crate功能说明相关文档相关实现自动补全与 Hover连接数据库后基于 schema 提供上下文感知补全与悬停信息editor_features.mdpgls_completions、pgls_hover语法诊断基于官方解析器的语法错误提示syntax_diagnostics.mdpgls_analyser类型检查通过EXPLAIN获取 Postgres 的真实校验结果type_checking.mdpgls_typecheck格式化SQL 代码格式化formatting.mdpgls_pretty_print迁移 Lint对 SQL 迁移文件做静态规则检查linting.mdpgls_pglinter24 个规则文件数据库 Lint直连数据库检查实际 schema 状态database_linting.mdpgls_splinter26 个规则文件PL/pgSQL 支持存储过程/函数语言支持plpgsql.mdpgls_plpgsql_check安装与启动根据 getting_started.mdPostgres Language Server 有三种安装形态作为项目开发依赖、作为独立可执行文件、或作为编辑器扩展。1. 作为 npm 开发依赖安装pnpm add -D -E postgres-language-server/cli对应包在仓库中的packages/postgres-language-server/cli/目录含package.json。-E用于锁定精确版本避免工具链行为随版本漂移。2. 编辑器扩展方式安装大多数 编辑器集成 会自动管理二进制安装无需手动干预。仓库根目录的postgres-language-server.jsonc与packages/postgres-language-server/wasm/还提供了基于 WebAssembly 的浏览器端能力。3. 独立可执行文件方式参见 manual_installation.md适合 CI runner 或无法使用包管理器的环境。从源码构建开发模式README 的 Development 小节给出了两条命令nix develop # 或跳过不使用 Nix 时 docker-compose up -d # 启动本地依赖如测试用 Postgres配置文件postgres-language-server.jsonc官方推荐为每个项目创建postgres-language-server.jsonc配置文件。好处有两点一是省去重复的 CLI 参数二是保证编辑器与 CLI 使用一致的配置部分选项如allowStatementExecutionsAgainst只能通过配置文件设置。该步骤是可选的——接受默认值就不需要配置文件。在项目根目录运行init命令即可生成默认配置getting_started.mdpostgres-language-server init生成的默认配置内容如下摘自 getting_started.md{ $schema: https://pg-language-server.com/latest/schema.json, vcs: { enabled: false, clientKind: git, useIgnoreFile: false }, files: { ignore: [] }, linter: { enabled: true, rules: { recommended: true } }, db: { host: 127.0.0.1, port: 5432, username: postgres, password: postgres, database: postgres, connTimeoutSecs: 10, allowStatementExecutionsAgainst: [127.0.0.1/*, localhost/*] } }各配置段说明$schema指向 JSON Schema 以启用编辑器补全与校验可以把latest换成具体版本例如https://pg-language-server.com/0.0.0/schema.json以固定配置校验规则。仓库内置的 schema 由 docs/codegen 生成最终产物见 docs/schema.json。vcs是否与 VCS当前支持git集成、是否读取.gitignore之类的 ignore 文件。对应 CLI 的--vcs-enabled、--vcs-client-kind、--vcs-use-ignore-file、--vcs-root、--vcs-default-branch等参数见 cli.md。files.ignore需要跳过的文件列表。linter迁移 lint 开关与规则配置详见下文迁移 Lint。db数据库连接。connTimeoutSecs默认 10 秒allowStatementExecutionsAgainst是安全白名单限定允许向哪些数据库地址实际执行语句如类型检查的EXPLAIN默认仅放行本机。生成配置文件后务必把数据库连接改成你的本地开发库。查看全部选项可运行postgres-language-server --help。配置的加载与优先级从源码可以确认配置解析的真实行为。pgls_cli/src/lib.rs 的prepare_with_config展示了完整加载链从文件系统加载postgres-language-server.jsonc若--config-path未指定则走默认解析见 cli_options.rs 的ConfigurationPathHint检测到旧版配置文件名时会打印弃用警告提示改用postgres-language-server.jsonc环境变量如数据库相关环境变量覆盖配置文件显式 CLI 参数优先级最高——配置文件 环境变量 CLI 参数。这正是 getting_started.md 所述CLI options take precedence over what is loaded from postgres-language-server.jsonc的源码级印证。CLI 使用指南check 命令一站式检查CLI 的核心命令是check对给定文件或路径执行全部检查语法、lint、类型检查等# 检查单个文件 postgres-language-server check myfile.sql # 检查目录例如迁移目录 postgres-language-server check supabase/migrations不带路径时会回退到当前工作目录见 check.rs。check的退出码由 enforce_exit_codes 决定存在错误时非零退出--error-on-warnings时警告也会导致非零退出非常适合 CI。全局 CLI 选项以下是 cli.md 中适用于所有命令的全局选项对应源码 cli_options.rs选项取值默认说明--colorsoff\|forceauto关闭或强制 ANSI 彩色输出--use-server布尔false连接到已运行的 daemon 服务器--skip-db布尔—跳过数据库连接只跑不依赖数据库的检查--verbose布尔false打印额外诊断与文件处理详情--config-pathPATH—指定配置文件路径或目录会禁用默认配置解析--max-diagnosticsnone\|NUMBER20限制显示诊断条数none取消限制--skip-errors布尔—跳过含语法错误的文件而不是报错--no-errors-on-unmatched布尔—没有文件被处理时也不报错--error-on-warnings布尔—有警告时以非零退出码结束--reporterjson\|json-pretty\|github\|junit\|summary\|gitlabdefault切换诊断与摘要的输出格式--log-levelnone\|debug\|info\|warn\|errornone日志级别同时支持PGT_LOG_LEVEL/PGLS_LOG_LEVEL环境变量--log-kindpretty\|compact\|jsonpretty日志格式--diagnostic-levelinfo\|warn\|errorinfo只显示等于或高于该级别的诊断其中--reporter的多种输出格式在源码 CliReporter 中有完整枚举github输出 GitHub Workflow commands 格式、gitlab输出 GitLab Code Quality 报告格式、junit用于 CI 集成、json/json-pretty供程序消费、summary只打印统计。这些 reporter 的实现位于 pgls_cli/src/reporter/ 下并有对应的快照测试见 pgls_cli/tests/snapshots/。check 专属选项check命令还支持以下专属参数cli.md--stdin-file-pathPATH从 stdin 读取代码并按扩展名检查例如echo SELECT 1 | postgres-language-server check --stdin-file-pathtest.sql文件不必真实存在扩展名决定处理方式。实现见 check.rs 的read_stdin_payload与 execute/stdin.rs。--staged只检查已暂存staged的文件适合本地提交前检查。--changed只检查相对defaultBranch有变更的文件适合 CI。--sinceREF配合--changed指定对比基准分支当配置文件中未设置defaultBranch时。注意--since与--changed/--staged存在互斥校验check.rs 的validate_args会拒绝非法组合。数据库连接参数--connection-stringlibpq 连接串设置后覆盖下面的单项参数、--host、--port、--username、--password、--database、--conn_timeout_secs默认 10。--migrations-dir/--after指定迁移目录与时间戳用于跳过此前的迁移文件。daemon 与 lsp-proxyCLI 还包含一组服务类命令cli.mdstart启动 daemon 服务器进程支持--log-path、--log-prefix-name默认日志前缀server.log可用环境变量PGT_LOG_PATH/PGT_LOG_PREFIX_NAME覆盖。结合--use-server可以让后续 CLI 调用复用已运行的 daemon。stop停止 daemon。clean清理 daemon 产生的日志。lsp-proxy作为 LSP 服务器在 stdin/stdout 上运行是编辑器集成的主要入口源码见 pgls_lsp 与 service。version打印版本信息后退出。编辑器集成Postgres Language Server 以扩展形式支持主流编辑器getting_started.mdVSCode通过 VSCode Marketplace 安装扩展名Supabase.postgrestools。Cursor通过 Open VSX Registry 安装同一扩展。Neovim安装nvim-lspconfig按其中postgres_lsp的配置指引启用。Emacs通过lsp-mode使用。Zed通过 Zed Extension 使用。更多细节参考 ide_setup.md。核心功能详解自动补全与 Hovereditor_features.md 说明连接数据库后语言服务器会基于真实 schema 提供两类能力自动补全——根据当前 SQL 上下文推荐相关数据库对象Tables数据库 schema 中可用的表Columns查询中引用到的表的列Functions数据库函数与过程Schemas可用的 schemaKeywordsSQL 关键字与语法。补全是上下文感知的在FROM之后输入会推荐表在SELECT之后输入会推荐相关表的列。实现层面pgls_completions/src/providers/ 下按对象类型拆分columns.rs、tables.rs、functions.rs、schemas.rs、roles.rs、policies.rs、keywords.rs再经 relevance 排序snapshots 目录 中如suggests_columns_in_where_clause.snap、completes_in_join_on_clause.snap等快照测试验证了各类上下文的行为。Hover 悬停信息——悬停数据库对象时显示Tablesschema、列清单与数据类型Columns数据类型、可空性、所属表Functions返回类型、参数信息。前提条件两个功能都要求配置好数据库连接、且语言服务器能读取 schema 信息没有数据库连接时这些功能不可用。语言服务器在启动时会缓存 schema 信息实现见 pgls_schema_cache其中queries/目录存放了读取表、列、函数、索引等元数据的 SQL。配置方法见 configure_database.md。语法诊断基于官方解析器任何不符合 Postgres 语法的代码都会直接在编辑器中得到诊断。由于解析器与 Postgres 完全一致语法错误提示的行为与真实执行一致详见 syntax_diagnostics.md。类型检查借助 EXPLAIN 的真实校验type_checking.md 描述了这一非常有特色的机制——它不是自研一套类型推断器而是直接问 Postgres 本身连接数据库用EXPLAIN让 Postgres 校验查询不实际执行把错误直接显示在编辑器中。因为使用的是真实数据库你在打字时得到的就是运行时才会发生的校验结果。支持范围由于依赖EXPLAIN类型检查仅覆盖 DML 语句SELECT、INSERT、UPDATE、DELETE以及 CTE公共表表达式。searchPath 配置可通过typecheck.searchPath控制参与类型检查的 schema 搜索路径{ typecheck: { searchPath: [public, app_*, auth] } }支持精确 schema 名如public支持 glob 模式如app_*可匹配app_users、app_products等顺序敏感按数组顺序搜索即使未配置public也始终排在最后一位被搜索。能捕获的错误均有真实示例表/列名拼写错误SELECT user_naem FROM users→ column user_naem does not exist类型不匹配user_id是整型却比较WHERE user_id abc表不存在表叫users却写SELECT * FROM user列数不符多列必填表却INSERT INTO users VALUES (1)。前提条件需要活动数据库连接以及执行 prepare 语句的权限。实现位于 pgls_typecheck其调用链与db.allowStatementExecutionsAgainst白名单直接相关——只有被白名单放行的地址才会实际执行EXPLAIN。格式化通过 LSP 的格式化请求或 CLI 提供 SQL 格式化能力详见 formatting.md。核心实现是 pgls_pretty_print基于.proto解析树的 pretty printer见 pgls_pretty_print_codegen其tests/data/下存放 514 个 SQL 样例、tests/snapshots/下对应 1028 个快照验证格式化输出的稳定性。迁移 Lintlinting.md 说明迁移 linter 对 SQL 代码做静态分析规则检测安全风险、最佳实践违规以及可能破坏现有应用的问题。规则组织规则按 Safety、Performance、Style 等类别组织每条规则可单独配置或整体禁用。完整规则列表见 rules.md规则实现位于 pgls_pglinter/src/rules/24 个规则文件如ban_drop_column.rs、adding_required_field.rs测试快照见 pgls_pglinter/tests/snapshots/。配置示例{ linter: { enabled: true, rules: { safety: { banDropColumn: error, // error, warn, info, hint, off banDropTable: warn, addingRequiredField: off } } } }每条规则的级别取值为error | warn | info | hint | off。抑制诊断可以用注释精确抑制某条诊断-- pgls-ignore lint/safety/banDropColumn: Intentionally dropping deprecated column ALTER TABLE users DROP COLUMN deprecated_field; -- pgls-ignore lint/safety/banDropTable: Cleanup during migration DROP TABLE temp_migration_table;抑制语法细节见 suppressions.md解析实现见 pgls_suppressions。schema 感知分析部分规则需要数据库连接才能做 schema 感知分析未配置连接时这些规则会被跳过。CLI 用法CI 友好# 检查迁移目录 postgres-language-server check migrations/ # 只运行特定规则 postgres-language-server check migrations/ --only safety/banDropColumn # 跳过某些规则 postgres-language-server check migrations/ --skip safety/banDropTable数据库 Lintdatabase_linting.md 区分了两类 lint 的边界文件型 linter 检查迁移文件而数据库 linter 直连数据库检查真实 schema 状态用于发现性能问题、安全漏洞与配置问题。所有数据库 lint 规则由 Splinter 等既有工具驱动。规则列表见 database_rules.md实现位于 pgls_splinter/src/rules/26 个规则文件。配置示例{ splinter: { enabled: true, rules: { performance: { noPrimaryKey: warn, unusedIndex: info }, security: { rlsDisabledInPublic: error, authUsersExposed: error } } } }忽略数据库对象支持用 Unix 风格 glob 忽略特定对象格式schema.object_name*匹配任意字符序列。可以全局忽略作用于所有规则或按规则忽略{ splinter: { ignore: [audit.*, temp_*], rules: { performance: { noPrimaryKey: { level: warn, options: { ignore: [public.temp_*, staging.*] } } } } } }常用模式示例模式匹配对象public.my_tablepublic schema 中的特定表audit.*audit schema 中的全部对象*.temp_*任意 schema 中带temp_前缀的对象public.log_*public schema 中以log_开头的表Supabase 专属规则部分规则专为 Supabase 项目设计Auth schema 暴露、RLS 策略配置、API schema 安全、Supabase 专属扩展等当检测不到 Supabase 专属数据库角色时会自动跳过。CLI 用法# 运行数据库 lint postgres-language-server dblint # 只运行特定规则 postgres-language-server dblint --only security/rlsDisabledInPublic # 跳过某些规则 postgres-language-server dblint --skip performance/tableBloat连接配置数据库 lint 需要活动连接在postgres-language-server.jsonc的db段配置同前文默认配置。注意dblint与check是独立的两个命令lib.rs 的命令分发可佐证后者不需要数据库也能跑语法与 lint 检查。PL/pgSQL 支持项目提供对 PL/pgSQL 存储过程语言的支持详见 plpgsql.md实现位于 pgls_plpgsql_check对函数体内部的 PL/pgSQL 代码进行诊断检查。在 CI 中集成getting_started.md 建议在 CI 管道中运行postgres-language-server check来校验 schema 变更、在团队中强制执行代码质量。官方提供 GitHub Action 在 runner 中安装 Postgres Language Server。完整示例见 continuous_integration.md。典型 CI 流程组合# 只检查相对主分支变更的文件CI 推荐 postgres-language-server check --changed # 使用 JUnit 报告供 CI 聚合 postgres-language-server check migrations/ --reporter junit # 使用 GitHub reporter 输出 workflow annotations postgres-language-server check migrations/ --reporter github--changed依赖配置中的defaultBranch或--since指定基准check.rs 会对参数组合做合法性校验。源码研读指引想深入理解实现建议从以下文件入手CLI 入口与会话管理crates/pgls_cli/src/lib.rs、crates/pgls_cli/src/commands/mod.rs命令行参数定义含全部选项的默认值crates/pgls_cli/src/cli_options.rscheck执行流程与退出码crates/pgls_cli/src/commands/check.rsLSP 服务器crates/pgls_lsp/src/server.rs数据库元数据缓存crates/pgls_schema_cache/src/schema_cache.rs解析与格式化crates/pgls_query/src/parse.rs、crates/pgls_pretty_print/src/lib.rs规则参考docs/reference/rules.md、docs/reference/database_rules.md、docs/reference/cli.md。致谢与生态README 的 Acknowledgements 特别致谢三个项目libpg_query提供 Postgres 官方解析器、Biome提供可复用的工具链基础设施、Squawklinter 规则灵感来源。这也解释了项目的技术选型解析层 100% 复用官方解析器工具链工程化借鉴 Biome 的 workspace/CLI 架构lint 规则参考 Squawk 的迁移安全实践经验——相关规则文档可对照 docs/reference/rules.md 中的规则说明。【免费下载链接】postgres_lspA Language Server for Postgres项目地址: https://gitcode.com/GitHub_Trending/po/postgres_lsp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Postgres Language Server：基于 libpg_query 的 Postgres 语言工具链与 LSP 实现
Postgres Language Server基于 libpg_query 的 Postgres 语言工具链与 LSP 实现【免费下载链接】postgres_lspA Language Server for Postgres项目地址: https://gitcode.com/GitHub_Trending/po/postgres_lspPostgres Language Serverpostgres_lsp是一套面向 Postgres 开发的完整语言工具链它基于 Postgres 官方解析器libpg_query构建通过 Language Server ProtocolLSP、CLI、HTTP API 与 WebAssembly 多种通道提供服务涵盖自动补全、Hover、语法诊断、类型检查、格式化、迁移 lint 与数据库 lint 等能力。本文将以仓库 README.md 为主线结合 docs/ 下的功能文档与crates/源码实现讲解项目架构、安装方式、配置文件、CLI 用法与各核心功能帮助你在编辑器与 CI 中落地这套 SQL 工具链。项目概览一个 Server-Client 架构的 Postgres 工具链README 对项目的定位非常明确A collection of language tools and a Language Server Protocol (LSP) implementation for Postgres即一组 Postgres 语言工具 一份 LSP 实现核心目标是提升开发者体验并提供可靠的 SQL 工具。项目在设计上有两个关键决策构建在 Postgres 官方解析器之上项目直接复用libpg_query由 pganalyze 维护的 Postgres 解析器提取版确保对 SQL 语法的100% 兼容——不会出现自定义解析器跟不上 PG 语法演进的问题。这一点在根目录 Cargo.toml 中有直接证据workspace 依赖声明了pg_query 6.1.0对应 Postgres 17 的解析能力pgls_pretty_print_codegen/postgres/17-6.1.0 目录下存放着对应的.proto与.h解析定义。Server-Client 架构、传输层无关所有能力既可以通过 LSP 暴露给编辑器也可以通过 CLI 暴露给终端与 CI。README 还提到未来所有功能都会通过CLI、HTTP API 和 WebAssembly 模块访问——仓库中 pgls_wasm crate 以及packages/postgres-language-server/下的 npm 包正是这一方向的实现。从工作区结构看Cargo.toml 声明了members [crates/*, xtask/codegen, xtask/rules_check, docs/codegen]整个项目由约 30 个pgls_*crate 组成职责分层清晰解析与语法层pgls_query、pgls_lexer、pgls_treesitter编辑器能力层pgls_completions、pgls_hover分析层pgls_analyser迁移 lint、pgls_pglinter、pgls_splinter数据库 lint、pgls_typecheck格式化pgls_pretty_print交互层pgls_cli、pgls_lsp、pgls_workspace。核心功能矩阵README 列出当前可用的功能每项都有对应的功能文档与实现 crate功能说明相关文档相关实现自动补全与 Hover连接数据库后基于 schema 提供上下文感知补全与悬停信息editor_features.mdpgls_completions、pgls_hover语法诊断基于官方解析器的语法错误提示syntax_diagnostics.mdpgls_analyser类型检查通过EXPLAIN获取 Postgres 的真实校验结果type_checking.mdpgls_typecheck格式化SQL 代码格式化formatting.mdpgls_pretty_print迁移 Lint对 SQL 迁移文件做静态规则检查linting.mdpgls_pglinter24 个规则文件数据库 Lint直连数据库检查实际 schema 状态database_linting.mdpgls_splinter26 个规则文件PL/pgSQL 支持存储过程/函数语言支持plpgsql.mdpgls_plpgsql_check安装与启动根据 getting_started.mdPostgres Language Server 有三种安装形态作为项目开发依赖、作为独立可执行文件、或作为编辑器扩展。1. 作为 npm 开发依赖安装pnpm add -D -E postgres-language-server/cli对应包在仓库中的packages/postgres-language-server/cli/目录含package.json。-E用于锁定精确版本避免工具链行为随版本漂移。2. 编辑器扩展方式安装大多数 编辑器集成 会自动管理二进制安装无需手动干预。仓库根目录的postgres-language-server.jsonc与packages/postgres-language-server/wasm/还提供了基于 WebAssembly 的浏览器端能力。3. 独立可执行文件方式参见 manual_installation.md适合 CI runner 或无法使用包管理器的环境。从源码构建开发模式README 的 Development 小节给出了两条命令nix develop # 或跳过不使用 Nix 时 docker-compose up -d # 启动本地依赖如测试用 Postgres配置文件postgres-language-server.jsonc官方推荐为每个项目创建postgres-language-server.jsonc配置文件。好处有两点一是省去重复的 CLI 参数二是保证编辑器与 CLI 使用一致的配置部分选项如allowStatementExecutionsAgainst只能通过配置文件设置。该步骤是可选的——接受默认值就不需要配置文件。在项目根目录运行init命令即可生成默认配置getting_started.mdpostgres-language-server init生成的默认配置内容如下摘自 getting_started.md{ $schema: https://pg-language-server.com/latest/schema.json, vcs: { enabled: false, clientKind: git, useIgnoreFile: false }, files: { ignore: [] }, linter: { enabled: true, rules: { recommended: true } }, db: { host: 127.0.0.1, port: 5432, username: postgres, password: postgres, database: postgres, connTimeoutSecs: 10, allowStatementExecutionsAgainst: [127.0.0.1/*, localhost/*] } }各配置段说明$schema指向 JSON Schema 以启用编辑器补全与校验可以把latest换成具体版本例如https://pg-language-server.com/0.0.0/schema.json以固定配置校验规则。仓库内置的 schema 由 docs/codegen 生成最终产物见 docs/schema.json。vcs是否与 VCS当前支持git集成、是否读取.gitignore之类的 ignore 文件。对应 CLI 的--vcs-enabled、--vcs-client-kind、--vcs-use-ignore-file、--vcs-root、--vcs-default-branch等参数见 cli.md。files.ignore需要跳过的文件列表。linter迁移 lint 开关与规则配置详见下文迁移 Lint。db数据库连接。connTimeoutSecs默认 10 秒allowStatementExecutionsAgainst是安全白名单限定允许向哪些数据库地址实际执行语句如类型检查的EXPLAIN默认仅放行本机。生成配置文件后务必把数据库连接改成你的本地开发库。查看全部选项可运行postgres-language-server --help。配置的加载与优先级从源码可以确认配置解析的真实行为。pgls_cli/src/lib.rs 的prepare_with_config展示了完整加载链从文件系统加载postgres-language-server.jsonc若--config-path未指定则走默认解析见 cli_options.rs 的ConfigurationPathHint检测到旧版配置文件名时会打印弃用警告提示改用postgres-language-server.jsonc环境变量如数据库相关环境变量覆盖配置文件显式 CLI 参数优先级最高——配置文件 环境变量 CLI 参数。这正是 getting_started.md 所述CLI options take precedence over what is loaded from postgres-language-server.jsonc的源码级印证。CLI 使用指南check 命令一站式检查CLI 的核心命令是check对给定文件或路径执行全部检查语法、lint、类型检查等# 检查单个文件 postgres-language-server check myfile.sql # 检查目录例如迁移目录 postgres-language-server check supabase/migrations不带路径时会回退到当前工作目录见 check.rs。check的退出码由 enforce_exit_codes 决定存在错误时非零退出--error-on-warnings时警告也会导致非零退出非常适合 CI。全局 CLI 选项以下是 cli.md 中适用于所有命令的全局选项对应源码 cli_options.rs选项取值默认说明--colorsoff\|forceauto关闭或强制 ANSI 彩色输出--use-server布尔false连接到已运行的 daemon 服务器--skip-db布尔—跳过数据库连接只跑不依赖数据库的检查--verbose布尔false打印额外诊断与文件处理详情--config-pathPATH—指定配置文件路径或目录会禁用默认配置解析--max-diagnosticsnone\|NUMBER20限制显示诊断条数none取消限制--skip-errors布尔—跳过含语法错误的文件而不是报错--no-errors-on-unmatched布尔—没有文件被处理时也不报错--error-on-warnings布尔—有警告时以非零退出码结束--reporterjson\|json-pretty\|github\|junit\|summary\|gitlabdefault切换诊断与摘要的输出格式--log-levelnone\|debug\|info\|warn\|errornone日志级别同时支持PGT_LOG_LEVEL/PGLS_LOG_LEVEL环境变量--log-kindpretty\|compact\|jsonpretty日志格式--diagnostic-levelinfo\|warn\|errorinfo只显示等于或高于该级别的诊断其中--reporter的多种输出格式在源码 CliReporter 中有完整枚举github输出 GitHub Workflow commands 格式、gitlab输出 GitLab Code Quality 报告格式、junit用于 CI 集成、json/json-pretty供程序消费、summary只打印统计。这些 reporter 的实现位于 pgls_cli/src/reporter/ 下并有对应的快照测试见 pgls_cli/tests/snapshots/。check 专属选项check命令还支持以下专属参数cli.md--stdin-file-pathPATH从 stdin 读取代码并按扩展名检查例如echo SELECT 1 | postgres-language-server check --stdin-file-pathtest.sql文件不必真实存在扩展名决定处理方式。实现见 check.rs 的read_stdin_payload与 execute/stdin.rs。--staged只检查已暂存staged的文件适合本地提交前检查。--changed只检查相对defaultBranch有变更的文件适合 CI。--sinceREF配合--changed指定对比基准分支当配置文件中未设置defaultBranch时。注意--since与--changed/--staged存在互斥校验check.rs 的validate_args会拒绝非法组合。数据库连接参数--connection-stringlibpq 连接串设置后覆盖下面的单项参数、--host、--port、--username、--password、--database、--conn_timeout_secs默认 10。--migrations-dir/--after指定迁移目录与时间戳用于跳过此前的迁移文件。daemon 与 lsp-proxyCLI 还包含一组服务类命令cli.mdstart启动 daemon 服务器进程支持--log-path、--log-prefix-name默认日志前缀server.log可用环境变量PGT_LOG_PATH/PGT_LOG_PREFIX_NAME覆盖。结合--use-server可以让后续 CLI 调用复用已运行的 daemon。stop停止 daemon。clean清理 daemon 产生的日志。lsp-proxy作为 LSP 服务器在 stdin/stdout 上运行是编辑器集成的主要入口源码见 pgls_lsp 与 service。version打印版本信息后退出。编辑器集成Postgres Language Server 以扩展形式支持主流编辑器getting_started.mdVSCode通过 VSCode Marketplace 安装扩展名Supabase.postgrestools。Cursor通过 Open VSX Registry 安装同一扩展。Neovim安装nvim-lspconfig按其中postgres_lsp的配置指引启用。Emacs通过lsp-mode使用。Zed通过 Zed Extension 使用。更多细节参考 ide_setup.md。核心功能详解自动补全与 Hovereditor_features.md 说明连接数据库后语言服务器会基于真实 schema 提供两类能力自动补全——根据当前 SQL 上下文推荐相关数据库对象Tables数据库 schema 中可用的表Columns查询中引用到的表的列Functions数据库函数与过程Schemas可用的 schemaKeywordsSQL 关键字与语法。补全是上下文感知的在FROM之后输入会推荐表在SELECT之后输入会推荐相关表的列。实现层面pgls_completions/src/providers/ 下按对象类型拆分columns.rs、tables.rs、functions.rs、schemas.rs、roles.rs、policies.rs、keywords.rs再经 relevance 排序snapshots 目录 中如suggests_columns_in_where_clause.snap、completes_in_join_on_clause.snap等快照测试验证了各类上下文的行为。Hover 悬停信息——悬停数据库对象时显示Tablesschema、列清单与数据类型Columns数据类型、可空性、所属表Functions返回类型、参数信息。前提条件两个功能都要求配置好数据库连接、且语言服务器能读取 schema 信息没有数据库连接时这些功能不可用。语言服务器在启动时会缓存 schema 信息实现见 pgls_schema_cache其中queries/目录存放了读取表、列、函数、索引等元数据的 SQL。配置方法见 configure_database.md。语法诊断基于官方解析器任何不符合 Postgres 语法的代码都会直接在编辑器中得到诊断。由于解析器与 Postgres 完全一致语法错误提示的行为与真实执行一致详见 syntax_diagnostics.md。类型检查借助 EXPLAIN 的真实校验type_checking.md 描述了这一非常有特色的机制——它不是自研一套类型推断器而是直接问 Postgres 本身连接数据库用EXPLAIN让 Postgres 校验查询不实际执行把错误直接显示在编辑器中。因为使用的是真实数据库你在打字时得到的就是运行时才会发生的校验结果。支持范围由于依赖EXPLAIN类型检查仅覆盖 DML 语句SELECT、INSERT、UPDATE、DELETE以及 CTE公共表表达式。searchPath 配置可通过typecheck.searchPath控制参与类型检查的 schema 搜索路径{ typecheck: { searchPath: [public, app_*, auth] } }支持精确 schema 名如public支持 glob 模式如app_*可匹配app_users、app_products等顺序敏感按数组顺序搜索即使未配置public也始终排在最后一位被搜索。能捕获的错误均有真实示例表/列名拼写错误SELECT user_naem FROM users→ column user_naem does not exist类型不匹配user_id是整型却比较WHERE user_id abc表不存在表叫users却写SELECT * FROM user列数不符多列必填表却INSERT INTO users VALUES (1)。前提条件需要活动数据库连接以及执行 prepare 语句的权限。实现位于 pgls_typecheck其调用链与db.allowStatementExecutionsAgainst白名单直接相关——只有被白名单放行的地址才会实际执行EXPLAIN。格式化通过 LSP 的格式化请求或 CLI 提供 SQL 格式化能力详见 formatting.md。核心实现是 pgls_pretty_print基于.proto解析树的 pretty printer见 pgls_pretty_print_codegen其tests/data/下存放 514 个 SQL 样例、tests/snapshots/下对应 1028 个快照验证格式化输出的稳定性。迁移 Lintlinting.md 说明迁移 linter 对 SQL 代码做静态分析规则检测安全风险、最佳实践违规以及可能破坏现有应用的问题。规则组织规则按 Safety、Performance、Style 等类别组织每条规则可单独配置或整体禁用。完整规则列表见 rules.md规则实现位于 pgls_pglinter/src/rules/24 个规则文件如ban_drop_column.rs、adding_required_field.rs测试快照见 pgls_pglinter/tests/snapshots/。配置示例{ linter: { enabled: true, rules: { safety: { banDropColumn: error, // error, warn, info, hint, off banDropTable: warn, addingRequiredField: off } } } }每条规则的级别取值为error | warn | info | hint | off。抑制诊断可以用注释精确抑制某条诊断-- pgls-ignore lint/safety/banDropColumn: Intentionally dropping deprecated column ALTER TABLE users DROP COLUMN deprecated_field; -- pgls-ignore lint/safety/banDropTable: Cleanup during migration DROP TABLE temp_migration_table;抑制语法细节见 suppressions.md解析实现见 pgls_suppressions。schema 感知分析部分规则需要数据库连接才能做 schema 感知分析未配置连接时这些规则会被跳过。CLI 用法CI 友好# 检查迁移目录 postgres-language-server check migrations/ # 只运行特定规则 postgres-language-server check migrations/ --only safety/banDropColumn # 跳过某些规则 postgres-language-server check migrations/ --skip safety/banDropTable数据库 Lintdatabase_linting.md 区分了两类 lint 的边界文件型 linter 检查迁移文件而数据库 linter 直连数据库检查真实 schema 状态用于发现性能问题、安全漏洞与配置问题。所有数据库 lint 规则由 Splinter 等既有工具驱动。规则列表见 database_rules.md实现位于 pgls_splinter/src/rules/26 个规则文件。配置示例{ splinter: { enabled: true, rules: { performance: { noPrimaryKey: warn, unusedIndex: info }, security: { rlsDisabledInPublic: error, authUsersExposed: error } } } }忽略数据库对象支持用 Unix 风格 glob 忽略特定对象格式schema.object_name*匹配任意字符序列。可以全局忽略作用于所有规则或按规则忽略{ splinter: { ignore: [audit.*, temp_*], rules: { performance: { noPrimaryKey: { level: warn, options: { ignore: [public.temp_*, staging.*] } } } } } }常用模式示例模式匹配对象public.my_tablepublic schema 中的特定表audit.*audit schema 中的全部对象*.temp_*任意 schema 中带temp_前缀的对象public.log_*public schema 中以log_开头的表Supabase 专属规则部分规则专为 Supabase 项目设计Auth schema 暴露、RLS 策略配置、API schema 安全、Supabase 专属扩展等当检测不到 Supabase 专属数据库角色时会自动跳过。CLI 用法# 运行数据库 lint postgres-language-server dblint # 只运行特定规则 postgres-language-server dblint --only security/rlsDisabledInPublic # 跳过某些规则 postgres-language-server dblint --skip performance/tableBloat连接配置数据库 lint 需要活动连接在postgres-language-server.jsonc的db段配置同前文默认配置。注意dblint与check是独立的两个命令lib.rs 的命令分发可佐证后者不需要数据库也能跑语法与 lint 检查。PL/pgSQL 支持项目提供对 PL/pgSQL 存储过程语言的支持详见 plpgsql.md实现位于 pgls_plpgsql_check对函数体内部的 PL/pgSQL 代码进行诊断检查。在 CI 中集成getting_started.md 建议在 CI 管道中运行postgres-language-server check来校验 schema 变更、在团队中强制执行代码质量。官方提供 GitHub Action 在 runner 中安装 Postgres Language Server。完整示例见 continuous_integration.md。典型 CI 流程组合# 只检查相对主分支变更的文件CI 推荐 postgres-language-server check --changed # 使用 JUnit 报告供 CI 聚合 postgres-language-server check migrations/ --reporter junit # 使用 GitHub reporter 输出 workflow annotations postgres-language-server check migrations/ --reporter github--changed依赖配置中的defaultBranch或--since指定基准check.rs 会对参数组合做合法性校验。源码研读指引想深入理解实现建议从以下文件入手CLI 入口与会话管理crates/pgls_cli/src/lib.rs、crates/pgls_cli/src/commands/mod.rs命令行参数定义含全部选项的默认值crates/pgls_cli/src/cli_options.rscheck执行流程与退出码crates/pgls_cli/src/commands/check.rsLSP 服务器crates/pgls_lsp/src/server.rs数据库元数据缓存crates/pgls_schema_cache/src/schema_cache.rs解析与格式化crates/pgls_query/src/parse.rs、crates/pgls_pretty_print/src/lib.rs规则参考docs/reference/rules.md、docs/reference/database_rules.md、docs/reference/cli.md。致谢与生态README 的 Acknowledgements 特别致谢三个项目libpg_query提供 Postgres 官方解析器、Biome提供可复用的工具链基础设施、Squawklinter 规则灵感来源。这也解释了项目的技术选型解析层 100% 复用官方解析器工具链工程化借鉴 Biome 的 workspace/CLI 架构lint 规则参考 Squawk 的迁移安全实践经验——相关规则文档可对照 docs/reference/rules.md 中的规则说明。【免费下载链接】postgres_lspA Language Server for Postgres项目地址: https://gitcode.com/GitHub_Trending/po/postgres_lsp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考