From cc80f712e0fc31721640225036673ea2f65f0b86 Mon Sep 17 00:00:00 2001 From: Copple <10214025+kiwicopple@users.noreply.github.com> Date: Sat, 29 Mar 2025 22:09:18 +0100 Subject: [PATCH] regrouping installation options Feel free to edit this. The goal is to create a clearer logical flow: - overview - install - configure - use previously the installation instructions are a bit scattered --- docs/index.md | 83 +++++++++++++++++++++++++++------------------------ 1 file changed, 44 insertions(+), 39 deletions(-) diff --git a/docs/index.md b/docs/index.md index 29d6eaed..f1477e17 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ ![Postgres Language Server](images/pls-github.png) -# Postgres Language Server +# Postgres Tools A collection of language tools and a Language Server Protocol (LSP) implementation for Postgres, focusing on developer experience and reliable SQL tooling. @@ -12,24 +12,34 @@ A collection of language tools and a Language Server Protocol (LSP) implementati ## Overview -LSP Demo | CLI Demo -:-------------------------:|:-------------------------: -![LSP Demo](images/lsp-demo.gif) | ![CLI Demo](images/cli-demo.png) +This project provides a toolchain for Postgres development -This project provides a toolchain for Postgres development, built on Postgres' own parser `libpg_query` to ensure 100% syntax compatibility. It is built on a Server-Client architecture with a transport-agnostic design. This means all features can be accessed not only through the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), but also through other interfaces like a CLI, HTTP APIs, or a WebAssembly module. The goal is to make all the great Postgres tooling out there as accessible as possible, and to build anything that is missing ourselves. +##### Postgres Language Server -Currently, the following features are implemented: +![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) -Our current focus is on refining and enhancing these core features while building a robust and easily accessible infrastructure. For future plans and opportunities to contribute, please check out the issues and discussions. Any contributions are welcome! +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 -To install Postgres Tools, 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. +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 @@ -38,23 +48,35 @@ chmod +x postgrestools Now you can use Postgres Tools by simply running `./postgrestools`. -If you are using Node, you can also install the CLI via NPM. Run the following commands in a directory containing a `package.json` file. +### 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 -pnpm add --save-dev --save-exact @postgrestools/postgrestools +npm add --save-dev --save-exact @postgrestools/postgrestools ``` -To use Postgres Tools in your favorite IDE, we recommend [installing an editor plugin](#install-an-editor-plugin). +### VSCode + +The language server is available on the [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=Supabase.postgrestools-vscode). Its 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). + +### 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 that you create a `postgrestools.jsonc` configuration file for each project. This eliminates the need to repeat the CLI options each time you run a command, and ensures that we use the same configuration in your editor. Some options are also only available from a configuration file. If you are happy with the defaults, you don’t need to create a configuration file. To create the `postgrestools.jsonc` file, run the `init` command in the root folder of your project: +We recommend creating a `postgrestools.jsonc` configuration file for each project. This eliminates repetitive CLI options and ensures that consitent 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 ``` -After running the `init` command, you’ll have a `postgrestools.jsonc` file in your directory: +You’ll now have a `postgrestools.jsonc` file in your directory: [//]: # (BEGIN DEFAULT_CONFIGURATION) @@ -88,11 +110,13 @@ After running the `init` command, you’ll have a `postgrestools.jsonc` file in [//]: # (END DEFAULT_CONFIGURATION) -Make sure to point the database connection settings at your local development database. To see what else can be configured, run `--help`. +Make sure to edit the database connection settings to connect to your local development database. To see all options, run `postgrestools --help`. ## Usage -You can use the language tools either via CLI or a Language Server. +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. @@ -100,33 +124,17 @@ The CLI exposes a simple `check` command that will run all checks on the given f postgrestools check myfile.sql ``` -Make sure to check out the other options. We will provide guides for specific use cases like linting migration files soon. +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. -## Install an Editor Plugin - -We recommend installing an editor plugin to get the most out of Postgres Language Tools. - -### VSCode - -The language server is available on the [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=Supabase.postgrestools-vscode). Its 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). - - -### Other - -Postgres Tools has first-class LSP support. If your editor does implement LSP, then the integration of Postgres Tools should be seamless. - -#### Use the LSP Proxy +#### 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. -#### Use the daemon with the binary +#### 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: @@ -141,6 +149,7 @@ echo "select 1" | biome 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;` @@ -151,7 +160,3 @@ For other operative systems, you can find the folder in the system’s temporary You can change the location of the `pgt-logs` folder via the `PGT_LOG_PATH` variable. -## CI Setup - -To use the CLI in GitHub Actions, you can install it via our [GitHub Action](https://github.com/supabase-community/postgrestools-cli-action). -