404
+ +Page not found
+ + +
+
+
+
+ {rule_name}"
+ )?;
+ }
+ writeln!(content)?;
+ }
+
+ write_documentation(group, rule, meta.docs, &mut content)?;
+
+ write_how_to_configure(group, rule, &mut content)?;
+
+ Ok(String::from_utf8(content)?)
+}
+
+fn write_how_to_configure(
+ group: &'static str,
+ rule: &'static str,
+ content: &mut Vec")?; + } + + Event::Start(Tag::List(num)) => { + list_indentation += 1; + if let Some(num) = num { + list_order = Some(num); + } + if list_indentation > 1 { + writeln!(content)?; + } + } + + Event::End(TagEnd::List(_)) => { + list_order = None; + list_indentation -= 1; + writeln!(content)?; + } + Event::Start(Tag::Item) => { + write!(content, "{}", " ".repeat(list_indentation - 1))?; + if let Some(num) = list_order { + write!(content, "{num}. ")?; + } else { + write!(content, "- ")?; + } + } + + Event::End(TagEnd::Item) => { + list_order = list_order.map(|item| item + 1); + writeln!(content)?; + } + + Event::Start(Tag::Strong) => { + write!(content, "**")?; + } + + Event::End(TagEnd::Strong) => { + write!(content, "**")?; + } + + Event::Start(Tag::Emphasis) => { + write!(content, "_")?; + } + + Event::End(TagEnd::Emphasis) => { + write!(content, "_")?; + } + + Event::Start(Tag::Strikethrough) => { + write!(content, "~")?; + } + + Event::End(TagEnd::Strikethrough) => { + write!(content, "~")?; + } + + Event::Start(Tag::BlockQuote(_)) => { + write!(content, ">")?; + } + + Event::End(TagEnd::BlockQuote(_)) => { + writeln!(content)?; + } + + _ => { + bail!("unimplemented event {event:?}") + } + } + } + + Ok(()) +} + +struct CodeBlockTest { + /// The language tag of this code block. + tag: String, + + /// True if this is an invalid example that should trigger a diagnostic. + expect_diagnostic: bool, + + /// Whether to ignore this code block. + ignore: bool, + + /// The number of lines in this code block. + line_count: u32, + + // The indices of lines that should be hidden from the public documentation. + hidden_lines: Vec
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Environment Variables
+PGT_LOG_PATH
+The directory where the Daemon logs will be saved.
+PGT_LOG_PREFIX_NAME
+A prefix that's added to the name of the log. Default: server.log.
PGT_CONFIG_PATH
+A path to the configuration file
+ +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/images/cli-demo.png b/0.10.0/images/cli-demo.png
similarity index 100%
rename from docs/images/cli-demo.png
rename to 0.10.0/images/cli-demo.png
diff --git a/docs/images/lsp-demo.gif b/0.10.0/images/lsp-demo.gif
similarity index 100%
rename from docs/images/lsp-demo.gif
rename to 0.10.0/images/lsp-demo.gif
diff --git a/docs/images/pls-github.png b/0.10.0/images/pls-github.png
similarity index 100%
rename from docs/images/pls-github.png
rename to 0.10.0/images/pls-github.png
diff --git a/0.10.0/img/favicon.ico b/0.10.0/img/favicon.ico
new file mode 100644
index 000000000..e85006a3c
Binary files /dev/null and b/0.10.0/img/favicon.ico differ
diff --git a/0.10.0/index.html b/0.10.0/index.html
new file mode 100644
index 000000000..dd8e094d5
--- /dev/null
+++ b/0.10.0/index.html
@@ -0,0 +1,290 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 
Postgres Tools
+A collection of language tools and a Language Server Protocol (LSP) implementation for Postgres, focusing on developer experience and reliable SQL tooling.
++
Source Code: https://github.com/supabase-community/postgres-language-server
++
Overview
+This project provides a toolchain for Postgres development
+Postgres Language Server
+
CLI Demo
+
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 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
EXPLAINerror insights)
+ - Linter, inspired by Squawk +
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 on GitHub and give it execution permission:
+curl -L https://github.com/supabase-community/postgres-language-server/releases/download/<version>/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.
npm add --save-dev --save-exact @postgrestools/postgrestools
+VSCode
+The language server is available on the VSCode Marketplace. It's published from this repo.
+Neovim
+You will have to install nvim-lspconfig, and follow the instructions.
Emacs
+The language client is available through lsp-mode. For more details, refer to their manual page.
+Zed
+The language server is available as an Extension. It's published from this repo.
+GitHub Actions
+To use the CLI in GitHub Actions, you can install it via our GitHub 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:
postgrestools init
+You’ll now have a postgrestools.jsonc file in your directory:
{
+ "$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/*"]
+ }
+}
+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.
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 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:
+postgrestools start
+Then, every command needs to add the --use-server options, e.g.:
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\<UserName>\AppData\Local\supabase-community\pgt\cache
+ - macOS:
/Users/<UserName>/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.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.10.0/js/html5shiv.min.js b/0.10.0/js/html5shiv.min.js
new file mode 100644
index 000000000..1a01c94ba
--- /dev/null
+++ b/0.10.0/js/html5shiv.min.js
@@ -0,0 +1,4 @@
+/**
+* @preserve HTML5 Shiv 3.7.3 | @afarkas @jdalton @jon_neal @rem | MIT/GPL2 Licensed
+*/
+!function(a,b){function c(a,b){var c=a.createElement("p"),d=a.getElementsByTagName("head")[0]||a.documentElement;return c.innerHTML="x",d.insertBefore(c.lastChild,d.firstChild)}function d(){var a=t.elements;return"string"==typeof a?a.split(" "):a}function e(a,b){var c=t.elements;"string"!=typeof c&&(c=c.join(" ")),"string"!=typeof a&&(a=a.join(" ")),t.elements=c+" "+a,j(b)}function f(a){var b=s[a[q]];return b||(b={},r++,a[q]=r,s[r]=b),b}function g(a,c,d){if(c||(c=b),l)return c.createElement(a);d||(d=f(c));var e;return e=d.cache[a]?d.cache[a].cloneNode():p.test(a)?(d.cache[a]=d.createElem(a)).cloneNode():d.createElem(a),!e.canHaveChildren||o.test(a)||e.tagUrn?e:d.frag.appendChild(e)}function h(a,c){if(a||(a=b),l)return a.createDocumentFragment();c=c||f(a);for(var e=c.frag.cloneNode(),g=0,h=d(),i=h.length;i>g;g++)e.createElement(h[g]);return e}function i(a,b){b.cache||(b.cache={},b.createElem=a.createElement,b.createFrag=a.createDocumentFragment,b.frag=b.createFrag()),a.createElement=function(c){return t.shivMethods?g(c,a,b):b.createElem(c)},a.createDocumentFragment=Function("h,f","return function(){var n=f.cloneNode(),c=n.createElement;h.shivMethods&&("+d().join().replace(/[\w\-:]+/g,function(a){return b.createElem(a),b.frag.createElement(a),'c("'+a+'")'})+");return n}")(t,b.frag)}function j(a){a||(a=b);var d=f(a);return!t.shivCSS||k||d.hasCSS||(d.hasCSS=!!c(a,"article,aside,dialog,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}mark{background:#FF0;color:#000}template{display:none}")),l||i(a,d),a}var k,l,m="3.7.3",n=a.html5||{},o=/^<|^(?:button|map|select|textarea|object|iframe|option|optgroup)$/i,p=/^(?:a|b|code|div|fieldset|h1|h2|h3|h4|h5|h6|i|label|li|ol|p|q|span|strong|style|table|tbody|td|th|tr|ul)$/i,q="_html5shiv",r=0,s={};!function(){try{var a=b.createElement("a");a.innerHTML="
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Exclusive rules
+Rules from other sources
+Squawk
+| Squawk Rule Name | +Rule Name | +
|---|---|
| adding-required-field | +addingRequiredField | +
| ban-drop-column | +banDropColumn | +
| ban-drop-database | +banDropDatabase | +
| ban-drop-not-null | +banDropNotNull | +
| ban-drop-table | +banDropTable | +
| ban-truncate-cascade | +banTruncateCascade | +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.10.0/rule_suppressions/index.html b/0.10.0/rule_suppressions/index.html
new file mode 100644
index 000000000..6bb2aa403
--- /dev/null
+++ b/0.10.0/rule_suppressions/index.html
@@ -0,0 +1,214 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rule 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.
+How to Suppress a Rule
+To suppress a rule, add a comment above the line causing the diagnostic with the following format:
+-- pgt-ignore lint/safety/banDropTable
+drop table users;
+You can suppress single rules, groups of rules, or entire categories. The format of the rule to suppress is:
+category(/group(/specific-rule))
Where group and specific rule are optional.
+So, to suppress the lint/safety/banDropTable diagnostic, all of these would work:
-- pgt-ignore lint
+-- pgt-ignore lint/safety
+-- pgt-ignore lint/safety/banDropTable
+You can also add an explanation to the suppression by adding a : and the explanation text:
-- pgt-ignore lint/safety/banDropTable: My startup never had any users.
+drop table users;
+Suppressing Rules for Block of Code
+You can suppress rules for blocks of code.
+create table users (
+ -- ...
+);
+
+-- pgt-ignore-start typecheck: The `users` table will be created with this migration.
+alter table users drop constraint users_pkey;
+
+alter table users add primary key (user_id);
+-- pgt-ignore-end typecheck
+Every pgt-ignore-start needs a pgt-ignore-end suppression comment, and the suppressed rules must match exactly.
This won't work, because the start tag suppresses a different diagnostic:
+-- pgt-ignore-start lint/safety/banDropColumn
+-- pgt-ignore-end lint/safety
+Nesting is allowed, so this works fine:
+-- pgt-ignore-start typecheck: outer
+-- pgt-ignore-start lint/safety: inner
+-- pgt-ignore-end lint/safety: inner
+-- pgt-ignore-end typecheck: outer
+Suppressing Rules for Entire Files
+Instead of repeating the same suppression on multiple lines, you can suppress for an entire file.
+-- pgt-ignore-all lint/safety/banDropTable
+
+drop table tasks;
+drop table projects;
+drop table users;
+Suppressing Multiple Rules
+You can suppress multiple rules by adding multiple suppression comments above a statement:
+-- pgt-ignore lint/safety/banDropColumn
+-- pgt-ignore typecheck
+alter table tasks drop column created_at;
+Notes
+-
+
- Trying to suppress diagnostics that have already been disabled in your configuration file will show a warning. +
- Trying to suppress diagnostics that don't haven't been raised will also show a warning. +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.10.0/rules/adding-required-field/index.html b/0.10.0/rules/adding-required-field/index.html
new file mode 100644
index 000000000..95a84af23
--- /dev/null
+++ b/0.10.0/rules/adding-required-field/index.html
@@ -0,0 +1,157 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ addingRequiredField
+Diagnostic Category: lint/safety/addingRequiredField
Since: vnext
Sources:
+- Inspired from: squawk/adding-required-field
Description
+Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required.
+This will fail immediately upon running for any populated table. Furthermore, old application code that is unaware of this column will fail to INSERT to this table.
+Make new columns optional initially by omitting the NOT NULL constraint until all existing data and application code has been updated. Once no NULL values are written to or persisted in the database, set it to NOT NULL. +Alternatively, if using Postgres version 11 or later, add a DEFAULT value that is not volatile. This allows the column to keep its NOT NULL constraint.
+Invalid
+alter table test add column count int not null;
+Valid in Postgres >= 11
+alter table test add column count int not null default 0;
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "addingRequiredField": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.10.0/rules/ban-drop-column/index.html b/0.10.0/rules/ban-drop-column/index.html
new file mode 100644
index 000000000..1790b7d29
--- /dev/null
+++ b/0.10.0/rules/ban-drop-column/index.html
@@ -0,0 +1,172 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropColumn
+Diagnostic Category: lint/safety/banDropColumn
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-column
Description
+Dropping a column may break existing clients.
+Update your application code to no longer read or write the column.
+You can leave the column as nullable or delete the column once queries no longer select or modify the column.
+Examples
+Invalid
+alter table test drop column id;
+code-block.sql:1:1 lint/safety/banDropColumn ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a column may break existing clients.
+
+ > 1 │ alter table test drop column id;
+ │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ 2 │
+
+ i You can leave the column as nullable or delete the column once queries no longer select or modify the column.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropColumn": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.10.0/rules/ban-drop-database/index.html b/0.10.0/rules/ban-drop-database/index.html
new file mode 100644
index 000000000..e09c07d12
--- /dev/null
+++ b/0.10.0/rules/ban-drop-database/index.html
@@ -0,0 +1,151 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropDatabase
+Diagnostic Category: lint/safety/banDropDatabase
Since: vnext
Sources:
+- Inspired from: squawk/ban-drop-database
Description
+Dropping a database may break existing clients (and everything else, really).
+Make sure that you really want to drop it.
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropDatabase": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.10.0/rules/ban-drop-not-null/index.html b/0.10.0/rules/ban-drop-not-null/index.html
new file mode 100644
index 000000000..9bd7bc4d4
--- /dev/null
+++ b/0.10.0/rules/ban-drop-not-null/index.html
@@ -0,0 +1,172 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropNotNull
+Diagnostic Category: lint/safety/banDropNotNull
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-not-null
Description
+Dropping a NOT NULL constraint may break existing clients.
+Application code or code written in procedural languages like PL/SQL or PL/pgSQL may not expect NULL values for the column that was previously guaranteed to be NOT NULL and therefore may fail to process them correctly.
+You can consider using a marker value that represents NULL. Alternatively, create a new table allowing NULL values, copy the data from the old table, and create a view that filters NULL values.
+Examples
+Invalid
+alter table users alter column email drop not null;
+code-block.sql:1:1 lint/safety/banDropNotNull ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a NOT NULL constraint may break existing clients.
+
+ > 1 │ alter table users alter column email drop not null;
+ │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ 2 │
+
+ i Consider using a marker value that represents NULL. Alternatively, create a new table allowing NULL values, copy the data from the old table, and create a view that filters NULL values.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropNotNull": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.10.0/rules/ban-drop-table/index.html b/0.10.0/rules/ban-drop-table/index.html
new file mode 100644
index 000000000..ac9554a25
--- /dev/null
+++ b/0.10.0/rules/ban-drop-table/index.html
@@ -0,0 +1,173 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropTable
+Diagnostic Category: lint/safety/banDropTable
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-table
Description
+Dropping a table may break existing clients.
+Update your application code to no longer read or write the table.
+Once the table is no longer needed, you can delete it by running the command "DROP TABLE mytable;".
+This command will permanently remove the table from the database and all its contents. +Be sure to back up the table before deleting it, just in case you need to restore it in the future.
+Examples
+drop table some_table;
+code-block.sql:1:1 lint/safety/banDropTable ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a table may break existing clients.
+
+ > 1 │ drop table some_table;
+ │ ^^^^^^^^^^^^^^^^^^^^^^
+ 2 │
+
+ i Update your application code to no longer read or write the table, and only then delete the table. Be sure to create a backup.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropTable": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.10.0/rules/ban-truncate-cascade/index.html b/0.10.0/rules/ban-truncate-cascade/index.html
new file mode 100644
index 000000000..cd690fa8c
--- /dev/null
+++ b/0.10.0/rules/ban-truncate-cascade/index.html
@@ -0,0 +1,157 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banTruncateCascade
+Diagnostic Category: lint/safety/banTruncateCascade
Since: vnext
Sources:
+- Inspired from: squawk/ban-truncate-cascade
Description
+Using TRUNCATE's CASCADE option will truncate any tables that are also foreign-keyed to the specified tables.
So if you had tables with foreign-keys like:
+a <- b <- c
and ran:
+truncate a cascade;
You'd end up with a, b, & c all being truncated!
+Instead, you can manually specify the tables you want.
+truncate a, b;
How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banTruncateCascade": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.10.0/rules/index.html b/0.10.0/rules/index.html
new file mode 100644
index 000000000..332706c93
--- /dev/null
+++ b/0.10.0/rules/index.html
@@ -0,0 +1,191 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rules
+Below the list of rules supported by Postgres Language Tools, divided by group. Here's a legend of the emojis:
+-
+
- The icon ✅ indicates that the rule is part of the recommended rules. +
Safety
+Rules that detect potential safety issues in your code.
+| Rule name | +Description | +Properties | +
|---|---|---|
| addingRequiredField | +Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required. | ++ |
| banDropColumn | +Dropping a column may break existing clients. | +✅ | +
| banDropDatabase | +Dropping a database may break existing clients (and everything else, really). | ++ |
| banDropNotNull | +Dropping a NOT NULL constraint may break existing clients. | +✅ | +
| banDropTable | +Dropping a table may break existing clients. | +✅ | +
| banTruncateCascade | +Using TRUNCATE's CASCADE option will truncate any tables that are also foreign-keyed to the specified tables. |
++ |
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.10.0/schema.json b/0.10.0/schema.json
new file mode 100644
index 000000000..1c56618ed
--- /dev/null
+++ b/0.10.0/schema.json
@@ -0,0 +1,471 @@
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "Configuration",
+ "description": "The configuration that is contained inside the configuration file.",
+ "type": "object",
+ "properties": {
+ "$schema": {
+ "description": "A field for the [JSON schema](https://json-schema.org/) specification",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "db": {
+ "description": "The configuration of the database connection",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/DatabaseConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "extends": {
+ "description": "A list of paths to other JSON files, used to extends the current configuration.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "files": {
+ "description": "The configuration of the filesystem",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/FilesConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "linter": {
+ "description": "The configuration for the linter",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/LinterConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "migrations": {
+ "description": "Configure migrations",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/MigrationsConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "vcs": {
+ "description": "The configuration of the VCS integration",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/VcsConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false,
+ "definitions": {
+ "DatabaseConfiguration": {
+ "description": "The configuration of the database connection.",
+ "type": "object",
+ "properties": {
+ "allowStatementExecutionsAgainst": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "connTimeoutSecs": {
+ "description": "The connection timeout in seconds.",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint16",
+ "minimum": 0.0
+ },
+ "database": {
+ "description": "The name of the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "host": {
+ "description": "The host of the database. Required if you want database-related features. All else falls back to sensible defaults.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "password": {
+ "description": "The password to connect to the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "port": {
+ "description": "The port of the database.",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint16",
+ "minimum": 0.0
+ },
+ "username": {
+ "description": "The username to connect to the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "FilesConfiguration": {
+ "description": "The configuration of the filesystem",
+ "type": "object",
+ "properties": {
+ "ignore": {
+ "description": "A list of Unix shell style patterns. Will ignore files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "include": {
+ "description": "A list of Unix shell style patterns. Will handle only those files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "maxSize": {
+ "description": "The maximum allowed size for source code files in bytes. Files above this limit will be ignored for performance reasons. Defaults to 1 MiB",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint64",
+ "minimum": 1.0
+ }
+ },
+ "additionalProperties": false
+ },
+ "LinterConfiguration": {
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "description": "if `false`, it disables the feature and the linter won't be executed. `true` by default",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "ignore": {
+ "description": "A list of Unix shell style patterns. The formatter will ignore files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "include": {
+ "description": "A list of Unix shell style patterns. The formatter will include files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "rules": {
+ "description": "List of rules",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/Rules"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "MigrationsConfiguration": {
+ "description": "The configuration of the filesystem",
+ "type": "object",
+ "properties": {
+ "after": {
+ "description": "Ignore any migrations before this timestamp",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint64",
+ "minimum": 0.0
+ },
+ "migrationsDir": {
+ "description": "The directory where the migration files are stored",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "RuleConfiguration": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RulePlainConfiguration"
+ },
+ {
+ "$ref": "#/definitions/RuleWithNoOptions"
+ }
+ ]
+ },
+ "RulePlainConfiguration": {
+ "type": "string",
+ "enum": [
+ "warn",
+ "error",
+ "info",
+ "off"
+ ]
+ },
+ "RuleWithNoOptions": {
+ "type": "object",
+ "required": [
+ "level"
+ ],
+ "properties": {
+ "level": {
+ "description": "The severity of the emitted diagnostics by the rule",
+ "allOf": [
+ {
+ "$ref": "#/definitions/RulePlainConfiguration"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "Rules": {
+ "type": "object",
+ "properties": {
+ "all": {
+ "description": "It enables ALL rules. The rules that belong to `nursery` won't be enabled.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "recommended": {
+ "description": "It enables the lint rules recommended by Postgres Tools. `true` by default.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "safety": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/Safety"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "Safety": {
+ "description": "A list of rules that belong to this group",
+ "type": "object",
+ "properties": {
+ "addingRequiredField": {
+ "description": "Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "all": {
+ "description": "It enables ALL rules for this group.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "banDropColumn": {
+ "description": "Dropping a column may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropDatabase": {
+ "description": "Dropping a database may break existing clients (and everything else, really).",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropNotNull": {
+ "description": "Dropping a NOT NULL constraint may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropTable": {
+ "description": "Dropping a table may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banTruncateCascade": {
+ "description": "Using TRUNCATE's CASCADE option will truncate any tables that are also foreign-keyed to the specified tables.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "recommended": {
+ "description": "It enables the recommended rules for this group",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "StringSet": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "uniqueItems": true
+ },
+ "VcsClientKind": {
+ "oneOf": [
+ {
+ "description": "Integration with the git client as VCS",
+ "type": "string",
+ "enum": [
+ "git"
+ ]
+ }
+ ]
+ },
+ "VcsConfiguration": {
+ "description": "Set of properties to integrate with a VCS software.",
+ "type": "object",
+ "properties": {
+ "clientKind": {
+ "description": "The kind of client.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/VcsClientKind"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "defaultBranch": {
+ "description": "The main branch of the project",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "enabled": {
+ "description": "Whether we should integrate itself with the VCS client",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "root": {
+ "description": "The folder where we should check for VCS files. By default, we will use the same folder where `postgrestools.jsonc` was found.\n\nIf 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",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "useIgnoreFile": {
+ "description": "Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ }
+ }
+}
\ No newline at end of file
diff --git a/0.10.0/sitemap.xml b/0.10.0/sitemap.xml
new file mode 100644
index 000000000..0af0ccef8
--- /dev/null
+++ b/0.10.0/sitemap.xml
@@ -0,0 +1,59 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/404.html b/0.11.0/404.html
new file mode 100644
index 000000000..4f5464516
--- /dev/null
+++ b/0.11.0/404.html
@@ -0,0 +1,128 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 404
+ +Page not found
+ + +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/checking_migrations/index.html b/0.11.0/checking_migrations/index.html
new file mode 100644
index 000000000..0c1e970e3
--- /dev/null
+++ b/0.11.0/checking_migrations/index.html
@@ -0,0 +1,161 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Linting Migrations
+Postgres Language Tools comes with a check command that can be integrated into your development workflow to catch problematic schema changes and encourage best practices.
To run it, simply point at your migrations directory.
+postgrestools check supabase/migrations
+When you are setting it up in an existing project, you might want to ignore all migrations that are already applied. To do so, add migrationsDir and after to your postgrestools.jsonc file
{
+ "migrations": {
+ "migrationsDir": "supabase/migrations",
+ "after": 1740868021
+ }
+}
+Alternatively, pass them directly.
+postgrestools check supabase/migrations --migrations-dir="supabase/migrations" --after=1740868021
+This will only check migrations after the specified timestamp.
+For pre-commit hooks and when working locally, use --staged to only lint files that have been staged. In CI environments, you most likely want to use --changed to only lint files that have been changed compared to your vcs.default_branch configuration. If default_branch is not set in your postgrestools.jsonc, use --since=REF to specify the base branch to compare against.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/cli_reference/index.html b/0.11.0/cli_reference/index.html
new file mode 100644
index 000000000..dae46bff6
--- /dev/null
+++ b/0.11.0/cli_reference/index.html
@@ -0,0 +1,382 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ CLI Reference
+Command summary
+-
+
postgrestools↴
+postgrestools version↴
+postgrestools check↴
+postgrestools start↴
+postgrestools stop↴
+postgrestools init↴
+postgrestools lsp-proxy↴
+postgrestools clean↴
+
postgrestools
+PostgresTools official CLI. Use it to check the health of your project or run it to check single files.
+Usage: postgrestools COMMAND ...
Available options:
+-
+
-h,--help— + Prints help information
+-V,--version— + Prints version information
+
Available commands:
+-
+
version— + Shows the version information and quit.
+check— + Runs everything to the requested files.
+start— + Starts the daemon server process.
+stop— + Stops the daemon server process.
+init— + Bootstraps a new project. Creates a configuration file with some defaults.
+lsp-proxy— + Acts as a server for the Language Server Protocol over stdin/stdout.
+clean— + Cleans the logs emitted by the daemon.
+
postgrestools version
+Shows the version information and quit.
+Usage: postgrestools version
Global options applied to all commands
+-
+
--colors=<off|force>— + 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— + Connect to a running instance of the daemon server.
+--skip-db— + Skip connecting to the database and only run checks that don't require a database connection.
+--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— + Set the file path to the configuration file, or the directory path to findpostgrestools.jsonc. If used, it disables the default configuration file resolution.
+--max-diagnostics=<none|<NUMBER>>— + Cap the amount of diagnostics displayed. Whennoneis provided, the limit is lifted. + [default: 20]
+--skip-errors— + Skip over files containing syntax errors instead of emitting an error diagnostic.
+--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— + Tell Postgres Tools to exit with an error code if some diagnostics emit warnings.
+--reporter=<json|json-pretty|github|junit|summary|gitlab>— + Allows to change how diagnostics and summary are reported.
+--log-level=<none|debug|info|warn|error>— + 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=<pretty|compact|json>— + How the log should look like. + [default: pretty]
+--diagnostic-level=<info|warn|error>— + The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing--diagnostic-level=errorwill cause Postgres Tools to print only diagnostics that contain only errors. + [default: info]
+
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools check
+Runs everything to the requested files.
+Usage: postgrestools check [--staged] [--changed] [--since=REF] [PATH]...
The configuration that is contained inside the configuration file.
+-
+
--vcs-enabled=<true|false>— + Whether we should integrate itself with the VCS client
+--vcs-client-kind=<git>— + The kind of client.
+--vcs-use-ignore-file=<true|false>— + Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file.
+--vcs-root=PATH— + The folder where we should check for VCS files. By default, we will use the same folder wherepostgrestools.jsoncwas 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— + The main branch of the project
+--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— + The directory where the migration files are stored
+--after=ARG— + Ignore any migrations before this timestamp
+--host=ARG— + The host of the database.
+--port=ARG— + The port of the database.
+--username=ARG— + The username to connect to the database.
+--password=ARG— + The password to connect to the database.
+--database=ARG— + The name of the database.
+--conn_timeout_secs=ARG— + The connection timeout in seconds. + [default: Some(10)]
+
Global options applied to all commands
+-
+
--colors=<off|force>— + 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— + Connect to a running instance of the daemon server.
+--skip-db— + Skip connecting to the database and only run checks that don't require a database connection.
+--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— + Set the file path to the configuration file, or the directory path to findpostgrestools.jsonc. If used, it disables the default configuration file resolution.
+--max-diagnostics=<none|<NUMBER>>— + Cap the amount of diagnostics displayed. Whennoneis provided, the limit is lifted. + [default: 20]
+--skip-errors— + Skip over files containing syntax errors instead of emitting an error diagnostic.
+--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— + Tell Postgres Tools to exit with an error code if some diagnostics emit warnings.
+--reporter=<json|json-pretty|github|junit|summary|gitlab>— + Allows to change how diagnostics and summary are reported.
+--log-level=<none|debug|info|warn|error>— + 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=<pretty|compact|json>— + How the log should look like. + [default: pretty]
+--diagnostic-level=<info|warn|error>— + The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing--diagnostic-level=errorwill cause Postgres Tools to print only diagnostics that contain only errors. + [default: info]
+
Available positional items:
+-
+
PATH— + Single file, single path or list of paths
+
Available options:
+-
+
--stdin-file-path=PATH— + Use this option when you want to format code piped fromstdin, and print the output tostdout.
+
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— + 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— + When set to true, only the files that have been changed compared to yourdefaultBranchconfiguration will be linted. This option should be used in CI environments.
+--since=REF— + Use this to specify the base branch to compare against when you're using the --changed flag and thedefaultBranchis not set in yourpostgrestools.jsonc
+-h,--help— + Prints help information
+
postgrestools start
+Starts the daemon server process.
+Usage: postgrestools start [--config-path=PATH]
Available options:
+-
+
--log-prefix-name=STRING— + Allows to change the prefix applied to the file name of the logs. + Uses environment variablePGT_LOG_PREFIX_NAME+ [default: server.log]
+--log-path=PATH— + Allows to change the folder where logs are stored. + Uses environment variablePGT_LOG_PATH
+--config-path=PATH— + Allows to set a custom file path to the configuration file, or a custom directory path to findpostgrestools.jsonc+ Uses environment variablePGT_LOG_PREFIX_NAME
+-h,--help— + Prints help information
+
postgrestools stop
+Stops the daemon server process.
+Usage: postgrestools stop
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools init
+Bootstraps a new project. Creates a configuration file with some defaults.
+Usage: postgrestools init
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools lsp-proxy
+Acts as a server for the Language Server Protocol over stdin/stdout.
+Usage: postgrestools lsp-proxy [--config-path=PATH]
Available options:
+-
+
--log-prefix-name=STRING— + Allows to change the prefix applied to the file name of the logs. + Uses environment variablePGT_LOG_PREFIX_NAME+ [default: server.log]
+--log-path=PATH— + Allows to change the folder where logs are stored. + Uses environment variablePGT_LOG_PATH
+--config-path=PATH— + Allows to set a custom file path to the configuration file, or a custom directory path to findpostgrestools.jsonc+ Uses environment variablePGT_CONFIG_PATH
+-h,--help— + Prints help information
+
postgrestools clean
+Cleans the logs emitted by the daemon.
+Usage: postgrestools clean
Available options:
+-
+
-h,--help— + Prints help information
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/codegen/Cargo.toml b/0.11.0/codegen/Cargo.toml
similarity index 100%
rename from docs/codegen/Cargo.toml
rename to 0.11.0/codegen/Cargo.toml
diff --git a/0.11.0/codegen/src/cli_doc.rs b/0.11.0/codegen/src/cli_doc.rs
new file mode 100644
index 000000000..47dd5ad7f
--- /dev/null
+++ b/0.11.0/codegen/src/cli_doc.rs
@@ -0,0 +1,20 @@
+use pgt_cli::pgt_command;
+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 content = fs::read_to_string(&file_path)?;
+
+ let new_content = utils::replace_section(
+ &content,
+ "CLI_REF",
+ &pgt_command().render_markdown("postgrestools"),
+ );
+
+ fs::write(file_path, &new_content)?;
+
+ Ok(())
+}
diff --git a/0.11.0/codegen/src/default_configuration.rs b/0.11.0/codegen/src/default_configuration.rs
new file mode 100644
index 000000000..bda30d148
--- /dev/null
+++ b/0.11.0/codegen/src/default_configuration.rs
@@ -0,0 +1,22 @@
+use std::{fs, path::Path};
+
+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 printed_config = format!(
+ "\n```json\n{}\n```\n",
+ serde_json::to_string_pretty(&PartialConfiguration::init())?
+ );
+
+ let data = fs::read_to_string(&index_path)?;
+
+ let new_data = replace_section(&data, "DEFAULT_CONFIGURATION", &printed_config);
+
+ fs::write(&index_path, new_data)?;
+
+ Ok(())
+}
diff --git a/0.11.0/codegen/src/env_variables.rs b/0.11.0/codegen/src/env_variables.rs
new file mode 100644
index 000000000..8834b4dc3
--- /dev/null
+++ b/0.11.0/codegen/src/env_variables.rs
@@ -0,0 +1,44 @@
+use anyhow::Result;
+use std::fs;
+use std::io::Write;
+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 mut content = vec![];
+
+ let env = pgt_flags::pgt_env();
+
+ writeln!(content, "\n",)?;
+
+ writeln!(
+ content,
+ "### `{}`\n\n {}\n",
+ env.pgt_log_path.name(),
+ env.pgt_log_path.description()
+ )?;
+ writeln!(
+ content,
+ "### `{}`\n\n {}\n",
+ env.pgt_log_prefix.name(),
+ env.pgt_log_prefix.description()
+ )?;
+ writeln!(
+ content,
+ "### `{}`\n\n {}\n",
+ env.pgt_config_path.name(),
+ env.pgt_config_path.description()
+ )?;
+
+ let data = fs::read_to_string(&file_path)?;
+
+ let conent_str = String::from_utf8(content)?;
+ let new_data = replace_section(&data, "ENV_VARS", &conent_str);
+
+ fs::write(file_path, new_data)?;
+
+ Ok(())
+}
diff --git a/0.11.0/codegen/src/lib.rs b/0.11.0/codegen/src/lib.rs
new file mode 100644
index 000000000..df49d5424
--- /dev/null
+++ b/0.11.0/codegen/src/lib.rs
@@ -0,0 +1,9 @@
+pub mod cli_doc;
+pub mod default_configuration;
+pub mod env_variables;
+pub mod rules_docs;
+pub mod rules_index;
+pub mod rules_sources;
+pub mod schema;
+
+mod utils;
diff --git a/0.11.0/codegen/src/main.rs b/0.11.0/codegen/src/main.rs
new file mode 100644
index 000000000..dfecbd533
--- /dev/null
+++ b/0.11.0/codegen/src/main.rs
@@ -0,0 +1,30 @@
+use std::env;
+use std::path::{Path, PathBuf};
+
+use docs_codegen::cli_doc::generate_cli_doc;
+use docs_codegen::default_configuration::generate_default_configuration;
+use docs_codegen::env_variables::generate_env_variables;
+use docs_codegen::rules_docs::generate_rules_docs;
+use docs_codegen::rules_index::generate_rules_index;
+use docs_codegen::rules_sources::generate_rule_sources;
+use docs_codegen::schema::generate_schema;
+
+fn docs_root() -> PathBuf {
+ let dir =
+ env::var("CARGO_MANIFEST_DIR").unwrap_or_else(|_| env!("CARGO_MANIFEST_DIR").to_owned());
+ Path::new(&dir).parent().unwrap().to_path_buf()
+}
+
+fn main() -> anyhow::Result<()> {
+ let docs_root = docs_root();
+
+ generate_default_configuration(&docs_root)?;
+ generate_env_variables(&docs_root)?;
+ generate_cli_doc(&docs_root)?;
+ generate_rules_docs(&docs_root)?;
+ generate_rules_index(&docs_root)?;
+ generate_rule_sources(&docs_root)?;
+ generate_schema(&docs_root)?;
+
+ Ok(())
+}
diff --git a/docs/codegen/src/rules_docs.rs b/0.11.0/codegen/src/rules_docs.rs
similarity index 100%
rename from docs/codegen/src/rules_docs.rs
rename to 0.11.0/codegen/src/rules_docs.rs
diff --git a/docs/codegen/src/rules_index.rs b/0.11.0/codegen/src/rules_index.rs
similarity index 100%
rename from docs/codegen/src/rules_index.rs
rename to 0.11.0/codegen/src/rules_index.rs
diff --git a/docs/codegen/src/rules_sources.rs b/0.11.0/codegen/src/rules_sources.rs
similarity index 100%
rename from docs/codegen/src/rules_sources.rs
rename to 0.11.0/codegen/src/rules_sources.rs
diff --git a/0.11.0/codegen/src/schema.rs b/0.11.0/codegen/src/schema.rs
new file mode 100644
index 000000000..3e430517d
--- /dev/null
+++ b/0.11.0/codegen/src/schema.rs
@@ -0,0 +1,186 @@
+use pgt_configuration::PartialConfiguration;
+use schemars::{
+ schema::{RootSchema, Schema, SchemaObject},
+ schema_for,
+};
+use serde_json::to_string_pretty;
+use std::{fs, path::Path};
+
+/// Generates the lint rules index.
+///
+/// * `docs_dir`: Path to the docs directory.
+pub fn generate_schema(docs_dir: &Path) -> anyhow::Result<()> {
+ let schema_path = docs_dir.join("schema.json");
+ let schema_content = get_configuration_schema_content()?;
+
+ fs::write(schema_path, &schema_content)?;
+
+ Ok(())
+}
+
+/// Get the content of the configuration schema
+pub(crate) fn get_configuration_schema_content() -> anyhow::Result
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Environment Variables
+PGT_LOG_PATH
+The directory where the Daemon logs will be saved.
+PGT_LOG_PREFIX_NAME
+A prefix that's added to the name of the log. Default: server.log.
PGT_CONFIG_PATH
+A path to the configuration file
+ +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/images/cli-demo.png b/0.11.0/images/cli-demo.png
new file mode 100644
index 000000000..33bac595c
Binary files /dev/null and b/0.11.0/images/cli-demo.png differ
diff --git a/0.11.0/images/lsp-demo.gif b/0.11.0/images/lsp-demo.gif
new file mode 100644
index 000000000..7fbff05fd
Binary files /dev/null and b/0.11.0/images/lsp-demo.gif differ
diff --git a/0.11.0/images/pls-github.png b/0.11.0/images/pls-github.png
new file mode 100644
index 000000000..95ae73828
Binary files /dev/null and b/0.11.0/images/pls-github.png differ
diff --git a/0.11.0/img/favicon.ico b/0.11.0/img/favicon.ico
new file mode 100644
index 000000000..e85006a3c
Binary files /dev/null and b/0.11.0/img/favicon.ico differ
diff --git a/0.11.0/index.html b/0.11.0/index.html
new file mode 100644
index 000000000..458c964de
--- /dev/null
+++ b/0.11.0/index.html
@@ -0,0 +1,292 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Postgres Tools
+A collection of language tools and a Language Server Protocol (LSP) implementation for Postgres, focusing on developer experience and reliable SQL tooling.
++
Source Code: https://github.com/supabase-community/postgres-language-server
++
Overview
+This project provides a toolchain for Postgres development
+Postgres Language Server
+
CLI Demo
+
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 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
EXPLAINerror insights)
+ - Linter, inspired by Squawk +
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 on GitHub and give it execution permission:
+curl -L https://github.com/supabase-community/postgres-language-server/releases/download/<version>/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.
npm add --save-dev --save-exact @postgrestools/postgrestools
+VSCode
+The language server is available on the VSCode Marketplace. It's published from this repo.
+Neovim
+You will have to install nvim-lspconfig, and follow the instructions.
Emacs
+The language client is available through lsp-mode. For more details, refer to their manual page.
+Zed
+The language server is available as an Extension. It's published from this repo.
+GitHub Actions
+To use the CLI in GitHub Actions, you can install it via our GitHub 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:
postgrestools init
+You’ll now have a postgrestools.jsonc file in your directory:
{
+ "$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/*"]
+ }
+}
+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.
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 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:
+postgrestools start
+Then, every command needs to add the --use-server options, e.g.:
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\<UserName>\AppData\Local\supabase-community\pgt\cache
+ - macOS:
/Users/<UserName>/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.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/js/html5shiv.min.js b/0.11.0/js/html5shiv.min.js
new file mode 100644
index 000000000..1a01c94ba
--- /dev/null
+++ b/0.11.0/js/html5shiv.min.js
@@ -0,0 +1,4 @@
+/**
+* @preserve HTML5 Shiv 3.7.3 | @afarkas @jdalton @jon_neal @rem | MIT/GPL2 Licensed
+*/
+!function(a,b){function c(a,b){var c=a.createElement("p"),d=a.getElementsByTagName("head")[0]||a.documentElement;return c.innerHTML="x",d.insertBefore(c.lastChild,d.firstChild)}function d(){var a=t.elements;return"string"==typeof a?a.split(" "):a}function e(a,b){var c=t.elements;"string"!=typeof c&&(c=c.join(" ")),"string"!=typeof a&&(a=a.join(" ")),t.elements=c+" "+a,j(b)}function f(a){var b=s[a[q]];return b||(b={},r++,a[q]=r,s[r]=b),b}function g(a,c,d){if(c||(c=b),l)return c.createElement(a);d||(d=f(c));var e;return e=d.cache[a]?d.cache[a].cloneNode():p.test(a)?(d.cache[a]=d.createElem(a)).cloneNode():d.createElem(a),!e.canHaveChildren||o.test(a)||e.tagUrn?e:d.frag.appendChild(e)}function h(a,c){if(a||(a=b),l)return a.createDocumentFragment();c=c||f(a);for(var e=c.frag.cloneNode(),g=0,h=d(),i=h.length;i>g;g++)e.createElement(h[g]);return e}function i(a,b){b.cache||(b.cache={},b.createElem=a.createElement,b.createFrag=a.createDocumentFragment,b.frag=b.createFrag()),a.createElement=function(c){return t.shivMethods?g(c,a,b):b.createElem(c)},a.createDocumentFragment=Function("h,f","return function(){var n=f.cloneNode(),c=n.createElement;h.shivMethods&&("+d().join().replace(/[\w\-:]+/g,function(a){return b.createElem(a),b.frag.createElement(a),'c("'+a+'")'})+");return n}")(t,b.frag)}function j(a){a||(a=b);var d=f(a);return!t.shivCSS||k||d.hasCSS||(d.hasCSS=!!c(a,"article,aside,dialog,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}mark{background:#FF0;color:#000}template{display:none}")),l||i(a,d),a}var k,l,m="3.7.3",n=a.html5||{},o=/^<|^(?:button|map|select|textarea|object|iframe|option|optgroup)$/i,p=/^(?:a|b|code|div|fieldset|h1|h2|h3|h4|h5|h6|i|label|li|ol|p|q|span|strong|style|table|tbody|td|th|tr|ul)$/i,q="_html5shiv",r=0,s={};!function(){try{var a=b.createElement("a");a.innerHTML="
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
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.
+ +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/rule_sources/index.html b/0.11.0/rule_sources/index.html
new file mode 100644
index 000000000..68d204c13
--- /dev/null
+++ b/0.11.0/rule_sources/index.html
@@ -0,0 +1,180 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Exclusive rules
+Rules from other sources
+Squawk
+| Squawk Rule Name | +Rule Name | +
|---|---|
| adding-required-field | +addingRequiredField | +
| ban-drop-column | +banDropColumn | +
| ban-drop-database | +banDropDatabase | +
| ban-drop-not-null | +banDropNotNull | +
| ban-drop-table | +banDropTable | +
| ban-truncate-cascade | +banTruncateCascade | +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/rule_suppressions/index.html b/0.11.0/rule_suppressions/index.html
new file mode 100644
index 000000000..b3fd451e1
--- /dev/null
+++ b/0.11.0/rule_suppressions/index.html
@@ -0,0 +1,216 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rule 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.
+How to Suppress a Rule
+To suppress a rule, add a comment above the line causing the diagnostic with the following format:
+-- pgt-ignore lint/safety/banDropTable
+drop table users;
+You can suppress single rules, groups of rules, or entire categories. The format of the rule to suppress is:
+category(/group(/specific-rule))
Where group and specific rule are optional.
+So, to suppress the lint/safety/banDropTable diagnostic, all of these would work:
-- pgt-ignore lint
+-- pgt-ignore lint/safety
+-- pgt-ignore lint/safety/banDropTable
+You can also add an explanation to the suppression by adding a : and the explanation text:
-- pgt-ignore lint/safety/banDropTable: My startup never had any users.
+drop table users;
+Suppressing Rules for Block of Code
+You can suppress rules for blocks of code.
+create table users (
+ -- ...
+);
+
+-- pgt-ignore-start typecheck: The `users` table will be created with this migration.
+alter table users drop constraint users_pkey;
+
+alter table users add primary key (user_id);
+-- pgt-ignore-end typecheck
+Every pgt-ignore-start needs a pgt-ignore-end suppression comment, and the suppressed rules must match exactly.
This won't work, because the start tag suppresses a different diagnostic:
+-- pgt-ignore-start lint/safety/banDropColumn
+-- pgt-ignore-end lint/safety
+Nesting is allowed, so this works fine:
+-- pgt-ignore-start typecheck: outer
+-- pgt-ignore-start lint/safety: inner
+-- pgt-ignore-end lint/safety: inner
+-- pgt-ignore-end typecheck: outer
+Suppressing Rules for Entire Files
+Instead of repeating the same suppression on multiple lines, you can suppress for an entire file.
+-- pgt-ignore-all lint/safety/banDropTable
+
+drop table tasks;
+drop table projects;
+drop table users;
+Suppressing Multiple Rules
+You can suppress multiple rules by adding multiple suppression comments above a statement:
+-- pgt-ignore lint/safety/banDropColumn
+-- pgt-ignore typecheck
+alter table tasks drop column created_at;
+Notes
+-
+
- Trying to suppress diagnostics that have already been disabled in your configuration file will show a warning. +
- Trying to suppress diagnostics that don't haven't been raised will also show a warning. +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/rules/adding-required-field/index.html b/0.11.0/rules/adding-required-field/index.html
new file mode 100644
index 000000000..28d71bcb1
--- /dev/null
+++ b/0.11.0/rules/adding-required-field/index.html
@@ -0,0 +1,159 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ addingRequiredField
+Diagnostic Category: lint/safety/addingRequiredField
Since: vnext
Sources:
+- Inspired from: squawk/adding-required-field
Description
+Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required.
+This will fail immediately upon running for any populated table. Furthermore, old application code that is unaware of this column will fail to INSERT to this table.
+Make new columns optional initially by omitting the NOT NULL constraint until all existing data and application code has been updated. Once no NULL values are written to or persisted in the database, set it to NOT NULL. +Alternatively, if using Postgres version 11 or later, add a DEFAULT value that is not volatile. This allows the column to keep its NOT NULL constraint.
+Invalid
+alter table test add column count int not null;
+Valid in Postgres >= 11
+alter table test add column count int not null default 0;
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "addingRequiredField": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/rules/ban-drop-column/index.html b/0.11.0/rules/ban-drop-column/index.html
new file mode 100644
index 000000000..b8234fbca
--- /dev/null
+++ b/0.11.0/rules/ban-drop-column/index.html
@@ -0,0 +1,174 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropColumn
+Diagnostic Category: lint/safety/banDropColumn
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-column
Description
+Dropping a column may break existing clients.
+Update your application code to no longer read or write the column.
+You can leave the column as nullable or delete the column once queries no longer select or modify the column.
+Examples
+Invalid
+alter table test drop column id;
+code-block.sql:1:1 lint/safety/banDropColumn ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a column may break existing clients.
+
+ > 1 │ alter table test drop column id;
+ │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ 2 │
+
+ i You can leave the column as nullable or delete the column once queries no longer select or modify the column.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropColumn": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/rules/ban-drop-database/index.html b/0.11.0/rules/ban-drop-database/index.html
new file mode 100644
index 000000000..8fd1ef5dc
--- /dev/null
+++ b/0.11.0/rules/ban-drop-database/index.html
@@ -0,0 +1,153 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropDatabase
+Diagnostic Category: lint/safety/banDropDatabase
Since: vnext
Sources:
+- Inspired from: squawk/ban-drop-database
Description
+Dropping a database may break existing clients (and everything else, really).
+Make sure that you really want to drop it.
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropDatabase": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/rules/ban-drop-not-null/index.html b/0.11.0/rules/ban-drop-not-null/index.html
new file mode 100644
index 000000000..1fd8f1b9c
--- /dev/null
+++ b/0.11.0/rules/ban-drop-not-null/index.html
@@ -0,0 +1,174 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropNotNull
+Diagnostic Category: lint/safety/banDropNotNull
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-not-null
Description
+Dropping a NOT NULL constraint may break existing clients.
+Application code or code written in procedural languages like PL/SQL or PL/pgSQL may not expect NULL values for the column that was previously guaranteed to be NOT NULL and therefore may fail to process them correctly.
+You can consider using a marker value that represents NULL. Alternatively, create a new table allowing NULL values, copy the data from the old table, and create a view that filters NULL values.
+Examples
+Invalid
+alter table users alter column email drop not null;
+code-block.sql:1:1 lint/safety/banDropNotNull ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a NOT NULL constraint may break existing clients.
+
+ > 1 │ alter table users alter column email drop not null;
+ │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ 2 │
+
+ i Consider using a marker value that represents NULL. Alternatively, create a new table allowing NULL values, copy the data from the old table, and create a view that filters NULL values.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropNotNull": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/rules/ban-drop-table/index.html b/0.11.0/rules/ban-drop-table/index.html
new file mode 100644
index 000000000..2e629b065
--- /dev/null
+++ b/0.11.0/rules/ban-drop-table/index.html
@@ -0,0 +1,175 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropTable
+Diagnostic Category: lint/safety/banDropTable
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-table
Description
+Dropping a table may break existing clients.
+Update your application code to no longer read or write the table.
+Once the table is no longer needed, you can delete it by running the command "DROP TABLE mytable;".
+This command will permanently remove the table from the database and all its contents. +Be sure to back up the table before deleting it, just in case you need to restore it in the future.
+Examples
+drop table some_table;
+code-block.sql:1:1 lint/safety/banDropTable ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a table may break existing clients.
+
+ > 1 │ drop table some_table;
+ │ ^^^^^^^^^^^^^^^^^^^^^^
+ 2 │
+
+ i Update your application code to no longer read or write the table, and only then delete the table. Be sure to create a backup.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropTable": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/rules/ban-truncate-cascade/index.html b/0.11.0/rules/ban-truncate-cascade/index.html
new file mode 100644
index 000000000..7ee474964
--- /dev/null
+++ b/0.11.0/rules/ban-truncate-cascade/index.html
@@ -0,0 +1,159 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banTruncateCascade
+Diagnostic Category: lint/safety/banTruncateCascade
Since: vnext
Sources:
+- Inspired from: squawk/ban-truncate-cascade
Description
+Using TRUNCATE's CASCADE option will truncate any tables that are also foreign-keyed to the specified tables.
So if you had tables with foreign-keys like:
+a <- b <- c
and ran:
+truncate a cascade;
You'd end up with a, b, & c all being truncated!
+Instead, you can manually specify the tables you want.
+truncate a, b;
How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banTruncateCascade": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/rules/index.html b/0.11.0/rules/index.html
new file mode 100644
index 000000000..03300300f
--- /dev/null
+++ b/0.11.0/rules/index.html
@@ -0,0 +1,193 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rules
+Below the list of rules supported by Postgres Language Tools, divided by group. Here's a legend of the emojis:
+-
+
- The icon ✅ indicates that the rule is part of the recommended rules. +
Safety
+Rules that detect potential safety issues in your code.
+| Rule name | +Description | +Properties | +
|---|---|---|
| addingRequiredField | +Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required. | ++ |
| banDropColumn | +Dropping a column may break existing clients. | +✅ | +
| banDropDatabase | +Dropping a database may break existing clients (and everything else, really). | ++ |
| banDropNotNull | +Dropping a NOT NULL constraint may break existing clients. | +✅ | +
| banDropTable | +Dropping a table may break existing clients. | +✅ | +
| banTruncateCascade | +Using TRUNCATE's CASCADE option will truncate any tables that are also foreign-keyed to the specified tables. |
++ |
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.11.0/schema.json b/0.11.0/schema.json
new file mode 100644
index 000000000..1c56618ed
--- /dev/null
+++ b/0.11.0/schema.json
@@ -0,0 +1,471 @@
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "Configuration",
+ "description": "The configuration that is contained inside the configuration file.",
+ "type": "object",
+ "properties": {
+ "$schema": {
+ "description": "A field for the [JSON schema](https://json-schema.org/) specification",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "db": {
+ "description": "The configuration of the database connection",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/DatabaseConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "extends": {
+ "description": "A list of paths to other JSON files, used to extends the current configuration.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "files": {
+ "description": "The configuration of the filesystem",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/FilesConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "linter": {
+ "description": "The configuration for the linter",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/LinterConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "migrations": {
+ "description": "Configure migrations",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/MigrationsConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "vcs": {
+ "description": "The configuration of the VCS integration",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/VcsConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false,
+ "definitions": {
+ "DatabaseConfiguration": {
+ "description": "The configuration of the database connection.",
+ "type": "object",
+ "properties": {
+ "allowStatementExecutionsAgainst": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "connTimeoutSecs": {
+ "description": "The connection timeout in seconds.",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint16",
+ "minimum": 0.0
+ },
+ "database": {
+ "description": "The name of the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "host": {
+ "description": "The host of the database. Required if you want database-related features. All else falls back to sensible defaults.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "password": {
+ "description": "The password to connect to the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "port": {
+ "description": "The port of the database.",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint16",
+ "minimum": 0.0
+ },
+ "username": {
+ "description": "The username to connect to the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "FilesConfiguration": {
+ "description": "The configuration of the filesystem",
+ "type": "object",
+ "properties": {
+ "ignore": {
+ "description": "A list of Unix shell style patterns. Will ignore files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "include": {
+ "description": "A list of Unix shell style patterns. Will handle only those files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "maxSize": {
+ "description": "The maximum allowed size for source code files in bytes. Files above this limit will be ignored for performance reasons. Defaults to 1 MiB",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint64",
+ "minimum": 1.0
+ }
+ },
+ "additionalProperties": false
+ },
+ "LinterConfiguration": {
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "description": "if `false`, it disables the feature and the linter won't be executed. `true` by default",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "ignore": {
+ "description": "A list of Unix shell style patterns. The formatter will ignore files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "include": {
+ "description": "A list of Unix shell style patterns. The formatter will include files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "rules": {
+ "description": "List of rules",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/Rules"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "MigrationsConfiguration": {
+ "description": "The configuration of the filesystem",
+ "type": "object",
+ "properties": {
+ "after": {
+ "description": "Ignore any migrations before this timestamp",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint64",
+ "minimum": 0.0
+ },
+ "migrationsDir": {
+ "description": "The directory where the migration files are stored",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "RuleConfiguration": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RulePlainConfiguration"
+ },
+ {
+ "$ref": "#/definitions/RuleWithNoOptions"
+ }
+ ]
+ },
+ "RulePlainConfiguration": {
+ "type": "string",
+ "enum": [
+ "warn",
+ "error",
+ "info",
+ "off"
+ ]
+ },
+ "RuleWithNoOptions": {
+ "type": "object",
+ "required": [
+ "level"
+ ],
+ "properties": {
+ "level": {
+ "description": "The severity of the emitted diagnostics by the rule",
+ "allOf": [
+ {
+ "$ref": "#/definitions/RulePlainConfiguration"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "Rules": {
+ "type": "object",
+ "properties": {
+ "all": {
+ "description": "It enables ALL rules. The rules that belong to `nursery` won't be enabled.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "recommended": {
+ "description": "It enables the lint rules recommended by Postgres Tools. `true` by default.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "safety": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/Safety"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "Safety": {
+ "description": "A list of rules that belong to this group",
+ "type": "object",
+ "properties": {
+ "addingRequiredField": {
+ "description": "Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "all": {
+ "description": "It enables ALL rules for this group.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "banDropColumn": {
+ "description": "Dropping a column may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropDatabase": {
+ "description": "Dropping a database may break existing clients (and everything else, really).",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropNotNull": {
+ "description": "Dropping a NOT NULL constraint may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropTable": {
+ "description": "Dropping a table may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banTruncateCascade": {
+ "description": "Using TRUNCATE's CASCADE option will truncate any tables that are also foreign-keyed to the specified tables.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "recommended": {
+ "description": "It enables the recommended rules for this group",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "StringSet": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "uniqueItems": true
+ },
+ "VcsClientKind": {
+ "oneOf": [
+ {
+ "description": "Integration with the git client as VCS",
+ "type": "string",
+ "enum": [
+ "git"
+ ]
+ }
+ ]
+ },
+ "VcsConfiguration": {
+ "description": "Set of properties to integrate with a VCS software.",
+ "type": "object",
+ "properties": {
+ "clientKind": {
+ "description": "The kind of client.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/VcsClientKind"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "defaultBranch": {
+ "description": "The main branch of the project",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "enabled": {
+ "description": "Whether we should integrate itself with the VCS client",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "root": {
+ "description": "The folder where we should check for VCS files. By default, we will use the same folder where `postgrestools.jsonc` was found.\n\nIf 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",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "useIgnoreFile": {
+ "description": "Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ }
+ }
+}
\ No newline at end of file
diff --git a/0.11.0/sitemap.xml b/0.11.0/sitemap.xml
new file mode 100644
index 000000000..043abf307
--- /dev/null
+++ b/0.11.0/sitemap.xml
@@ -0,0 +1,63 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/404.html b/0.12.0/404.html
new file mode 100644
index 000000000..985392138
--- /dev/null
+++ b/0.12.0/404.html
@@ -0,0 +1,128 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 404
+ +Page not found
+ + +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/checking_migrations/index.html b/0.12.0/checking_migrations/index.html
new file mode 100644
index 000000000..fc3a9be72
--- /dev/null
+++ b/0.12.0/checking_migrations/index.html
@@ -0,0 +1,161 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Linting Migrations
+Postgres Language Tools comes with a check command that can be integrated into your development workflow to catch problematic schema changes and encourage best practices.
To run it, simply point at your migrations directory.
+postgrestools check supabase/migrations
+When you are setting it up in an existing project, you might want to ignore all migrations that are already applied. To do so, add migrationsDir and after to your postgrestools.jsonc file
{
+ "migrations": {
+ "migrationsDir": "supabase/migrations",
+ "after": 1740868021
+ }
+}
+Alternatively, pass them directly.
+postgrestools check supabase/migrations --migrations-dir="supabase/migrations" --after=1740868021
+This will only check migrations after the specified timestamp.
+For pre-commit hooks and when working locally, use --staged to only lint files that have been staged. In CI environments, you most likely want to use --changed to only lint files that have been changed compared to your vcs.default_branch configuration. If default_branch is not set in your postgrestools.jsonc, use --since=REF to specify the base branch to compare against.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/cli_reference/index.html b/0.12.0/cli_reference/index.html
new file mode 100644
index 000000000..21c852ac0
--- /dev/null
+++ b/0.12.0/cli_reference/index.html
@@ -0,0 +1,382 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ CLI Reference
+Command summary
+-
+
postgrestools↴
+postgrestools version↴
+postgrestools check↴
+postgrestools start↴
+postgrestools stop↴
+postgrestools init↴
+postgrestools lsp-proxy↴
+postgrestools clean↴
+
postgrestools
+PostgresTools official CLI. Use it to check the health of your project or run it to check single files.
+Usage: postgrestools COMMAND ...
Available options:
+-
+
-h,--help— + Prints help information
+-V,--version— + Prints version information
+
Available commands:
+-
+
version— + Shows the version information and quit.
+check— + Runs everything to the requested files.
+start— + Starts the daemon server process.
+stop— + Stops the daemon server process.
+init— + Bootstraps a new project. Creates a configuration file with some defaults.
+lsp-proxy— + Acts as a server for the Language Server Protocol over stdin/stdout.
+clean— + Cleans the logs emitted by the daemon.
+
postgrestools version
+Shows the version information and quit.
+Usage: postgrestools version
Global options applied to all commands
+-
+
--colors=<off|force>— + 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— + Connect to a running instance of the daemon server.
+--skip-db— + Skip connecting to the database and only run checks that don't require a database connection.
+--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— + Set the file path to the configuration file, or the directory path to findpostgrestools.jsonc. If used, it disables the default configuration file resolution.
+--max-diagnostics=<none|<NUMBER>>— + Cap the amount of diagnostics displayed. Whennoneis provided, the limit is lifted. + [default: 20]
+--skip-errors— + Skip over files containing syntax errors instead of emitting an error diagnostic.
+--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— + Tell Postgres Tools to exit with an error code if some diagnostics emit warnings.
+--reporter=<json|json-pretty|github|junit|summary|gitlab>— + Allows to change how diagnostics and summary are reported.
+--log-level=<none|debug|info|warn|error>— + 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=<pretty|compact|json>— + How the log should look like. + [default: pretty]
+--diagnostic-level=<info|warn|error>— + The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing--diagnostic-level=errorwill cause Postgres Tools to print only diagnostics that contain only errors. + [default: info]
+
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools check
+Runs everything to the requested files.
+Usage: postgrestools check [--staged] [--changed] [--since=REF] [PATH]...
The configuration that is contained inside the configuration file.
+-
+
--vcs-enabled=<true|false>— + Whether we should integrate itself with the VCS client
+--vcs-client-kind=<git>— + The kind of client.
+--vcs-use-ignore-file=<true|false>— + Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file.
+--vcs-root=PATH— + The folder where we should check for VCS files. By default, we will use the same folder wherepostgrestools.jsoncwas 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— + The main branch of the project
+--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— + The directory where the migration files are stored
+--after=ARG— + Ignore any migrations before this timestamp
+--host=ARG— + The host of the database.
+--port=ARG— + The port of the database.
+--username=ARG— + The username to connect to the database.
+--password=ARG— + The password to connect to the database.
+--database=ARG— + The name of the database.
+--conn_timeout_secs=ARG— + The connection timeout in seconds. + [default: Some(10)]
+
Global options applied to all commands
+-
+
--colors=<off|force>— + 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— + Connect to a running instance of the daemon server.
+--skip-db— + Skip connecting to the database and only run checks that don't require a database connection.
+--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— + Set the file path to the configuration file, or the directory path to findpostgrestools.jsonc. If used, it disables the default configuration file resolution.
+--max-diagnostics=<none|<NUMBER>>— + Cap the amount of diagnostics displayed. Whennoneis provided, the limit is lifted. + [default: 20]
+--skip-errors— + Skip over files containing syntax errors instead of emitting an error diagnostic.
+--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— + Tell Postgres Tools to exit with an error code if some diagnostics emit warnings.
+--reporter=<json|json-pretty|github|junit|summary|gitlab>— + Allows to change how diagnostics and summary are reported.
+--log-level=<none|debug|info|warn|error>— + 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=<pretty|compact|json>— + How the log should look like. + [default: pretty]
+--diagnostic-level=<info|warn|error>— + The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing--diagnostic-level=errorwill cause Postgres Tools to print only diagnostics that contain only errors. + [default: info]
+
Available positional items:
+-
+
PATH— + Single file, single path or list of paths
+
Available options:
+-
+
--stdin-file-path=PATH— + Use this option when you want to format code piped fromstdin, and print the output tostdout.
+
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— + 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— + When set to true, only the files that have been changed compared to yourdefaultBranchconfiguration will be linted. This option should be used in CI environments.
+--since=REF— + Use this to specify the base branch to compare against when you're using the --changed flag and thedefaultBranchis not set in yourpostgrestools.jsonc
+-h,--help— + Prints help information
+
postgrestools start
+Starts the daemon server process.
+Usage: postgrestools start [--config-path=PATH]
Available options:
+-
+
--log-prefix-name=STRING— + Allows to change the prefix applied to the file name of the logs. + Uses environment variablePGT_LOG_PREFIX_NAME+ [default: server.log]
+--log-path=PATH— + Allows to change the folder where logs are stored. + Uses environment variablePGT_LOG_PATH
+--config-path=PATH— + Allows to set a custom file path to the configuration file, or a custom directory path to findpostgrestools.jsonc+ Uses environment variablePGT_LOG_PREFIX_NAME
+-h,--help— + Prints help information
+
postgrestools stop
+Stops the daemon server process.
+Usage: postgrestools stop
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools init
+Bootstraps a new project. Creates a configuration file with some defaults.
+Usage: postgrestools init
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools lsp-proxy
+Acts as a server for the Language Server Protocol over stdin/stdout.
+Usage: postgrestools lsp-proxy [--config-path=PATH]
Available options:
+-
+
--log-prefix-name=STRING— + Allows to change the prefix applied to the file name of the logs. + Uses environment variablePGT_LOG_PREFIX_NAME+ [default: server.log]
+--log-path=PATH— + Allows to change the folder where logs are stored. + Uses environment variablePGT_LOG_PATH
+--config-path=PATH— + Allows to set a custom file path to the configuration file, or a custom directory path to findpostgrestools.jsonc+ Uses environment variablePGT_CONFIG_PATH
+-h,--help— + Prints help information
+
postgrestools clean
+Cleans the logs emitted by the daemon.
+Usage: postgrestools clean
Available options:
+-
+
-h,--help— + Prints help information
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/codegen/Cargo.toml b/0.12.0/codegen/Cargo.toml
new file mode 100644
index 000000000..bf650ac9b
--- /dev/null
+++ b/0.12.0/codegen/Cargo.toml
@@ -0,0 +1,35 @@
+
+[package]
+authors.workspace = true
+categories.workspace = true
+description = "{rule_name}"
+ )?;
+ }
+ writeln!(content)?;
+ }
+
+ write_documentation(group, rule, meta.docs, &mut content)?;
+
+ write_how_to_configure(group, rule, &mut content)?;
+
+ Ok(String::from_utf8(content)?)
+}
+
+fn write_how_to_configure(
+ group: &'static str,
+ rule: &'static str,
+ content: &mut Vec")?; + } + + Event::Start(Tag::List(num)) => { + list_indentation += 1; + if let Some(num) = num { + list_order = Some(num); + } + if list_indentation > 1 { + writeln!(content)?; + } + } + + Event::End(TagEnd::List(_)) => { + list_order = None; + list_indentation -= 1; + writeln!(content)?; + } + Event::Start(Tag::Item) => { + write!(content, "{}", " ".repeat(list_indentation - 1))?; + if let Some(num) = list_order { + write!(content, "{num}. ")?; + } else { + write!(content, "- ")?; + } + } + + Event::End(TagEnd::Item) => { + list_order = list_order.map(|item| item + 1); + writeln!(content)?; + } + + Event::Start(Tag::Strong) => { + write!(content, "**")?; + } + + Event::End(TagEnd::Strong) => { + write!(content, "**")?; + } + + Event::Start(Tag::Emphasis) => { + write!(content, "_")?; + } + + Event::End(TagEnd::Emphasis) => { + write!(content, "_")?; + } + + Event::Start(Tag::Strikethrough) => { + write!(content, "~")?; + } + + Event::End(TagEnd::Strikethrough) => { + write!(content, "~")?; + } + + Event::Start(Tag::BlockQuote(_)) => { + write!(content, ">")?; + } + + Event::End(TagEnd::BlockQuote(_)) => { + writeln!(content)?; + } + + _ => { + bail!("unimplemented event {event:?}") + } + } + } + + Ok(()) +} + +struct CodeBlockTest { + /// The language tag of this code block. + tag: String, + + /// True if this is an invalid example that should trigger a diagnostic. + expect_diagnostic: bool, + + /// Whether to ignore this code block. + ignore: bool, + + /// The number of lines in this code block. + line_count: u32, + + // The indices of lines that should be hidden from the public documentation. + hidden_lines: Vec
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Environment Variables
+PGT_LOG_PATH
+The directory where the Daemon logs will be saved.
+PGT_LOG_PREFIX_NAME
+A prefix that's added to the name of the log. Default: server.log.
PGT_CONFIG_PATH
+A path to the configuration file
+ +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/images/cli-demo.png b/0.12.0/images/cli-demo.png
new file mode 100644
index 000000000..33bac595c
Binary files /dev/null and b/0.12.0/images/cli-demo.png differ
diff --git a/0.12.0/images/lsp-demo.gif b/0.12.0/images/lsp-demo.gif
new file mode 100644
index 000000000..7fbff05fd
Binary files /dev/null and b/0.12.0/images/lsp-demo.gif differ
diff --git a/0.12.0/images/pls-github.png b/0.12.0/images/pls-github.png
new file mode 100644
index 000000000..95ae73828
Binary files /dev/null and b/0.12.0/images/pls-github.png differ
diff --git a/0.12.0/img/favicon.ico b/0.12.0/img/favicon.ico
new file mode 100644
index 000000000..e85006a3c
Binary files /dev/null and b/0.12.0/img/favicon.ico differ
diff --git a/0.12.0/index.html b/0.12.0/index.html
new file mode 100644
index 000000000..38bd760db
--- /dev/null
+++ b/0.12.0/index.html
@@ -0,0 +1,292 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Postgres Tools
+A collection of language tools and a Language Server Protocol (LSP) implementation for Postgres, focusing on developer experience and reliable SQL tooling.
++
Source Code: https://github.com/supabase-community/postgres-language-server
++
Overview
+This project provides a toolchain for Postgres development
+Postgres Language Server
+
CLI Demo
+
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 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
EXPLAINerror insights)
+ - Linter, inspired by Squawk +
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 on GitHub and give it execution permission:
+curl -L https://github.com/supabase-community/postgres-language-server/releases/download/<version>/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.
npm add --save-dev --save-exact @postgrestools/postgrestools
+VSCode
+The language server is available on the VSCode Marketplace. It's published from this repo.
+Neovim
+You will have to install nvim-lspconfig, and follow the instructions.
Emacs
+The language client is available through lsp-mode. For more details, refer to their manual page.
+Zed
+The language server is available as an Extension. It's published from this repo.
+GitHub Actions
+To use the CLI in GitHub Actions, you can install it via our GitHub 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:
postgrestools init
+You’ll now have a postgrestools.jsonc file in your directory:
{
+ "$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/*"]
+ }
+}
+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.
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 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:
+postgrestools start
+Then, every command needs to add the --use-server options, e.g.:
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\<UserName>\AppData\Local\supabase-community\pgt\cache
+ - macOS:
/Users/<UserName>/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.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/js/html5shiv.min.js b/0.12.0/js/html5shiv.min.js
new file mode 100644
index 000000000..1a01c94ba
--- /dev/null
+++ b/0.12.0/js/html5shiv.min.js
@@ -0,0 +1,4 @@
+/**
+* @preserve HTML5 Shiv 3.7.3 | @afarkas @jdalton @jon_neal @rem | MIT/GPL2 Licensed
+*/
+!function(a,b){function c(a,b){var c=a.createElement("p"),d=a.getElementsByTagName("head")[0]||a.documentElement;return c.innerHTML="x",d.insertBefore(c.lastChild,d.firstChild)}function d(){var a=t.elements;return"string"==typeof a?a.split(" "):a}function e(a,b){var c=t.elements;"string"!=typeof c&&(c=c.join(" ")),"string"!=typeof a&&(a=a.join(" ")),t.elements=c+" "+a,j(b)}function f(a){var b=s[a[q]];return b||(b={},r++,a[q]=r,s[r]=b),b}function g(a,c,d){if(c||(c=b),l)return c.createElement(a);d||(d=f(c));var e;return e=d.cache[a]?d.cache[a].cloneNode():p.test(a)?(d.cache[a]=d.createElem(a)).cloneNode():d.createElem(a),!e.canHaveChildren||o.test(a)||e.tagUrn?e:d.frag.appendChild(e)}function h(a,c){if(a||(a=b),l)return a.createDocumentFragment();c=c||f(a);for(var e=c.frag.cloneNode(),g=0,h=d(),i=h.length;i>g;g++)e.createElement(h[g]);return e}function i(a,b){b.cache||(b.cache={},b.createElem=a.createElement,b.createFrag=a.createDocumentFragment,b.frag=b.createFrag()),a.createElement=function(c){return t.shivMethods?g(c,a,b):b.createElem(c)},a.createDocumentFragment=Function("h,f","return function(){var n=f.cloneNode(),c=n.createElement;h.shivMethods&&("+d().join().replace(/[\w\-:]+/g,function(a){return b.createElem(a),b.frag.createElement(a),'c("'+a+'")'})+");return n}")(t,b.frag)}function j(a){a||(a=b);var d=f(a);return!t.shivCSS||k||d.hasCSS||(d.hasCSS=!!c(a,"article,aside,dialog,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}mark{background:#FF0;color:#000}template{display:none}")),l||i(a,d),a}var k,l,m="3.7.3",n=a.html5||{},o=/^<|^(?:button|map|select|textarea|object|iframe|option|optgroup)$/i,p=/^(?:a|b|code|div|fieldset|h1|h2|h3|h4|h5|h6|i|label|li|ol|p|q|span|strong|style|table|tbody|td|th|tr|ul)$/i,q="_html5shiv",r=0,s={};!function(){try{var a=b.createElement("a");a.innerHTML="
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
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.
+ +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/rule_sources/index.html b/0.12.0/rule_sources/index.html
new file mode 100644
index 000000000..f3c54a18f
--- /dev/null
+++ b/0.12.0/rule_sources/index.html
@@ -0,0 +1,180 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Exclusive rules
+Rules from other sources
+Squawk
+| Squawk Rule Name | +Rule Name | +
|---|---|
| adding-required-field | +addingRequiredField | +
| ban-drop-column | +banDropColumn | +
| ban-drop-database | +banDropDatabase | +
| ban-drop-not-null | +banDropNotNull | +
| ban-drop-table | +banDropTable | +
| ban-truncate-cascade | +banTruncateCascade | +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/rule_suppressions/index.html b/0.12.0/rule_suppressions/index.html
new file mode 100644
index 000000000..90c7da661
--- /dev/null
+++ b/0.12.0/rule_suppressions/index.html
@@ -0,0 +1,216 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rule 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.
+How to Suppress a Rule
+To suppress a rule, add a comment above the line causing the diagnostic with the following format:
+-- pgt-ignore lint/safety/banDropTable
+drop table users;
+You can suppress single rules, groups of rules, or entire categories. The format of the rule to suppress is:
+category(/group(/specific-rule))
Where group and specific rule are optional.
+So, to suppress the lint/safety/banDropTable diagnostic, all of these would work:
-- pgt-ignore lint
+-- pgt-ignore lint/safety
+-- pgt-ignore lint/safety/banDropTable
+You can also add an explanation to the suppression by adding a : and the explanation text:
-- pgt-ignore lint/safety/banDropTable: My startup never had any users.
+drop table users;
+Suppressing Rules for Block of Code
+You can suppress rules for blocks of code.
+create table users (
+ -- ...
+);
+
+-- pgt-ignore-start typecheck: The `users` table will be created with this migration.
+alter table users drop constraint users_pkey;
+
+alter table users add primary key (user_id);
+-- pgt-ignore-end typecheck
+Every pgt-ignore-start needs a pgt-ignore-end suppression comment, and the suppressed rules must match exactly.
This won't work, because the start tag suppresses a different diagnostic:
+-- pgt-ignore-start lint/safety/banDropColumn
+-- pgt-ignore-end lint/safety
+Nesting is allowed, so this works fine:
+-- pgt-ignore-start typecheck: outer
+-- pgt-ignore-start lint/safety: inner
+-- pgt-ignore-end lint/safety: inner
+-- pgt-ignore-end typecheck: outer
+Suppressing Rules for Entire Files
+Instead of repeating the same suppression on multiple lines, you can suppress for an entire file.
+-- pgt-ignore-all lint/safety/banDropTable
+
+drop table tasks;
+drop table projects;
+drop table users;
+Suppressing Multiple Rules
+You can suppress multiple rules by adding multiple suppression comments above a statement:
+-- pgt-ignore lint/safety/banDropColumn
+-- pgt-ignore typecheck
+alter table tasks drop column created_at;
+Notes
+-
+
- Trying to suppress diagnostics that have already been disabled in your configuration file will show a warning. +
- Trying to suppress diagnostics that don't haven't been raised will also show a warning. +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/rules/adding-required-field/index.html b/0.12.0/rules/adding-required-field/index.html
new file mode 100644
index 000000000..86cae15a1
--- /dev/null
+++ b/0.12.0/rules/adding-required-field/index.html
@@ -0,0 +1,159 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ addingRequiredField
+Diagnostic Category: lint/safety/addingRequiredField
Since: vnext
Sources:
+- Inspired from: squawk/adding-required-field
Description
+Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required.
+This will fail immediately upon running for any populated table. Furthermore, old application code that is unaware of this column will fail to INSERT to this table.
+Make new columns optional initially by omitting the NOT NULL constraint until all existing data and application code has been updated. Once no NULL values are written to or persisted in the database, set it to NOT NULL. +Alternatively, if using Postgres version 11 or later, add a DEFAULT value that is not volatile. This allows the column to keep its NOT NULL constraint.
+Invalid
+alter table test add column count int not null;
+Valid in Postgres >= 11
+alter table test add column count int not null default 0;
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "addingRequiredField": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/rules/ban-drop-column/index.html b/0.12.0/rules/ban-drop-column/index.html
new file mode 100644
index 000000000..b4b73cf07
--- /dev/null
+++ b/0.12.0/rules/ban-drop-column/index.html
@@ -0,0 +1,174 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropColumn
+Diagnostic Category: lint/safety/banDropColumn
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-column
Description
+Dropping a column may break existing clients.
+Update your application code to no longer read or write the column.
+You can leave the column as nullable or delete the column once queries no longer select or modify the column.
+Examples
+Invalid
+alter table test drop column id;
+code-block.sql:1:1 lint/safety/banDropColumn ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a column may break existing clients.
+
+ > 1 │ alter table test drop column id;
+ │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ 2 │
+
+ i You can leave the column as nullable or delete the column once queries no longer select or modify the column.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropColumn": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/rules/ban-drop-database/index.html b/0.12.0/rules/ban-drop-database/index.html
new file mode 100644
index 000000000..bc634460a
--- /dev/null
+++ b/0.12.0/rules/ban-drop-database/index.html
@@ -0,0 +1,153 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropDatabase
+Diagnostic Category: lint/safety/banDropDatabase
Since: vnext
Sources:
+- Inspired from: squawk/ban-drop-database
Description
+Dropping a database may break existing clients (and everything else, really).
+Make sure that you really want to drop it.
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropDatabase": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/rules/ban-drop-not-null/index.html b/0.12.0/rules/ban-drop-not-null/index.html
new file mode 100644
index 000000000..ee6646f5d
--- /dev/null
+++ b/0.12.0/rules/ban-drop-not-null/index.html
@@ -0,0 +1,174 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropNotNull
+Diagnostic Category: lint/safety/banDropNotNull
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-not-null
Description
+Dropping a NOT NULL constraint may break existing clients.
+Application code or code written in procedural languages like PL/SQL or PL/pgSQL may not expect NULL values for the column that was previously guaranteed to be NOT NULL and therefore may fail to process them correctly.
+You can consider using a marker value that represents NULL. Alternatively, create a new table allowing NULL values, copy the data from the old table, and create a view that filters NULL values.
+Examples
+Invalid
+alter table users alter column email drop not null;
+code-block.sql:1:1 lint/safety/banDropNotNull ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a NOT NULL constraint may break existing clients.
+
+ > 1 │ alter table users alter column email drop not null;
+ │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ 2 │
+
+ i Consider using a marker value that represents NULL. Alternatively, create a new table allowing NULL values, copy the data from the old table, and create a view that filters NULL values.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropNotNull": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/rules/ban-drop-table/index.html b/0.12.0/rules/ban-drop-table/index.html
new file mode 100644
index 000000000..e87b981a2
--- /dev/null
+++ b/0.12.0/rules/ban-drop-table/index.html
@@ -0,0 +1,175 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropTable
+Diagnostic Category: lint/safety/banDropTable
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-table
Description
+Dropping a table may break existing clients.
+Update your application code to no longer read or write the table.
+Once the table is no longer needed, you can delete it by running the command "DROP TABLE mytable;".
+This command will permanently remove the table from the database and all its contents. +Be sure to back up the table before deleting it, just in case you need to restore it in the future.
+Examples
+drop table some_table;
+code-block.sql:1:1 lint/safety/banDropTable ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a table may break existing clients.
+
+ > 1 │ drop table some_table;
+ │ ^^^^^^^^^^^^^^^^^^^^^^
+ 2 │
+
+ i Update your application code to no longer read or write the table, and only then delete the table. Be sure to create a backup.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropTable": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/rules/ban-truncate-cascade/index.html b/0.12.0/rules/ban-truncate-cascade/index.html
new file mode 100644
index 000000000..e345fdf06
--- /dev/null
+++ b/0.12.0/rules/ban-truncate-cascade/index.html
@@ -0,0 +1,159 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banTruncateCascade
+Diagnostic Category: lint/safety/banTruncateCascade
Since: vnext
Sources:
+- Inspired from: squawk/ban-truncate-cascade
Description
+Using TRUNCATE's CASCADE option will truncate any tables that are also foreign-keyed to the specified tables.
So if you had tables with foreign-keys like:
+a <- b <- c
and ran:
+truncate a cascade;
You'd end up with a, b, & c all being truncated!
+Instead, you can manually specify the tables you want.
+truncate a, b;
How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banTruncateCascade": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/rules/index.html b/0.12.0/rules/index.html
new file mode 100644
index 000000000..d8785b8db
--- /dev/null
+++ b/0.12.0/rules/index.html
@@ -0,0 +1,193 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rules
+Below the list of rules supported by Postgres Language Tools, divided by group. Here's a legend of the emojis:
+-
+
- The icon ✅ indicates that the rule is part of the recommended rules. +
Safety
+Rules that detect potential safety issues in your code.
+| Rule name | +Description | +Properties | +
|---|---|---|
| addingRequiredField | +Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required. | ++ |
| banDropColumn | +Dropping a column may break existing clients. | +✅ | +
| banDropDatabase | +Dropping a database may break existing clients (and everything else, really). | ++ |
| banDropNotNull | +Dropping a NOT NULL constraint may break existing clients. | +✅ | +
| banDropTable | +Dropping a table may break existing clients. | +✅ | +
| banTruncateCascade | +Using TRUNCATE's CASCADE option will truncate any tables that are also foreign-keyed to the specified tables. |
++ |
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.12.0/schema.json b/0.12.0/schema.json
new file mode 100644
index 000000000..e0abf20aa
--- /dev/null
+++ b/0.12.0/schema.json
@@ -0,0 +1,500 @@
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "Configuration",
+ "description": "The configuration that is contained inside the configuration file.",
+ "type": "object",
+ "properties": {
+ "$schema": {
+ "description": "A field for the [JSON schema](https://json-schema.org/) specification",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "db": {
+ "description": "The configuration of the database connection",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/DatabaseConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "extends": {
+ "description": "A list of paths to other JSON files, used to extends the current configuration.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "files": {
+ "description": "The configuration of the filesystem",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/FilesConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "linter": {
+ "description": "The configuration for the linter",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/LinterConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "migrations": {
+ "description": "Configure migrations",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/MigrationsConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "typecheck": {
+ "description": "The configuration for type checking",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/TypecheckConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "vcs": {
+ "description": "The configuration of the VCS integration",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/VcsConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false,
+ "definitions": {
+ "DatabaseConfiguration": {
+ "description": "The configuration of the database connection.",
+ "type": "object",
+ "properties": {
+ "allowStatementExecutionsAgainst": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "connTimeoutSecs": {
+ "description": "The connection timeout in seconds.",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint16",
+ "minimum": 0.0
+ },
+ "database": {
+ "description": "The name of the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "host": {
+ "description": "The host of the database. Required if you want database-related features. All else falls back to sensible defaults.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "password": {
+ "description": "The password to connect to the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "port": {
+ "description": "The port of the database.",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint16",
+ "minimum": 0.0
+ },
+ "username": {
+ "description": "The username to connect to the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "FilesConfiguration": {
+ "description": "The configuration of the filesystem",
+ "type": "object",
+ "properties": {
+ "ignore": {
+ "description": "A list of Unix shell style patterns. Will ignore files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "include": {
+ "description": "A list of Unix shell style patterns. Will handle only those files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "maxSize": {
+ "description": "The maximum allowed size for source code files in bytes. Files above this limit will be ignored for performance reasons. Defaults to 1 MiB",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint64",
+ "minimum": 1.0
+ }
+ },
+ "additionalProperties": false
+ },
+ "LinterConfiguration": {
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "description": "if `false`, it disables the feature and the linter won't be executed. `true` by default",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "ignore": {
+ "description": "A list of Unix shell style patterns. The formatter will ignore files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "include": {
+ "description": "A list of Unix shell style patterns. The formatter will include files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "rules": {
+ "description": "List of rules",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/Rules"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "MigrationsConfiguration": {
+ "description": "The configuration of the filesystem",
+ "type": "object",
+ "properties": {
+ "after": {
+ "description": "Ignore any migrations before this timestamp",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint64",
+ "minimum": 0.0
+ },
+ "migrationsDir": {
+ "description": "The directory where the migration files are stored",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "RuleConfiguration": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RulePlainConfiguration"
+ },
+ {
+ "$ref": "#/definitions/RuleWithNoOptions"
+ }
+ ]
+ },
+ "RulePlainConfiguration": {
+ "type": "string",
+ "enum": [
+ "warn",
+ "error",
+ "info",
+ "off"
+ ]
+ },
+ "RuleWithNoOptions": {
+ "type": "object",
+ "required": [
+ "level"
+ ],
+ "properties": {
+ "level": {
+ "description": "The severity of the emitted diagnostics by the rule",
+ "allOf": [
+ {
+ "$ref": "#/definitions/RulePlainConfiguration"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "Rules": {
+ "type": "object",
+ "properties": {
+ "all": {
+ "description": "It enables ALL rules. The rules that belong to `nursery` won't be enabled.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "recommended": {
+ "description": "It enables the lint rules recommended by Postgres Tools. `true` by default.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "safety": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/Safety"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "Safety": {
+ "description": "A list of rules that belong to this group",
+ "type": "object",
+ "properties": {
+ "addingRequiredField": {
+ "description": "Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "all": {
+ "description": "It enables ALL rules for this group.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "banDropColumn": {
+ "description": "Dropping a column may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropDatabase": {
+ "description": "Dropping a database may break existing clients (and everything else, really).",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropNotNull": {
+ "description": "Dropping a NOT NULL constraint may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropTable": {
+ "description": "Dropping a table may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banTruncateCascade": {
+ "description": "Using TRUNCATE's CASCADE option will truncate any tables that are also foreign-keyed to the specified tables.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "recommended": {
+ "description": "It enables the recommended rules for this group",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "StringSet": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "uniqueItems": true
+ },
+ "TypecheckConfiguration": {
+ "description": "The configuration for type checking.",
+ "type": "object",
+ "properties": {
+ "searchPath": {
+ "description": "Default search path schemas for type checking. Can be a list of schema names or glob patterns like [\"public\", \"app_*\"]. If not specified, defaults to [\"public\"].",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "VcsClientKind": {
+ "oneOf": [
+ {
+ "description": "Integration with the git client as VCS",
+ "type": "string",
+ "enum": [
+ "git"
+ ]
+ }
+ ]
+ },
+ "VcsConfiguration": {
+ "description": "Set of properties to integrate with a VCS software.",
+ "type": "object",
+ "properties": {
+ "clientKind": {
+ "description": "The kind of client.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/VcsClientKind"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "defaultBranch": {
+ "description": "The main branch of the project",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "enabled": {
+ "description": "Whether we should integrate itself with the VCS client",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "root": {
+ "description": "The folder where we should check for VCS files. By default, we will use the same folder where `postgrestools.jsonc` was found.\n\nIf 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",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "useIgnoreFile": {
+ "description": "Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ }
+ }
+}
\ No newline at end of file
diff --git a/0.12.0/sitemap.xml b/0.12.0/sitemap.xml
new file mode 100644
index 000000000..932ce3809
--- /dev/null
+++ b/0.12.0/sitemap.xml
@@ -0,0 +1,63 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/404.html b/0.13.0/404.html
new file mode 100644
index 000000000..bba9e58c8
--- /dev/null
+++ b/0.13.0/404.html
@@ -0,0 +1,128 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 404
+ +Page not found
+ + +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/checking_migrations/index.html b/0.13.0/checking_migrations/index.html
new file mode 100644
index 000000000..b9dfb1deb
--- /dev/null
+++ b/0.13.0/checking_migrations/index.html
@@ -0,0 +1,161 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Linting Migrations
+Postgres Language Tools comes with a check command that can be integrated into your development workflow to catch problematic schema changes and encourage best practices.
To run it, simply point at your migrations directory.
+postgrestools check supabase/migrations
+When you are setting it up in an existing project, you might want to ignore all migrations that are already applied. To do so, add migrationsDir and after to your postgrestools.jsonc file
{
+ "migrations": {
+ "migrationsDir": "supabase/migrations",
+ "after": 1740868021
+ }
+}
+Alternatively, pass them directly.
+postgrestools check supabase/migrations --migrations-dir="supabase/migrations" --after=1740868021
+This will only check migrations after the specified timestamp.
+For pre-commit hooks and when working locally, use --staged to only lint files that have been staged. In CI environments, you most likely want to use --changed to only lint files that have been changed compared to your vcs.default_branch configuration. If default_branch is not set in your postgrestools.jsonc, use --since=REF to specify the base branch to compare against.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/cli_reference/index.html b/0.13.0/cli_reference/index.html
new file mode 100644
index 000000000..1528f2fee
--- /dev/null
+++ b/0.13.0/cli_reference/index.html
@@ -0,0 +1,382 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ CLI Reference
+Command summary
+-
+
postgrestools↴
+postgrestools version↴
+postgrestools check↴
+postgrestools start↴
+postgrestools stop↴
+postgrestools init↴
+postgrestools lsp-proxy↴
+postgrestools clean↴
+
postgrestools
+PostgresTools official CLI. Use it to check the health of your project or run it to check single files.
+Usage: postgrestools COMMAND ...
Available options:
+-
+
-h,--help— + Prints help information
+-V,--version— + Prints version information
+
Available commands:
+-
+
version— + Shows the version information and quit.
+check— + Runs everything to the requested files.
+start— + Starts the daemon server process.
+stop— + Stops the daemon server process.
+init— + Bootstraps a new project. Creates a configuration file with some defaults.
+lsp-proxy— + Acts as a server for the Language Server Protocol over stdin/stdout.
+clean— + Cleans the logs emitted by the daemon.
+
postgrestools version
+Shows the version information and quit.
+Usage: postgrestools version
Global options applied to all commands
+-
+
--colors=<off|force>— + 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— + Connect to a running instance of the daemon server.
+--skip-db— + Skip connecting to the database and only run checks that don't require a database connection.
+--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— + Set the file path to the configuration file, or the directory path to findpostgrestools.jsonc. If used, it disables the default configuration file resolution.
+--max-diagnostics=<none|<NUMBER>>— + Cap the amount of diagnostics displayed. Whennoneis provided, the limit is lifted. + [default: 20]
+--skip-errors— + Skip over files containing syntax errors instead of emitting an error diagnostic.
+--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— + Tell Postgres Tools to exit with an error code if some diagnostics emit warnings.
+--reporter=<json|json-pretty|github|junit|summary|gitlab>— + Allows to change how diagnostics and summary are reported.
+--log-level=<none|debug|info|warn|error>— + 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=<pretty|compact|json>— + How the log should look like. + [default: pretty]
+--diagnostic-level=<info|warn|error>— + The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing--diagnostic-level=errorwill cause Postgres Tools to print only diagnostics that contain only errors. + [default: info]
+
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools check
+Runs everything to the requested files.
+Usage: postgrestools check [--staged] [--changed] [--since=REF] [PATH]...
The configuration that is contained inside the configuration file.
+-
+
--vcs-enabled=<true|false>— + Whether we should integrate itself with the VCS client
+--vcs-client-kind=<git>— + The kind of client.
+--vcs-use-ignore-file=<true|false>— + Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file.
+--vcs-root=PATH— + The folder where we should check for VCS files. By default, we will use the same folder wherepostgrestools.jsoncwas 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— + The main branch of the project
+--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— + The directory where the migration files are stored
+--after=ARG— + Ignore any migrations before this timestamp
+--host=ARG— + The host of the database.
+--port=ARG— + The port of the database.
+--username=ARG— + The username to connect to the database.
+--password=ARG— + The password to connect to the database.
+--database=ARG— + The name of the database.
+--conn_timeout_secs=ARG— + The connection timeout in seconds. + [default: Some(10)]
+
Global options applied to all commands
+-
+
--colors=<off|force>— + 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— + Connect to a running instance of the daemon server.
+--skip-db— + Skip connecting to the database and only run checks that don't require a database connection.
+--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— + Set the file path to the configuration file, or the directory path to findpostgrestools.jsonc. If used, it disables the default configuration file resolution.
+--max-diagnostics=<none|<NUMBER>>— + Cap the amount of diagnostics displayed. Whennoneis provided, the limit is lifted. + [default: 20]
+--skip-errors— + Skip over files containing syntax errors instead of emitting an error diagnostic.
+--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— + Tell Postgres Tools to exit with an error code if some diagnostics emit warnings.
+--reporter=<json|json-pretty|github|junit|summary|gitlab>— + Allows to change how diagnostics and summary are reported.
+--log-level=<none|debug|info|warn|error>— + 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=<pretty|compact|json>— + How the log should look like. + [default: pretty]
+--diagnostic-level=<info|warn|error>— + The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing--diagnostic-level=errorwill cause Postgres Tools to print only diagnostics that contain only errors. + [default: info]
+
Available positional items:
+-
+
PATH— + Single file, single path or list of paths
+
Available options:
+-
+
--stdin-file-path=PATH— + Use this option when you want to format code piped fromstdin, and print the output tostdout.
+
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— + 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— + When set to true, only the files that have been changed compared to yourdefaultBranchconfiguration will be linted. This option should be used in CI environments.
+--since=REF— + Use this to specify the base branch to compare against when you're using the --changed flag and thedefaultBranchis not set in yourpostgrestools.jsonc
+-h,--help— + Prints help information
+
postgrestools start
+Starts the daemon server process.
+Usage: postgrestools start [--config-path=PATH]
Available options:
+-
+
--log-prefix-name=STRING— + Allows to change the prefix applied to the file name of the logs. + Uses environment variablePGT_LOG_PREFIX_NAME+ [default: server.log]
+--log-path=PATH— + Allows to change the folder where logs are stored. + Uses environment variablePGT_LOG_PATH
+--config-path=PATH— + Allows to set a custom file path to the configuration file, or a custom directory path to findpostgrestools.jsonc+ Uses environment variablePGT_LOG_PREFIX_NAME
+-h,--help— + Prints help information
+
postgrestools stop
+Stops the daemon server process.
+Usage: postgrestools stop
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools init
+Bootstraps a new project. Creates a configuration file with some defaults.
+Usage: postgrestools init
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools lsp-proxy
+Acts as a server for the Language Server Protocol over stdin/stdout.
+Usage: postgrestools lsp-proxy [--config-path=PATH]
Available options:
+-
+
--log-prefix-name=STRING— + Allows to change the prefix applied to the file name of the logs. + Uses environment variablePGT_LOG_PREFIX_NAME+ [default: server.log]
+--log-path=PATH— + Allows to change the folder where logs are stored. + Uses environment variablePGT_LOG_PATH
+--config-path=PATH— + Allows to set a custom file path to the configuration file, or a custom directory path to findpostgrestools.jsonc+ Uses environment variablePGT_CONFIG_PATH
+-h,--help— + Prints help information
+
postgrestools clean
+Cleans the logs emitted by the daemon.
+Usage: postgrestools clean
Available options:
+-
+
-h,--help— + Prints help information
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/codegen/Cargo.toml b/0.13.0/codegen/Cargo.toml
new file mode 100644
index 000000000..bf650ac9b
--- /dev/null
+++ b/0.13.0/codegen/Cargo.toml
@@ -0,0 +1,35 @@
+
+[package]
+authors.workspace = true
+categories.workspace = true
+description = "{rule_name}"
+ )?;
+ }
+ writeln!(content)?;
+ }
+
+ write_documentation(group, rule, meta.docs, &mut content)?;
+
+ write_how_to_configure(group, rule, &mut content)?;
+
+ Ok(String::from_utf8(content)?)
+}
+
+fn write_how_to_configure(
+ group: &'static str,
+ rule: &'static str,
+ content: &mut Vec")?; + } + + Event::Start(Tag::List(num)) => { + list_indentation += 1; + if let Some(num) = num { + list_order = Some(num); + } + if list_indentation > 1 { + writeln!(content)?; + } + } + + Event::End(TagEnd::List(_)) => { + list_order = None; + list_indentation -= 1; + writeln!(content)?; + } + Event::Start(Tag::Item) => { + write!(content, "{}", " ".repeat(list_indentation - 1))?; + if let Some(num) = list_order { + write!(content, "{num}. ")?; + } else { + write!(content, "- ")?; + } + } + + Event::End(TagEnd::Item) => { + list_order = list_order.map(|item| item + 1); + writeln!(content)?; + } + + Event::Start(Tag::Strong) => { + write!(content, "**")?; + } + + Event::End(TagEnd::Strong) => { + write!(content, "**")?; + } + + Event::Start(Tag::Emphasis) => { + write!(content, "_")?; + } + + Event::End(TagEnd::Emphasis) => { + write!(content, "_")?; + } + + Event::Start(Tag::Strikethrough) => { + write!(content, "~")?; + } + + Event::End(TagEnd::Strikethrough) => { + write!(content, "~")?; + } + + Event::Start(Tag::BlockQuote(_)) => { + write!(content, ">")?; + } + + Event::End(TagEnd::BlockQuote(_)) => { + writeln!(content)?; + } + + _ => { + bail!("unimplemented event {event:?}") + } + } + } + + Ok(()) +} + +struct CodeBlockTest { + /// The language tag of this code block. + tag: String, + + /// True if this is an invalid example that should trigger a diagnostic. + expect_diagnostic: bool, + + /// Whether to ignore this code block. + ignore: bool, + + /// The number of lines in this code block. + line_count: u32, + + // The indices of lines that should be hidden from the public documentation. + hidden_lines: Vec
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Environment Variables
+PGT_LOG_PATH
+The directory where the Daemon logs will be saved.
+PGT_LOG_PREFIX_NAME
+A prefix that's added to the name of the log. Default: server.log.
PGT_CONFIG_PATH
+A path to the configuration file
+ +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/images/cli-demo.png b/0.13.0/images/cli-demo.png
new file mode 100644
index 000000000..33bac595c
Binary files /dev/null and b/0.13.0/images/cli-demo.png differ
diff --git a/0.13.0/images/lsp-demo.gif b/0.13.0/images/lsp-demo.gif
new file mode 100644
index 000000000..7fbff05fd
Binary files /dev/null and b/0.13.0/images/lsp-demo.gif differ
diff --git a/0.13.0/images/pls-github.png b/0.13.0/images/pls-github.png
new file mode 100644
index 000000000..95ae73828
Binary files /dev/null and b/0.13.0/images/pls-github.png differ
diff --git a/0.13.0/img/favicon.ico b/0.13.0/img/favicon.ico
new file mode 100644
index 000000000..e85006a3c
Binary files /dev/null and b/0.13.0/img/favicon.ico differ
diff --git a/0.13.0/index.html b/0.13.0/index.html
new file mode 100644
index 000000000..8dc590983
--- /dev/null
+++ b/0.13.0/index.html
@@ -0,0 +1,292 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Postgres Tools
+A collection of language tools and a Language Server Protocol (LSP) implementation for Postgres, focusing on developer experience and reliable SQL tooling.
++
Source Code: https://github.com/supabase-community/postgres-language-server
++
Overview
+This project provides a toolchain for Postgres development
+Postgres Language Server
+
CLI Demo
+
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 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
EXPLAINerror insights)
+ - Linter, inspired by Squawk +
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 on GitHub and give it execution permission:
+curl -L https://github.com/supabase-community/postgres-language-server/releases/download/<version>/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.
npm add --save-dev --save-exact @postgrestools/postgrestools
+VSCode
+The language server is available on the VSCode Marketplace. It's published from this repo.
+Neovim
+You will have to install nvim-lspconfig, and follow the instructions.
Emacs
+The language client is available through lsp-mode. For more details, refer to their manual page.
+Zed
+The language server is available as an Extension. It's published from this repo.
+GitHub Actions
+To use the CLI in GitHub Actions, you can install it via our GitHub 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:
postgrestools init
+You’ll now have a postgrestools.jsonc file in your directory:
{
+ "$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/*"]
+ }
+}
+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.
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 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:
+postgrestools start
+Then, every command needs to add the --use-server options, e.g.:
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\<UserName>\AppData\Local\supabase-community\pgt\cache
+ - macOS:
/Users/<UserName>/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.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/js/html5shiv.min.js b/0.13.0/js/html5shiv.min.js
new file mode 100644
index 000000000..1a01c94ba
--- /dev/null
+++ b/0.13.0/js/html5shiv.min.js
@@ -0,0 +1,4 @@
+/**
+* @preserve HTML5 Shiv 3.7.3 | @afarkas @jdalton @jon_neal @rem | MIT/GPL2 Licensed
+*/
+!function(a,b){function c(a,b){var c=a.createElement("p"),d=a.getElementsByTagName("head")[0]||a.documentElement;return c.innerHTML="x",d.insertBefore(c.lastChild,d.firstChild)}function d(){var a=t.elements;return"string"==typeof a?a.split(" "):a}function e(a,b){var c=t.elements;"string"!=typeof c&&(c=c.join(" ")),"string"!=typeof a&&(a=a.join(" ")),t.elements=c+" "+a,j(b)}function f(a){var b=s[a[q]];return b||(b={},r++,a[q]=r,s[r]=b),b}function g(a,c,d){if(c||(c=b),l)return c.createElement(a);d||(d=f(c));var e;return e=d.cache[a]?d.cache[a].cloneNode():p.test(a)?(d.cache[a]=d.createElem(a)).cloneNode():d.createElem(a),!e.canHaveChildren||o.test(a)||e.tagUrn?e:d.frag.appendChild(e)}function h(a,c){if(a||(a=b),l)return a.createDocumentFragment();c=c||f(a);for(var e=c.frag.cloneNode(),g=0,h=d(),i=h.length;i>g;g++)e.createElement(h[g]);return e}function i(a,b){b.cache||(b.cache={},b.createElem=a.createElement,b.createFrag=a.createDocumentFragment,b.frag=b.createFrag()),a.createElement=function(c){return t.shivMethods?g(c,a,b):b.createElem(c)},a.createDocumentFragment=Function("h,f","return function(){var n=f.cloneNode(),c=n.createElement;h.shivMethods&&("+d().join().replace(/[\w\-:]+/g,function(a){return b.createElem(a),b.frag.createElement(a),'c("'+a+'")'})+");return n}")(t,b.frag)}function j(a){a||(a=b);var d=f(a);return!t.shivCSS||k||d.hasCSS||(d.hasCSS=!!c(a,"article,aside,dialog,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}mark{background:#FF0;color:#000}template{display:none}")),l||i(a,d),a}var k,l,m="3.7.3",n=a.html5||{},o=/^<|^(?:button|map|select|textarea|object|iframe|option|optgroup)$/i,p=/^(?:a|b|code|div|fieldset|h1|h2|h3|h4|h5|h6|i|label|li|ol|p|q|span|strong|style|table|tbody|td|th|tr|ul)$/i,q="_html5shiv",r=0,s={};!function(){try{var a=b.createElement("a");a.innerHTML="
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
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.
+ +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/rule_sources/index.html b/0.13.0/rule_sources/index.html
new file mode 100644
index 000000000..c24791309
--- /dev/null
+++ b/0.13.0/rule_sources/index.html
@@ -0,0 +1,180 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Exclusive rules
+Rules from other sources
+Squawk
+| Squawk Rule Name | +Rule Name | +
|---|---|
| adding-required-field | +addingRequiredField | +
| ban-drop-column | +banDropColumn | +
| ban-drop-database | +banDropDatabase | +
| ban-drop-not-null | +banDropNotNull | +
| ban-drop-table | +banDropTable | +
| ban-truncate-cascade | +banTruncateCascade | +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/rule_suppressions/index.html b/0.13.0/rule_suppressions/index.html
new file mode 100644
index 000000000..6ca6959e8
--- /dev/null
+++ b/0.13.0/rule_suppressions/index.html
@@ -0,0 +1,216 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rule 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.
+How to Suppress a Rule
+To suppress a rule, add a comment above the line causing the diagnostic with the following format:
+-- pgt-ignore lint/safety/banDropTable
+drop table users;
+You can suppress single rules, groups of rules, or entire categories. The format of the rule to suppress is:
+category(/group(/specific-rule))
Where group and specific rule are optional.
+So, to suppress the lint/safety/banDropTable diagnostic, all of these would work:
-- pgt-ignore lint
+-- pgt-ignore lint/safety
+-- pgt-ignore lint/safety/banDropTable
+You can also add an explanation to the suppression by adding a : and the explanation text:
-- pgt-ignore lint/safety/banDropTable: My startup never had any users.
+drop table users;
+Suppressing Rules for Block of Code
+You can suppress rules for blocks of code.
+create table users (
+ -- ...
+);
+
+-- pgt-ignore-start typecheck: The `users` table will be created with this migration.
+alter table users drop constraint users_pkey;
+
+alter table users add primary key (user_id);
+-- pgt-ignore-end typecheck
+Every pgt-ignore-start needs a pgt-ignore-end suppression comment, and the suppressed rules must match exactly.
This won't work, because the start tag suppresses a different diagnostic:
+-- pgt-ignore-start lint/safety/banDropColumn
+-- pgt-ignore-end lint/safety
+Nesting is allowed, so this works fine:
+-- pgt-ignore-start typecheck: outer
+-- pgt-ignore-start lint/safety: inner
+-- pgt-ignore-end lint/safety: inner
+-- pgt-ignore-end typecheck: outer
+Suppressing Rules for Entire Files
+Instead of repeating the same suppression on multiple lines, you can suppress for an entire file.
+-- pgt-ignore-all lint/safety/banDropTable
+
+drop table tasks;
+drop table projects;
+drop table users;
+Suppressing Multiple Rules
+You can suppress multiple rules by adding multiple suppression comments above a statement:
+-- pgt-ignore lint/safety/banDropColumn
+-- pgt-ignore typecheck
+alter table tasks drop column created_at;
+Notes
+-
+
- Trying to suppress diagnostics that have already been disabled in your configuration file will show a warning. +
- Trying to suppress diagnostics that don't haven't been raised will also show a warning. +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/rules/adding-required-field/index.html b/0.13.0/rules/adding-required-field/index.html
new file mode 100644
index 000000000..4ef974cac
--- /dev/null
+++ b/0.13.0/rules/adding-required-field/index.html
@@ -0,0 +1,159 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ addingRequiredField
+Diagnostic Category: lint/safety/addingRequiredField
Since: vnext
Sources:
+- Inspired from: squawk/adding-required-field
Description
+Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required.
+This will fail immediately upon running for any populated table. Furthermore, old application code that is unaware of this column will fail to INSERT to this table.
+Make new columns optional initially by omitting the NOT NULL constraint until all existing data and application code has been updated. Once no NULL values are written to or persisted in the database, set it to NOT NULL. +Alternatively, if using Postgres version 11 or later, add a DEFAULT value that is not volatile. This allows the column to keep its NOT NULL constraint.
+Invalid
+alter table test add column count int not null;
+Valid in Postgres >= 11
+alter table test add column count int not null default 0;
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "addingRequiredField": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/rules/ban-drop-column/index.html b/0.13.0/rules/ban-drop-column/index.html
new file mode 100644
index 000000000..bb06367ec
--- /dev/null
+++ b/0.13.0/rules/ban-drop-column/index.html
@@ -0,0 +1,174 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropColumn
+Diagnostic Category: lint/safety/banDropColumn
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-column
Description
+Dropping a column may break existing clients.
+Update your application code to no longer read or write the column.
+You can leave the column as nullable or delete the column once queries no longer select or modify the column.
+Examples
+Invalid
+alter table test drop column id;
+code-block.sql:1:1 lint/safety/banDropColumn ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a column may break existing clients.
+
+ > 1 │ alter table test drop column id;
+ │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ 2 │
+
+ i You can leave the column as nullable or delete the column once queries no longer select or modify the column.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropColumn": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/rules/ban-drop-database/index.html b/0.13.0/rules/ban-drop-database/index.html
new file mode 100644
index 000000000..779e7f76a
--- /dev/null
+++ b/0.13.0/rules/ban-drop-database/index.html
@@ -0,0 +1,153 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropDatabase
+Diagnostic Category: lint/safety/banDropDatabase
Since: vnext
Sources:
+- Inspired from: squawk/ban-drop-database
Description
+Dropping a database may break existing clients (and everything else, really).
+Make sure that you really want to drop it.
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropDatabase": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/rules/ban-drop-not-null/index.html b/0.13.0/rules/ban-drop-not-null/index.html
new file mode 100644
index 000000000..65bd95015
--- /dev/null
+++ b/0.13.0/rules/ban-drop-not-null/index.html
@@ -0,0 +1,174 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropNotNull
+Diagnostic Category: lint/safety/banDropNotNull
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-not-null
Description
+Dropping a NOT NULL constraint may break existing clients.
+Application code or code written in procedural languages like PL/SQL or PL/pgSQL may not expect NULL values for the column that was previously guaranteed to be NOT NULL and therefore may fail to process them correctly.
+You can consider using a marker value that represents NULL. Alternatively, create a new table allowing NULL values, copy the data from the old table, and create a view that filters NULL values.
+Examples
+Invalid
+alter table users alter column email drop not null;
+code-block.sql:1:1 lint/safety/banDropNotNull ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a NOT NULL constraint may break existing clients.
+
+ > 1 │ alter table users alter column email drop not null;
+ │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ 2 │
+
+ i Consider using a marker value that represents NULL. Alternatively, create a new table allowing NULL values, copy the data from the old table, and create a view that filters NULL values.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropNotNull": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/rules/ban-drop-table/index.html b/0.13.0/rules/ban-drop-table/index.html
new file mode 100644
index 000000000..741b77b97
--- /dev/null
+++ b/0.13.0/rules/ban-drop-table/index.html
@@ -0,0 +1,175 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropTable
+Diagnostic Category: lint/safety/banDropTable
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-table
Description
+Dropping a table may break existing clients.
+Update your application code to no longer read or write the table.
+Once the table is no longer needed, you can delete it by running the command "DROP TABLE mytable;".
+This command will permanently remove the table from the database and all its contents. +Be sure to back up the table before deleting it, just in case you need to restore it in the future.
+Examples
+drop table some_table;
+code-block.sql:1:1 lint/safety/banDropTable ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a table may break existing clients.
+
+ > 1 │ drop table some_table;
+ │ ^^^^^^^^^^^^^^^^^^^^^^
+ 2 │
+
+ i Update your application code to no longer read or write the table, and only then delete the table. Be sure to create a backup.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropTable": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/rules/ban-truncate-cascade/index.html b/0.13.0/rules/ban-truncate-cascade/index.html
new file mode 100644
index 000000000..437f5e9ef
--- /dev/null
+++ b/0.13.0/rules/ban-truncate-cascade/index.html
@@ -0,0 +1,159 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banTruncateCascade
+Diagnostic Category: lint/safety/banTruncateCascade
Since: vnext
Sources:
+- Inspired from: squawk/ban-truncate-cascade
Description
+Using TRUNCATE's CASCADE option will truncate any tables that are also foreign-keyed to the specified tables.
So if you had tables with foreign-keys like:
+a <- b <- c
and ran:
+truncate a cascade;
You'd end up with a, b, & c all being truncated!
+Instead, you can manually specify the tables you want.
+truncate a, b;
How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banTruncateCascade": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.13.0/rules/index.html b/0.13.0/rules/index.html
new file mode 100644
index 000000000..59d05760e
--- /dev/null
+++ b/0.13.0/rules/index.html
@@ -0,0 +1,193 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rules
+Below the list of rules supported by Postgres Language Tools, divided by group. Here's a legend of the emojis:
+-
+
- The icon ✅ indicates that the rule is part of the recommended rules. +
Safety
+Rules that detect potential safety issues in your code.
+| Rule name | +Description | +Properties | +
|---|---|---|
| addingRequiredField | +Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required. | ++ |
| banDropColumn | +Dropping a column may break existing clients. | +✅ | +
| banDropDatabase | +Dropping a database may break existing clients (and everything else, really). | ++ |
| banDropNotNull | +Dropping a NOT NULL constraint may break existing clients. | +✅ | +
| banDropTable | +Dropping a table may break existing clients. | +✅ | +
| banTruncateCascade | +Using TRUNCATE's CASCADE option will truncate any tables that are also foreign-keyed to the specified tables. |
++ |
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/schema.json b/0.13.0/schema.json
similarity index 100%
rename from docs/schema.json
rename to 0.13.0/schema.json
diff --git a/0.13.0/sitemap.xml b/0.13.0/sitemap.xml
new file mode 100644
index 000000000..2682b301a
--- /dev/null
+++ b/0.13.0/sitemap.xml
@@ -0,0 +1,63 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.0/404.html b/0.8.0/404.html
new file mode 100644
index 000000000..11a78fa09
--- /dev/null
+++ b/0.8.0/404.html
@@ -0,0 +1,124 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 404
+ +Page not found
+ + +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.0/checking_migrations/index.html b/0.8.0/checking_migrations/index.html
new file mode 100644
index 000000000..3a001df44
--- /dev/null
+++ b/0.8.0/checking_migrations/index.html
@@ -0,0 +1,157 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Linting Migrations
+Postgres Language Tools comes with a check command that can be integrated into your development workflow to catch problematic schema changes and encourage best practices.
To run it, simply point at your migrations directory.
+postgrestools check supabase/migrations
+When you are setting it up in an existing project, you might want to ignore all migrations that are already applied. To do so, add migrationsDir and after to your postgrestools.jsonc file
{
+ "migrations": {
+ "migrationsDir": "supabase/migrations",
+ "after": 1740868021
+ }
+}
+Alternatively, pass them directly.
+postgrestools check supabase/migrations --migrations-dir="supabase/migrations" --after=1740868021
+This will only check migrations after the specified timestamp.
+For pre-commit hooks and when working locally, use --staged to only lint files that have been staged. In CI environments, you most likely want to use --changed to only lint files that have been changed compared to your vcs.default_branch configuration. If default_branch is not set in your postgrestools.jsonc, use --since=REF to specify the base branch to compare against.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.0/cli_reference/index.html b/0.8.0/cli_reference/index.html
new file mode 100644
index 000000000..710774e18
--- /dev/null
+++ b/0.8.0/cli_reference/index.html
@@ -0,0 +1,378 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ CLI Reference
+Command summary
+-
+
postgrestools↴
+postgrestools version↴
+postgrestools check↴
+postgrestools start↴
+postgrestools stop↴
+postgrestools init↴
+postgrestools lsp-proxy↴
+postgrestools clean↴
+
postgrestools
+PostgresTools official CLI. Use it to check the health of your project or run it to check single files.
+Usage: postgrestools COMMAND ...
Available options:
+-
+
-h,--help— + Prints help information
+-V,--version— + Prints version information
+
Available commands:
+-
+
version— + Shows the version information and quit.
+check— + Runs everything to the requested files.
+start— + Starts the daemon server process.
+stop— + Stops the daemon server process.
+init— + Bootstraps a new project. Creates a configuration file with some defaults.
+lsp-proxy— + Acts as a server for the Language Server Protocol over stdin/stdout.
+clean— + Cleans the logs emitted by the daemon.
+
postgrestools version
+Shows the version information and quit.
+Usage: postgrestools version
Global options applied to all commands
+-
+
--colors=<off|force>— + 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— + Connect to a running instance of the daemon server.
+--skip-db— + Skip connecting to the database and only run checks that don't require a database connection.
+--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— + Set the file path to the configuration file, or the directory path to findpostgrestools.jsonc. If used, it disables the default configuration file resolution.
+--max-diagnostics=<none|<NUMBER>>— + Cap the amount of diagnostics displayed. Whennoneis provided, the limit is lifted. + [default: 20]
+--skip-errors— + Skip over files containing syntax errors instead of emitting an error diagnostic.
+--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— + Tell Postgres Tools to exit with an error code if some diagnostics emit warnings.
+--reporter=<json|json-pretty|github|junit|summary|gitlab>— + Allows to change how diagnostics and summary are reported.
+--log-level=<none|debug|info|warn|error>— + 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=<pretty|compact|json>— + How the log should look like. + [default: pretty]
+--diagnostic-level=<info|warn|error>— + The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing--diagnostic-level=errorwill cause Postgres Tools to print only diagnostics that contain only errors. + [default: info]
+
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools check
+Runs everything to the requested files.
+Usage: postgrestools check [--staged] [--changed] [--since=REF] [PATH]...
The configuration that is contained inside the configuration file.
+-
+
--vcs-enabled=<true|false>— + Whether we should integrate itself with the VCS client
+--vcs-client-kind=<git>— + The kind of client.
+--vcs-use-ignore-file=<true|false>— + Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file.
+--vcs-root=PATH— + The folder where we should check for VCS files. By default, we will use the same folder wherepostgrestools.jsoncwas 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— + The main branch of the project
+--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— + The directory where the migration files are stored
+--after=ARG— + Ignore any migrations before this timestamp
+--host=ARG— + The host of the database.
+--port=ARG— + The port of the database.
+--username=ARG— + The username to connect to the database.
+--password=ARG— + The password to connect to the database.
+--database=ARG— + The name of the database.
+--conn_timeout_secs=ARG— + The connection timeout in seconds. + [default: Some(10)]
+
Global options applied to all commands
+-
+
--colors=<off|force>— + 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— + Connect to a running instance of the daemon server.
+--skip-db— + Skip connecting to the database and only run checks that don't require a database connection.
+--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— + Set the file path to the configuration file, or the directory path to findpostgrestools.jsonc. If used, it disables the default configuration file resolution.
+--max-diagnostics=<none|<NUMBER>>— + Cap the amount of diagnostics displayed. Whennoneis provided, the limit is lifted. + [default: 20]
+--skip-errors— + Skip over files containing syntax errors instead of emitting an error diagnostic.
+--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— + Tell Postgres Tools to exit with an error code if some diagnostics emit warnings.
+--reporter=<json|json-pretty|github|junit|summary|gitlab>— + Allows to change how diagnostics and summary are reported.
+--log-level=<none|debug|info|warn|error>— + 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=<pretty|compact|json>— + How the log should look like. + [default: pretty]
+--diagnostic-level=<info|warn|error>— + The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing--diagnostic-level=errorwill cause Postgres Tools to print only diagnostics that contain only errors. + [default: info]
+
Available positional items:
+-
+
PATH— + Single file, single path or list of paths
+
Available options:
+-
+
--stdin-file-path=PATH— + Use this option when you want to format code piped fromstdin, and print the output tostdout.
+
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— + 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— + When set to true, only the files that have been changed compared to yourdefaultBranchconfiguration will be linted. This option should be used in CI environments.
+--since=REF— + Use this to specify the base branch to compare against when you're using the --changed flag and thedefaultBranchis not set in yourpostgrestools.jsonc
+-h,--help— + Prints help information
+
postgrestools start
+Starts the daemon server process.
+Usage: postgrestools start [--config-path=PATH]
Available options:
+-
+
--log-prefix-name=STRING— + Allows to change the prefix applied to the file name of the logs. + Uses environment variablePGT_LOG_PREFIX_NAME+ [default: server.log]
+--log-path=PATH— + Allows to change the folder where logs are stored. + Uses environment variablePGT_LOG_PATH
+--config-path=PATH— + Allows to set a custom file path to the configuration file, or a custom directory path to findpostgrestools.jsonc+ Uses environment variablePGT_LOG_PREFIX_NAME
+-h,--help— + Prints help information
+
postgrestools stop
+Stops the daemon server process.
+Usage: postgrestools stop
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools init
+Bootstraps a new project. Creates a configuration file with some defaults.
+Usage: postgrestools init
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools lsp-proxy
+Acts as a server for the Language Server Protocol over stdin/stdout.
+Usage: postgrestools lsp-proxy [--config-path=PATH]
Available options:
+-
+
--log-prefix-name=STRING— + Allows to change the prefix applied to the file name of the logs. + Uses environment variablePGT_LOG_PREFIX_NAME+ [default: server.log]
+--log-path=PATH— + Allows to change the folder where logs are stored. + Uses environment variablePGT_LOG_PATH
+--config-path=PATH— + Allows to set a custom file path to the configuration file, or a custom directory path to findpostgrestools.jsonc+ Uses environment variablePGT_CONFIG_PATH
+-h,--help— + Prints help information
+
postgrestools clean
+Cleans the logs emitted by the daemon.
+Usage: postgrestools clean
Available options:
+-
+
-h,--help— + Prints help information
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.0/codegen/Cargo.toml b/0.8.0/codegen/Cargo.toml
new file mode 100644
index 000000000..96092a7a3
--- /dev/null
+++ b/0.8.0/codegen/Cargo.toml
@@ -0,0 +1,34 @@
+
+[package]
+authors.workspace = true
+categories.workspace = true
+description = "{rule_name}"
+ )?;
+ }
+ writeln!(content)?;
+ }
+
+ write_documentation(group, rule, meta.docs, &mut content)?;
+
+ write_how_to_configure(group, rule, &mut content)?;
+
+ Ok(String::from_utf8(content)?)
+}
+
+fn write_how_to_configure(
+ group: &'static str,
+ rule: &'static str,
+ content: &mut Vec")?; + } + + Event::Start(Tag::List(num)) => { + list_indentation += 1; + if let Some(num) = num { + list_order = Some(num); + } + if list_indentation > 1 { + writeln!(content)?; + } + } + + Event::End(TagEnd::List(_)) => { + list_order = None; + list_indentation -= 1; + writeln!(content)?; + } + Event::Start(Tag::Item) => { + write!(content, "{}", " ".repeat(list_indentation - 1))?; + if let Some(num) = list_order { + write!(content, "{num}. ")?; + } else { + write!(content, "- ")?; + } + } + + Event::End(TagEnd::Item) => { + list_order = list_order.map(|item| item + 1); + writeln!(content)?; + } + + Event::Start(Tag::Strong) => { + write!(content, "**")?; + } + + Event::End(TagEnd::Strong) => { + write!(content, "**")?; + } + + Event::Start(Tag::Emphasis) => { + write!(content, "_")?; + } + + Event::End(TagEnd::Emphasis) => { + write!(content, "_")?; + } + + Event::Start(Tag::Strikethrough) => { + write!(content, "~")?; + } + + Event::End(TagEnd::Strikethrough) => { + write!(content, "~")?; + } + + Event::Start(Tag::BlockQuote(_)) => { + write!(content, ">")?; + } + + Event::End(TagEnd::BlockQuote(_)) => { + writeln!(content)?; + } + + _ => { + bail!("unimplemented event {event:?}") + } + } + } + + Ok(()) +} + +struct CodeBlockTest { + /// The language tag of this code block. + tag: String, + + /// True if this is an invalid example that should trigger a diagnostic. + expect_diagnostic: bool, + + /// Whether to ignore this code block. + ignore: bool, + + /// The number of lines in this code block. + line_count: u32, + + // The indices of lines that should be hidden from the public documentation. + hidden_lines: Vec
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Environment Variables
+PGT_LOG_PATH
+The directory where the Daemon logs will be saved.
+PGT_LOG_PREFIX_NAME
+A prefix that's added to the name of the log. Default: server.log.
PGT_CONFIG_PATH
+A path to the configuration file
+ +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.0/images/cli-demo.png b/0.8.0/images/cli-demo.png
new file mode 100644
index 000000000..33bac595c
Binary files /dev/null and b/0.8.0/images/cli-demo.png differ
diff --git a/0.8.0/images/lsp-demo.gif b/0.8.0/images/lsp-demo.gif
new file mode 100644
index 000000000..7fbff05fd
Binary files /dev/null and b/0.8.0/images/lsp-demo.gif differ
diff --git a/0.8.0/images/pls-github.png b/0.8.0/images/pls-github.png
new file mode 100644
index 000000000..95ae73828
Binary files /dev/null and b/0.8.0/images/pls-github.png differ
diff --git a/0.8.0/img/favicon.ico b/0.8.0/img/favicon.ico
new file mode 100644
index 000000000..e85006a3c
Binary files /dev/null and b/0.8.0/img/favicon.ico differ
diff --git a/0.8.0/index.html b/0.8.0/index.html
new file mode 100644
index 000000000..8f5cf6847
--- /dev/null
+++ b/0.8.0/index.html
@@ -0,0 +1,287 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Postgres Tools
+A collection of language tools and a Language Server Protocol (LSP) implementation for Postgres, focusing on developer experience and reliable SQL tooling.
++
Source Code: https://github.com/supabase-community/postgres-language-server
++
Overview
+This project provides a toolchain for Postgres development
+Postgres Language Server
+
CLI Demo
+
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 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
EXPLAINerror insights)
+ - Linter, inspired by Squawk +
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 on GitHub and give it execution permission:
+curl -L https://github.com/supabase-community/postgres-language-server/releases/download/<version>/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.
npm add --save-dev --save-exact @postgrestools/postgrestools
+VSCode
+The language server is available on the VSCode Marketplace. It's published from this repo.
+Neovim
+You will have to install nvim-lspconfig, and follow the instructions.
Emacs
+The language client is available through lsp-mode. For more details, refer to their manual page.
+Zed
+The language server is available as an Extension. It's published from this repo.
+GitHub Actions
+To use the CLI in GitHub Actions, you can install it via our GitHub 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:
postgrestools init
+You’ll now have a postgrestools.jsonc file in your directory:
{
+ "$schema": "https://pgtools.dev/schemas/0.0.0/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/*"]
+ }
+}
+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 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.
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 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:
+postgrestools start
+Then, every command needs to add the --use-server options, e.g.:
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;
+ - Windows:
C:\Users\<UserName>\AppData\Local\supabase-community\pgt\cache
+ - macOS:
/Users/<UserName>/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.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.0/js/html5shiv.min.js b/0.8.0/js/html5shiv.min.js
new file mode 100644
index 000000000..1a01c94ba
--- /dev/null
+++ b/0.8.0/js/html5shiv.min.js
@@ -0,0 +1,4 @@
+/**
+* @preserve HTML5 Shiv 3.7.3 | @afarkas @jdalton @jon_neal @rem | MIT/GPL2 Licensed
+*/
+!function(a,b){function c(a,b){var c=a.createElement("p"),d=a.getElementsByTagName("head")[0]||a.documentElement;return c.innerHTML="x",d.insertBefore(c.lastChild,d.firstChild)}function d(){var a=t.elements;return"string"==typeof a?a.split(" "):a}function e(a,b){var c=t.elements;"string"!=typeof c&&(c=c.join(" ")),"string"!=typeof a&&(a=a.join(" ")),t.elements=c+" "+a,j(b)}function f(a){var b=s[a[q]];return b||(b={},r++,a[q]=r,s[r]=b),b}function g(a,c,d){if(c||(c=b),l)return c.createElement(a);d||(d=f(c));var e;return e=d.cache[a]?d.cache[a].cloneNode():p.test(a)?(d.cache[a]=d.createElem(a)).cloneNode():d.createElem(a),!e.canHaveChildren||o.test(a)||e.tagUrn?e:d.frag.appendChild(e)}function h(a,c){if(a||(a=b),l)return a.createDocumentFragment();c=c||f(a);for(var e=c.frag.cloneNode(),g=0,h=d(),i=h.length;i>g;g++)e.createElement(h[g]);return e}function i(a,b){b.cache||(b.cache={},b.createElem=a.createElement,b.createFrag=a.createDocumentFragment,b.frag=b.createFrag()),a.createElement=function(c){return t.shivMethods?g(c,a,b):b.createElem(c)},a.createDocumentFragment=Function("h,f","return function(){var n=f.cloneNode(),c=n.createElement;h.shivMethods&&("+d().join().replace(/[\w\-:]+/g,function(a){return b.createElem(a),b.frag.createElement(a),'c("'+a+'")'})+");return n}")(t,b.frag)}function j(a){a||(a=b);var d=f(a);return!t.shivCSS||k||d.hasCSS||(d.hasCSS=!!c(a,"article,aside,dialog,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}mark{background:#FF0;color:#000}template{display:none}")),l||i(a,d),a}var k,l,m="3.7.3",n=a.html5||{},o=/^<|^(?:button|map|select|textarea|object|iframe|option|optgroup)$/i,p=/^(?:a|b|code|div|fieldset|h1|h2|h3|h4|h5|h6|i|label|li|ol|p|q|span|strong|style|table|tbody|td|th|tr|ul)$/i,q="_html5shiv",r=0,s={};!function(){try{var a=b.createElement("a");a.innerHTML="
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Exclusive rules
+Rules from other sources
+Squawk
+| Squawk Rule Name | +Rule Name | +
|---|---|
| adding-required-field | +addingRequiredField | +
| ban-drop-column | +banDropColumn | +
| ban-drop-not-null | +banDropNotNull | +
| ban-drop-table | +banDropTable | +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.0/rules/adding-required-field/index.html b/0.8.0/rules/adding-required-field/index.html
new file mode 100644
index 000000000..6dc01187d
--- /dev/null
+++ b/0.8.0/rules/adding-required-field/index.html
@@ -0,0 +1,155 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ addingRequiredField
+Diagnostic Category: lint/safety/addingRequiredField
Since: vnext
Sources:
+- Inspired from: squawk/adding-required-field
Description
+Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required.
+This will fail immediately upon running for any populated table. Furthermore, old application code that is unaware of this column will fail to INSERT to this table.
+Make new columns optional initially by omitting the NOT NULL constraint until all existing data and application code has been updated. Once no NULL values are written to or persisted in the database, set it to NOT NULL. +Alternatively, if using Postgres version 11 or later, add a DEFAULT value that is not volatile. This allows the column to keep its NOT NULL constraint.
+Invalid
+alter table test add column count int not null;
+Valid in Postgres >= 11
+alter table test add column count int not null default 0;
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "addingRequiredField": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.0/rules/ban-drop-column/index.html b/0.8.0/rules/ban-drop-column/index.html
new file mode 100644
index 000000000..b88bea6d9
--- /dev/null
+++ b/0.8.0/rules/ban-drop-column/index.html
@@ -0,0 +1,166 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropColumn
+Diagnostic Category: lint/safety/banDropColumn
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-column
Description
+Dropping a column may break existing clients.
+Update your application code to no longer read or write the column.
+You can leave the column as nullable or delete the column once queries no longer select or modify the column.
+Examples
+Invalid
+alter table test drop column id;
+code-block.sql lint/safety/banDropColumn ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ × Dropping a column may break existing clients.
+
+ i You can leave the column as nullable or delete the column once queries no longer select or modify the column.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropColumn": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.0/rules/ban-drop-not-null/index.html b/0.8.0/rules/ban-drop-not-null/index.html
new file mode 100644
index 000000000..99c791190
--- /dev/null
+++ b/0.8.0/rules/ban-drop-not-null/index.html
@@ -0,0 +1,166 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropNotNull
+Diagnostic Category: lint/safety/banDropNotNull
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-not-null
Description
+Dropping a NOT NULL constraint may break existing clients.
+Application code or code written in procedural languages like PL/SQL or PL/pgSQL may not expect NULL values for the column that was previously guaranteed to be NOT NULL and therefore may fail to process them correctly.
+You can consider using a marker value that represents NULL. Alternatively, create a new table allowing NULL values, copy the data from the old table, and create a view that filters NULL values.
+Examples
+Invalid
+alter table users alter column email drop not null;
+code-block.sql lint/safety/banDropNotNull ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ × Dropping a NOT NULL constraint may break existing clients.
+
+ i Consider using a marker value that represents NULL. Alternatively, create a new table allowing NULL values, copy the data from the old table, and create a view that filters NULL values.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropNotNull": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.0/rules/ban-drop-table/index.html b/0.8.0/rules/ban-drop-table/index.html
new file mode 100644
index 000000000..94d966b11
--- /dev/null
+++ b/0.8.0/rules/ban-drop-table/index.html
@@ -0,0 +1,167 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropTable
+Diagnostic Category: lint/safety/banDropTable
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-table
Description
+Dropping a table may break existing clients.
+Update your application code to no longer read or write the table.
+Once the table is no longer needed, you can delete it by running the command "DROP TABLE mytable;".
+This command will permanently remove the table from the database and all its contents. +Be sure to back up the table before deleting it, just in case you need to restore it in the future.
+Examples
+drop table some_table;
+code-block.sql lint/safety/banDropTable ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ × Dropping a table may break existing clients.
+
+ i Update your application code to no longer read or write the table, and only then delete the table. Be sure to create a backup.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropTable": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.0/rules/index.html b/0.8.0/rules/index.html
new file mode 100644
index 000000000..1e525f2c3
--- /dev/null
+++ b/0.8.0/rules/index.html
@@ -0,0 +1,179 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rules
+Below the list of rules supported by Postgres Language Tools, divided by group. Here's a legend of the emojis:
+-
+
- The icon ✅ indicates that the rule is part of the recommended rules. +
Safety
+Rules that detect potential safety issues in your code.
+| Rule name | +Description | +Properties | +
|---|---|---|
| addingRequiredField | +Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required. | ++ |
| banDropColumn | +Dropping a column may break existing clients. | +✅ | +
| banDropNotNull | +Dropping a NOT NULL constraint may break existing clients. | +✅ | +
| banDropTable | +Dropping a table may break existing clients. | +✅ | +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.0/schema.json b/0.8.0/schema.json
new file mode 100644
index 000000000..8c478d0ae
--- /dev/null
+++ b/0.8.0/schema.json
@@ -0,0 +1,449 @@
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "Configuration",
+ "description": "The configuration that is contained inside the configuration file.",
+ "type": "object",
+ "properties": {
+ "$schema": {
+ "description": "A field for the [JSON schema](https://json-schema.org/) specification",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "db": {
+ "description": "The configuration of the database connection",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/DatabaseConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "extends": {
+ "description": "A list of paths to other JSON files, used to extends the current configuration.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "files": {
+ "description": "The configuration of the filesystem",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/FilesConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "linter": {
+ "description": "The configuration for the linter",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/LinterConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "migrations": {
+ "description": "Configure migrations",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/MigrationsConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "vcs": {
+ "description": "The configuration of the VCS integration",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/VcsConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false,
+ "definitions": {
+ "DatabaseConfiguration": {
+ "description": "The configuration of the database connection.",
+ "type": "object",
+ "properties": {
+ "allowStatementExecutionsAgainst": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "connTimeoutSecs": {
+ "description": "The connection timeout in seconds.",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint16",
+ "minimum": 0.0
+ },
+ "database": {
+ "description": "The name of the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "host": {
+ "description": "The host of the database. Required if you want database-related features. All else falls back to sensible defaults.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "password": {
+ "description": "The password to connect to the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "port": {
+ "description": "The port of the database.",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint16",
+ "minimum": 0.0
+ },
+ "username": {
+ "description": "The username to connect to the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "FilesConfiguration": {
+ "description": "The configuration of the filesystem",
+ "type": "object",
+ "properties": {
+ "ignore": {
+ "description": "A list of Unix shell style patterns. Will ignore files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "include": {
+ "description": "A list of Unix shell style patterns. Will handle only those files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "maxSize": {
+ "description": "The maximum allowed size for source code files in bytes. Files above this limit will be ignored for performance reasons. Defaults to 1 MiB",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint64",
+ "minimum": 1.0
+ }
+ },
+ "additionalProperties": false
+ },
+ "LinterConfiguration": {
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "description": "if `false`, it disables the feature and the linter won't be executed. `true` by default",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "ignore": {
+ "description": "A list of Unix shell style patterns. The formatter will ignore files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "include": {
+ "description": "A list of Unix shell style patterns. The formatter will include files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "rules": {
+ "description": "List of rules",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/Rules"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "MigrationsConfiguration": {
+ "description": "The configuration of the filesystem",
+ "type": "object",
+ "properties": {
+ "after": {
+ "description": "Ignore any migrations before this timestamp",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint64",
+ "minimum": 0.0
+ },
+ "migrationsDir": {
+ "description": "The directory where the migration files are stored",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "RuleConfiguration": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RulePlainConfiguration"
+ },
+ {
+ "$ref": "#/definitions/RuleWithNoOptions"
+ }
+ ]
+ },
+ "RulePlainConfiguration": {
+ "type": "string",
+ "enum": [
+ "warn",
+ "error",
+ "info",
+ "off"
+ ]
+ },
+ "RuleWithNoOptions": {
+ "type": "object",
+ "required": [
+ "level"
+ ],
+ "properties": {
+ "level": {
+ "description": "The severity of the emitted diagnostics by the rule",
+ "allOf": [
+ {
+ "$ref": "#/definitions/RulePlainConfiguration"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "Rules": {
+ "type": "object",
+ "properties": {
+ "all": {
+ "description": "It enables ALL rules. The rules that belong to `nursery` won't be enabled.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "recommended": {
+ "description": "It enables the lint rules recommended by Postgres Tools. `true` by default.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "safety": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/Safety"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "Safety": {
+ "description": "A list of rules that belong to this group",
+ "type": "object",
+ "properties": {
+ "addingRequiredField": {
+ "description": "Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "all": {
+ "description": "It enables ALL rules for this group.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "banDropColumn": {
+ "description": "Dropping a column may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropNotNull": {
+ "description": "Dropping a NOT NULL constraint may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropTable": {
+ "description": "Dropping a table may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "recommended": {
+ "description": "It enables the recommended rules for this group",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "StringSet": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "uniqueItems": true
+ },
+ "VcsClientKind": {
+ "oneOf": [
+ {
+ "description": "Integration with the git client as VCS",
+ "type": "string",
+ "enum": [
+ "git"
+ ]
+ }
+ ]
+ },
+ "VcsConfiguration": {
+ "description": "Set of properties to integrate with a VCS software.",
+ "type": "object",
+ "properties": {
+ "clientKind": {
+ "description": "The kind of client.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/VcsClientKind"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "defaultBranch": {
+ "description": "The main branch of the project",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "enabled": {
+ "description": "Whether we should integrate itself with the VCS client",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "root": {
+ "description": "The folder where we should check for VCS files. By default, we will use the same folder where `postgrestools.jsonc` was found.\n\nIf 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",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "useIgnoreFile": {
+ "description": "Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ }
+ }
+}
\ No newline at end of file
diff --git a/0.8.0/sitemap.xml b/0.8.0/sitemap.xml
new file mode 100644
index 000000000..a3d79626e
--- /dev/null
+++ b/0.8.0/sitemap.xml
@@ -0,0 +1,47 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.1/404.html b/0.8.1/404.html
new file mode 100644
index 000000000..7e2b12783
--- /dev/null
+++ b/0.8.1/404.html
@@ -0,0 +1,124 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 404
+ +Page not found
+ + +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.1/checking_migrations/index.html b/0.8.1/checking_migrations/index.html
new file mode 100644
index 000000000..cb047c631
--- /dev/null
+++ b/0.8.1/checking_migrations/index.html
@@ -0,0 +1,157 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Linting Migrations
+Postgres Language Tools comes with a check command that can be integrated into your development workflow to catch problematic schema changes and encourage best practices.
To run it, simply point at your migrations directory.
+postgrestools check supabase/migrations
+When you are setting it up in an existing project, you might want to ignore all migrations that are already applied. To do so, add migrationsDir and after to your postgrestools.jsonc file
{
+ "migrations": {
+ "migrationsDir": "supabase/migrations",
+ "after": 1740868021
+ }
+}
+Alternatively, pass them directly.
+postgrestools check supabase/migrations --migrations-dir="supabase/migrations" --after=1740868021
+This will only check migrations after the specified timestamp.
+For pre-commit hooks and when working locally, use --staged to only lint files that have been staged. In CI environments, you most likely want to use --changed to only lint files that have been changed compared to your vcs.default_branch configuration. If default_branch is not set in your postgrestools.jsonc, use --since=REF to specify the base branch to compare against.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.1/cli_reference/index.html b/0.8.1/cli_reference/index.html
new file mode 100644
index 000000000..cb9442b37
--- /dev/null
+++ b/0.8.1/cli_reference/index.html
@@ -0,0 +1,378 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ CLI Reference
+Command summary
+-
+
postgrestools↴
+postgrestools version↴
+postgrestools check↴
+postgrestools start↴
+postgrestools stop↴
+postgrestools init↴
+postgrestools lsp-proxy↴
+postgrestools clean↴
+
postgrestools
+PostgresTools official CLI. Use it to check the health of your project or run it to check single files.
+Usage: postgrestools COMMAND ...
Available options:
+-
+
-h,--help— + Prints help information
+-V,--version— + Prints version information
+
Available commands:
+-
+
version— + Shows the version information and quit.
+check— + Runs everything to the requested files.
+start— + Starts the daemon server process.
+stop— + Stops the daemon server process.
+init— + Bootstraps a new project. Creates a configuration file with some defaults.
+lsp-proxy— + Acts as a server for the Language Server Protocol over stdin/stdout.
+clean— + Cleans the logs emitted by the daemon.
+
postgrestools version
+Shows the version information and quit.
+Usage: postgrestools version
Global options applied to all commands
+-
+
--colors=<off|force>— + 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— + Connect to a running instance of the daemon server.
+--skip-db— + Skip connecting to the database and only run checks that don't require a database connection.
+--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— + Set the file path to the configuration file, or the directory path to findpostgrestools.jsonc. If used, it disables the default configuration file resolution.
+--max-diagnostics=<none|<NUMBER>>— + Cap the amount of diagnostics displayed. Whennoneis provided, the limit is lifted. + [default: 20]
+--skip-errors— + Skip over files containing syntax errors instead of emitting an error diagnostic.
+--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— + Tell Postgres Tools to exit with an error code if some diagnostics emit warnings.
+--reporter=<json|json-pretty|github|junit|summary|gitlab>— + Allows to change how diagnostics and summary are reported.
+--log-level=<none|debug|info|warn|error>— + 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=<pretty|compact|json>— + How the log should look like. + [default: pretty]
+--diagnostic-level=<info|warn|error>— + The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing--diagnostic-level=errorwill cause Postgres Tools to print only diagnostics that contain only errors. + [default: info]
+
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools check
+Runs everything to the requested files.
+Usage: postgrestools check [--staged] [--changed] [--since=REF] [PATH]...
The configuration that is contained inside the configuration file.
+-
+
--vcs-enabled=<true|false>— + Whether we should integrate itself with the VCS client
+--vcs-client-kind=<git>— + The kind of client.
+--vcs-use-ignore-file=<true|false>— + Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file.
+--vcs-root=PATH— + The folder where we should check for VCS files. By default, we will use the same folder wherepostgrestools.jsoncwas 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— + The main branch of the project
+--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— + The directory where the migration files are stored
+--after=ARG— + Ignore any migrations before this timestamp
+--host=ARG— + The host of the database.
+--port=ARG— + The port of the database.
+--username=ARG— + The username to connect to the database.
+--password=ARG— + The password to connect to the database.
+--database=ARG— + The name of the database.
+--conn_timeout_secs=ARG— + The connection timeout in seconds. + [default: Some(10)]
+
Global options applied to all commands
+-
+
--colors=<off|force>— + 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— + Connect to a running instance of the daemon server.
+--skip-db— + Skip connecting to the database and only run checks that don't require a database connection.
+--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— + Set the file path to the configuration file, or the directory path to findpostgrestools.jsonc. If used, it disables the default configuration file resolution.
+--max-diagnostics=<none|<NUMBER>>— + Cap the amount of diagnostics displayed. Whennoneis provided, the limit is lifted. + [default: 20]
+--skip-errors— + Skip over files containing syntax errors instead of emitting an error diagnostic.
+--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— + Tell Postgres Tools to exit with an error code if some diagnostics emit warnings.
+--reporter=<json|json-pretty|github|junit|summary|gitlab>— + Allows to change how diagnostics and summary are reported.
+--log-level=<none|debug|info|warn|error>— + 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=<pretty|compact|json>— + How the log should look like. + [default: pretty]
+--diagnostic-level=<info|warn|error>— + The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing--diagnostic-level=errorwill cause Postgres Tools to print only diagnostics that contain only errors. + [default: info]
+
Available positional items:
+-
+
PATH— + Single file, single path or list of paths
+
Available options:
+-
+
--stdin-file-path=PATH— + Use this option when you want to format code piped fromstdin, and print the output tostdout.
+
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— + 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— + When set to true, only the files that have been changed compared to yourdefaultBranchconfiguration will be linted. This option should be used in CI environments.
+--since=REF— + Use this to specify the base branch to compare against when you're using the --changed flag and thedefaultBranchis not set in yourpostgrestools.jsonc
+-h,--help— + Prints help information
+
postgrestools start
+Starts the daemon server process.
+Usage: postgrestools start [--config-path=PATH]
Available options:
+-
+
--log-prefix-name=STRING— + Allows to change the prefix applied to the file name of the logs. + Uses environment variablePGT_LOG_PREFIX_NAME+ [default: server.log]
+--log-path=PATH— + Allows to change the folder where logs are stored. + Uses environment variablePGT_LOG_PATH
+--config-path=PATH— + Allows to set a custom file path to the configuration file, or a custom directory path to findpostgrestools.jsonc+ Uses environment variablePGT_LOG_PREFIX_NAME
+-h,--help— + Prints help information
+
postgrestools stop
+Stops the daemon server process.
+Usage: postgrestools stop
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools init
+Bootstraps a new project. Creates a configuration file with some defaults.
+Usage: postgrestools init
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools lsp-proxy
+Acts as a server for the Language Server Protocol over stdin/stdout.
+Usage: postgrestools lsp-proxy [--config-path=PATH]
Available options:
+-
+
--log-prefix-name=STRING— + Allows to change the prefix applied to the file name of the logs. + Uses environment variablePGT_LOG_PREFIX_NAME+ [default: server.log]
+--log-path=PATH— + Allows to change the folder where logs are stored. + Uses environment variablePGT_LOG_PATH
+--config-path=PATH— + Allows to set a custom file path to the configuration file, or a custom directory path to findpostgrestools.jsonc+ Uses environment variablePGT_CONFIG_PATH
+-h,--help— + Prints help information
+
postgrestools clean
+Cleans the logs emitted by the daemon.
+Usage: postgrestools clean
Available options:
+-
+
-h,--help— + Prints help information
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.1/codegen/Cargo.toml b/0.8.1/codegen/Cargo.toml
new file mode 100644
index 000000000..96092a7a3
--- /dev/null
+++ b/0.8.1/codegen/Cargo.toml
@@ -0,0 +1,34 @@
+
+[package]
+authors.workspace = true
+categories.workspace = true
+description = "{rule_name}"
+ )?;
+ }
+ writeln!(content)?;
+ }
+
+ write_documentation(group, rule, meta.docs, &mut content)?;
+
+ write_how_to_configure(group, rule, &mut content)?;
+
+ Ok(String::from_utf8(content)?)
+}
+
+fn write_how_to_configure(
+ group: &'static str,
+ rule: &'static str,
+ content: &mut Vec")?; + } + + Event::Start(Tag::List(num)) => { + list_indentation += 1; + if let Some(num) = num { + list_order = Some(num); + } + if list_indentation > 1 { + writeln!(content)?; + } + } + + Event::End(TagEnd::List(_)) => { + list_order = None; + list_indentation -= 1; + writeln!(content)?; + } + Event::Start(Tag::Item) => { + write!(content, "{}", " ".repeat(list_indentation - 1))?; + if let Some(num) = list_order { + write!(content, "{num}. ")?; + } else { + write!(content, "- ")?; + } + } + + Event::End(TagEnd::Item) => { + list_order = list_order.map(|item| item + 1); + writeln!(content)?; + } + + Event::Start(Tag::Strong) => { + write!(content, "**")?; + } + + Event::End(TagEnd::Strong) => { + write!(content, "**")?; + } + + Event::Start(Tag::Emphasis) => { + write!(content, "_")?; + } + + Event::End(TagEnd::Emphasis) => { + write!(content, "_")?; + } + + Event::Start(Tag::Strikethrough) => { + write!(content, "~")?; + } + + Event::End(TagEnd::Strikethrough) => { + write!(content, "~")?; + } + + Event::Start(Tag::BlockQuote(_)) => { + write!(content, ">")?; + } + + Event::End(TagEnd::BlockQuote(_)) => { + writeln!(content)?; + } + + _ => { + bail!("unimplemented event {event:?}") + } + } + } + + Ok(()) +} + +struct CodeBlockTest { + /// The language tag of this code block. + tag: String, + + /// True if this is an invalid example that should trigger a diagnostic. + expect_diagnostic: bool, + + /// Whether to ignore this code block. + ignore: bool, + + /// The number of lines in this code block. + line_count: u32, + + // The indices of lines that should be hidden from the public documentation. + hidden_lines: Vec
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Environment Variables
+PGT_LOG_PATH
+The directory where the Daemon logs will be saved.
+PGT_LOG_PREFIX_NAME
+A prefix that's added to the name of the log. Default: server.log.
PGT_CONFIG_PATH
+A path to the configuration file
+ +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.1/images/cli-demo.png b/0.8.1/images/cli-demo.png
new file mode 100644
index 000000000..33bac595c
Binary files /dev/null and b/0.8.1/images/cli-demo.png differ
diff --git a/0.8.1/images/lsp-demo.gif b/0.8.1/images/lsp-demo.gif
new file mode 100644
index 000000000..7fbff05fd
Binary files /dev/null and b/0.8.1/images/lsp-demo.gif differ
diff --git a/0.8.1/images/pls-github.png b/0.8.1/images/pls-github.png
new file mode 100644
index 000000000..95ae73828
Binary files /dev/null and b/0.8.1/images/pls-github.png differ
diff --git a/0.8.1/img/favicon.ico b/0.8.1/img/favicon.ico
new file mode 100644
index 000000000..e85006a3c
Binary files /dev/null and b/0.8.1/img/favicon.ico differ
diff --git a/0.8.1/index.html b/0.8.1/index.html
new file mode 100644
index 000000000..827a52191
--- /dev/null
+++ b/0.8.1/index.html
@@ -0,0 +1,287 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Postgres Tools
+A collection of language tools and a Language Server Protocol (LSP) implementation for Postgres, focusing on developer experience and reliable SQL tooling.
++
Source Code: https://github.com/supabase-community/postgres-language-server
++
Overview
+This project provides a toolchain for Postgres development
+Postgres Language Server
+
CLI Demo
+
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 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
EXPLAINerror insights)
+ - Linter, inspired by Squawk +
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 on GitHub and give it execution permission:
+curl -L https://github.com/supabase-community/postgres-language-server/releases/download/<version>/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.
npm add --save-dev --save-exact @postgrestools/postgrestools
+VSCode
+The language server is available on the VSCode Marketplace. It's published from this repo.
+Neovim
+You will have to install nvim-lspconfig, and follow the instructions.
Emacs
+The language client is available through lsp-mode. For more details, refer to their manual page.
+Zed
+The language server is available as an Extension. It's published from this repo.
+GitHub Actions
+To use the CLI in GitHub Actions, you can install it via our GitHub 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:
postgrestools init
+You’ll now have a postgrestools.jsonc file in your directory:
{
+ "$schema": "https://pgtools.dev/schemas/0.0.0/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/*"]
+ }
+}
+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 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.
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 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:
+postgrestools start
+Then, every command needs to add the --use-server options, e.g.:
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;
+ - Windows:
C:\Users\<UserName>\AppData\Local\supabase-community\pgt\cache
+ - macOS:
/Users/<UserName>/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.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.1/js/html5shiv.min.js b/0.8.1/js/html5shiv.min.js
new file mode 100644
index 000000000..1a01c94ba
--- /dev/null
+++ b/0.8.1/js/html5shiv.min.js
@@ -0,0 +1,4 @@
+/**
+* @preserve HTML5 Shiv 3.7.3 | @afarkas @jdalton @jon_neal @rem | MIT/GPL2 Licensed
+*/
+!function(a,b){function c(a,b){var c=a.createElement("p"),d=a.getElementsByTagName("head")[0]||a.documentElement;return c.innerHTML="x",d.insertBefore(c.lastChild,d.firstChild)}function d(){var a=t.elements;return"string"==typeof a?a.split(" "):a}function e(a,b){var c=t.elements;"string"!=typeof c&&(c=c.join(" ")),"string"!=typeof a&&(a=a.join(" ")),t.elements=c+" "+a,j(b)}function f(a){var b=s[a[q]];return b||(b={},r++,a[q]=r,s[r]=b),b}function g(a,c,d){if(c||(c=b),l)return c.createElement(a);d||(d=f(c));var e;return e=d.cache[a]?d.cache[a].cloneNode():p.test(a)?(d.cache[a]=d.createElem(a)).cloneNode():d.createElem(a),!e.canHaveChildren||o.test(a)||e.tagUrn?e:d.frag.appendChild(e)}function h(a,c){if(a||(a=b),l)return a.createDocumentFragment();c=c||f(a);for(var e=c.frag.cloneNode(),g=0,h=d(),i=h.length;i>g;g++)e.createElement(h[g]);return e}function i(a,b){b.cache||(b.cache={},b.createElem=a.createElement,b.createFrag=a.createDocumentFragment,b.frag=b.createFrag()),a.createElement=function(c){return t.shivMethods?g(c,a,b):b.createElem(c)},a.createDocumentFragment=Function("h,f","return function(){var n=f.cloneNode(),c=n.createElement;h.shivMethods&&("+d().join().replace(/[\w\-:]+/g,function(a){return b.createElem(a),b.frag.createElement(a),'c("'+a+'")'})+");return n}")(t,b.frag)}function j(a){a||(a=b);var d=f(a);return!t.shivCSS||k||d.hasCSS||(d.hasCSS=!!c(a,"article,aside,dialog,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}mark{background:#FF0;color:#000}template{display:none}")),l||i(a,d),a}var k,l,m="3.7.3",n=a.html5||{},o=/^<|^(?:button|map|select|textarea|object|iframe|option|optgroup)$/i,p=/^(?:a|b|code|div|fieldset|h1|h2|h3|h4|h5|h6|i|label|li|ol|p|q|span|strong|style|table|tbody|td|th|tr|ul)$/i,q="_html5shiv",r=0,s={};!function(){try{var a=b.createElement("a");a.innerHTML="
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Exclusive rules
+Rules from other sources
+Squawk
+| Squawk Rule Name | +Rule Name | +
|---|---|
| adding-required-field | +addingRequiredField | +
| ban-drop-column | +banDropColumn | +
| ban-drop-not-null | +banDropNotNull | +
| ban-drop-table | +banDropTable | +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.1/rules/adding-required-field/index.html b/0.8.1/rules/adding-required-field/index.html
new file mode 100644
index 000000000..c78f5ba51
--- /dev/null
+++ b/0.8.1/rules/adding-required-field/index.html
@@ -0,0 +1,155 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ addingRequiredField
+Diagnostic Category: lint/safety/addingRequiredField
Since: vnext
Sources:
+- Inspired from: squawk/adding-required-field
Description
+Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required.
+This will fail immediately upon running for any populated table. Furthermore, old application code that is unaware of this column will fail to INSERT to this table.
+Make new columns optional initially by omitting the NOT NULL constraint until all existing data and application code has been updated. Once no NULL values are written to or persisted in the database, set it to NOT NULL. +Alternatively, if using Postgres version 11 or later, add a DEFAULT value that is not volatile. This allows the column to keep its NOT NULL constraint.
+Invalid
+alter table test add column count int not null;
+Valid in Postgres >= 11
+alter table test add column count int not null default 0;
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "addingRequiredField": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.1/rules/ban-drop-column/index.html b/0.8.1/rules/ban-drop-column/index.html
new file mode 100644
index 000000000..a535aa17e
--- /dev/null
+++ b/0.8.1/rules/ban-drop-column/index.html
@@ -0,0 +1,166 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropColumn
+Diagnostic Category: lint/safety/banDropColumn
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-column
Description
+Dropping a column may break existing clients.
+Update your application code to no longer read or write the column.
+You can leave the column as nullable or delete the column once queries no longer select or modify the column.
+Examples
+Invalid
+alter table test drop column id;
+code-block.sql lint/safety/banDropColumn ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ × Dropping a column may break existing clients.
+
+ i You can leave the column as nullable or delete the column once queries no longer select or modify the column.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropColumn": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.1/rules/ban-drop-not-null/index.html b/0.8.1/rules/ban-drop-not-null/index.html
new file mode 100644
index 000000000..8fdac2f4d
--- /dev/null
+++ b/0.8.1/rules/ban-drop-not-null/index.html
@@ -0,0 +1,166 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropNotNull
+Diagnostic Category: lint/safety/banDropNotNull
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-not-null
Description
+Dropping a NOT NULL constraint may break existing clients.
+Application code or code written in procedural languages like PL/SQL or PL/pgSQL may not expect NULL values for the column that was previously guaranteed to be NOT NULL and therefore may fail to process them correctly.
+You can consider using a marker value that represents NULL. Alternatively, create a new table allowing NULL values, copy the data from the old table, and create a view that filters NULL values.
+Examples
+Invalid
+alter table users alter column email drop not null;
+code-block.sql lint/safety/banDropNotNull ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ × Dropping a NOT NULL constraint may break existing clients.
+
+ i Consider using a marker value that represents NULL. Alternatively, create a new table allowing NULL values, copy the data from the old table, and create a view that filters NULL values.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropNotNull": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.1/rules/ban-drop-table/index.html b/0.8.1/rules/ban-drop-table/index.html
new file mode 100644
index 000000000..6d40b3577
--- /dev/null
+++ b/0.8.1/rules/ban-drop-table/index.html
@@ -0,0 +1,167 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropTable
+Diagnostic Category: lint/safety/banDropTable
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-table
Description
+Dropping a table may break existing clients.
+Update your application code to no longer read or write the table.
+Once the table is no longer needed, you can delete it by running the command "DROP TABLE mytable;".
+This command will permanently remove the table from the database and all its contents. +Be sure to back up the table before deleting it, just in case you need to restore it in the future.
+Examples
+drop table some_table;
+code-block.sql lint/safety/banDropTable ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ × Dropping a table may break existing clients.
+
+ i Update your application code to no longer read or write the table, and only then delete the table. Be sure to create a backup.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropTable": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.1/rules/index.html b/0.8.1/rules/index.html
new file mode 100644
index 000000000..ac8a65af1
--- /dev/null
+++ b/0.8.1/rules/index.html
@@ -0,0 +1,179 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rules
+Below the list of rules supported by Postgres Language Tools, divided by group. Here's a legend of the emojis:
+-
+
- The icon ✅ indicates that the rule is part of the recommended rules. +
Safety
+Rules that detect potential safety issues in your code.
+| Rule name | +Description | +Properties | +
|---|---|---|
| addingRequiredField | +Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required. | ++ |
| banDropColumn | +Dropping a column may break existing clients. | +✅ | +
| banDropNotNull | +Dropping a NOT NULL constraint may break existing clients. | +✅ | +
| banDropTable | +Dropping a table may break existing clients. | +✅ | +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.8.1/schema.json b/0.8.1/schema.json
new file mode 100644
index 000000000..8c478d0ae
--- /dev/null
+++ b/0.8.1/schema.json
@@ -0,0 +1,449 @@
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "Configuration",
+ "description": "The configuration that is contained inside the configuration file.",
+ "type": "object",
+ "properties": {
+ "$schema": {
+ "description": "A field for the [JSON schema](https://json-schema.org/) specification",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "db": {
+ "description": "The configuration of the database connection",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/DatabaseConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "extends": {
+ "description": "A list of paths to other JSON files, used to extends the current configuration.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "files": {
+ "description": "The configuration of the filesystem",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/FilesConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "linter": {
+ "description": "The configuration for the linter",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/LinterConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "migrations": {
+ "description": "Configure migrations",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/MigrationsConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "vcs": {
+ "description": "The configuration of the VCS integration",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/VcsConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false,
+ "definitions": {
+ "DatabaseConfiguration": {
+ "description": "The configuration of the database connection.",
+ "type": "object",
+ "properties": {
+ "allowStatementExecutionsAgainst": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "connTimeoutSecs": {
+ "description": "The connection timeout in seconds.",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint16",
+ "minimum": 0.0
+ },
+ "database": {
+ "description": "The name of the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "host": {
+ "description": "The host of the database. Required if you want database-related features. All else falls back to sensible defaults.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "password": {
+ "description": "The password to connect to the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "port": {
+ "description": "The port of the database.",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint16",
+ "minimum": 0.0
+ },
+ "username": {
+ "description": "The username to connect to the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "FilesConfiguration": {
+ "description": "The configuration of the filesystem",
+ "type": "object",
+ "properties": {
+ "ignore": {
+ "description": "A list of Unix shell style patterns. Will ignore files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "include": {
+ "description": "A list of Unix shell style patterns. Will handle only those files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "maxSize": {
+ "description": "The maximum allowed size for source code files in bytes. Files above this limit will be ignored for performance reasons. Defaults to 1 MiB",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint64",
+ "minimum": 1.0
+ }
+ },
+ "additionalProperties": false
+ },
+ "LinterConfiguration": {
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "description": "if `false`, it disables the feature and the linter won't be executed. `true` by default",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "ignore": {
+ "description": "A list of Unix shell style patterns. The formatter will ignore files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "include": {
+ "description": "A list of Unix shell style patterns. The formatter will include files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "rules": {
+ "description": "List of rules",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/Rules"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "MigrationsConfiguration": {
+ "description": "The configuration of the filesystem",
+ "type": "object",
+ "properties": {
+ "after": {
+ "description": "Ignore any migrations before this timestamp",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint64",
+ "minimum": 0.0
+ },
+ "migrationsDir": {
+ "description": "The directory where the migration files are stored",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "RuleConfiguration": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RulePlainConfiguration"
+ },
+ {
+ "$ref": "#/definitions/RuleWithNoOptions"
+ }
+ ]
+ },
+ "RulePlainConfiguration": {
+ "type": "string",
+ "enum": [
+ "warn",
+ "error",
+ "info",
+ "off"
+ ]
+ },
+ "RuleWithNoOptions": {
+ "type": "object",
+ "required": [
+ "level"
+ ],
+ "properties": {
+ "level": {
+ "description": "The severity of the emitted diagnostics by the rule",
+ "allOf": [
+ {
+ "$ref": "#/definitions/RulePlainConfiguration"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "Rules": {
+ "type": "object",
+ "properties": {
+ "all": {
+ "description": "It enables ALL rules. The rules that belong to `nursery` won't be enabled.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "recommended": {
+ "description": "It enables the lint rules recommended by Postgres Tools. `true` by default.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "safety": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/Safety"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "Safety": {
+ "description": "A list of rules that belong to this group",
+ "type": "object",
+ "properties": {
+ "addingRequiredField": {
+ "description": "Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "all": {
+ "description": "It enables ALL rules for this group.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "banDropColumn": {
+ "description": "Dropping a column may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropNotNull": {
+ "description": "Dropping a NOT NULL constraint may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropTable": {
+ "description": "Dropping a table may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "recommended": {
+ "description": "It enables the recommended rules for this group",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "StringSet": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "uniqueItems": true
+ },
+ "VcsClientKind": {
+ "oneOf": [
+ {
+ "description": "Integration with the git client as VCS",
+ "type": "string",
+ "enum": [
+ "git"
+ ]
+ }
+ ]
+ },
+ "VcsConfiguration": {
+ "description": "Set of properties to integrate with a VCS software.",
+ "type": "object",
+ "properties": {
+ "clientKind": {
+ "description": "The kind of client.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/VcsClientKind"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "defaultBranch": {
+ "description": "The main branch of the project",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "enabled": {
+ "description": "Whether we should integrate itself with the VCS client",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "root": {
+ "description": "The folder where we should check for VCS files. By default, we will use the same folder where `postgrestools.jsonc` was found.\n\nIf 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",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "useIgnoreFile": {
+ "description": "Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ }
+ }
+}
\ No newline at end of file
diff --git a/0.8.1/sitemap.xml b/0.8.1/sitemap.xml
new file mode 100644
index 000000000..83d327b7c
--- /dev/null
+++ b/0.8.1/sitemap.xml
@@ -0,0 +1,47 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/404.html b/0.9.0/404.html
new file mode 100644
index 000000000..c3b0cea64
--- /dev/null
+++ b/0.9.0/404.html
@@ -0,0 +1,126 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 404
+ +Page not found
+ + +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/checking_migrations/index.html b/0.9.0/checking_migrations/index.html
new file mode 100644
index 000000000..f283bb11e
--- /dev/null
+++ b/0.9.0/checking_migrations/index.html
@@ -0,0 +1,159 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Linting Migrations
+Postgres Language Tools comes with a check command that can be integrated into your development workflow to catch problematic schema changes and encourage best practices.
To run it, simply point at your migrations directory.
+postgrestools check supabase/migrations
+When you are setting it up in an existing project, you might want to ignore all migrations that are already applied. To do so, add migrationsDir and after to your postgrestools.jsonc file
{
+ "migrations": {
+ "migrationsDir": "supabase/migrations",
+ "after": 1740868021
+ }
+}
+Alternatively, pass them directly.
+postgrestools check supabase/migrations --migrations-dir="supabase/migrations" --after=1740868021
+This will only check migrations after the specified timestamp.
+For pre-commit hooks and when working locally, use --staged to only lint files that have been staged. In CI environments, you most likely want to use --changed to only lint files that have been changed compared to your vcs.default_branch configuration. If default_branch is not set in your postgrestools.jsonc, use --since=REF to specify the base branch to compare against.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/cli_reference/index.html b/0.9.0/cli_reference/index.html
new file mode 100644
index 000000000..fdec28fc5
--- /dev/null
+++ b/0.9.0/cli_reference/index.html
@@ -0,0 +1,380 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ CLI Reference
+Command summary
+-
+
postgrestools↴
+postgrestools version↴
+postgrestools check↴
+postgrestools start↴
+postgrestools stop↴
+postgrestools init↴
+postgrestools lsp-proxy↴
+postgrestools clean↴
+
postgrestools
+PostgresTools official CLI. Use it to check the health of your project or run it to check single files.
+Usage: postgrestools COMMAND ...
Available options:
+-
+
-h,--help— + Prints help information
+-V,--version— + Prints version information
+
Available commands:
+-
+
version— + Shows the version information and quit.
+check— + Runs everything to the requested files.
+start— + Starts the daemon server process.
+stop— + Stops the daemon server process.
+init— + Bootstraps a new project. Creates a configuration file with some defaults.
+lsp-proxy— + Acts as a server for the Language Server Protocol over stdin/stdout.
+clean— + Cleans the logs emitted by the daemon.
+
postgrestools version
+Shows the version information and quit.
+Usage: postgrestools version
Global options applied to all commands
+-
+
--colors=<off|force>— + 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— + Connect to a running instance of the daemon server.
+--skip-db— + Skip connecting to the database and only run checks that don't require a database connection.
+--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— + Set the file path to the configuration file, or the directory path to findpostgrestools.jsonc. If used, it disables the default configuration file resolution.
+--max-diagnostics=<none|<NUMBER>>— + Cap the amount of diagnostics displayed. Whennoneis provided, the limit is lifted. + [default: 20]
+--skip-errors— + Skip over files containing syntax errors instead of emitting an error diagnostic.
+--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— + Tell Postgres Tools to exit with an error code if some diagnostics emit warnings.
+--reporter=<json|json-pretty|github|junit|summary|gitlab>— + Allows to change how diagnostics and summary are reported.
+--log-level=<none|debug|info|warn|error>— + 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=<pretty|compact|json>— + How the log should look like. + [default: pretty]
+--diagnostic-level=<info|warn|error>— + The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing--diagnostic-level=errorwill cause Postgres Tools to print only diagnostics that contain only errors. + [default: info]
+
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools check
+Runs everything to the requested files.
+Usage: postgrestools check [--staged] [--changed] [--since=REF] [PATH]...
The configuration that is contained inside the configuration file.
+-
+
--vcs-enabled=<true|false>— + Whether we should integrate itself with the VCS client
+--vcs-client-kind=<git>— + The kind of client.
+--vcs-use-ignore-file=<true|false>— + Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file.
+--vcs-root=PATH— + The folder where we should check for VCS files. By default, we will use the same folder wherepostgrestools.jsoncwas 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— + The main branch of the project
+--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— + The directory where the migration files are stored
+--after=ARG— + Ignore any migrations before this timestamp
+--host=ARG— + The host of the database.
+--port=ARG— + The port of the database.
+--username=ARG— + The username to connect to the database.
+--password=ARG— + The password to connect to the database.
+--database=ARG— + The name of the database.
+--conn_timeout_secs=ARG— + The connection timeout in seconds. + [default: Some(10)]
+
Global options applied to all commands
+-
+
--colors=<off|force>— + 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— + Connect to a running instance of the daemon server.
+--skip-db— + Skip connecting to the database and only run checks that don't require a database connection.
+--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— + Set the file path to the configuration file, or the directory path to findpostgrestools.jsonc. If used, it disables the default configuration file resolution.
+--max-diagnostics=<none|<NUMBER>>— + Cap the amount of diagnostics displayed. Whennoneis provided, the limit is lifted. + [default: 20]
+--skip-errors— + Skip over files containing syntax errors instead of emitting an error diagnostic.
+--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— + Tell Postgres Tools to exit with an error code if some diagnostics emit warnings.
+--reporter=<json|json-pretty|github|junit|summary|gitlab>— + Allows to change how diagnostics and summary are reported.
+--log-level=<none|debug|info|warn|error>— + 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=<pretty|compact|json>— + How the log should look like. + [default: pretty]
+--diagnostic-level=<info|warn|error>— + The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing--diagnostic-level=errorwill cause Postgres Tools to print only diagnostics that contain only errors. + [default: info]
+
Available positional items:
+-
+
PATH— + Single file, single path or list of paths
+
Available options:
+-
+
--stdin-file-path=PATH— + Use this option when you want to format code piped fromstdin, and print the output tostdout.
+
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— + 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— + When set to true, only the files that have been changed compared to yourdefaultBranchconfiguration will be linted. This option should be used in CI environments.
+--since=REF— + Use this to specify the base branch to compare against when you're using the --changed flag and thedefaultBranchis not set in yourpostgrestools.jsonc
+-h,--help— + Prints help information
+
postgrestools start
+Starts the daemon server process.
+Usage: postgrestools start [--config-path=PATH]
Available options:
+-
+
--log-prefix-name=STRING— + Allows to change the prefix applied to the file name of the logs. + Uses environment variablePGT_LOG_PREFIX_NAME+ [default: server.log]
+--log-path=PATH— + Allows to change the folder where logs are stored. + Uses environment variablePGT_LOG_PATH
+--config-path=PATH— + Allows to set a custom file path to the configuration file, or a custom directory path to findpostgrestools.jsonc+ Uses environment variablePGT_LOG_PREFIX_NAME
+-h,--help— + Prints help information
+
postgrestools stop
+Stops the daemon server process.
+Usage: postgrestools stop
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools init
+Bootstraps a new project. Creates a configuration file with some defaults.
+Usage: postgrestools init
Available options:
+-
+
-h,--help— + Prints help information
+
postgrestools lsp-proxy
+Acts as a server for the Language Server Protocol over stdin/stdout.
+Usage: postgrestools lsp-proxy [--config-path=PATH]
Available options:
+-
+
--log-prefix-name=STRING— + Allows to change the prefix applied to the file name of the logs. + Uses environment variablePGT_LOG_PREFIX_NAME+ [default: server.log]
+--log-path=PATH— + Allows to change the folder where logs are stored. + Uses environment variablePGT_LOG_PATH
+--config-path=PATH— + Allows to set a custom file path to the configuration file, or a custom directory path to findpostgrestools.jsonc+ Uses environment variablePGT_CONFIG_PATH
+-h,--help— + Prints help information
+
postgrestools clean
+Cleans the logs emitted by the daemon.
+Usage: postgrestools clean
Available options:
+-
+
-h,--help— + Prints help information
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/codegen/Cargo.toml b/0.9.0/codegen/Cargo.toml
new file mode 100644
index 000000000..96092a7a3
--- /dev/null
+++ b/0.9.0/codegen/Cargo.toml
@@ -0,0 +1,34 @@
+
+[package]
+authors.workspace = true
+categories.workspace = true
+description = "{rule_name}"
+ )?;
+ }
+ writeln!(content)?;
+ }
+
+ write_documentation(group, rule, meta.docs, &mut content)?;
+
+ write_how_to_configure(group, rule, &mut content)?;
+
+ Ok(String::from_utf8(content)?)
+}
+
+fn write_how_to_configure(
+ group: &'static str,
+ rule: &'static str,
+ content: &mut Vec")?; + } + + Event::Start(Tag::List(num)) => { + list_indentation += 1; + if let Some(num) = num { + list_order = Some(num); + } + if list_indentation > 1 { + writeln!(content)?; + } + } + + Event::End(TagEnd::List(_)) => { + list_order = None; + list_indentation -= 1; + writeln!(content)?; + } + Event::Start(Tag::Item) => { + write!(content, "{}", " ".repeat(list_indentation - 1))?; + if let Some(num) = list_order { + write!(content, "{num}. ")?; + } else { + write!(content, "- ")?; + } + } + + Event::End(TagEnd::Item) => { + list_order = list_order.map(|item| item + 1); + writeln!(content)?; + } + + Event::Start(Tag::Strong) => { + write!(content, "**")?; + } + + Event::End(TagEnd::Strong) => { + write!(content, "**")?; + } + + Event::Start(Tag::Emphasis) => { + write!(content, "_")?; + } + + Event::End(TagEnd::Emphasis) => { + write!(content, "_")?; + } + + Event::Start(Tag::Strikethrough) => { + write!(content, "~")?; + } + + Event::End(TagEnd::Strikethrough) => { + write!(content, "~")?; + } + + Event::Start(Tag::BlockQuote(_)) => { + write!(content, ">")?; + } + + Event::End(TagEnd::BlockQuote(_)) => { + writeln!(content)?; + } + + _ => { + bail!("unimplemented event {event:?}") + } + } + } + + Ok(()) +} + +struct CodeBlockTest { + /// The language tag of this code block. + tag: String, + + /// True if this is an invalid example that should trigger a diagnostic. + expect_diagnostic: bool, + + /// Whether to ignore this code block. + ignore: bool, + + /// The number of lines in this code block. + line_count: u32, + + // The indices of lines that should be hidden from the public documentation. + hidden_lines: Vec
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Environment Variables
+PGT_LOG_PATH
+The directory where the Daemon logs will be saved.
+PGT_LOG_PREFIX_NAME
+A prefix that's added to the name of the log. Default: server.log.
PGT_CONFIG_PATH
+A path to the configuration file
+ +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/images/cli-demo.png b/0.9.0/images/cli-demo.png
new file mode 100644
index 000000000..33bac595c
Binary files /dev/null and b/0.9.0/images/cli-demo.png differ
diff --git a/0.9.0/images/lsp-demo.gif b/0.9.0/images/lsp-demo.gif
new file mode 100644
index 000000000..7fbff05fd
Binary files /dev/null and b/0.9.0/images/lsp-demo.gif differ
diff --git a/0.9.0/images/pls-github.png b/0.9.0/images/pls-github.png
new file mode 100644
index 000000000..95ae73828
Binary files /dev/null and b/0.9.0/images/pls-github.png differ
diff --git a/0.9.0/img/favicon.ico b/0.9.0/img/favicon.ico
new file mode 100644
index 000000000..e85006a3c
Binary files /dev/null and b/0.9.0/img/favicon.ico differ
diff --git a/0.9.0/index.html b/0.9.0/index.html
new file mode 100644
index 000000000..06020a54e
--- /dev/null
+++ b/0.9.0/index.html
@@ -0,0 +1,290 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Postgres Tools
+A collection of language tools and a Language Server Protocol (LSP) implementation for Postgres, focusing on developer experience and reliable SQL tooling.
++
Source Code: https://github.com/supabase-community/postgres-language-server
++
Overview
+This project provides a toolchain for Postgres development
+Postgres Language Server
+
CLI Demo
+
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 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
EXPLAINerror insights)
+ - Linter, inspired by Squawk +
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 on GitHub and give it execution permission:
+curl -L https://github.com/supabase-community/postgres-language-server/releases/download/<version>/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.
npm add --save-dev --save-exact @postgrestools/postgrestools
+VSCode
+The language server is available on the VSCode Marketplace. It's published from this repo.
+Neovim
+You will have to install nvim-lspconfig, and follow the instructions.
Emacs
+The language client is available through lsp-mode. For more details, refer to their manual page.
+Zed
+The language server is available as an Extension. It's published from this repo.
+GitHub Actions
+To use the CLI in GitHub Actions, you can install it via our GitHub 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:
postgrestools init
+You’ll now have a postgrestools.jsonc file in your directory:
{
+ "$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/*"]
+ }
+}
+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.
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 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:
+postgrestools start
+Then, every command needs to add the --use-server options, e.g.:
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\<UserName>\AppData\Local\supabase-community\pgt\cache
+ - macOS:
/Users/<UserName>/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.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/js/html5shiv.min.js b/0.9.0/js/html5shiv.min.js
new file mode 100644
index 000000000..1a01c94ba
--- /dev/null
+++ b/0.9.0/js/html5shiv.min.js
@@ -0,0 +1,4 @@
+/**
+* @preserve HTML5 Shiv 3.7.3 | @afarkas @jdalton @jon_neal @rem | MIT/GPL2 Licensed
+*/
+!function(a,b){function c(a,b){var c=a.createElement("p"),d=a.getElementsByTagName("head")[0]||a.documentElement;return c.innerHTML="x",d.insertBefore(c.lastChild,d.firstChild)}function d(){var a=t.elements;return"string"==typeof a?a.split(" "):a}function e(a,b){var c=t.elements;"string"!=typeof c&&(c=c.join(" ")),"string"!=typeof a&&(a=a.join(" ")),t.elements=c+" "+a,j(b)}function f(a){var b=s[a[q]];return b||(b={},r++,a[q]=r,s[r]=b),b}function g(a,c,d){if(c||(c=b),l)return c.createElement(a);d||(d=f(c));var e;return e=d.cache[a]?d.cache[a].cloneNode():p.test(a)?(d.cache[a]=d.createElem(a)).cloneNode():d.createElem(a),!e.canHaveChildren||o.test(a)||e.tagUrn?e:d.frag.appendChild(e)}function h(a,c){if(a||(a=b),l)return a.createDocumentFragment();c=c||f(a);for(var e=c.frag.cloneNode(),g=0,h=d(),i=h.length;i>g;g++)e.createElement(h[g]);return e}function i(a,b){b.cache||(b.cache={},b.createElem=a.createElement,b.createFrag=a.createDocumentFragment,b.frag=b.createFrag()),a.createElement=function(c){return t.shivMethods?g(c,a,b):b.createElem(c)},a.createDocumentFragment=Function("h,f","return function(){var n=f.cloneNode(),c=n.createElement;h.shivMethods&&("+d().join().replace(/[\w\-:]+/g,function(a){return b.createElem(a),b.frag.createElement(a),'c("'+a+'")'})+");return n}")(t,b.frag)}function j(a){a||(a=b);var d=f(a);return!t.shivCSS||k||d.hasCSS||(d.hasCSS=!!c(a,"article,aside,dialog,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}mark{background:#FF0;color:#000}template{display:none}")),l||i(a,d),a}var k,l,m="3.7.3",n=a.html5||{},o=/^<|^(?:button|map|select|textarea|object|iframe|option|optgroup)$/i,p=/^(?:a|b|code|div|fieldset|h1|h2|h3|h4|h5|h6|i|label|li|ol|p|q|span|strong|style|table|tbody|td|th|tr|ul)$/i,q="_html5shiv",r=0,s={};!function(){try{var a=b.createElement("a");a.innerHTML="
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Exclusive rules
+Rules from other sources
+Squawk
+| Squawk Rule Name | +Rule Name | +
|---|---|
| adding-required-field | +addingRequiredField | +
| ban-drop-column | +banDropColumn | +
| ban-drop-database | +banDropDatabase | +
| ban-drop-not-null | +banDropNotNull | +
| ban-drop-table | +banDropTable | +
| ban-truncate-cascade | +banTruncateCascade | +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/rule_suppressions/index.html b/0.9.0/rule_suppressions/index.html
new file mode 100644
index 000000000..a7e553bf9
--- /dev/null
+++ b/0.9.0/rule_suppressions/index.html
@@ -0,0 +1,214 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rule 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.
+How to Suppress a Rule
+To suppress a rule, add a comment above the line causing the diagnostic with the following format:
+-- pgt-ignore lint/safety/banDropTable
+drop table users;
+You can suppress single rules, groups of rules, or entire categories. The format of the rule to suppress is:
+category(/group(/specific-rule))
Where group and specific rule are optional.
+So, to suppress the lint/safety/banDropTable diagnostic, all of these would work:
-- pgt-ignore lint
+-- pgt-ignore lint/safety
+-- pgt-ignore lint/safety/banDropTable
+You can also add an explanation to the suppression by adding a : and the explanation text:
-- pgt-ignore lint/safety/banDropTable: My startup never had any users.
+drop table users;
+Suppressing Rules for Block of Code
+You can suppress rules for blocks of code.
+create table users (
+ -- ...
+);
+
+-- pgt-ignore-start typecheck: The `users` table will be created with this migration.
+alter table users drop constraint users_pkey;
+
+alter table users add primary key (user_id);
+-- pgt-ignore-end typecheck
+Every pgt-ignore-start needs a pgt-ignore-end suppression comment, and the suppressed rules must match exactly.
This won't work, because the start tag suppresses a different diagnostic:
+-- pgt-ignore-start lint/safety/banDropColumn
+-- pgt-ignore-end lint/safety
+Nesting is allowed, so this works fine:
+-- pgt-ignore-start typecheck: outer
+-- pgt-ignore-start lint/safety: inner
+-- pgt-ignore-end lint/safety: inner
+-- pgt-ignore-end typecheck: outer
+Suppressing Rules for Entire Files
+Instead of repeating the same suppression on multiple lines, you can suppress for an entire file.
+-- pgt-ignore-all lint/safety/banDropTable
+
+drop table tasks;
+drop table projects;
+drop table users;
+Suppressing Multiple Rules
+You can suppress multiple rules by adding multiple suppression comments above a statement:
+-- pgt-ignore lint/safety/banDropColumn
+-- pgt-ignore typecheck
+alter table tasks drop column created_at;
+Notes
+-
+
- Trying to suppress diagnostics that have already been disabled in your configuration file will show a warning. +
- Trying to suppress diagnostics that don't haven't been raised will also show a warning. +
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/rules/adding-required-field/index.html b/0.9.0/rules/adding-required-field/index.html
new file mode 100644
index 000000000..a4696983c
--- /dev/null
+++ b/0.9.0/rules/adding-required-field/index.html
@@ -0,0 +1,157 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ addingRequiredField
+Diagnostic Category: lint/safety/addingRequiredField
Since: vnext
Sources:
+- Inspired from: squawk/adding-required-field
Description
+Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required.
+This will fail immediately upon running for any populated table. Furthermore, old application code that is unaware of this column will fail to INSERT to this table.
+Make new columns optional initially by omitting the NOT NULL constraint until all existing data and application code has been updated. Once no NULL values are written to or persisted in the database, set it to NOT NULL. +Alternatively, if using Postgres version 11 or later, add a DEFAULT value that is not volatile. This allows the column to keep its NOT NULL constraint.
+Invalid
+alter table test add column count int not null;
+Valid in Postgres >= 11
+alter table test add column count int not null default 0;
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "addingRequiredField": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/rules/ban-drop-column/index.html b/0.9.0/rules/ban-drop-column/index.html
new file mode 100644
index 000000000..b503b6330
--- /dev/null
+++ b/0.9.0/rules/ban-drop-column/index.html
@@ -0,0 +1,168 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropColumn
+Diagnostic Category: lint/safety/banDropColumn
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-column
Description
+Dropping a column may break existing clients.
+Update your application code to no longer read or write the column.
+You can leave the column as nullable or delete the column once queries no longer select or modify the column.
+Examples
+Invalid
+alter table test drop column id;
+code-block.sql lint/safety/banDropColumn ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a column may break existing clients.
+
+ i You can leave the column as nullable or delete the column once queries no longer select or modify the column.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropColumn": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/rules/ban-drop-database/index.html b/0.9.0/rules/ban-drop-database/index.html
new file mode 100644
index 000000000..40da75d56
--- /dev/null
+++ b/0.9.0/rules/ban-drop-database/index.html
@@ -0,0 +1,151 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropDatabase
+Diagnostic Category: lint/safety/banDropDatabase
Since: vnext
Sources:
+- Inspired from: squawk/ban-drop-database
Description
+Dropping a database may break existing clients (and everything else, really).
+Make sure that you really want to drop it.
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropDatabase": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/rules/ban-drop-not-null/index.html b/0.9.0/rules/ban-drop-not-null/index.html
new file mode 100644
index 000000000..d59f2f956
--- /dev/null
+++ b/0.9.0/rules/ban-drop-not-null/index.html
@@ -0,0 +1,168 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropNotNull
+Diagnostic Category: lint/safety/banDropNotNull
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-not-null
Description
+Dropping a NOT NULL constraint may break existing clients.
+Application code or code written in procedural languages like PL/SQL or PL/pgSQL may not expect NULL values for the column that was previously guaranteed to be NOT NULL and therefore may fail to process them correctly.
+You can consider using a marker value that represents NULL. Alternatively, create a new table allowing NULL values, copy the data from the old table, and create a view that filters NULL values.
+Examples
+Invalid
+alter table users alter column email drop not null;
+code-block.sql lint/safety/banDropNotNull ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a NOT NULL constraint may break existing clients.
+
+ i Consider using a marker value that represents NULL. Alternatively, create a new table allowing NULL values, copy the data from the old table, and create a view that filters NULL values.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropNotNull": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/rules/ban-drop-table/index.html b/0.9.0/rules/ban-drop-table/index.html
new file mode 100644
index 000000000..aafc31ada
--- /dev/null
+++ b/0.9.0/rules/ban-drop-table/index.html
@@ -0,0 +1,169 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banDropTable
+Diagnostic Category: lint/safety/banDropTable
Since: vnext
+
+Note
+This rule is recommended. A diagnostic error will appear when linting your code.
+Sources:
+- Inspired from: squawk/ban-drop-table
Description
+Dropping a table may break existing clients.
+Update your application code to no longer read or write the table.
+Once the table is no longer needed, you can delete it by running the command "DROP TABLE mytable;".
+This command will permanently remove the table from the database and all its contents. +Be sure to back up the table before deleting it, just in case you need to restore it in the future.
+Examples
+drop table some_table;
+code-block.sql lint/safety/banDropTable ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ! Dropping a table may break existing clients.
+
+ i Update your application code to no longer read or write the table, and only then delete the table. Be sure to create a backup.
+
+
+How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banDropTable": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/rules/ban-truncate-cascade/index.html b/0.9.0/rules/ban-truncate-cascade/index.html
new file mode 100644
index 000000000..e8f1068ad
--- /dev/null
+++ b/0.9.0/rules/ban-truncate-cascade/index.html
@@ -0,0 +1,157 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ banTruncateCascade
+Diagnostic Category: lint/safety/banTruncateCascade
Since: vnext
Sources:
+- Inspired from: squawk/ban-truncate-cascade
Description
+Using TRUNCATE's CASCADE option will truncate any tables that are also foreign-keyed to the specified tables.
So if you had tables with foreign-keys like:
+a <- b <- c
and ran:
+truncate a cascade;
You'd end up with a, b, & c all being truncated!
+Instead, you can manually specify the tables you want.
+truncate a, b;
How to configure
+
+{
+ "linter": {
+ "rules": {
+ "safety": {
+ "banTruncateCascade": "error"
+ }
+ }
+ }
+}
+
+
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/rules/index.html b/0.9.0/rules/index.html
new file mode 100644
index 000000000..0b3a93672
--- /dev/null
+++ b/0.9.0/rules/index.html
@@ -0,0 +1,191 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rules
+Below the list of rules supported by Postgres Language Tools, divided by group. Here's a legend of the emojis:
+-
+
- The icon ✅ indicates that the rule is part of the recommended rules. +
Safety
+Rules that detect potential safety issues in your code.
+| Rule name | +Description | +Properties | +
|---|---|---|
| addingRequiredField | +Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required. | ++ |
| banDropColumn | +Dropping a column may break existing clients. | +✅ | +
| banDropDatabase | +Dropping a database may break existing clients (and everything else, really). | ++ |
| banDropNotNull | +Dropping a NOT NULL constraint may break existing clients. | +✅ | +
| banDropTable | +Dropping a table may break existing clients. | +✅ | +
| banTruncateCascade | +Using TRUNCATE's CASCADE option will truncate any tables that are also foreign-keyed to the specified tables. |
++ |
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/0.9.0/schema.json b/0.9.0/schema.json
new file mode 100644
index 000000000..1c56618ed
--- /dev/null
+++ b/0.9.0/schema.json
@@ -0,0 +1,471 @@
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "Configuration",
+ "description": "The configuration that is contained inside the configuration file.",
+ "type": "object",
+ "properties": {
+ "$schema": {
+ "description": "A field for the [JSON schema](https://json-schema.org/) specification",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "db": {
+ "description": "The configuration of the database connection",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/DatabaseConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "extends": {
+ "description": "A list of paths to other JSON files, used to extends the current configuration.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "files": {
+ "description": "The configuration of the filesystem",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/FilesConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "linter": {
+ "description": "The configuration for the linter",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/LinterConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "migrations": {
+ "description": "Configure migrations",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/MigrationsConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "vcs": {
+ "description": "The configuration of the VCS integration",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/VcsConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false,
+ "definitions": {
+ "DatabaseConfiguration": {
+ "description": "The configuration of the database connection.",
+ "type": "object",
+ "properties": {
+ "allowStatementExecutionsAgainst": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "connTimeoutSecs": {
+ "description": "The connection timeout in seconds.",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint16",
+ "minimum": 0.0
+ },
+ "database": {
+ "description": "The name of the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "host": {
+ "description": "The host of the database. Required if you want database-related features. All else falls back to sensible defaults.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "password": {
+ "description": "The password to connect to the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "port": {
+ "description": "The port of the database.",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint16",
+ "minimum": 0.0
+ },
+ "username": {
+ "description": "The username to connect to the database.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "FilesConfiguration": {
+ "description": "The configuration of the filesystem",
+ "type": "object",
+ "properties": {
+ "ignore": {
+ "description": "A list of Unix shell style patterns. Will ignore files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "include": {
+ "description": "A list of Unix shell style patterns. Will handle only those files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "maxSize": {
+ "description": "The maximum allowed size for source code files in bytes. Files above this limit will be ignored for performance reasons. Defaults to 1 MiB",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint64",
+ "minimum": 1.0
+ }
+ },
+ "additionalProperties": false
+ },
+ "LinterConfiguration": {
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "description": "if `false`, it disables the feature and the linter won't be executed. `true` by default",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "ignore": {
+ "description": "A list of Unix shell style patterns. The formatter will ignore files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "include": {
+ "description": "A list of Unix shell style patterns. The formatter will include files/folders that will match these patterns.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/StringSet"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "rules": {
+ "description": "List of rules",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/Rules"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "MigrationsConfiguration": {
+ "description": "The configuration of the filesystem",
+ "type": "object",
+ "properties": {
+ "after": {
+ "description": "Ignore any migrations before this timestamp",
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "uint64",
+ "minimum": 0.0
+ },
+ "migrationsDir": {
+ "description": "The directory where the migration files are stored",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "RuleConfiguration": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RulePlainConfiguration"
+ },
+ {
+ "$ref": "#/definitions/RuleWithNoOptions"
+ }
+ ]
+ },
+ "RulePlainConfiguration": {
+ "type": "string",
+ "enum": [
+ "warn",
+ "error",
+ "info",
+ "off"
+ ]
+ },
+ "RuleWithNoOptions": {
+ "type": "object",
+ "required": [
+ "level"
+ ],
+ "properties": {
+ "level": {
+ "description": "The severity of the emitted diagnostics by the rule",
+ "allOf": [
+ {
+ "$ref": "#/definitions/RulePlainConfiguration"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "Rules": {
+ "type": "object",
+ "properties": {
+ "all": {
+ "description": "It enables ALL rules. The rules that belong to `nursery` won't be enabled.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "recommended": {
+ "description": "It enables the lint rules recommended by Postgres Tools. `true` by default.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "safety": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/Safety"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "Safety": {
+ "description": "A list of rules that belong to this group",
+ "type": "object",
+ "properties": {
+ "addingRequiredField": {
+ "description": "Adding a new column that is NOT NULL and has no default value to an existing table effectively makes it required.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "all": {
+ "description": "It enables ALL rules for this group.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "banDropColumn": {
+ "description": "Dropping a column may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropDatabase": {
+ "description": "Dropping a database may break existing clients (and everything else, really).",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropNotNull": {
+ "description": "Dropping a NOT NULL constraint may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banDropTable": {
+ "description": "Dropping a table may break existing clients.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "banTruncateCascade": {
+ "description": "Using TRUNCATE's CASCADE option will truncate any tables that are also foreign-keyed to the specified tables.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/RuleConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "recommended": {
+ "description": "It enables the recommended rules for this group",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ },
+ "StringSet": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "uniqueItems": true
+ },
+ "VcsClientKind": {
+ "oneOf": [
+ {
+ "description": "Integration with the git client as VCS",
+ "type": "string",
+ "enum": [
+ "git"
+ ]
+ }
+ ]
+ },
+ "VcsConfiguration": {
+ "description": "Set of properties to integrate with a VCS software.",
+ "type": "object",
+ "properties": {
+ "clientKind": {
+ "description": "The kind of client.",
+ "anyOf": [
+ {
+ "$ref": "#/definitions/VcsClientKind"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "defaultBranch": {
+ "description": "The main branch of the project",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "enabled": {
+ "description": "Whether we should integrate itself with the VCS client",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "root": {
+ "description": "The folder where we should check for VCS files. By default, we will use the same folder where `postgrestools.jsonc` was found.\n\nIf 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",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "useIgnoreFile": {
+ "description": "Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "additionalProperties": false
+ }
+ }
+}
\ No newline at end of file
diff --git a/0.9.0/sitemap.xml b/0.9.0/sitemap.xml
new file mode 100644
index 000000000..f43c31661
--- /dev/null
+++ b/0.9.0/sitemap.xml
@@ -0,0 +1,59 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+ supabase-community/postgres-language-server
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
deleted file mode 100644
index 5a10be2d5..000000000
--- a/ARCHITECTURE.md
+++ /dev/null
@@ -1,71 +0,0 @@
-## Architecture
-
-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.
-
-### Bird's Eye View
-
-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.
-
-### Entry Points
-
-The main entry point is as of now the `pg_lsp` crate, especially the `main.rs` function. It spawns the language server and starts listening for incoming messages. The server is implemented in the `server` module.
-
-There might be an additional entry point for a CLI tool in the future.
-
-### Code Map
-
-This section talks briefly about various important directories and data structures.
-
-#### `lib/`
-
-Independent libraries that are used by the project but are not specific for postgres.
-
-#### `crates/pg_lsp`
-
-The main entry point of the language server. It contains the server implementation and the main loop.
-
-#### `crates/pg_workspace`
-
-> This crate will grow significantly in near future. The current implementation just contains the base data structures and stores the diagnostic results from various features.
-
-The main API for consumers of the IDE. It stores the internal state of the workspace, such as the schema cache and the parsed statements and their analysis.
-
-#### `crates/pg_lexer`
-
-Simple lexer that tokenizes the input source code. Enhances the output of the `pg_query` tokenizer with the missing whitespace tokens.
-
-#### `crates/pg_statement_splitter`
-
-Implements the statement splitter, which cuts the input source code into individual statements.
-
-#### `crates/pg_base_db`
-
-Implements the base data structures and defines how documents and statements are stored and updated efficiently.
-
-#### `crates/pg_schema_cache`
-
-We store an in-memory representation of the database schema to efficiently resolve types.
-
-#### `crates/pg_query_ext`
-
-Simple wrapper crate for `pg_query` to expose types and a function to get the root node for an SQL statement. It also host any "extensions" to the `pg_query` crate that are not yet contributed upstream. Once all extensions are contributed upstream, this crate will be removed.
-
-#### `crates/pg_query_proto_parser`
-
-We use procedural macros a lot to generate repetitive code from the protobuf definition provided by `libg_query`. The `pg_query_proto_parser` crate is used to parse the proto file into a more usable data structure.
-
-#### `crates/pg_syntax`
-
-Implements the CST parser and AST enhancer. The CST parser is what is described in [this blog post](https://supabase.com/blog/postgres-language-server-implementing-parser). The AST enhancer takes in the CST and enriches the AST returned by `pg_query` with a range for each node.
-
-#### `crates/pg_type_resolver`
-
-Utility crate used by the feature crates listed below to resolve the source types to the actual types in the schema cache.
-
-#### `crates/pg_commands`, `crates/pg_completions`, `crates/pg_hover`, `crates/pg_inlay_hints`, `crates/pg_lint`, `crates/pg_typecheck`
-
-These crates implement the various features of the language server. They are all independent of each other and always operate on the schema cache and a single statement and its parse results. They are intentionally implemented in separate creates and without any language server flavour to make them reusable eg in a later cli.
diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index 057163a94..000000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1,155 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-This is a Postgres Language Server implementation providing LSP features for SQL development, including autocompletion, syntax error highlighting, type-checking, and linting. The project is built in Rust using a modular crate architecture and includes TypeScript packages for editor integrations.
-
-## Key Commands
-
-### Development Setup
-```bash
-# Install development tools
-just install-tools
-
-# Start database for schema introspection
-docker-compose up -d
-
-# For Nix users
-nix develop && docker-compose up -d
-```
-
-### Building and Testing
-```bash
-# Run all tests
-just test
-# or: cargo test run --no-fail-fast
-
-# Test specific crate
-just test-crate pgt_lsp
-
-# Run doc tests
-just test-doc
-```
-
-### Code Quality
-```bash
-# Format all code (Rust, TOML, JS/TS)
-just format
-
-# Lint entire codebase
-just lint
-# or: cargo clippy && cargo run -p rules_check && bun biome lint
-
-# Fix linting issues
-just lint-fix
-
-# Full ready check (run before committing)
-just ready
-```
-
-### Code Generation
-```bash
-# Generate linter code and configuration
-just gen-lint
-
-# Create new lint rule
-just new-lintrule