SQL Formatting

DBCode provides flexible SQL code formatting powered by sql-formatter with multiple configuration options. You can configure formatting through VS Code settings, workspace configuration files, or explicit config file paths.

The SQL dialect is automatically detected based on your active database connection, so you don’t need to configure it manually.

Quick Start

Option 1: VS Code Settings (Recommended)

The easiest and most discoverable way to configure SQL formatting:

1. Open VS Code Settings (Cmd/Ctrl + ,)
2. Search for “dbcode formatting”
3. Configure your preferences (e.g., Keyword Case, Indent Style, Tab Width, etc.)

Settings can be configured at:

• User level (applies to all projects)
• Workspace level (applies to current project only)

Option 2: Configuration Files

For team-shared configurations or project-specific formatting rules:

Auto-Detection:

1. Create a .sql-formatter.json file in your workspace root
2. Add your formatting preferences (see examples below)
3. DBCode automatically detects and uses your config

Custom Path:

1. Open VS Code Settings
2. Search for “dbcode.formatting.configPath”
3. Set the path to your config file (absolute or relative to workspace root)

Configuration Priority

When formatting SQL, DBCode merges options in this order (later takes precedence):

1. sql-formatter defaults
2. VS Code editor settings (editor.tabSize, editor.insertSpaces)
3. DBCode formatting settings (dbcode.formatting.*)
4. Workspace .sql-formatter.json file (if found)
5. Explicit config file at dbcode.formatting.configPath (if set)
6. SQL dialect (automatically detected from your database connection)

This allows you to set global defaults in VS Code settings, override them per-project with .sql-formatter.json, and further override with an explicit config file if needed.

Configuration Options

Case Formatting

Control the casing of SQL keywords, data types, functions, and identifiers:

{
  "keywordCase": "upper",
  "dataTypeCase": "upper",
  "functionCase": "upper",
  "identifierCase": "preserve"
}

Options: "preserve", "upper", "lower"

Example:

-- Before
select count(*) from users where created_at > now()

-- After (with upper case keywords/functions)
SELECT COUNT(*) FROM users WHERE created_at > NOW()

Indentation Style

Choose how SQL statements are indented:

{
  "indentStyle": "standard",
  "tabWidth": 2,
  "useTabs": false
}

Indent Style Options:

• "standard" - Standard block indentation
• "tabularLeft" - Align keywords to the left
• "tabularRight" - Align keywords to the right

Example (standard):

SELECT
  user_id,
  email,
  created_at
FROM users
WHERE active = true

Example (tabularLeft):

SELECT user_id,
       email,
       created_at
  FROM users
 WHERE active = true

Logical Operators

Control newline placement for AND/OR operators:

{
  "logicalOperatorNewline": "before"
}

Options: "before", "after"

Example (before):

SELECT *
FROM users
WHERE status = 'active'
  AND created_at > '2024-01-01'
  AND email_verified = true

Example (after):

SELECT *
FROM users
WHERE status = 'active' AND
  created_at > '2024-01-01' AND
  email_verified = true

Expression Width

Set maximum characters in parenthesized expressions:

{
  "expressionWidth": 50
}

Example:

-- Short expressions stay on one line
SELECT * FROM users WHERE (status = 'active' AND verified = true)

-- Long expressions break to multiple lines
SELECT *
FROM users
WHERE (
  status = 'active'
  AND email_verified = true
  AND created_at > '2024-01-01'
)

Spacing Options

Control spacing and line breaks:

{
  "linesBetweenQueries": 2,
  "denseOperators": false,
  "newlineBeforeSemicolon": false
}

linesBetweenQueries: Number of blank lines between separate queries

denseOperators: When true, removes spaces around operators

-- denseOperators: false
WHERE age >= 18 AND status = 'active'

-- denseOperators: true
WHERE age>=18 AND status='active'

newlineBeforeSemicolon: When true, places semicolons on separate lines

-- newlineBeforeSemicolon: false
SELECT * FROM users;

-- newlineBeforeSemicolon: true
SELECT * FROM users
;

Column Alias Alignment

Align AS keywords in SELECT column lists for improved readability:

{
  "tabulateAlias": true
}

When enabled, DBCode automatically aligns AS keywords and their aliases within SELECT clauses, making column lists easier to scan.

Example:

-- Before
SELECT user_id AS id, email AS user_email, first_name AS fname FROM users

-- After (with tabulateAlias: true)
SELECT
  user_id     AS id,
  email       AS user_email,
  first_name  AS fname
FROM users

Works with complex queries:

SELECT
  u.user_id           AS id,
  u.email             AS user_email,
  COUNT(o.order_id)   AS order_count,
  SUM(o.total)        AS total_spent
FROM users u
LEFT JOIN orders o ON u.user_id = o.user_id
GROUP BY u.user_id, u.email

Note: This feature works best with single-line column expressions. Multi-line expressions (like complex subqueries) may not align as expected.

Complete Configuration Examples

Basic Configuration

Suitable for most teams - uppercase keywords, standard indentation:

{
  "keywordCase": "upper",
  "dataTypeCase": "upper",
  "functionCase": "upper",
  "tabWidth": 2,
  "linesBetweenQueries": 2
}

Tabular Style

Great for aligned keywords:

{
  "keywordCase": "upper",
  "dataTypeCase": "upper",
  "functionCase": "lower",
  "identifierCase": "preserve",
  "indentStyle": "tabularLeft",
  "logicalOperatorNewline": "before",
  "expressionWidth": 50,
  "linesBetweenQueries": 1,
  "tabWidth": 4,
  "useTabs": false
}

Compact Style

Minimalist formatting with lowercase keywords:

{
  "keywordCase": "lower",
  "dataTypeCase": "lower",
  "functionCase": "lower",
  "indentStyle": "standard",
  "linesBetweenQueries": 1,
  "denseOperators": true,
  "tabWidth": 2
}

Using Formatting

Once your configuration is set up, format SQL code using:

Format Entire Document:

• Right-click → Format Document
• Or press Alt+Shift+F (Windows/Linux) or Option+Shift+F (macOS)

Format Selection:

• Select code → Right-click → Format Selection
• Or press Ctrl+K Ctrl+F (Windows/Linux) or Cmd+K Cmd+F (macOS)

Multiple Workspaces

For monorepos or multi-project workspaces, place separate .sql-formatter.json files in each workspace folder. DBCode checks each workspace folder in order.

Using VS Code Settings

All formatting options can be configured through VS Code settings under the dbcode.formatting namespace:

• dbcode.formatting.keywordCase - Case for SQL keywords (preserve/upper/lower)
• dbcode.formatting.dataTypeCase - Case for data types (preserve/upper/lower)
• dbcode.formatting.functionCase - Case for function names (preserve/upper/lower)
• dbcode.formatting.identifierCase - Case for identifiers (preserve/upper/lower)
• dbcode.formatting.indentStyle - Indentation style (standard/tabularLeft/tabularRight)
• dbcode.formatting.logicalOperatorNewline - AND/OR newline placement (before/after)
• dbcode.formatting.expressionWidth - Max chars in expressions (number)
• dbcode.formatting.linesBetweenQueries - Blank lines between queries (number)
• dbcode.formatting.denseOperators - Remove spaces around operators (boolean)
• dbcode.formatting.newlineBeforeSemicolon - Place semicolons on new lines (boolean)
• dbcode.formatting.tabulateAlias - Align AS keywords in SELECT lists (boolean)

Note: Tab width and tab/space preferences are automatically inherited from VS Code’s editor.tabSize and editor.insertSpaces settings.

Global Configuration File

Use the dbcode.formatting.configPath setting to point to a shared config file:

{
  "dbcode.formatting.configPath": "~/shared-configs/sql-formatter.json"
}

Troubleshooting

Config not working:

• Verify JSON syntax is valid (use a JSON validator)
• Ensure file is named exactly .sql-formatter.json
• Check file is in workspace root or path is correct in settings
• Restart VS Code to reload the configuration

Inconsistent formatting:

• Multiple config files may exist (explicit path overrides workspace file)
• Verify options match sql-formatter documentation
• Check that your database dialect is supported

Configuration not reloading:

• DBCode watches for file changes automatically
• If changes don’t apply, try reloading VS Code window

Further Reading

• sql-formatter - The open-source formatter library powering DBCode’s SQL formatting
• sql-formatter configuration options - Complete reference for all available options
• SQL Editor - Learn about SQL editing features in DBCode
• Autocomplete - Intelligent SQL code completion