holywell

library1.8.10jsnpmunverified

An opinionated SQL formatter implementing Simon Holywell's sqlstyle.guide with zero dependencies. Current stable version is 1.8.10 (as of Oct 2024). It enforces specific formatting rules such as river alignment (right-aligned keywords), keyword uppercasing, and consistent indentation. Unlike general-purpose SQL formatters (e.g., sql-formatter or pgFormatter), holywell strictly follows a single style guide with minimal configuration, making output deterministic. It supports CLI (glob patterns, --check, --write) and programmatic usage via named export formatSQL. Requires Node.js ≥18 and ships TypeScript types. Does not support custom configuration or multiple dialects beyond standard SQL.

database devops

npm install holywell

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HOLYWELL

holywell

databasejavascriptv1.8.10

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

formatSQL

✓ import { formatSQL } from 'holywell'

✗ import formatSQL from 'holywell'

formatSQL is a named export, not default. Common mistake: using default import.

holywell (CLI)

✓ npx holywell "**/*.sql"

✗ npx holywell --format "**/*.sql"

CLI does not have a --format flag; use --check or --write for modes.

TypeScript types

✓ import { formatSQL } from 'holywell'

✗ const formatSQL = require('holywell')

Package is ESM-only. CommonJS require() will fail. Use dynamic import if needed: const { formatSQL } = await import('holywell').

Formats a multi-line SQL query with JOINs and window function using the holywell library.

import { formatSQL } from 'holywell'; const sql = `SELECT e.name, e.salary, d.department_name, RANK() OVER (PARTITION BY d.department_name ORDER BY e.salary DESC) AS dept_rank FROM employees AS e INNER JOIN departments AS d ON e.department_id = d.id WHERE e.start_date >= '2024-01-01' AND d.active = TRUE ORDER BY d.department_name, dept_rank;`; const formatted = formatSQL(sql); console.log(formatted);

Debug

Known issues

breakingOnly supports Node.js >=18. Throws engine check error on lower versions.

fix

Update Node.js to 18 or later, or use npm@9+ with --ignore-engines (not recommended).

affects: >=1.0.0

gotchaZero configuration: no options to customize keyword casing, indentation width, or line length. Output is deterministic.

fix

If you need custom formatting, consider another library like sql-formatter. holywell is intentionally opinionated.

affects: >=1.0.0

gotchaDoes not support all SQL dialects (e.g., PL/SQL, T-SQL specific features like MERGE, TRY...CATCH). May produce incorrect output for vendor-specific syntax.

fix

Use a dialect-aware formatter like sql-formatter with dialect option for non-standard SQL.

affects: >=1.0.0

breakingESM-only package. require('holywell') throws ERR_REQUIRE_ESM.

fix

Use import statements or dynamic import. In CommonJS, use async wrapper: const { formatSQL } = await import('holywell');

affects: >=1.0.0

deprecatedIn older versions (<1.0.0), the package may have had a different API (e.g., default export). Check changelog.

fix

Upgrade to >=1.0.0 and use named export formatSQL.

affects: <1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/node_modules/holywell/dist/index.js from /path/script.js not supported. Instead change the require of index.js in /path/script.js to a dynamic import() which is available in all CommonJS modules.

Attempting to use require() on an ESM-only package.

fix

Change to import { formatSQL } from 'holywell'; or use dynamic import: const { formatSQL } = await import('holywell');

TypeError: formatSQL is not a function

Using default import instead of named import.

fix

Change import formatSQL from 'holywell' to import { formatSQL } from 'holywell'.

Error: SQL parsing error at position 15: unexpected token

Input SQL contains syntax errors (e.g., missing comma, unclosed quote) or vendor-specific syntax not supported.

fix

Fix SQL syntax or use a dialect-aware formatter for your specific SQL variant.

Error: Node.js version 16.x is not supported. Please use version >=18.

Package requires Node.js >=18.

fix

Upgrade Node.js to 18 or later.

Upgrade

Version history

1.8.10latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/vinsidious/holywell ↗

packageholywell ↗

homepagehttps://github.com/vinsidious/holywell ↗