0
# SQL Formatter
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: sql-formatter
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install sql-formatter`
10

11
## Core Imports
12

13
```typescript
14
import { format, supportedDialects } from "sql-formatter";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { format, supportedDialects } = require("sql-formatter");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { format } from "sql-formatter";
27

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

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

38
// With parameter replacement
39
const formatted = format("SELECT * FROM users WHERE id = ?", {
40
  language: "postgresql",
41
  params: ["123"]
42
});
43
```
44

45
## Architecture
46

47
SQL Formatter is built around several key components:
48

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

56
## Capabilities
57

58
### Core Formatting
59

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

62
```typescript { .api }
63
function format(query: string, cfg?: FormatOptionsWithLanguage): string;
64

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

67
const supportedDialects: string[];
68

69
type SqlLanguage = 
70
  | "bigquery" 
71
  | "db2" 
72
  | "db2i" 
73
  | "duckdb" 
74
  | "hive" 
75
  | "mariadb" 
76
  | "mysql" 
77
  | "n1ql" 
78
  | "plsql" 
79
  | "postgresql" 
80
  | "redshift" 
81
  | "spark" 
82
  | "sqlite" 
83
  | "sql" 
84
  | "tidb" 
85
  | "trino" 
86
  | "transactsql" 
87
  | "tsql" 
88
  | "singlestoredb" 
89
  | "snowflake";
90
```
91

92
[Core Formatting](./core-formatting.md)
93

94
### Configuration Options
95

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

98
```typescript { .api }
99
interface FormatOptions {
100
  tabWidth: number;
101
  useTabs: boolean;
102
  keywordCase: KeywordCase;
103
  identifierCase: IdentifierCase;
104
  dataTypeCase: DataTypeCase;
105
  functionCase: FunctionCase;
106
  indentStyle: IndentStyle;
107
  logicalOperatorNewline: LogicalOperatorNewline;
108
  expressionWidth: number;
109
  linesBetweenQueries: number;
110
  denseOperators: boolean;
111
  newlineBeforeSemicolon: boolean;
112
  params?: ParamItems | string[];
113
  paramTypes?: ParamTypes;
114
}
115

116
type KeywordCase = "preserve" | "upper" | "lower";
117
type IndentStyle = "standard" | "tabularLeft" | "tabularRight";
118
type LogicalOperatorNewline = "before" | "after";
119
```
120

121
[Configuration Options](./configuration.md)
122

123
### SQL Dialect Support
124

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

127
```typescript { .api }
128
// Dialect objects for direct use with formatDialect()
129
const bigquery: DialectOptions;
130
const mysql: DialectOptions;
131
const postgresql: DialectOptions;
132
const sqlite: DialectOptions;
133
// ... and 15 more dialects
134

135
interface DialectOptions {
136
  name: string;
137
  tokenizerOptions: TokenizerOptions;
138
  formatOptions: DialectFormatOptions;
139
}
140
```
141

142
[SQL Dialects](./dialects.md)
143

144
### Parameter Replacement
145

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

148
```typescript { .api }
149
type ParamItems = { [k: string]: string };
150

151
interface ParamTypes {
152
  positional?: boolean;
153
  numbered?: ("?" | ":" | "$")[];
154
  named?: (":" | "@" | "$")[];
155
  quoted?: (":" | "@" | "$")[];
156
  custom?: CustomParameter[];
157
}
158

159
interface CustomParameter {
160
  regex: string;
161
  key?: (text: string) => string;
162
}
163
```
164

165
[Parameter Replacement](./parameters.md)
166

167
### Utility Functions
168

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

171
```typescript { .api }
172
function expandPhrases(phrases: string[]): string[];
173

174
class ConfigError extends Error {}
175
```
176

177
[Utilities](./utilities.md)
178

179
## Command Line Interface
180

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

183
```bash
184
npm install -g sql-formatter
185
sql-formatter --language mysql input.sql --output formatted.sql
186
```
187

188
[CLI Usage](./cli.md)