mirror of
https://github.com/t8y2/dbx.git
synced 2026-11-06 08:44:32 +08:00
114 lines
4.3 KiB
Plaintext
114 lines
4.3 KiB
Plaintext
---
|
|
title: SQL Formatting
|
|
description: Format a selection or the full editor with database-aware syntax, then manage the current formatter options and JSON config.
|
|
---
|
|
|
|
DBX chooses a formatter dialect from the active connection and writes the result back to the query editor. When text is selected, only that range is formatted; otherwise DBX formats the entire editor.
|
|
|
|
Use the **Format SQL** toolbar button or the configurable formatting command documented under [Keyboard Shortcuts](/en/docs/keyboard-shortcuts).
|
|
|
|
<Callout type="info">
|
|
Formatting only rewrites text and never executes SQL. Unsupported syntax returns an error and leaves the original text unchanged. One formatting operation accepts at most `1,000,000` characters.
|
|
</Callout>
|
|
|
|
## Dialect Selection
|
|
|
|
DBX currently uses dedicated formatter grammars for:
|
|
|
|
| Connection type | Formatter dialect |
|
|
| --- | --- |
|
|
| MySQL | MySQL |
|
|
| PostgreSQL, openGauss, GaussDB, KingbaseES, Redshift, and related profiles | PostgreSQL |
|
|
| SQLite, Turso, rqlite, and Cloudflare D1 | SQLite |
|
|
| SQL Server | Transact-SQL |
|
|
| ClickHouse | ClickHouse |
|
|
| Other SQL databases | Generic SQL, with one PostgreSQL-grammar retry when needed |
|
|
|
|
The MongoDB query editor uses a separate Mongo Shell formatter rather than this SQL dialect mapping.
|
|
|
|
## Configure Formatting Options
|
|
|
|
Open **Settings → SQL Formatter**. Form mode exposes:
|
|
|
|
| Option | Values or behavior |
|
|
| --- | --- |
|
|
| Keyword, data type, function, and identifier case | `upper`, `lower`, or `preserve` |
|
|
| Indent style | `standard`, `tabularLeft`, or `tabularRight` |
|
|
| Indentation | Spaces or tabs |
|
|
| Tab width | `2` or `4` |
|
|
| Logical operator newline | Before or after the operator |
|
|
| Expression width | `50`, `80`, or `120` |
|
|
| Lines between queries | `0`, `1`, or `2` |
|
|
| Dense operators | Reduces spaces around operators |
|
|
| Newline before semicolon | Places a statement-ending semicolon on a new line |
|
|
| Parameter types | Recognizes positional, numbered, named, quoted, or custom-regex parameters |
|
|
|
|
**Restore Defaults** restores the formatter settings defined by the current DBX build. Click **Apply** in the settings dialog to persist changes.
|
|
|
|
## JSON Mode and Import / Export
|
|
|
|
JSON mode is useful for exact editing, copying, or moving formatter settings. The current file contains only `version`, `formatter`, and `options`:
|
|
|
|
```json
|
|
{
|
|
"version": 1,
|
|
"formatter": "sql-formatter",
|
|
"options": {
|
|
"keywordCase": "upper",
|
|
"dataTypeCase": "preserve",
|
|
"functionCase": "preserve",
|
|
"identifierCase": "preserve",
|
|
"indentStyle": "standard",
|
|
"useTabs": false,
|
|
"tabWidth": 2,
|
|
"logicalOperatorNewline": "before",
|
|
"expressionWidth": 50,
|
|
"linesBetweenQueries": 1,
|
|
"denseOperators": false,
|
|
"newlineBeforeSemicolon": false,
|
|
"paramTypes": null
|
|
}
|
|
}
|
|
```
|
|
|
|
The JSON editor validates the draft continuously. DBX blocks apply or import when:
|
|
|
|
- the text is not valid JSON;
|
|
- `version` is not `1`;
|
|
- `formatter` is not `sql-formatter`;
|
|
- `options` contains an unknown field; or
|
|
- a value is outside the range accepted by the current build.
|
|
|
|
**Export Config** downloads `dbx-sql-formatter.json`. Import replaces only SQL formatter options; it does not change connections, editor shortcuts, or other DBX settings. Use [Configuration Cloud Sync](/en/docs/cloud-sync) when you need a broader settings migration.
|
|
|
|
## Parameter Recognition
|
|
|
|
Set `paramTypes` to `null` to use the formatter defaults. Configure additional parameter syntax with an object such as:
|
|
|
|
```json
|
|
{
|
|
"positional": true,
|
|
"numbered": ["?", "$"],
|
|
"named": [":", "@", "$"],
|
|
"quoted": [":", "@", "$"],
|
|
"custom": [
|
|
{ "regex": "@\\{[^}]+\\}" }
|
|
]
|
|
}
|
|
```
|
|
|
|
- `numbered` accepts only `?`, `:`, and `$`.
|
|
- `named` and `quoted` accept only `:`, `@`, and `$`.
|
|
- Each `custom` item may contain only a non-empty, valid `regex`.
|
|
|
|
DBX always adds recognition for `${name}` and `#{name}` variables so those templates do not cause formatter parse failures. A non-null legacy `params` option is no longer used for text substitution; configure `paramTypes` instead.
|
|
|
|
<Cards>
|
|
<Card title="Query Editor" href="/en/docs/query-editor">
|
|
Learn how formatting, compression, execution scope, and completion work.
|
|
</Card>
|
|
<Card title="SQL Snippets" href="/en/docs/sql-snippets">
|
|
Build reusable SQL templates with tab-stop placeholders.
|
|
</Card>
|
|
</Cards>
|