Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 4e2cafd

Browse files
chore: rewrite docs (#491)
I think this is best reviewed locally via `just serve-docs`. its time to improve here... will rewrite the documentation based on the new structure over the next days. the goal is to show the features we support better. right now, they are hidden in the main index page. will add example gifs etc to the feature pages too. progress - [x] index - [x] getting started - [x] manual installation - [x] configuration - [x] features/editor_features - [x] features/linting - [x] features/plpgsql - [x] features/syntax_diagnostics - [x] features/type_checking - [x] guides/check_migrations - [x] guides/configure_databases - [x] guides/continuous_integration - [x] guides/ide_setup - [x] guides/suppressions - [x] guides/vcs_integration - [x] reference/cli - [x] reference/env_variables - [x] reference/rules
1 parent e58e564 commit 4e2cafd

34 files changed

+862
-275
lines changed

‎docs/codegen/src/cli_doc.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ use std::{fs, path::Path};
44
use crate::utils;
55

66
pub fn generate_cli_doc(docs_dir: &Path) -> anyhow::Result<()> {
7-
let file_path = docs_dir.join("cli_reference.md");
7+
let file_path = docs_dir.join("reference/cli.md");
88

99
let content = fs::read_to_string(&file_path)?;
1010

‎docs/codegen/src/default_configuration.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ use crate::utils::replace_section;
55
use pgt_configuration::PartialConfiguration;
66

77
pub fn generate_default_configuration(docs_dir: &Path) -> anyhow::Result<()> {
8-
let index_path = docs_dir.join("index.md");
8+
let index_path = docs_dir.join("getting_started.md");
99

1010
let printed_config = format!(
1111
"\n```json\n{}\n```\n",

‎docs/codegen/src/env_variables.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ use std::path::Path;
66
use crate::utils::replace_section;
77

88
pub fn generate_env_variables(docs_dir: &Path) -> Result<()> {
9-
let file_path = docs_dir.join("env_variables.md");
9+
let file_path = docs_dir.join("reference/env_variables.md");
1010

1111
let mut content = vec![];
1212

‎docs/codegen/src/rules_docs.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ use std::{
2020
///
2121
/// * `docs_dir`: Path to the docs directory.
2222
pub fn generate_rules_docs(docs_dir: &Path) -> anyhow::Result<()> {
23-
let rules_dir = docs_dir.join("rules");
23+
let rules_dir = docs_dir.join("reference/rules");
2424

2525
if rules_dir.exists() {
2626
fs::remove_dir_all(&rules_dir)?;

‎docs/codegen/src/rules_index.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ use crate::utils;
1717
///
1818
/// * `docs_dir`: Path to the docs directory.
1919
pub fn generate_rules_index(docs_dir: &Path) -> anyhow::Result<()> {
20-
let index_file = docs_dir.join("rules.md");
20+
let index_file = docs_dir.join("reference/rules.md");
2121

2222
let mut visitor = crate::utils::LintRulesVisitor::default();
2323
pgt_analyser::visit_registry(&mut visitor);

‎docs/codegen/src/rules_sources.rs

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ impl PartialOrd for SourceSet {
2828
}
2929

3030
pub fn generate_rule_sources(docs_dir: &Path) -> anyhow::Result<()> {
31-
let rule_sources_file = docs_dir.join("rule_sources.md");
31+
let rule_sources_file = docs_dir.join("reference/rule_sources.md");
3232

3333
let mut visitor = crate::utils::LintRulesVisitor::default();
3434
pgt_analyser::visit_registry(&mut visitor);
@@ -69,7 +69,16 @@ pub fn generate_rule_sources(docs_dir: &Path) -> anyhow::Result<()> {
6969
}
7070
}
7171

72+
writeln!(buffer, "# Rule Sources",)?;
73+
writeln!(
74+
buffer,
75+
"Many rules are inspired by or directly ported from other tools. This page lists the sources of each rule.",
76+
)?;
77+
7278
writeln!(buffer, "## Exclusive rules",)?;
79+
if exclusive_rules.is_empty() {
80+
writeln!(buffer, "_No exclusive rules available._")?;
81+
}
7382
for (rule, link) in exclusive_rules {
7483
writeln!(buffer, "- [{rule}]({link}) ")?;
7584
}

‎docs/configuration.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Configuration
2+
3+
This guide will help you to understand how to configure the Postgres Language Server. It explains the structure of the configuration file and how the configuration is resolved.
4+
5+
The Postgres Language Server allows you to customize its behavior using CLI options or a configuration file named `postgrestools.jsonc`. We recommend that you create a configuration file for each project. This ensures that each team member has the same configuration in the CLI and in any editor that allows Biome integration. Many of the options available in a configuration file are also available in the CLI.
6+
7+
## Configuration file structure
8+
9+
A configuration file is usually placed in your project’s root folder. It is organized around the tools that are provided. All tools are enabled by default, but some require additional setup like a database connection or the `plpgsql_check` extension.
10+
11+
```json
12+
{
13+
"$schema": "https://pgtools.dev/latest/schema.json",
14+
"linter": {
15+
"enabled": true,
16+
"rules": {
17+
"recommended": true
18+
}
19+
},
20+
"typecheck": {
21+
"enabled": true
22+
}
23+
"plpgsqlCheck": {
24+
"enabled" : true
25+
}
26+
}
27+
```
28+
29+
## Configuring a database connection
30+
31+
Some tools that the Postgres Language Server provides are implemented as mere interfaces on top of functionality that is provided by the database itself. This ensures correctness, but requires an active connection to a Postgres database. We strongly recommend to only connect to a local development database.
32+
33+
```json
34+
{
35+
"$schema": "https://pgtools.dev/latest/schema.json",
36+
"db": {
37+
"host": "127.0.0.1",
38+
"port": 5432,
39+
"username": "postgres",
40+
"password": "postgres",
41+
"database": "postgres",
42+
"connTimeoutSecs": 10,
43+
"allowStatementExecutionsAgainst": ["127.0.0.1/*", "localhost/*"]
44+
}
45+
}
46+
```
47+
48+
49+
## Specifying files to process
50+
51+
You can control the files/folders to process using different strategies, either CLI, configuration and VCS.
52+
53+
### Include files via CLI
54+
The first way to control which files and folders are processed is to list them in the CLI. In the following command, we only check `file1.sql` and all the files in the `src` folder, because folders are recursively traversed.
55+
56+
```shell
57+
postgrestools check file1.js src/
58+
```
59+
60+
### Control files via configuration
61+
62+
The configuration file can be used to refine which files are processed. You can explicitly list the files to be processed using the `files.includes` field. `files.includes` accepts glob patterns such as sql/**/*.sql. Negated patterns starting with `!` can be used to exclude files.
63+
64+
Paths and globs inside the configuration file are resolved relative to the folder the configuration file is in. An exception to this is when a configuration file is extended by another.
65+
66+
#### Include files via configuration
67+
Let’s take the following configuration, where we want to include only SQL files (`.sql`) that are inside the `sql/` folder:
68+
69+
```json
70+
{
71+
"files": {
72+
"includes": ["sql/**/*.sql"]
73+
}
74+
}
75+
```
76+
77+
#### Exclude files via configuration
78+
If you want to exclude files and folders from being processed, you can use the `files.ignore` .
79+
80+
In the following example, we include all files, except those in any test/ folder:
81+
82+
```json
83+
{
84+
"files": {
85+
"ignore": [
86+
"**/test",
87+
]
88+
}
89+
}
90+
```
91+
92+
#### Control files via VCS
93+
You can ignore files ignored by your [VCS](/guides/vcs_integration.md).
94+
95+
96+

‎docs/features/editor_features.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Autocompletion & Hover
2+
3+
The language server provides autocompletion and hover information when connected to a database.
4+
5+
## Autocompletion
6+
7+
As you type SQL, the language server suggests relevant database objects based on your current context:
8+
9+
- **Tables**: Available tables from your database schema
10+
- **Columns**: Columns from tables referenced in your query
11+
- **Functions**: Database functions and procedures
12+
- **Schemas**: Available schemas in your database
13+
- **Keywords**: SQL keywords and syntax
14+
15+
The suggestions are context-aware - for example, when typing after `FROM`, you'll see table suggestions, and when typing after `SELECT`, you'll see column suggestions from relevant tables.
16+
17+
## Hover Information
18+
19+
Hovering over database objects in your SQL shows detailed information:
20+
21+
- **Tables**: Schema, column list with data types
22+
- **Columns**: Data type, nullable status, table location
23+
- **Functions**: Return type, parameter information
24+
25+
The hover information is pulled from your database schema.
26+
27+
## Requirements
28+
29+
Both features require:
30+
- A configured database connection
31+
- The language server must be able to read schema information from your database
32+
33+
Without a database connection, these features are not available.
34+
35+
## Configuration
36+
37+
These features work automatically when you have a database connection configured. See the [database configuration guide](../guides/configure_database.md) for setup instructions.
38+
39+
The language server caches schema information on startup.

‎docs/features/linting.md

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Linting
2+
3+
The language server provides static analysis through linting rules that detect potential issues in your SQL code. The linter analyses SQL statements for safety issues, best practices violations, and problems that could break existing applications.
4+
5+
## Rules
6+
7+
Rules are organized into categories like Safety, Performance, and Style. Each rule can be configured individually or disabled entirely.
8+
9+
See the [Rules Reference](../reference/rules.md) for the complete list of available rules and their descriptions.
10+
11+
## Configuration
12+
13+
Configure linting behavior in your `postgrestools.jsonc`:
14+
15+
```json
16+
{
17+
"linter": {
18+
// Enable/disable the linter entirely
19+
"enabled": true,
20+
"rules": {
21+
// Configure rule groups
22+
"safety": {
23+
// Individual rule configuration
24+
"banDropColumn": "error", // error, warn, info, hint, off
25+
"banDropTable": "warn",
26+
"addingRequiredField": "off"
27+
}
28+
}
29+
}
30+
}
31+
```
32+
33+
## Suppressing Diagnostics
34+
35+
You can suppress specific diagnostics using comments:
36+
37+
```sql
38+
-- pgt-ignore-next-line safety/banDropColumn: Intentionally dropping deprecated column
39+
ALTER TABLE users DROP COLUMN deprecated_field;
40+
41+
-- pgt-ignore safety/banDropTable: Cleanup during migration
42+
DROP TABLE temp_migration_table;
43+
```
44+
45+
For more details on suppressions check out [our guide]('../guides/suppressions.md').
46+
47+
## Schema-Aware Analysis
48+
49+
Some rules require a database connection to perform schema-aware analysis. If no connection is configured, they are skipped.
50+
51+
## CLI Usage
52+
53+
The linter can also be used via the CLI for CI integration:
54+
55+
```bash
56+
# Lint specific files
57+
postgrestools check migrations/
58+
59+
# With specific rules
60+
postgrestools check migrations/ --only safety/banDropColumn
61+
62+
# Skip certain rules
63+
postgrestools check migrations/ --skip safety/banDropTable
64+
```
65+
66+
See the [CLI Reference](../reference/cli.md) for more options, and check the guide on [linting migrations]('../guides/checking_migrations.md').

‎docs/features/plpgsql.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# PL/pgSQL Support
2+
3+
The Postgres Language Server partially supports `PL/pgSQL`. By default, use `libpg_query` to parse the function body and show any syntax error. This is a great way to quickly reduce the feedback loop when developing. Unfortunately, the reported errors do not contain any location information and we always report an error on the entire function body.
4+
5+
To get more sophisticated and fine-grained errors, we strongly recommend to enable the [`plpgsql_check`](https://github.com/okbob/plpgsql_check) extension in your development database.
6+
7+
```sql
8+
CREATE EXTENSION IF NOT EXISTS plpgsql_check;
9+
```
10+
11+
The language server will automatically detect the extension and start forwarding its reports as diagnostics.
12+
13+
For any `CREATE FUNCTION` statement with the language `PL/pgSQL`, the following process occurs:
14+
15+
1. The language server creates the function in a temporary transaction
16+
2. Calls `plpgsql_check_function()` to perform comprehensive static analysis of the function body
17+
3. For trigger functions, the analysis runs against each table that has triggers using this function, providing context-specific validation
18+
4. Errors are mapped back to source locations with token-level precision
19+
20+
The integration provides more detailed and actionable feedback compared to basic syntax checking, including:
21+
22+
> - checks fields of referenced database objects and types inside embedded SQL
23+
> - validates you are using the correct types for function parameters
24+
> - identifies unused variables and function arguments, unmodified OUT arguments
25+
> - partial detection of dead code (code after an RETURN command)
26+
> - detection of missing RETURN command in function (common after exception handlers, complex logic)
27+
> - tries to identify unwanted hidden casts, which can be a performance issue like unused indexes
28+
> - ability to collect relations and functions used by function
29+
> - ability to check EXECUTE statements against SQL injection vulnerability
30+
31+
You can always disable the integration if you do not want the language server to hit your development database.
32+
33+
```json
34+
{
35+
"plpqsqlCheck": {
36+
"enabled": false
37+
}
38+
}
39+
```
40+

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /