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

SQL Dialects

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

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

Capabilities

Dialect Objects

Each SQL dialect is exported as a constant that can be used directly with formatDialect().

// Database dialects
const bigquery: DialectOptions;     // Google Cloud BigQuery
const db2: DialectOptions;          // IBM DB2
const db2i: DialectOptions;         // IBM DB2i
const duckdb: DialectOptions;       // DuckDB
const hive: DialectOptions;         // Apache Hive
const mariadb: DialectOptions;      // MariaDB
const mysql: DialectOptions;        // MySQL
const postgresql: DialectOptions;   // PostgreSQL
const redshift: DialectOptions;     // Amazon Redshift
const singlestoredb: DialectOptions; // SingleStoreDB
const snowflake: DialectOptions;    // Snowflake
const spark: DialectOptions;        // Apache Spark SQL
const sqlite: DialectOptions;       // SQLite
const tidb: DialectOptions;         // TiDB
const trino: DialectOptions;        // Trino
const transactsql: DialectOptions;  // SQL Server Transact-SQL

// Query languages
const n1ql: DialectOptions;         // Couchbase N1QL
const plsql: DialectOptions;        // Oracle PL/SQL
const sql: DialectOptions;          // Generic SQL (default)

Usage Examples:

import { formatDialect, mysql, postgresql } from "sql-formatter";

// Use MySQL dialect directly
const mysqlFormatted = formatDialect(
  "SELECT `user_id`, COUNT(*) FROM `users` GROUP BY `user_id`",
  { dialect: mysql }
);

// Use PostgreSQL dialect with configuration
const pgFormatted = formatDialect(
  'SELECT "user_id", COUNT(*) FROM "users" GROUP BY "user_id"',
  { 
    dialect: postgresql,
    keywordCase: "upper",
    indentStyle: "tabularLeft"
  }
);

Dialect Options Interface

Configuration structure for each SQL dialect.

interface DialectOptions {
  /** Name of the dialect */
  name: string;
  /** Tokenizer configuration for lexical analysis */
  tokenizerOptions: TokenizerOptions;
  /** Formatting options specific to this dialect */
  formatOptions: DialectFormatOptions;
}

interface TokenizerOptions {
  /** SELECT clause variations */
  reservedSelect: string[];
  /** Main clauses that start new blocks */
  reservedClauses: string[];
  /** Set operations like UNION */
  reservedSetOperations: string[];
  /** Join variations */
  reservedJoins: string[];
  /** Multi-word keyword phrases */
  reservedKeywordPhrases?: string[];
  /** Multi-word data type phrases */
  reservedDataTypePhrases?: string[];
  /** Built-in function names */
  reservedFunctionNames: string[];
  /** Data type names */
  reservedDataTypes: string[];
  /** Other reserved keywords */
  reservedKeywords: string[];
  /** String literal quote types */
  stringTypes: QuoteType[];
  /** Identifier quote types */
  identTypes: QuoteType[];
  /** Variable quote types */
  variableTypes?: VariableType[];
  /** Additional parenthesis types */
  extraParens?: ('[]' | '{}')[];
  /** Parameter placeholder types */
  paramTypes?: ParamTypes;
  /** Line comment types */
  lineCommentTypes?: string[];
  /** Enable nested block comments */
  nestedBlockComments?: boolean;
  /** Additional identifier characters */
  identChars?: IdentChars;
  /** Additional parameter characters */
  paramChars?: IdentChars;
  /** Additional operators */
  operators?: string[];
  /** Property access operators */
  propertyAccessOperators?: string[];
  /** Enable PostgreSQL OPERATOR(...) syntax */
  operatorKeyword?: boolean;
  /** Support underscores in numbers */
  underscoresInNumbers?: boolean;
  /** Post-processing function */
  postProcess?: (tokens: Token[]) => Token[];
}

Major SQL Dialects

MySQL

MySQL dialect with MySQL-specific syntax, functions, and operators.

const mysql: DialectOptions;

Features:

Backtick identifiers `table_name`
MySQL-specific functions (GROUP_CONCAT, etc.)
Variable syntax with @ prefix
MySQL operators (<=>, <<, >>, etc.)
STRAIGHT_JOIN support

Usage Examples:

import { format, mysql, formatDialect } from "sql-formatter";

// Using language string
const result1 = format("SELECT * FROM `users`", { language: "mysql" });

// Using dialect object
const result2 = formatDialect("SELECT * FROM `users`", { dialect: mysql });

PostgreSQL

PostgreSQL dialect with PostgreSQL-specific syntax and features.

const postgresql: DialectOptions;

Features:

Double-quoted identifiers "table_name"
PostgreSQL-specific functions and operators
Dollar-quoted strings $tag$content$tag$
Array and JSON operators (->, ->>, etc.)
OPERATOR() syntax support

SQL Server (Transact-SQL)

SQL Server Transact-SQL dialect.

const transactsql: DialectOptions;

Features:

Square bracket identifiers [table_name]
SQL Server specific functions
Variable syntax with @ prefix
TOP clause support
OUTPUT clause support

BigQuery

Google Cloud BigQuery dialect.

const bigquery: DialectOptions;

Features:

Backtick identifiers for dataset.table references
BigQuery-specific functions (ARRAY_AGG, STRUCT, etc.)
Standard SQL and legacy SQL support
Parameterized queries with @ prefix

Oracle PL/SQL

Oracle PL/SQL dialect.

const plsql: DialectOptions;

Features:

PL/SQL block structure support
Oracle-specific functions and operators
CONNECT BY hierarchical queries
Dual table references

Dialect Creation

Factory function for creating dialect objects with caching.

/**
 * Factory function for building Dialect objects.
 * When called repeatedly with same options object returns the cached Dialect,
 * to avoid the cost of creating it again.
 */
function createDialect(options: DialectOptions): Dialect;

interface Dialect {
  tokenizer: Tokenizer;
  formatOptions: ProcessedDialectFormatOptions;
}

Usage Examples:

import { createDialect, mysql } from "sql-formatter";

// Create a dialect instance (cached)
const dialect = createDialect(mysql);

// Use with custom formatter logic
const formatted = new Formatter(dialect, options).format(query);

Install with Tessl CLI