tessl/npm-sql-formatter

Format whitespace in a SQL query to make it more readable with support for multiple SQL dialects

—

Pending

Overview

Eval results

Files

CLI Usage

Name: tessl/npm-sql-formatter
Author: tessl

Command-line interface for formatting SQL files and integrating with development workflows.

Installation

Install the CLI tool globally or use with npx:

# Global installation
npm install -g sql-formatter

# Or use with npx (no installation required)
npx sql-formatter --help

Command Syntax

sql-formatter [-h] [-o OUTPUT] [--fix] 
              [-l LANGUAGE] [-c CONFIG] [--version] [FILE]

Options

Basic Options

# Show help message
sql-formatter -h
sql-formatter --help

# Show version number  
sql-formatter --version

Input/Output Options

# Format file and output to stdout
sql-formatter input.sql

# Format from stdin
echo "SELECT * FROM users" | sql-formatter

# Specify output file
sql-formatter input.sql -o formatted.sql
sql-formatter input.sql --output formatted.sql

# Update file in-place
sql-formatter input.sql --fix

Language Options

# Specify SQL dialect
sql-formatter -l mysql input.sql
sql-formatter --language postgresql input.sql

# Available languages:
# bigquery, db2, db2i, duckdb, hive, mariadb, mysql, n1ql, plsql, 
# postgresql, redshift, singlestoredb, snowflake, spark, sql, 
# sqlite, tidb, transactsql, trino, tsql

Configuration Options

# Specify config file
sql-formatter -c .sql-formatter.json input.sql
sql-formatter --config config.json input.sql

# Specify config as JSON string
sql-formatter -c '{"keywordCase":"upper","tabWidth":4}' input.sql

Usage Examples

Basic Formatting

# Format a single file
sql-formatter query.sql

# Format from stdin
echo "select * from users where active=1" | sql-formatter

# Format with specific dialect
sql-formatter --language mysql query.sql

File Operations

# Format and save to new file
sql-formatter input.sql --output formatted.sql

# Update file in-place
sql-formatter query.sql --fix

# Process multiple files (using shell)
for file in *.sql; do
  sql-formatter "$file" --fix
done

Configuration Examples

# Use custom configuration file
sql-formatter --config .sql-formatter.json query.sql

# Inline configuration
sql-formatter -c '{"keywordCase":"upper","indentStyle":"tabularLeft"}' query.sql

# Combined language and config
sql-formatter --language postgresql --config config.json query.sql

Configuration File

The CLI automatically looks for .sql-formatter.json in the current directory and parent directories.

Example .sql-formatter.json:

{
  "language": "mysql",
  "keywordCase": "upper", 
  "identifierCase": "lower",
  "tabWidth": 4,
  "indentStyle": "standard",
  "linesBetweenQueries": 2
}

Configuration Search Order:

File specified with --config option
JSON string passed to --config option
.sql-formatter.json in current directory
.sql-formatter.json in parent directories (recursive search)
Default configuration

Integration Examples

Git Hooks

Format SQL files before commit:

# .git/hooks/pre-commit
#!/bin/sh
for file in $(git diff --cached --name-only --diff-filter=ACM | grep '\.sql$'); do
  sql-formatter "$file" --fix
  git add "$file"
done

NPM Scripts

Add to package.json:

{
  "scripts": {
    "format:sql": "sql-formatter --fix src/**/*.sql",
    "check:sql": "sql-formatter --config .sql-formatter.json src/**/*.sql"
  }
}

CI/CD Pipeline

GitHub Actions example:

- name: Format SQL files
  run: |
    npm install -g sql-formatter
    sql-formatter --fix database/migrations/*.sql
    
- name: Check SQL formatting
  run: |
    sql-formatter --config .sql-formatter.json database/**/*.sql > /dev/null
    if [ $? -ne 0 ]; then
      echo "SQL files are not properly formatted"
      exit 1
    fi

Build Tools

Webpack Integration

const { execSync } = require('child_process');

module.exports = {
  // ... webpack config
  plugins: [
    {
      apply: (compiler) => {
        compiler.hooks.beforeCompile.tap('FormatSQL', () => {
          execSync('sql-formatter --fix src/**/*.sql');
        });
      }
    }
  ]
};

Gulp Integration

const { exec } = require('child_process');
const gulp = require('gulp');

gulp.task('format-sql', (cb) => {
  exec('sql-formatter --fix src/**/*.sql', cb);
});

Error Handling

The CLI provides helpful error messages for common issues:

# File not found
sql-formatter nonexistent.sql
# Error: could not open file nonexistent.sql

# No input provided
sql-formatter
# Error: no file specified and no data in stdin

# Invalid configuration
sql-formatter -c '{"invalid": json}' query.sql  
# Error: unable to parse as JSON or treat as JSON file

# Conflicting options
sql-formatter --output out.sql --fix input.sql
# Error: Cannot use both --output and --fix options simultaneously

# Missing file for --fix
sql-formatter --fix
# Error: The --fix option cannot be used without a filename

Exit Codes

0 - Success
1 - Error (invalid input, configuration, or file system error)

Performance Tips

For large files or batch processing:

# Process files in parallel (if using GNU parallel)
find . -name "*.sql" | parallel sql-formatter {} --fix

# Use specific language to avoid detection overhead
sql-formatter --language mysql large-file.sql

# Use configuration file instead of inline JSON for repeated use
sql-formatter --config .sql-formatter.json query.sql

Install with Tessl CLI