prettier-plugin-sql

0.20.0 verified Sat Apr 25 auth: no javascript

Prettier plugin for formatting SQL files and SQL-in-JS. Wraps sql-formatter and node-sql-parser to support 20+ dialects including BigQuery, PostgreSQL, MySQL, ClickHouse. Requires Prettier 3.0.3+ and Node 14.18+. Version 0.20.0 adds ClickHouse support. Plugin is under active development but stable for basic usage. Differentiator: integrates with prettier-plugin-embed for embedded SQL in tagged templates.

Common errors

error Cannot find module 'prettier-plugin-sql' ↓

cause Plugin not installed or not in node_modules

fix

Run: npm install -D prettier prettier-plugin-sql

error Error: Could not load plugin 'prettier-plugin-sql' ↓

cause Prettier version <3.0.3

fix

Upgrade Prettier: npm install -D prettier@latest

error Module not found: Can't resolve 'prettier-plugin-sql' ↓

cause Importing directly instead of using Prettier plugin system

fix

Do not import; add to .prettierrc plugins array.

error TypeError: Cannot read properties of undefined (reading 'format') ↓

cause Using node-sql-parser with unsupported language/dialect

fix

Use formatter: 'sql-formatter' or ensure language is supported by node-sql-parser.

Warnings

breaking prettier-plugin-sql requires Prettier v3.0.3 or later ↓

fix Upgrade Prettier to ^3.0.3

deprecated CommonJS named exports removed in v0.19.2; use default export for CJS ↓

fix Use require('prettier-plugin-sql').default or switch to ESM

gotcha Options like params, paramTypes, dialect must be JSON-stringified strings (JSOX). Passing objects will silently fail. ↓

fix Set params: JSON.stringify({}) instead of params: {}

gotcha When using node-sql-parser formatter, only a subset of sql-formatter options are available; language defaults to 'sql'. ↓

fix Set formatter: 'sql-formatter' for full option support.

deprecated Node.js v14 is EOL; future releases may drop support ↓

fix Upgrade to Node.js 16 or higher.

Install

npm install prettier-plugin-sql

yarn add prettier-plugin-sql

pnpm add prettier-plugin-sql

Imports

prettier-plugin-sql

wrong

import prettierPluginSql from 'prettier-plugin-sql'

correct

Prettier plugin loaded via plugins config in .prettierrc: { "plugins": ["prettier-plugin-sql"] }

Not imported directly; Prettier discovers it when listed in plugins array.

SqlBaseOptions

wrong

const { SqlBaseOptions } = require('prettier-plugin-sql')

correct

import type { SqlBaseOptions } from 'prettier-plugin-sql'

Type only; erased at runtime. In CJS, use import() or require with .d.ts.

PrettierPluginEmbedOptions
```
import type { PrettierPluginEmbedOptions } from 'prettier-plugin-embed'
```
For SQL-in-JS formatting, embed options come from a separate package.

Quickstart

Basic setup: add plugin to .prettierrc, configure PostgreSQL dialect and uppercase keywords, format a SQL file.

// Install: npm i -D prettier prettier-plugin-sql
// .prettierrc
{
  "plugins": ["prettier-plugin-sql"],
  "language": "postgresql",
  "keywordCase": "upper"
}

// Run: npx prettier --write db.sql
// Before (db.sql):
//   sELect  first_name,    species froM
//    animals
//          WhERE
//   id = 1
//
// After:
//   SELECT
//     first_name,
//     species
//   FROM
//     animals
//   WHERE
//     id = 1