diff --git a/docs/codegen/src/cli_doc.rs b/docs/codegen/src/cli_doc.rs index 47dd5ad7f..b6c4a75b8 100644 --- a/docs/codegen/src/cli_doc.rs +++ b/docs/codegen/src/cli_doc.rs @@ -4,7 +4,7 @@ use std::{fs, path::Path}; use crate::utils; pub fn generate_cli_doc(docs_dir: &Path) -> anyhow::Result<()> { - let file_path = docs_dir.join("cli_reference.md"); + let file_path = docs_dir.join("reference/cli.md"); let content = fs::read_to_string(&file_path)?; diff --git a/docs/codegen/src/default_configuration.rs b/docs/codegen/src/default_configuration.rs index bda30d148..7b7eadfd4 100644 --- a/docs/codegen/src/default_configuration.rs +++ b/docs/codegen/src/default_configuration.rs @@ -5,7 +5,7 @@ use crate::utils::replace_section; use pgt_configuration::PartialConfiguration; pub fn generate_default_configuration(docs_dir: &Path) -> anyhow::Result<()> { - let index_path = docs_dir.join("index.md"); + let index_path = docs_dir.join("getting_started.md"); let printed_config = format!( "\n```json\n{}\n```\n", diff --git a/docs/codegen/src/env_variables.rs b/docs/codegen/src/env_variables.rs index 8834b4dc3..fd21ed1b5 100644 --- a/docs/codegen/src/env_variables.rs +++ b/docs/codegen/src/env_variables.rs @@ -6,7 +6,7 @@ use std::path::Path; use crate::utils::replace_section; pub fn generate_env_variables(docs_dir: &Path) -> Result<()> { - let file_path = docs_dir.join("env_variables.md"); + let file_path = docs_dir.join("reference/env_variables.md"); let mut content = vec![]; diff --git a/docs/codegen/src/rules_docs.rs b/docs/codegen/src/rules_docs.rs index 67626237d..3624dfb86 100644 --- a/docs/codegen/src/rules_docs.rs +++ b/docs/codegen/src/rules_docs.rs @@ -20,7 +20,7 @@ use std::{ /// /// * `docs_dir`: Path to the docs directory. pub fn generate_rules_docs(docs_dir: &Path) -> anyhow::Result<()> { - let rules_dir = docs_dir.join("rules"); + let rules_dir = docs_dir.join("reference/rules"); if rules_dir.exists() { fs::remove_dir_all(&rules_dir)?; diff --git a/docs/codegen/src/rules_index.rs b/docs/codegen/src/rules_index.rs index 99d22580e..443c5c031 100644 --- a/docs/codegen/src/rules_index.rs +++ b/docs/codegen/src/rules_index.rs @@ -17,7 +17,7 @@ use crate::utils; /// /// * `docs_dir`: Path to the docs directory. pub fn generate_rules_index(docs_dir: &Path) -> anyhow::Result<()> { - let index_file = docs_dir.join("rules.md"); + let index_file = docs_dir.join("reference/rules.md"); let mut visitor = crate::utils::LintRulesVisitor::default(); pgt_analyser::visit_registry(&mut visitor); diff --git a/docs/codegen/src/rules_sources.rs b/docs/codegen/src/rules_sources.rs index 5b21ea933..ddbadec8e 100644 --- a/docs/codegen/src/rules_sources.rs +++ b/docs/codegen/src/rules_sources.rs @@ -28,7 +28,7 @@ impl PartialOrd for SourceSet { } pub fn generate_rule_sources(docs_dir: &Path) -> anyhow::Result<()> { - let rule_sources_file = docs_dir.join("rule_sources.md"); + let rule_sources_file = docs_dir.join("reference/rule_sources.md"); let mut visitor = crate::utils::LintRulesVisitor::default(); pgt_analyser::visit_registry(&mut visitor); @@ -69,7 +69,16 @@ pub fn generate_rule_sources(docs_dir: &Path) -> anyhow::Result<()> { } } + writeln!(buffer, "# Rule Sources",)?; + writeln!( + buffer, + "Many rules are inspired by or directly ported from other tools. This page lists the sources of each rule.", + )?; + writeln!(buffer, "## Exclusive rules",)?; + if exclusive_rules.is_empty() { + writeln!(buffer, "_No exclusive rules available._")?; + } for (rule, link) in exclusive_rules { writeln!(buffer, "- [{rule}]({link}) ")?; } diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 000000000..9661d2a87 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,96 @@ +# Configuration + +This guide will help you to understand how to configure the Postgres Language Server. It explains the structure of the configuration file and how the configuration is resolved. + +The Postgres Language Server allows you to customize its behavior using CLI options or a configuration file named `postgrestools.jsonc`. We recommend that you create a configuration file for each project. This ensures that each team member has the same configuration in the CLI and in any editor that allows Biome integration. Many of the options available in a configuration file are also available in the CLI. + +## Configuration file structure + +A configuration file is usually placed in your project’s root folder. It is organized around the tools that are provided. All tools are enabled by default, but some require additional setup like a database connection or the `plpgsql_check` extension. + +```json +{ + "$schema": "https://pgtools.dev/latest/schema.json", + "linter": { + "enabled": true, + "rules": { + "recommended": true + } + }, + "typecheck": { + "enabled": true + } + "plpgsqlCheck": { + "enabled" : true + } +} +``` + +## Configuring a database connection + +Some tools that the Postgres Language Server provides are implemented as mere interfaces on top of functionality that is provided by the database itself. This ensures correctness, but requires an active connection to a Postgres database. We strongly recommend to only connect to a local development database. + +```json +{ + "$schema": "https://pgtools.dev/latest/schema.json", + "db": { + "host": "127.0.0.1", + "port": 5432, + "username": "postgres", + "password": "postgres", + "database": "postgres", + "connTimeoutSecs": 10, + "allowStatementExecutionsAgainst": ["127.0.0.1/*", "localhost/*"] + } +} +``` + + +## Specifying files to process + +You can control the files/folders to process using different strategies, either CLI, configuration and VCS. + +### Include files via CLI +The first way to control which files and folders are processed is to list them in the CLI. In the following command, we only check `file1.sql` and all the files in the `src` folder, because folders are recursively traversed. + +```shell +postgrestools check file1.js src/ +``` + +### Control files via configuration + +The configuration file can be used to refine which files are processed. You can explicitly list the files to be processed using the `files.includes` field. `files.includes` accepts glob patterns such as sql/**/*.sql. Negated patterns starting with `!` can be used to exclude files. + +Paths and globs inside the configuration file are resolved relative to the folder the configuration file is in. An exception to this is when a configuration file is extended by another. + +#### Include files via configuration +Let’s take the following configuration, where we want to include only SQL files (`.sql`) that are inside the `sql/` folder: + +```json +{ + "files": { + "includes": ["sql/**/*.sql"] + } +} +``` + +#### Exclude files via configuration +If you want to exclude files and folders from being processed, you can use the `files.ignore` . + +In the following example, we include all files, except those in any test/ folder: + +```json +{ + "files": { + "ignore": [ + "**/test", + ] + } +} +``` + +#### Control files via VCS +You can ignore files ignored by your [VCS](/guides/vcs_integration.md). + + + diff --git a/docs/features/editor_features.md b/docs/features/editor_features.md new file mode 100644 index 000000000..3306b969e --- /dev/null +++ b/docs/features/editor_features.md @@ -0,0 +1,39 @@ +# Autocompletion & Hover + +The language server provides autocompletion and hover information when connected to a database. + +## Autocompletion + +As you type SQL, the language server suggests relevant database objects based on your current context: + +- **Tables**: Available tables from your database schema +- **Columns**: Columns from tables referenced in your query +- **Functions**: Database functions and procedures +- **Schemas**: Available schemas in your database +- **Keywords**: SQL keywords and syntax + +The suggestions are context-aware - for example, when typing after `FROM`, you'll see table suggestions, and when typing after `SELECT`, you'll see column suggestions from relevant tables. + +## Hover Information + +Hovering over database objects in your SQL shows detailed information: + +- **Tables**: Schema, column list with data types +- **Columns**: Data type, nullable status, table location +- **Functions**: Return type, parameter information + +The hover information is pulled from your database schema. + +## Requirements + +Both features require: +- A configured database connection +- The language server must be able to read schema information from your database + +Without a database connection, these features are not available. + +## Configuration + +These features work automatically when you have a database connection configured. See the [database configuration guide](../guides/configure_database.md) for setup instructions. + +The language server caches schema information on startup. diff --git a/docs/features/linting.md b/docs/features/linting.md new file mode 100644 index 000000000..814ce558e --- /dev/null +++ b/docs/features/linting.md @@ -0,0 +1,66 @@ +# Linting + +The language server provides static analysis through linting rules that detect potential issues in your SQL code. The linter analyses SQL statements for safety issues, best practices violations, and problems that could break existing applications. + +## Rules + +Rules are organized into categories like Safety, Performance, and Style. Each rule can be configured individually or disabled entirely. + +See the [Rules Reference](../reference/rules.md) for the complete list of available rules and their descriptions. + +## Configuration + +Configure linting behavior in your `postgrestools.jsonc`: + +```json +{ + "linter": { + // Enable/disable the linter entirely + "enabled": true, + "rules": { + // Configure rule groups + "safety": { + // Individual rule configuration + "banDropColumn": "error", // error, warn, info, hint, off + "banDropTable": "warn", + "addingRequiredField": "off" + } + } + } +} +``` + +## Suppressing Diagnostics + +You can suppress specific diagnostics using comments: + +```sql +-- pgt-ignore-next-line safety/banDropColumn: Intentionally dropping deprecated column +ALTER TABLE users DROP COLUMN deprecated_field; + +-- pgt-ignore safety/banDropTable: Cleanup during migration +DROP TABLE temp_migration_table; +``` + +For more details on suppressions check out [our guide]('../guides/suppressions.md'). + +## Schema-Aware Analysis + +Some rules require a database connection to perform schema-aware analysis. If no connection is configured, they are skipped. + +## CLI Usage + +The linter can also be used via the CLI for CI integration: + +```bash +# Lint specific files +postgrestools check migrations/ + +# With specific rules +postgrestools check migrations/ --only safety/banDropColumn + +# Skip certain rules +postgrestools check migrations/ --skip safety/banDropTable +``` + +See the [CLI Reference](../reference/cli.md) for more options, and check the guide on [linting migrations]('../guides/checking_migrations.md'). diff --git a/docs/features/plpgsql.md b/docs/features/plpgsql.md new file mode 100644 index 000000000..a3a442749 --- /dev/null +++ b/docs/features/plpgsql.md @@ -0,0 +1,40 @@ +# PL/pgSQL Support + +The Postgres Language Server partially supports `PL/pgSQL`. By default, use `libpg_query` to parse the function body and show any syntax error. This is a great way to quickly reduce the feedback loop when developing. Unfortunately, the reported errors do not contain any location information and we always report an error on the entire function body. + +To get more sophisticated and fine-grained errors, we strongly recommend to enable the [`plpgsql_check`](https://github.com/okbob/plpgsql_check) extension in your development database. + +```sql +CREATE EXTENSION IF NOT EXISTS plpgsql_check; +``` + +The language server will automatically detect the extension and start forwarding its reports as diagnostics. + +For any `CREATE FUNCTION` statement with the language `PL/pgSQL`, the following process occurs: + +1. The language server creates the function in a temporary transaction +2. Calls `plpgsql_check_function()` to perform comprehensive static analysis of the function body +3. For trigger functions, the analysis runs against each table that has triggers using this function, providing context-specific validation +4. Errors are mapped back to source locations with token-level precision + +The integration provides more detailed and actionable feedback compared to basic syntax checking, including: + +> - checks fields of referenced database objects and types inside embedded SQL +> - validates you are using the correct types for function parameters +> - identifies unused variables and function arguments, unmodified OUT arguments +> - partial detection of dead code (code after an RETURN command) +> - detection of missing RETURN command in function (common after exception handlers, complex logic) +> - tries to identify unwanted hidden casts, which can be a performance issue like unused indexes +> - ability to collect relations and functions used by function +> - ability to check EXECUTE statements against SQL injection vulnerability + +You can always disable the integration if you do not want the language server to hit your development database. + +```json +{ + "plpqsqlCheck": { + "enabled": false + } +} +``` + diff --git a/docs/features/syntax_diagnostics.md b/docs/features/syntax_diagnostics.md new file mode 100644 index 000000000..70d736885 --- /dev/null +++ b/docs/features/syntax_diagnostics.md @@ -0,0 +1,26 @@ +# Syntax Diagnostics + +The Postgres Language Server reports diagnostics for syntax errors in your SQL files. Syntax diagnostics are enabled by default and cannot be disabled. + +## How it Works + +The language server uses [libpg_query](https://github.com/pganalyze/libpg_query) to parse SQL statements, which is the actual Postgres parser packaged as a library. This ensures 100% compatibility with Postgres syntax. + +When you type or modify SQL, the language server: +1. Parses the SQL using `libpg_query` +2. Reports any syntax errors as diagnostics + +## Features + +- Always correct: Uses the same parser as Postgres itself for accurate syntax validation +- Named Parameter Support: We convert `:param` and `@param` to positional parameters (`$1`, `$2`) so the Postgres parser understands them and the LSP works with ORMs and other tooling +- `PL/pgSQL`: In addition to SQL, also validates `PL/pgSQL` function bodies for basic syntax errors + +## Error Information + +Syntax errors include: +- The exact error message from the Postgres parser +- Source location when available (though `libpg_query` does not always provide precise positions) +- Error severity (always "Error" for syntax issues) + +Note: For more advanced `PL/pgSQL` validation beyond basic syntax, see the [PL/pgSQL feature](plpgsql.md) which integrates with the `plpgsql_check` extension. diff --git a/docs/features/type_checking.md b/docs/features/type_checking.md new file mode 100644 index 000000000..94613ca31 --- /dev/null +++ b/docs/features/type_checking.md @@ -0,0 +1,57 @@ +# Type Checking + +The Postgres Language Server validates your SQL queries against your actual database schema. As you type, it checks that your tables exist, columns are spelled correctly, and data types match - just like Postgres would when executing the query. + +## How it Works + +When you write a SQL query, the language server: + +1. Connects to your database +2. Asks Postgres to validate your query without running it +3. Shows any errors directly in your editor + +Since it uses your actual database, you get the same validation that happens at runtime - as soon as you type. + +## Supported Statements + +Since we are using `EXPLAIN`, type checking is only available for DML statements: +- `SELECT` statements +- `INSERT` statements +- `UPDATE` statements +- `DELETE` statements +- Common Table Expressions (CTEs) + +## Configuration + +You can configure the schemas included in the search path for type checking: + +```json +{ + "typecheck": { + "searchPath": ["public", "app_*", "auth"] + } +} +``` + +The `searchPath` supports: +- Exact schema names (e.g., `"public"`) +- Glob patterns (e.g., `"app_*"` to match `app_users`, `app_products`, etc.) +- The order matters - schemas are searched in the order specified + +Even if not specified, the LSP will always search`"public"` in last position. + +## What Gets Checked + +The type checker catches common SQL mistakes: + +- **Typos in table and column names**: `SELECT user_naem FROM users` → "column 'user_naem' does not exist" +- **Type mismatches**: `WHERE user_id = 'abc'` when `user_id` is an integer +- **Missing tables**: `SELECT * FROM user` when the table is named `users` +- **Wrong number of columns**: `INSERT INTO users VALUES (1)` when the table has multiple required columns + +## Requirements + +Type checking requires: + +- An active database connection +- Appropriate permissions to prepare statements in your database diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 000000000..8cbe655bd --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,85 @@ +# Getting Started + +The Postgres Language Server can be installed as a development dependency of your project, a standalone executable, or as an extension of your favorite editor. + +## Configuration + +We recommend creating a `postgrestools.jsonc` configuration file for each project. This eliminates repetitive CLI options and ensures that consistent configuration in your editor. Some options are only available from a configuration file. This step is optional though: if you are happy with the defaults, you don’t need a configuration file. To create the `postgrestools.jsonc` file, run the `init` command in the root folder of your project: + +```sh +postgrestools init +``` + +You’ll now have a `postgrestools.jsonc` file in your directory: + +[//]: # "BEGIN DEFAULT_CONFIGURATION" + +```json +{ + "$schema": "https://pgtools.dev/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/*"] + } +} +``` + +[//]: # "END DEFAULT_CONFIGURATION" + +Make sure to edit the database connection settings to connect to your local development database. To see all options, run `postgrestools --help`. + +You can use your current `postgrestools` version instead of "latest" in the `$schema` URL, e.g. `https://pgtools.dev/0.8.1/schema.json`. + +## Usage + +Lets get a quick overview of how to use the Postgres Language Server in your project. + +### Command-line interface + +The CLI exposes a `check` command that will run all checks on the given files or paths. + +```sh +# check a specific file +postgrestools check myfile.sql + +# check a directory +postgrestools check supabase/migrations +``` + +Run `postgrestools --help` for all options. The CLI options take precedence over what is loaded from `postgrestools.jsonc`. + +### Editor Integrations + +The Postgres Language Server is available as an extension in your favorite editors. + +- VSCode: The language server is available on the [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=Supabase.postgrestools). It's published from [this repo](https://github.com/supabase-community/postgrestools-vscode). +- Neovim: You will have to install `nvim-lspconfig`, and follow the [instructions](https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#postgres_lsp). +- Emacs: The language client is available through [lsp-mode](https://github.com/emacs-lsp/lsp-mode). For more details, refer to their [manual page](https://emacs-lsp.github.io/lsp-mode/page/lsp-postgres/). +- Zed: The language server is available as an Extension. It's published from [this repo](https://github.com/LoamStudios/zed-postgres-language-server). + +### Continuous Integration + +Run `postgrestools check` in your CI pipeline to lint your schema changes and enforce code quality across your team. We provide a [GitHub Action](https://github.com/supabase-community/postgrestools-cli-action) to setup the Postgres Language Server in your runner. + +See the [Continuous Integration](/guides/continuous_integration) guide for an example. + + diff --git a/docs/checking_migrations.md b/docs/guides/checking_migrations.md similarity index 100% rename from docs/checking_migrations.md rename to docs/guides/checking_migrations.md diff --git a/docs/guides/configure_database.md b/docs/guides/configure_database.md new file mode 100644 index 000000000..ae4d6d0c2 --- /dev/null +++ b/docs/guides/configure_database.md @@ -0,0 +1,88 @@ +# Configure database connection + +The language server requires a database connection for schema-dependent features. + +## Features requiring database connection + +- Type checking using `EXPLAIN` +- Autocompletion for tables, columns, functions, and schemas +- Hover information for database objects +- PL/pgSQL analysis via `plpgsql_check` extension +- Code actions for executing statements under the cursor +- Schema-aware validation and object resolution + +## Configuration + +Configure database connection details in your `postgrestools.jsonc` file: + +```json +{ + "database": { + // Database host address (default: "127.0.0.1") + "host": "localhost", + // Database port (default: 5432) + "port": 5432, + // Database username (default: "postgres") + "username": "postgres", + // Database password (default: "postgres") + "password": "your_password", + // Database name to connect to (default: "postgres") + "database": "your_database_name", + // Connection timeout in seconds (default: 10) + "connTimeoutSecs": 10, + // Schemas where code action statement execution is allowed (default: []) + "allowStatementExecutionsAgainst": ["public", "testing"], + // Completely disable database features (default: false) + "disableConnection": false + } +} +``` + + +## Security Considerations + +### Read-Only Access +The language server primarily needs read access to your database schema. Consider creating a dedicated user with limited permissions: + +```sql +CREATE USER postgrestools_lsp WITH PASSWORD 'secure_password'; +GRANT CONNECT ON DATABASE your_database TO postgrestools_lsp; +GRANT USAGE ON SCHEMA public TO postgrestools_lsp; +GRANT SELECT ON ALL TABLES IN SCHEMA public TO postgrestools_lsp; +GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO postgrestools_lsp; +GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA public TO postgrestools_lsp; +``` + +### Statement Execution Control +You can control which schemas allow code action statement execution (executing statements under the cursor): + +```json +{ + "database": { + "allowStatementExecutionsAgainst": ["public", "testing"] + } +} +``` + +## Disabling Database Features + +If you prefer to work without a database connection, you can disable all database-related features: + +```json +{ + "database": { + "disableConnection": true + } +} +``` + +Or use the command line flag: + +```bash +postgrestools check sql/ --disable-db +``` + +When disabled, you'll still get: + +- Basic syntax highlighting +- Linting rules that don't require schema information diff --git a/docs/guides/continuous_integration.md b/docs/guides/continuous_integration.md new file mode 100644 index 000000000..44ac4c2d3 --- /dev/null +++ b/docs/guides/continuous_integration.md @@ -0,0 +1,45 @@ +# Continuous Integration + +Running the Postgres Language Server in a CI environment can boost your teams confidence by linting your schema changes and catching errors early. + +### GitHub Actions + +We provide a first-party [GitHub Action](https://github.com/supabase-community/postgrestools-cli-action) to setup the CLI in your runner. Here’s what a simple workflow might look like: + +```yaml +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: supabase-community/pglt-cli-action@main + with: + version: latest + - run: postgrestools check --skip-db sql/ +``` + +You likely want to setup Postgres to enable more advanced checks: + +```yaml +jobs: + lint: + runs-on: ubuntu-latest + services: + postgres: + image: postgres:latest + env: + POSTGRES_USER: postgres + POSTGRES_PASSWORD: postgres + POSTGRES_DB: postgres + ports: + - 5432:5432 + steps: + - uses: actions/checkout@v4 + - uses: supabase-community/pglt-cli-action@main + with: + version: latest + - run: postgrestools check sql/ +``` + +A common use-case is to check your migration files. Check out [the dedicated guide](./checking_migrations.md) for details. + diff --git a/docs/guides/ide_setup.md b/docs/guides/ide_setup.md new file mode 100644 index 000000000..b97c6c249 --- /dev/null +++ b/docs/guides/ide_setup.md @@ -0,0 +1,70 @@ +# Use in your IDE + +Th Postgres Language Server has first-class [LSP](https://microsoft.github.io/language-server-protocol/) support to seamlessly integrate into your favorite editor. + +## VSCode + +The language server is available on the [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=Supabase.postgrestools). It's published from [this repo](https://github.com/supabase-community/postgrestools-vscode). + +## Neovim + +You will have to install `nvim-lspconfig`, and follow the [instructions](https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#postgres_lsp). + +## Emacs + +The language client is available through [lsp-mode](https://github.com/emacs-lsp/lsp-mode). For more details, refer to their [manual page](https://emacs-lsp.github.io/lsp-mode/page/lsp-postgres/). + +## Zed + +The language server is available as an Extension. It's published from [this repo](https://github.com/LoamStudios/zed-postgres-language-server). + +> [!NOTE] +> Is there a extension for an editor that is not listed here? Please file a PR and we will be happy to add it to the list + +## Integrate in an editor extension + +Is your favorite editor missing? Thanks to the language server protocol, integrating the Postgres Language Server protocol should be straightforward. + +### Use the LSP proxy +The CLI has a command called `lsp-proxy`. When executed, we will spawn two processes: + +- a daemon that does execute the requested operations; +- a server that functions as a proxy between the requests of the client - the editor - and the server - the daemon; + +If your editor is able to interact with a server and send [JSON-RPC](https://www.jsonrpc.org/) request, you only need to configure the editor run that command. + + +### Use the daemon with the binary +Using the binary via CLI is very efficient, although you will not be able to provide logs to your users. The CLI allows you to bootstrap a daemon and then use the CLI commands through the daemon itself. + +If order to do so, you first need to start a daemon process with the start command: + +```shell +postgrestools start +``` + +Then, every command needs to add the `--use-server` options, e.g.: + +```shell +postgrestools check --use-server --stdin-file-path=dummy.sql +``` + + +> [!Note] +> If you decide to use the daemon, you’re also responsible to restart/kill the process with the stop command, to avoid having ghost processes. +Caution + +Operations via the daemon are significantly slower than the CLI itself, so it’s advised to run operations only on single files. + +### Daemon logs + +The daemon saves logs in your file system. Logs are stored in a folder called `pgt-logs`. The path of this folder changes based on your operative system: + +- Linux: `~/.cache/pgt;` +- Windows: `C:\Users\\AppData\Local\supabase-community\pgt\cache` +- macOS: `/Users//Library/Caches/dev.supabase-community.pgt` + +For other operative systems, you can find the folder in the system’s temporary directory. + +You can change the location of the `pgt-logs` folder via the `PGT_LOG_PATH` variable. + diff --git a/docs/rule_suppressions.md b/docs/guides/suppressions.md similarity index 97% rename from docs/rule_suppressions.md rename to docs/guides/suppressions.md index af5890e72..0ffea005a 100644 --- a/docs/rule_suppressions.md +++ b/docs/guides/suppressions.md @@ -1,4 +1,4 @@ -# Rule Suppressions +# Diagnostics Suppressions You can suppress specific diagnostics or rules in your code using suppression comments. This is useful when you want to ignore a particular rule for an entire file, a line or a block of code. @@ -90,5 +90,5 @@ alter table tasks drop column created_at; ## Notes -- Trying to suppress diagnostics that have already been disabled in your [configuration file](/#configuration) will show a warning. -- Trying to suppress diagnostics that don't haven't been raised will also show a warning. +- Trying to suppress diagnostics that have already been disabled in your [configuration file](/#configuration) will show a warning. +- Trying to suppress diagnostics that don't haven't been raised will also show a warning. diff --git a/docs/guides/vcs_integration.md b/docs/guides/vcs_integration.md new file mode 100644 index 000000000..e22e83676 --- /dev/null +++ b/docs/guides/vcs_integration.md @@ -0,0 +1,69 @@ +# Integrate with VCS + +The VCS (Version Control System) integration is meant to take advantage of additional features that only a VCS can provide. These features include ignoring files based on your VCS ignore patterns, checking only changed files, and checking staged files before commits. + +The integration is opt-in. You have to enable `vcs.enabled` and set `vcs.clientKind` in the configuration file: + + +```json +{ + "vcs": { + "enabled": true, + "clientKind": "git" + } +} +``` + +This configuration doesn’t do anything per se. You need to opt-in the features you want. + +## Use the ignore file + +Enable `vcs.useIgnoreFile`, to to ignore all the files and directories listed in the project’s VCS ignore file as well as a `.ignore` file. + + +```json +{ + "vcs": { + "enabled": true, + "clientKind": "git", + "useIgnoreFile": true + } +} +``` + +## Process only changed files + +This is a feature that is available only via CLI, and allows processing only the files that have changed from one revision to another. +First, you have to update your configuration file with the default branch via the `vcs.defaultBranch` field: + +```json +{ + "vcs": { + "enabled": true, + "clientKind": "git", + "useIgnoreFile": true, + "defaultBranch": "main" + } +} +``` + +Add the `--changed` option to your command to process only those files that your VCS acknowledged as “changed”. The language server will determine the changed files from the branch `main` and your current revision: + +```shell +postgrestools check --changed +``` + +Alternatively, you can use the option `--since` to specify an arbitrary branch. This option takes precedence over the option `vcs.defaultBranch`. For example, you might want to check your changes against the `next` branch: + +```shell +postgrestools check --changed --since=next +``` + +## Process only staged files + +Before committing your changes, you may want to check the files that have been added to the index, also known as staged files. Add the `--staged` option to process only those files: + +```shell +postgrestools check --staged +``` + diff --git a/docs/index.md b/docs/index.md index 328e7c770..ff8a2a544 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ ![Postgres Language Server](images/pls-github.png) -# Postgres Tools +# Postgres Language Server A collection of language tools and a Language Server Protocol (LSP) implementation for Postgres, focusing on developer experience and reliable SQL tooling. @@ -10,164 +10,14 @@ A collection of language tools and a Language Server Protocol (LSP) implementati --- -## Overview +The language server is built on Postgres' own parser `libpg_query` to ensure 100% syntax compatibility. It uses a Server-Client architecture and is a transport-agnostic. This means all features can be accessed through the Language Server Protocol as well as a CLI. -This project provides a toolchain for Postgres development +The following features are available today: -##### Postgres Language Server +- [Syntax Diagnostics](/features/syntax_diagnostics) +- [Linting](/features/linting) +- [Type Checking](/features/type_checking) +- [PL/pgSQL Support](/features/plpgsql) +- [Autocompletion & Hover](/features/editor_features) -![LSP Demo](images/lsp-demo.gif) - -##### CLI Demo - -![CLI Demo](images/cli-demo.png) - -The toolchain is built on Postgres' own parser `libpg_query` to ensure 100% syntax compatibility. It uses a Server-Client architecture and is a transport-agnostic. This means all features can be accessed through the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) as well as various interfaces like a CLI, HTTP APIs, or a WebAssembly module. - -The following features are implemented: - -- Autocompletion -- Syntax Error Highlighting -- Type-checking (via `EXPLAIN` error insights) -- Linter, inspired by [Squawk](https://squawkhq.com) - -We are currently focused on refining and enhancing these core features. For future plans and opportunities to contribute, please check out the issues and discussions. Any contributions are welcome! - -## Installation - -There are various ways to use the toolchain. - -### CLI - -Grab the executable for your platform from the [latest CLI release](https://github.com/supabase-community/postgres-language-server/releases/latest) on GitHub and give it execution permission: - -```sh -curl -L https://github.com/supabase-community/postgres-language-server/releases/download//postgrestools_aarch64-apple-darwin -o postgrestools -chmod +x postgrestools -``` - -Now you can use Postgres Tools by simply running `./postgrestools`. - -### NPM - -If you are using Node, you can install the CLI via NPM. Run the following commands in a directory containing a `package.json` file. - -```sh -npm add --save-dev --save-exact @postgrestools/postgrestools -``` - -### VSCode - -The language server is available on the [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=Supabase.postgrestools). It's published from [this repo](https://github.com/supabase-community/postgrestools-vscode). - -### Neovim - -You will have to install `nvim-lspconfig`, and follow the [instructions](https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#postgres_lsp). - -### Emacs - -The language client is available through [lsp-mode](https://github.com/emacs-lsp/lsp-mode). For more details, refer to their [manual page](https://emacs-lsp.github.io/lsp-mode/page/lsp-postgres/). - -### Zed - -The language server is available as an Extension. It's published from [this repo](https://github.com/LoamStudios/zed-postgres-language-server). - -### GitHub Actions - -To use the CLI in GitHub Actions, you can install it via our [GitHub Action](https://github.com/supabase-community/postgrestools-cli-action). - -## Configuration - -We recommend creating a `postgrestools.jsonc` configuration file for each project. This eliminates repetitive CLI options and ensures that consistent configuration in your editor. Some options are only available from a configuration file. This step is optional: if you are happy with the defaults, you don’t need a configuration file. To create the `postgrestools.jsonc` file, run the `init` command in the root folder of your project: - -```sh -postgrestools init -``` - -You’ll now have a `postgrestools.jsonc` file in your directory: - -[//]: # "BEGIN DEFAULT_CONFIGURATION" - -```json -{ - "$schema": "https://pgtools.dev/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/*"] - } -} -``` - -[//]: # "END DEFAULT_CONFIGURATION" - -Make sure to edit the database connection settings to connect to your local development database. To see all options, run `postgrestools --help`. - -You can use your current `postgrestools` version instead of "latest" in the `$schema` URL, e.g. `https://pgtools.dev/0.8.1/schema.json`. - -## Usage - -You can use Postgres Tools via the command line or a using a code editor that supports an LSP. - -#### Using the CLI - -The CLI exposes a simple `check` command that will run all checks on the given files or paths. - -```sh -postgrestools check myfile.sql -``` - -Make sure to check out the other options by running `postgrestools --help`. We will provide guides for specific use cases like linting migration files soon. - -#### Using the LSP Proxy - -Postgres Tools has a command called `lsp-proxy`. When executed, two processes will spawn: - -- a daemon that does execute the requested operations; -- a server that functions as a proxy between the requests of the client - the editor - and the server - the daemon; - If your editor is able to interact with a server and send [JSON-RPC](https://www.jsonrpc.org) requests, you only need to configure the editor to run that command. - -#### Using the daemon with the binary - -Using the binary via CLI is very efficient, although you won’t be able to provide logs to your users. The CLI allows you to bootstrap a daemon and then use the CLI commands through the daemon itself. -In order to do so, you first need to start a daemon process with the start command: - -```sh -postgrestools start -``` - -Then, every command needs to add the `--use-server` options, e.g.: - -```sh -echo "select 1" | postgrestools check --use-server --stdin-file-path=dummy.sql -``` - -#### Daemon logs - -The daemon saves logs in your file system. Logs are stored in a folder called `pgt-logs`. The path of this folder changes based on your operative system: - -- Linux: `~/.cache/pgt;` -- Windows: `C:\Users\\AppData\Local\supabase-community\pgt\cache` -- macOS: `/Users//Library/Caches/dev.supabase-community.pgt` - -For other operative systems, you can find the folder in the system’s temporary directory. - -You can change the location of the `pgt-logs` folder via the `PGT_LOG_PATH` variable. +For future plans and opportunities to contribute, please check out the issues and discussions. Any contributions are welcome! diff --git a/docs/manual_installation.md b/docs/manual_installation.md new file mode 100644 index 000000000..2c20f9dc2 --- /dev/null +++ b/docs/manual_installation.md @@ -0,0 +1,53 @@ +## Manual installation + +Directly installing the standalone CLI can be a great alternative if you are not already using a package manager. + +### Supported platforms + +You have to pick the correct binary for your platform. The following table should help you do so. + +| CPU Architecture | Operating System | Binary name | +|------------------|------------------|-------------| +| x86_64 | Linux | `postgrestools-x86_64-unknown-linux-gnu` | +| aarch64 | Linux | `postgrestools-aarch64-unknown-linux-gnu` | +| x86_64 | macOS | `postgrestools-x86_64-apple-darwin` | +| aarch64 (M1/M2) | macOS | `postgrestools-aarch64-apple-darwin` | +| x86_64 | Windows | `postgrestools-x86_64-pc-windows-msvc.exe` | +| aarch64 | Windows | `postgrestools-aarch64-pc-windows-msvc.exe` | + +> **Note**: Use the Linux variant for Windows Subsystem for Linux (WSL). + + +### Homebrew + +We were not able to publish to Homebrew yet due to naming conflicts. We are actively working to resolve this. + +### Using a published binary + +To install postgrestools, grab the executable for your platform from the latest CLI release on GitHub and give it execution permission. + +```bash +# macOS arm (M1 or newer) +curl -L https://github.com/supabase-community/postgres-language-server/releases/latest/download/postgrestools-aarch64-apple-darwin -o postgrestools +chmod +x postgrestools + +# macOS x86_64 +curl -L https://github.com/supabase-community/postgres-language-server/releases/latest/download/postgrestools-x86_64-apple-darwin -o postgrestools +chmod +x postgrestools + +# Linux (x86_64) +curl -L https://github.com/supabase-community/postgres-language-server/releases/latest/download/postgrestools-x86_64-unknown-linux-gnu -o postgrestools +chmod +x postgrestools + +# Linux (aarch64) +curl -L https://github.com/supabase-community/postgres-language-server/releases/latest/download/postgrestools-aarch64-unknown-linux-gnu -o postgrestools +chmod +x postgrestools + +# Windows (x86_64, PowerShell) +Invoke-WebRequest -Uri "https://github.com/supabase-community/postgres-language-server/releases/latest/download/postgrestools-x86_64-pc-windows-msvc.exe" -OutFile "postgrestools.exe" + +# Windows (aarch64, PowerShell) +Invoke-WebRequest -Uri "https://github.com/supabase-community/postgres-language-server/releases/latest/download/postgrestools-aarch64-pc-windows-msvc.exe" -OutFile "postgrestools.exe" +``` + +Now you can use the Postgres Language Server by simply running `./postgrestools`. diff --git a/docs/plpgsql.md b/docs/plpgsql.md deleted file mode 100644 index da190b0ca..000000000 --- a/docs/plpgsql.md +++ /dev/null @@ -1,9 +0,0 @@ -# PL/pgSQL Support - -Postgres Language Tools partially supports PL/pgSQL. We use `libpg_query` to parse the function body and show any syntax error. For a more sophisticated integration, make sure to enable the `plpgsql_check` extension in your development database. - -```sql -CREATE EXTENSION IF NOT EXISTS plpgsql_check; -``` - -If the extension is detected, we leverage it to run more advanced checks against your PL/pgSQL functions. diff --git a/docs/cli_reference.md b/docs/reference/cli.md similarity index 73% rename from docs/cli_reference.md rename to docs/reference/cli.md index f87807898..81db5e1e5 100644 --- a/docs/cli_reference.md +++ b/docs/reference/cli.md @@ -1,17 +1,17 @@ -## CLI Reference +# CLI Reference [//]: # "BEGIN CLI_REF" # Command summary -- [`postgrestools`↴](#postgrestools) -- [`postgrestools version`↴](#postgrestools-version) -- [`postgrestools check`↴](#postgrestools-check) -- [`postgrestools start`↴](#postgrestools-start) -- [`postgrestools stop`↴](#postgrestools-stop) -- [`postgrestools init`↴](#postgrestools-init) -- [`postgrestools lsp-proxy`↴](#postgrestools-lsp-proxy) -- [`postgrestools clean`↴](#postgrestools-clean) +- [`postgrestools`↴](#postgrestools) +- [`postgrestools version`↴](#postgrestools-version) +- [`postgrestools check`↴](#postgrestools-check) +- [`postgrestools start`↴](#postgrestools-start) +- [`postgrestools stop`↴](#postgrestools-stop) +- [`postgrestools init`↴](#postgrestools-init) +- [`postgrestools lsp-proxy`↴](#postgrestools-lsp-proxy) +- [`postgrestools clean`↴](#postgrestools-clean) ## postgrestools @@ -21,26 +21,26 @@ PostgresTools official CLI. Use it to check the health of your project or run it **Available options:** -- **`-h`**, **`--help`** — +- **`-h`**, **`--help`** — Prints help information -- **`-V`**, **`--version`** — +- **`-V`**, **`--version`** — Prints version information **Available commands:** -- **`version`** — +- **`version`** — Shows the version information and quit. -- **`check`** — +- **`check`** — Runs everything to the requested files. -- **`start`** — +- **`start`** — Starts the daemon server process. -- **`stop`** — +- **`stop`** — Stops the daemon server process. -- **`init`** — +- **`init`** — Bootstraps a new project. Creates a configuration file with some defaults. -- **`lsp-proxy`** — +- **`lsp-proxy`** — Acts as a server for the Language Server Protocol over stdin/stdout. -- **`clean`** — +- **`clean`** — Cleans the logs emitted by the daemon. ## postgrestools version @@ -51,44 +51,44 @@ Shows the version information and quit. **Global options applied to all commands** -- **` --colors`**=_``_ — +- **` --colors`**=_``_ — Set the formatting mode for markup: "off" prints everything as plain text, "force" forces the formatting of markup using ANSI even if the console output is determined to be incompatible -- **` --use-server`** — +- **` --use-server`** — Connect to a running instance of the daemon server. -- **` --skip-db`** — +- **` --skip-db`** — Skip connecting to the database and only run checks that don't require a database connection. -- **` --verbose`** — +- **` --verbose`** — Print additional diagnostics, and some diagnostics show more information. Also, print out what files were processed and which ones were modified. -- **` --config-path`**=_`PATH`_ — +- **` --config-path`**=_`PATH`_ — Set the file path to the configuration file, or the directory path to find `postgrestools.jsonc`. If used, it disables the default configuration file resolution. -- **` --max-diagnostics`**=_`>`_ — +- **` --max-diagnostics`**=_`>`_ — Cap the amount of diagnostics displayed. When `none` is provided, the limit is lifted. [default: 20] -- **` --skip-errors`** — +- **` --skip-errors`** — Skip over files containing syntax errors instead of emitting an error diagnostic. -- **` --no-errors-on-unmatched`** — +- **` --no-errors-on-unmatched`** — Silence errors that would be emitted in case no files were processed during the execution of the command. -- **` --error-on-warnings`** — +- **` --error-on-warnings`** — Tell Postgres Tools to exit with an error code if some diagnostics emit warnings. -- **` --reporter`**=_``_ — +- **` --reporter`**=_``_ — Allows to change how diagnostics and summary are reported. -- **` --log-level`**=_``_ — +- **` --log-level`**=_``_ — The level of logging. In order, from the most verbose to the least verbose: debug, info, warn, error. The value `none` won't show any logging. [default: none] -- **` --log-kind`**=_``_ — +- **` --log-kind`**=_``_ — How the log should look like. [default: pretty] -- **` --diagnostic-level`**=_``_ — +- **` --diagnostic-level`**=_``_ — The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing `--diagnostic-level=error` will cause Postgres Tools to print only diagnostics that contain only errors. [default: info] **Available options:** -- **`-h`**, **`--help`** — +- **`-h`**, **`--help`** — Prints help information ## postgrestools check @@ -99,97 +99,97 @@ Runs everything to the requested files. **The configuration that is contained inside the configuration file.** -- **` --vcs-enabled`**=_``_ — +- **` --vcs-enabled`**=_``_ — Whether we should integrate itself with the VCS client -- **` --vcs-client-kind`**=_``_ — +- **` --vcs-client-kind`**=_``_ — The kind of client. -- **` --vcs-use-ignore-file`**=_``_ — +- **` --vcs-use-ignore-file`**=_``_ — Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file. -- **` --vcs-root`**=_`PATH`_ — +- **` --vcs-root`**=_`PATH`_ — The folder where we should check for VCS files. By default, we will use the same folder where `postgrestools.jsonc` was found. If we can't find the configuration, it will attempt to use the current working directory. If no current working directory can't be found, we won't use the VCS integration, and a diagnostic will be emitted -- **` --vcs-default-branch`**=_`BRANCH`_ — +- **` --vcs-default-branch`**=_`BRANCH`_ — The main branch of the project -- **` --files-max-size`**=_`NUMBER`_ — +- **` --files-max-size`**=_`NUMBER`_ — The maximum allowed size for source code files in bytes. Files above this limit will be ignored for performance reasons. Defaults to 1 MiB -- **` --migrations-dir`**=_`ARG`_ — +- **` --migrations-dir`**=_`ARG`_ — The directory where the migration files are stored -- **` --after`**=_`ARG`_ — +- **` --after`**=_`ARG`_ — Ignore any migrations before this timestamp -- **` --host`**=_`ARG`_ — +- **` --host`**=_`ARG`_ — The host of the database. -- **` --port`**=_`ARG`_ — +- **` --port`**=_`ARG`_ — The port of the database. -- **` --username`**=_`ARG`_ — +- **` --username`**=_`ARG`_ — The username to connect to the database. -- **` --password`**=_`ARG`_ — +- **` --password`**=_`ARG`_ — The password to connect to the database. -- **` --database`**=_`ARG`_ — +- **` --database`**=_`ARG`_ — The name of the database. -- **` --conn_timeout_secs`**=_`ARG`_ — +- **` --conn_timeout_secs`**=_`ARG`_ — The connection timeout in seconds. [default: Some(10)] **Global options applied to all commands** -- **` --colors`**=_``_ — +- **` --colors`**=_``_ — Set the formatting mode for markup: "off" prints everything as plain text, "force" forces the formatting of markup using ANSI even if the console output is determined to be incompatible -- **` --use-server`** — +- **` --use-server`** — Connect to a running instance of the daemon server. -- **` --skip-db`** — +- **` --skip-db`** — Skip connecting to the database and only run checks that don't require a database connection. -- **` --verbose`** — +- **` --verbose`** — Print additional diagnostics, and some diagnostics show more information. Also, print out what files were processed and which ones were modified. -- **` --config-path`**=_`PATH`_ — +- **` --config-path`**=_`PATH`_ — Set the file path to the configuration file, or the directory path to find `postgrestools.jsonc`. If used, it disables the default configuration file resolution. -- **` --max-diagnostics`**=_`>`_ — +- **` --max-diagnostics`**=_`>`_ — Cap the amount of diagnostics displayed. When `none` is provided, the limit is lifted. [default: 20] -- **` --skip-errors`** — +- **` --skip-errors`** — Skip over files containing syntax errors instead of emitting an error diagnostic. -- **` --no-errors-on-unmatched`** — +- **` --no-errors-on-unmatched`** — Silence errors that would be emitted in case no files were processed during the execution of the command. -- **` --error-on-warnings`** — +- **` --error-on-warnings`** — Tell Postgres Tools to exit with an error code if some diagnostics emit warnings. -- **` --reporter`**=_``_ — +- **` --reporter`**=_``_ — Allows to change how diagnostics and summary are reported. -- **` --log-level`**=_``_ — +- **` --log-level`**=_``_ — The level of logging. In order, from the most verbose to the least verbose: debug, info, warn, error. The value `none` won't show any logging. [default: none] -- **` --log-kind`**=_``_ — +- **` --log-kind`**=_``_ — How the log should look like. [default: pretty] -- **` --diagnostic-level`**=_``_ — +- **` --diagnostic-level`**=_``_ — The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing `--diagnostic-level=error` will cause Postgres Tools to print only diagnostics that contain only errors. [default: info] **Available positional items:** -- _`PATH`_ — +- _`PATH`_ — Single file, single path or list of paths **Available options:** -- **` --stdin-file-path`**=_`PATH`_ — +- **` --stdin-file-path`**=_`PATH`_ — Use this option when you want to format code piped from `stdin`, and print the output to `stdout`. The file doesn't need to exist on disk, what matters is the extension of the file. Based on the extension, we know how to check the code. Example: `echo 'let a;' | pgt_cli check --stdin-file-path=test.sql` -- **` --staged`** — +- **` --staged`** — When set to true, only the files that have been staged (the ones prepared to be committed) will be linted. This option should be used when working locally. -- **` --changed`** — +- **` --changed`** — When set to true, only the files that have been changed compared to your `defaultBranch` configuration will be linted. This option should be used in CI environments. -- **` --since`**=_`REF`_ — +- **` --since`**=_`REF`_ — Use this to specify the base branch to compare against when you're using the --changed flag and the `defaultBranch` is not set in your `postgrestools.jsonc` -- **`-h`**, **`--help`** — +- **`-h`**, **`--help`** — Prints help information ## postgrestools start @@ -200,17 +200,17 @@ Starts the daemon server process. **Available options:** -- **` --log-prefix-name`**=_`STRING`_ — +- **` --log-prefix-name`**=_`STRING`_ — Allows to change the prefix applied to the file name of the logs. Uses environment variable **`PGT_LOG_PREFIX_NAME`** [default: server.log] -- **` --log-path`**=_`PATH`_ — +- **` --log-path`**=_`PATH`_ — Allows to change the folder where logs are stored. Uses environment variable **`PGT_LOG_PATH`** -- **` --config-path`**=_`PATH`_ — +- **` --config-path`**=_`PATH`_ — Allows to set a custom file path to the configuration file, or a custom directory path to find `postgrestools.jsonc` Uses environment variable **`PGT_LOG_PREFIX_NAME`** -- **`-h`**, **`--help`** — +- **`-h`**, **`--help`** — Prints help information ## postgrestools stop @@ -221,7 +221,7 @@ Stops the daemon server process. **Available options:** -- **`-h`**, **`--help`** — +- **`-h`**, **`--help`** — Prints help information ## postgrestools init @@ -232,7 +232,7 @@ Bootstraps a new project. Creates a configuration file with some defaults. **Available options:** -- **`-h`**, **`--help`** — +- **`-h`**, **`--help`** — Prints help information ## postgrestools lsp-proxy @@ -243,17 +243,17 @@ Acts as a server for the Language Server Protocol over stdin/stdout. **Available options:** -- **` --log-prefix-name`**=_`STRING`_ — +- **` --log-prefix-name`**=_`STRING`_ — Allows to change the prefix applied to the file name of the logs. Uses environment variable **`PGT_LOG_PREFIX_NAME`** [default: server.log] -- **` --log-path`**=_`PATH`_ — +- **` --log-path`**=_`PATH`_ — Allows to change the folder where logs are stored. Uses environment variable **`PGT_LOG_PATH`** -- **` --config-path`**=_`PATH`_ — +- **` --config-path`**=_`PATH`_ — Allows to set a custom file path to the configuration file, or a custom directory path to find `postgrestools.jsonc` Uses environment variable **`PGT_CONFIG_PATH`** -- **`-h`**, **`--help`** — +- **`-h`**, **`--help`** — Prints help information ## postgrestools clean @@ -264,7 +264,7 @@ Cleans the logs emitted by the daemon. **Available options:** -- **`-h`**, **`--help`** — +- **`-h`**, **`--help`** — Prints help information [//]: # "END CLI_REF" diff --git a/docs/env_variables.md b/docs/reference/env_variables.md similarity index 91% rename from docs/env_variables.md rename to docs/reference/env_variables.md index a3091f48e..c8f7097a2 100644 --- a/docs/env_variables.md +++ b/docs/reference/env_variables.md @@ -1,4 +1,4 @@ -## Environment Variables +# Environment Variables [//]: # (BEGIN ENV_VARS) diff --git a/docs/rule_sources.md b/docs/reference/rule_sources.md similarity index 84% rename from docs/rule_sources.md rename to docs/reference/rule_sources.md index 679448cdc..087555aa6 100644 --- a/docs/rule_sources.md +++ b/docs/reference/rule_sources.md @@ -1,4 +1,7 @@ +# Rule Sources +Many rules are inspired by or directly ported from other tools. This page lists the sources of each rule. ## Exclusive rules +_No exclusive rules available._ ## Rules from other sources ### Squawk | Squawk Rule Name | Rule Name | diff --git a/docs/rules.md b/docs/reference/rules.md similarity index 88% rename from docs/rules.md rename to docs/reference/rules.md index d74b67e88..2ff8361b7 100644 --- a/docs/rules.md +++ b/docs/reference/rules.md @@ -1,8 +1,8 @@ # Rules -Below the list of rules supported by Postgres Language Tools, divided by group. Here's a legend of the emojis: +Below the list of rules supported by the Postgres Language Server, divided by group. Here's a legend of the emojis: -- The icon ✅ indicates that the rule is part of the recommended rules. +- The icon ✅ indicates that the rule is part of the recommended rules. [//]: # (BEGIN RULES_INDEX) @@ -21,4 +21,3 @@ Rules that detect potential safety issues in your code. [//]: # (END RULES_INDEX) - diff --git a/docs/rules/adding-required-field.md b/docs/reference/rules/adding-required-field.md similarity index 100% rename from docs/rules/adding-required-field.md rename to docs/reference/rules/adding-required-field.md diff --git a/docs/rules/ban-drop-column.md b/docs/reference/rules/ban-drop-column.md similarity index 100% rename from docs/rules/ban-drop-column.md rename to docs/reference/rules/ban-drop-column.md diff --git a/docs/rules/ban-drop-database.md b/docs/reference/rules/ban-drop-database.md similarity index 100% rename from docs/rules/ban-drop-database.md rename to docs/reference/rules/ban-drop-database.md diff --git a/docs/rules/ban-drop-not-null.md b/docs/reference/rules/ban-drop-not-null.md similarity index 100% rename from docs/rules/ban-drop-not-null.md rename to docs/reference/rules/ban-drop-not-null.md diff --git a/docs/rules/ban-drop-table.md b/docs/reference/rules/ban-drop-table.md similarity index 100% rename from docs/rules/ban-drop-table.md rename to docs/reference/rules/ban-drop-table.md diff --git a/docs/rules/ban-truncate-cascade.md b/docs/reference/rules/ban-truncate-cascade.md similarity index 100% rename from docs/rules/ban-truncate-cascade.md rename to docs/reference/rules/ban-truncate-cascade.md diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md deleted file mode 100644 index f9d91561e..000000000 --- a/docs/troubleshooting.md +++ /dev/null @@ -1,9 +0,0 @@ -## Troubleshooting - -This guide describes how to resolve common issues with Postgres Language Tools. - -### Incorrect and / or misplaced diagnostics - -We are employing pragmatic solutions to split a SQL file into statements, and they might be incorrect in certain cases. If you see diagnostics like `Unexpected token` in the middle of a valid statement, make sure to either end all statements with a semicolon, or put two double newlines between them. If there are still issues, its most likely a bug in the change handler that is gone after reopening the file. But please file an issue with sample code so we can fix the root cause. - - diff --git a/mkdocs.yml b/mkdocs.yml index 120be04db..489a1aff0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,17 +13,27 @@ theme: primary: grey accent: red nav: - - Introduction: index.md + - Getting Started: getting_started.md + - Manual Installation: manual_installation.md + - Configuration: configuration.md + - Features: + - Syntax Diagnostics: features/syntax_diagnostics.md + - Linting: features/linting.md + - Type Checking: features/type_checking.md + - PL/pgSQL Support: features/plpgsql.md + - Autocompletion & Hover: features/editor_features.md - Guides: - - Linting Migrations: checking_migrations.md - - PL/pgSQL Support: plpgsql.md - - Troubleshooting: troubleshooting.md + - Use in your IDE: guides/ide_setup.md + - Checking Migrations: guides/checking_migrations.md + - Configure database connection: guides/configure_database.md + - Suppressions: guides/suppressions.md + - Integrate with VCS: guides/vcs_integration.md + - Continuous Integration: guides/continuous_integration.md - Reference: - - Rules: rules.md - - Rule Sources: rule_sources.md - - Rule Suppressions: rule_suppressions.md - - CLI: cli_reference.md - - Environment Variables: env_variables.md + - CLI Commands: reference/cli.md + - Linter Rules: reference/rules.md + - Rule Sources: reference/rule_sources.md + - Environment Variables: reference/env_variables.md plugins: - gh-admonitions