This document describes the high-level architecture of postgres_lsp. If you want to familiarize yourself with the code base, you are just in the right place!
Since the project still evolves rapidly, this document may not be up-to-date. If you find any inconsistency, please let us know by creating an issue.
On the highest level, the postgres language server is a thing which accepts input source code, cuts it into individual sql statements and parses and analyses each. In addition, it connects to a postgres database and stores an im-memory schema cache with all required type information such as tables, columns and functions. The result of the parsing is used alongside the schema cache to answer queries about a statement.
The client can submit a delta of input data (typically, a change to a single file), and the server will update the affected statements and their analysis accordingly. The underlying engine makes sure that we only re-parse and re-analyse what is necessary.
There are two main entry points, both thin frontends over the shared pgls_workspace API:
crates/pgls_lsp— the language server. It spawns the server and listens for incoming LSP messages.crates/pgls_cli— the command-line interface, exposing commands likecheck. The published binary ispostgres-language-server(legacy namepostgrestools).
This section talks briefly about various important crates and data structures. All crates are prefixed with pgls_.
The main API for consumers of the IDE (both the LSP and the CLI). It stores the internal state of the workspace — the schema cache, the parsed documents and their per-feature analysis — and orchestrates the feature crates. Its _macros companion (pgls_workspace_macros) generates repetitive glue code.
Virtual file system abstraction used to read and watch source files.
Configuration model and loading. pgls_configuration_macros generates the merge/partial boilerplate.
Environment variables and runtime configuration constants.
Wraps libpg_query to parse an SQL statement into a Postgres AST (NodeEnum). Also provides deparsing, normalization, fingerprinting, statement splitting hints, plpgsql parsing, and mutable/immutable node iterators. Much of the repetitive node code is generated by pgls_query_macros from the protobuf definitions shipped with libpg_query.
Thin extension layer over pgls_query holding helpers and diagnostics not yet contributed upstream.
Tokenize the input source code. pgls_tokenizer is the low-level scanner; pgls_lexer enriches it with whitespace tokens. pgls_lexer_codegen generates the token definitions.
Cuts the input source code into individual SQL statements.
Tree-sitter integration used by features (e.g. completions and hover) that need positional/CST context. pgls_treesitter_grammar holds the grammar.
In-memory representation of the database schema (tables, columns, functions, types). Built from introspection SQL queries and used to resolve types efficiently.
Utility crate used by the feature crates to resolve source types to the actual types in the schema cache.
SQL pretty-printer / formatter: normalizes the AST and renders it back to formatted SQL with a safety re-parse check. pgls_pretty_print_codegen generates the per-node emitters.
The linting framework. pgls_analyse provides the rule registry, categories, filters, and metadata; pgls_analyser hosts the concrete lint rules and the linter runtime.
Integration with the pglinter Postgres extension for database-level linting.
Runs Splinter rules against a live database connection to surface schema/security advisories.
Integration with plpgsql_check to validate PL/pgSQL function bodies.
Type-checks statements against the database (via EXPLAIN).
Handles -- pgls-ignore style rule suppression comments.
Autocompletion and hover providers. They operate on the schema cache plus a single statement and its parse results, and are intentionally free of any language-server flavour so they can be reused from the CLI.
crates/pgls_diagnostics(+_categories,_macros) — error and warning reporting model.crates/pgls_console/pgls_markup— terminal output and markup.crates/pgls_text_edit,pgls_text_size— text manipulation and byte/char range types.crates/pgls_matcher— Unix shell style pattern matching (glob).crates/pgls_test_utils,pgls_test_macros— shared test helpers.crates/pgls_wasm— WASM bindings for browser/editor integrations.
Editor integrations and distribution live under packages/: a JSON-RPC backend bridge, the npm CLI wrapper, and the WASM package. See AGENTS.md for the full list.