# supabase-community/postgres-language-server architecture

> Architecture diagram of the GitHub repository supabase-community/postgres-language-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/supabase-community/postgres-language-server
- Repository: https://github.com/supabase-community/postgres-language-server

## Overview

##### And define the main components
- Client Interfaces: Represent the different “front-ends” that interact with your toolchain. This includes:
– LSP Clients (editors such as VSCode, Neovim, etc.)
– CLI (command line interface)
– (Potentially) Other interfaces like HTTP APIs or WebAssembly modules, as hinted by the transport-agnostic design.
- Server / Core Service: This layer is responsible for processing and handing off requests from the client interfaces. It will include:
– The LSP server implementation (see the pgt_lsp crate)
– The CLI backend (pgt_cli crate)
– libpg_query integration (libpg_query module)
– pgt_analyse and pgt_analyser (for analysis and linting)
– pgt_diagnostics, pgt_diagnostics_categories, and pgt_diagnostics_macros (for diagnostics and error reporting)
– pgt_configuration (reading and managing configurations)
– pgt_lexer and pgt_lexer_codegen (parsing and syntax processing)
– pgt_schema_cache, pgt_statement_splitter, pgt_type_resolver, pgt_typecheck (for SQL statement handling and type checking)
– pgt_fs and pgt_workspace (for file, workspace, and environment management)
- Additional Tools: There are also helper modules for generating completions (pgt_completions), markup (pgt_console, pgt_markup), treesitter queries, text editing, text sizing, etc. These provide supporting functionality and can be grouped as “Utility Libraries.”

##### Out relationships and data flow
- Within the server component, show a breakdown where requests are passed into a “Processing Pipeline” that leverages the core libraries:
– A “Parser” submodule (using libpg_query, pgt_lexer, etc.) to transform SQL input into ASTs.
– A “Linter/Analyser” submodule (using pgt_analyse/pgt_analyser and diagnostics modules) to check for syntax, lint, and type issues.
– A “Configuration and Workspace” submodule (pgt_configuration, pgt_workspace, pgt_fs) to manage settings and context.
– A “Response Generation” submodule (pgt_console, pgt_completions, etc.) that formats and sends results back to the client.
– From “LSP Client” → “LSP Server” → “Parsing Module” → “Linter/Diagnostic Module” → “Response Formatter” → back to “LSP Client.”
– Similarly for the CLI route.

##### Architectural patterns and design principles
- Separation of concerns: distinct crates handling parsing, diagnostics, configuration, and client communication.
- Modularity provided by the Cargo workspace, with each crate (located in the “crates” directory) responsible for a specific part of the functionality.

##### Technical stack and technologies
- Integration with libpg_query and other core dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Interfaces
    subgraph "Client Interfaces"
        LSPClient("LSP (Editor)"):::client
        CLIClient("CLI (Terminal)"):::client
    end

    %% Server / Core Service
    subgraph "Server / Core Service"
        LSPSrv("LSP Server (pgt_lsp)"):::server
        CLISrv("CLI Backend (pgt_cli)"):::server
    end

    %% Processing Pipeline
    subgraph "Processing Pipeline"
        %% Parser Module
        subgraph "Parser Module"
            Libpg("libpg_query (External)"):::external
            Lexer("Lexer (pgt_lexer)"):::parser
            LexerCodegen("Lexer Codegen (pgt_lexer_codegen)"):::parser
        end

        %% Analysis & Diagnostics
        subgraph "Analysis & Diagnostics"
            Analyse("Analyser (pgt_analyse)"):::analysis
            Analyser("Analyser (pgt_analyser)"):::analysis
            Diagnostics("Diagnostics (pgt_diagnostics)"):::analysis
            DiagCat("Diagnostics Categories (pgt_diagnostics_categories)"):::analysis
            DiagMacro("Diagnostics Macros (pgt_diagnostics_macros)"):::analysis
        end

        %% Configuration & Workspace
        subgraph "Configuration & Workspace"
            Config("Configuration (pgt_configuration)"):::config
            FS("File System (pgt_fs)"):::config
            Workspace("Workspace (pgt_workspace)"):::config
        end

        %% SQL Statement Handling
        subgraph "SQL Statement Handling"
            StatementSplitter("Statement Splitter (pgt_statement_splitter)"):::statement
            SchemaCache("Schema Cache (pgt_schema_cache)"):::statement
            TypeResolver("Type Resolver (pgt_type_resolver)"):::statement
            Typecheck("Typechecker (pgt_typecheck)"):::statement
        end

        %% Response Generation / Utility
        subgraph "Response Generation / Utility"
            Completions("Completions (pgt_completions)"):::utility
            Console("Console (pgt_console)"):::utility
            Markup("Markup (pgt_markup)"):::utility
        end

        %% Treesitter Query Support
        subgraph "Treesitter Query Support"
            TSQueries("Treesitter Queries (pgt_treesitter_queries)"):::utility
        end
    end

    %% Data Flows
    LSPClient --> LSPSrv
    CLIClient --> CLISrv
    LSPSrv --> Libpg
    CLISrv --> Libpg
    Libpg --> Lexer
    Lexer --> LexerCodegen
    LexerCodegen --> Analyse
    Analyse --> Analyser
    Analyser --> Diagnostics
    Diagnostics --> DiagCat
    DiagCat --> DiagMacro
    DiagMacro --> Config
    Config --> FS
    FS --> Workspace
    Workspace --> StatementSplitter
    StatementSplitter --> SchemaCache
    SchemaCache --> TypeResolver
    TypeResolver --> Typecheck
    Typecheck --> Completions
    Completions --> Console
    Console --> Markup
    Markup --> LSPSrv
    Markup --> CLISrv
    LexerCodegen -- "branch" --> TSQueries

    %% Click Events
    click LSPSrv "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_lsp"
    click CLISrv "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_cli"
    click Libpg "https://github.com/supabase-community/postgres-language-server/tree/main/libpg_query"
    click Lexer "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_lexer"
    click LexerCodegen "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_lexer_codegen"
    click Analyse "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_analyse"
    click Analyser "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_analyser"
    click Diagnostics "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_diagnostics"
    click DiagCat "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_diagnostics_categories"
    click DiagMacro "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_diagnostics_macros"
    click Config "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_configuration"
    click FS "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_fs"
    click Workspace "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_workspace"
    click StatementSplitter "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_statement_splitter"
    click SchemaCache "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_schema_cache"
    click TypeResolver "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_type_resolver"
    click Typecheck "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_typecheck"
    click Completions "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_completions"
    click Console "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_console"
    click Markup "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_markup"
    click TSQueries "https://github.com/supabase-community/postgres-language-server/tree/main/crates/pgt_treesitter_queries"

    %% Styles
    classDef client fill:#ffddcc,stroke:#cc5500,stroke-width:2px;
    classDef server fill:#ffe6e6,stroke:#ff6666,stroke-width:2px;
    classDef parser fill:#e0f7fa,stroke:#00acc1,stroke-width:2px;
    classDef analysis fill:#e8f5e9,stroke:#43a047,stroke-width:2px;
    classDef config fill:#fff9c4,stroke:#f57f17,stroke-width:2px;
    classDef statement fill:#fce4ec,stroke:#d81b60,stroke-width:2px;
    classDef utility fill:#ede7f6,stroke:#673ab7,stroke-width:2px;
    classDef external fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px;
```
