or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdconfiguration.mdcore-formatting.mddialects.mdindex.mdparameters.mdutilities.md
tile.json

tessl/npm-sql-formatter

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/sql-formatter@15.6.x

To install, run

npx @tessl/cli install tessl/npm-sql-formatter@15.6.0

index.mddocs/

SQL Formatter

SQL Formatter is a JavaScript library for pretty-printing SQL queries with support for various SQL dialects. It provides comprehensive formatting options, parameter replacement capabilities, and supports 19 different SQL dialects including BigQuery, MySQL, PostgreSQL, and many others.

Package Information

  • Package Name: sql-formatter
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install sql-formatter

Core Imports

import { format, supportedDialects } from "sql-formatter";

For CommonJS:

const { format, supportedDialects } = require("sql-formatter");

Basic Usage

import { format } from "sql-formatter";

// Basic formatting with default options
const formatted = format("SELECT * FROM users WHERE id = 1");

// With dialect-specific formatting
const formatted = format("SELECT * FROM users WHERE id = 1", {
  language: "mysql",
  keywordCase: "upper",
  indentStyle: "standard"
});

// With parameter replacement
const formatted = format("SELECT * FROM users WHERE id = ?", {
  language: "postgresql",
  params: ["123"]
});

Architecture

SQL Formatter is built around several key components:

  • Core Formatting API: Main format() and formatDialect() functions for SQL formatting
  • Dialect System: 19 SQL dialect formatters with dialect-specific syntax rules and keywords
  • Configuration System: Comprehensive formatting options for customizing output style
  • Parameter Replacement: Support for positional, named, and custom parameter placeholders
  • CLI Tool: Command-line interface for batch processing and integration workflows
  • Tokenizer Engine: Lexical analysis with dialect-specific tokenization rules

Capabilities

Core Formatting

Primary SQL formatting functionality with dialect detection and comprehensive formatting options. Handles whitespace, indentation, keyword casing, and query structure.

function format(query: string, cfg?: FormatOptionsWithLanguage): string;

function formatDialect(query: string, cfg: FormatOptionsWithDialect): string;

const supportedDialects: string[];

type SqlLanguage = 
  | "bigquery" 
  | "db2" 
  | "db2i" 
  | "duckdb" 
  | "hive" 
  | "mariadb" 
  | "mysql" 
  | "n1ql" 
  | "plsql" 
  | "postgresql" 
  | "redshift" 
  | "spark" 
  | "sqlite" 
  | "sql" 
  | "tidb" 
  | "trino" 
  | "transactsql" 
  | "tsql" 
  | "singlestoredb" 
  | "snowflake";

Core Formatting

Configuration Options

Comprehensive formatting configuration including indentation, casing, operators, and layout options.

interface FormatOptions {
  tabWidth: number;
  useTabs: boolean;
  keywordCase: KeywordCase;
  identifierCase: IdentifierCase;
  dataTypeCase: DataTypeCase;
  functionCase: FunctionCase;
  indentStyle: IndentStyle;
  logicalOperatorNewline: LogicalOperatorNewline;
  expressionWidth: number;
  linesBetweenQueries: number;
  denseOperators: boolean;
  newlineBeforeSemicolon: boolean;
  params?: ParamItems | string[];
  paramTypes?: ParamTypes;
}

type KeywordCase = "preserve" | "upper" | "lower";
type IndentStyle = "standard" | "tabularLeft" | "tabularRight";
type LogicalOperatorNewline = "before" | "after";

Configuration Options

SQL Dialect Support

Individual dialect formatters for 19 SQL dialects, each with dialect-specific syntax rules, keywords, and formatting options.

// Dialect objects for direct use with formatDialect()
const bigquery: DialectOptions;
const mysql: DialectOptions;
const postgresql: DialectOptions;
const sqlite: DialectOptions;
// ... and 15 more dialects

interface DialectOptions {
  name: string;
  tokenizerOptions: TokenizerOptions;
  formatOptions: DialectFormatOptions;
}

SQL Dialects

Parameter Replacement

Parameter placeholder replacement for prepared statements with support for positional, named, and custom parameter types.

type ParamItems = { [k: string]: string };

interface ParamTypes {
  positional?: boolean;
  numbered?: ("?" | ":" | "$")[];
  named?: (":" | "@" | "$")[];
  quoted?: (":" | "@" | "$")[];
  custom?: CustomParameter[];
}

interface CustomParameter {
  regex: string;
  key?: (text: string) => string;
}

Parameter Replacement

Utility Functions

Helper functions for expanding SQL syntax patterns and handling configuration validation.

function expandPhrases(phrases: string[]): string[];

class ConfigError extends Error {}

Utilities

Command Line Interface

The package includes a command-line tool for formatting SQL files and integrating with development workflows.

npm install -g sql-formatter
sql-formatter --language mysql input.sql --output formatted.sql

CLI Usage