{"id":13471135,"url":"https://sql-formatter-org.github.io/sql-formatter/","last_synced_at":"2025-03-26T13:30:48.487Z","repository":{"id":37094316,"uuid":"68009783","full_name":"sql-formatter-org/sql-formatter","owner":"sql-formatter-org","description":"A whitespace formatter for different query languages","archived":false,"fork":false,"pushed_at":"2024-10-25T18:14:54.000Z","size":5027,"stargazers_count":2343,"open_issues_count":60,"forks_count":402,"subscribers_count":28,"default_branch":"master","last_synced_at":"2024-10-29T14:51:41.527Z","etag":null,"topics":["formatter","javascript","n1ql","sql"],"latest_commit_sha":null,"homepage":"https://sql-formatter-org.github.io/sql-formatter/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sql-formatter-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-12T13:09:04.000Z","updated_at":"2024-10-29T00:53:35.000Z","dependencies_parsed_at":"2022-07-09T19:16:20.483Z","dependency_job_id":"78cb09aa-ff7d-4225-a72d-d8b886c75945","html_url":"https://github.com/sql-formatter-org/sql-formatter","commit_stats":{"total_commits":2535,"total_committers":60,"mean_commits":42.25,"dds":0.368836291913215,"last_synced_commit":"31c1c5e0cc1f172e87931ee6bf95d5bcf4fcd766"},"previous_names":["zeroturnaround/sql-formatter"],"tags_count":161,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sql-formatter-org%2Fsql-formatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sql-formatter-org%2Fsql-formatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sql-formatter-org%2Fsql-formatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sql-formatter-org%2Fsql-formatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sql-formatter-org","download_url":"https://codeload.github.com/sql-formatter-org/sql-formatter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243982177,"owners_count":20378604,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["formatter","javascript","n1ql","sql"],"created_at":"2024-07-31T16:00:40.362Z","updated_at":"2025-03-26T13:30:48.480Z","avatar_url":"https://github.com/sql-formatter-org.png","language":"TypeScript","readme":"\u003ca href='https://github.com/sql-formatter-org/sql-formatter'\u003e\u003cimg src=\"static/prettier-sql-clean.svg\" width=\"128\"/\u003e\u003c/a\u003e\n\n# SQL Formatter [![NPM version](https://img.shields.io/npm/v/sql-formatter.svg)](https://npmjs.com/package/sql-formatter) ![Build status](https://img.shields.io/github/actions/workflow/status/sql-formatter-org/sql-formatter/coveralls.yaml) [![Coverage Status](https://coveralls.io/repos/github/sql-formatter-org/sql-formatter/badge.svg?branch=master)](https://coveralls.io/github/sql-formatter-org/sql-formatter?branch=master)\n\n**SQL Formatter** is a JavaScript library for pretty-printing SQL queries.\n\nIt started as a port of a [PHP Library][], but has since considerably diverged.\n\nIt supports various SQL dialects:\nGCP BigQuery, IBM DB2, Apache Hive, MariaDB, MySQL, TiDB, Couchbase N1QL, Oracle PL/SQL, PostgreSQL, Amazon Redshift, SingleStoreDB, Snowflake, Spark, SQL Server Transact-SQL, Trino (and Presto).\nSee [language option docs](docs/language.md) for more details.\n\nIt does not support:\n\n- Stored procedures.\n- Changing of the delimiter type to something else than `;`.\n\n→ [Try the demo.](https://sql-formatter-org.github.io/sql-formatter)\n\n## Install\n\nGet the latest version from NPM:\n\n```sh\nnpm install sql-formatter\n```\n\nAlso available with yarn:\n\n```sh\nyarn add sql-formatter\n```\n\n## Usage\n\n### Usage as library\n\n```js\nimport { format } from 'sql-formatter';\n\nconsole.log(format('SELECT * FROM tbl', { language: 'mysql' }));\n```\n\nThis will output:\n\n```sql\nSELECT\n  *\nFROM\n  tbl\n```\n\nYou can also pass in configuration options:\n\n```js\nformat('SELECT * FROM tbl', {\n  language: 'spark',\n  tabWidth: 2,\n  keywordCase: 'upper',\n  linesBetweenQueries: 2,\n});\n```\n\n### Disabling the formatter\n\nYou can disable the formatter for a section of SQL by surrounding it with disable/enable comments:\n\n```sql\n/* sql-formatter-disable */\nSELECT * FROM tbl1;\n/* sql-formatter-enable */\nSELECT * FROM tbl2;\n```\n\nwhich produces:\n\n```sql\n/* sql-formatter-disable */\nSELECT * FROM tbl1;\n/* sql-formatter-enable */\nSELECT\n  *\nFROM\n  tbl2;\n```\n\nThe formatter doesn't even parse the code between these comments.\nSo in case there's some SQL that happens to crash SQL Formatter,\nyou can at comment the culprit out (at least until the issue gets\nfixed in SQL Formatter).\n\n### Placeholders replacement\n\nIn addition to formatting, this library can also perform placeholder replacement in prepared SQL statements:\n\n```js\nformat('SELECT * FROM tbl WHERE foo = ?', {\n  params: [\"'bar'\"],\n});\n```\n\nResults in:\n\n```sql\nSELECT\n  *\nFROM\n  tbl\nWHERE\n  foo = 'bar'\n```\n\nFor more details see [docs of params option.](docs/params.md)\n\n### Usage from command line\n\nThe CLI tool will be installed under `sql-formatter`\nand may be invoked via `npx sql-formatter`:\n\n```sh\nsql-formatter -h\n```\n\n```\nusage: sql-formatter [-h] [-o OUTPUT] \\\n[-l {bigquery,db2,db2i,hive,mariadb,mysql,n1ql,plsql,postgresql,redshift,singlestoredb,snowflake,spark,sql,sqlite,tidb,transactsql,trino,tsql}] [-c CONFIG] [--version] [FILE]\n\nSQL Formatter\n\npositional arguments:\n  FILE            Input SQL file (defaults to stdin)\n\noptional arguments:\n  -h, --help      show this help message and exit\n  -o, --output    OUTPUT\n                    File to write SQL output (defaults to stdout)\n  --fix           Update the file in-place\n  -l, --language  {bigquery,db2,db2i,hive,mariadb,mysql,n1ql,plsql,postgresql,redshift,singlestoredb,snowflake,spark,sql,sqlite,tidb,trino,tsql}\n                    SQL dialect (defaults to basic sql)\n  -c, --config    CONFIG\n                    Path to config JSON file or json string (will find a file named '.sql-formatter.json' or use default configs if unspecified)\n  --version       show program's version number and exit\n```\n\nBy default, the tool takes queries from stdin and processes them to stdout but\none can also name an input file name or use the `--output` option.\n\n```sh\necho 'select * from tbl where id = 3' | sql-formatter\n```\n\n```sql\nselect\n  *\nfrom\n  tbl\nwhere\n  id = 3\n```\n\nThe tool also accepts a JSON config file named .sql-formatter.json in the current or any parent directory, or with the `--config` option that takes this form:\n\n```json\n{\n  \"language\": \"spark\",\n  \"tabWidth\": 2,\n  \"keywordCase\": \"upper\",\n  \"linesBetweenQueries\": 2\n}\n```\n\nAll fields are optional and all fields that are not specified will be filled with their default values.\n\n### Configuration options\n\n- [**`language`**](docs/language.md) the SQL dialect to use (when using `format()`).\n- [**`dialect`**](docs/dialect.md) the SQL dialect to use (when using `formatDialect()` since version 12).\n- [**`tabWidth`**](docs/tabWidth.md) amount of indentation to use.\n- [**`useTabs`**](docs/useTabs.md) to use tabs for indentation.\n- [**`keywordCase`**](docs/keywordCase.md) uppercases or lowercases keywords.\n- [**`dataTypeCase`**](docs/dataTypeCase.md) uppercases or lowercases data types.\n- [**`functionCase`**](docs/functionCase.md) uppercases or lowercases function names.\n- [**`identifierCase`**](docs/identifierCase.md) uppercases or lowercases identifiers. (**experimental!**)\n- [**`indentStyle`**](docs/indentStyle.md) defines overall indentation style. (**deprecated!**)\n- [**`logicalOperatorNewline`**](docs/logicalOperatorNewline.md) newline before or after boolean operator (AND, OR, XOR).\n- [**`expressionWidth`**](docs/expressionWidth.md) maximum number of characters in parenthesized expressions to be kept on single line.\n- [**`linesBetweenQueries`**](docs/linesBetweenQueries.md) how many newlines to insert between queries.\n- [**`denseOperators`**](docs/denseOperators.md) packs operators densely without spaces.\n- [**`newlineBeforeSemicolon`**](docs/newlineBeforeSemicolon.md) places semicolon on separate line.\n- [**`params`**](docs/params.md) collection of values for placeholder replacement.\n- [**`paramTypes`**](docs/paramTypes.md) specifies parameter placeholders types to support.\n\n### Usage without NPM\n\nIf you don't use a module bundler, clone the repository, run `npm install` and grab a file from `/dist` directory to use inside a `\u003cscript\u003e` tag.\nThis makes SQL Formatter available as a global variable `window.sqlFormatter`.\n\n### Usage in editors\n\n- [VSCode extension](https://marketplace.visualstudio.com/items?itemName=ReneSaarsoo.sql-formatter-vsc)\n  - [Repo](https://github.com/sql-formatter-org/sql-formatter-vscode)\n- [Vim extension](https://github.com/fannheyward/coc-sql/)\n- [Prettier plugin](https://github.com/un-ts/prettier/tree/master/packages/sql)\n\n### Usage as ESLint plugin\n\n- Inside `eslint-plugin-sql` by using the rule [eslint-plugin-sql#format](https://github.com/gajus/eslint-plugin-sql#format).\n\n## Frequently Asked Questions\n\n### Parse error: Unexpected ... at line ...\n\nThe most common cause is that you haven't specified an SQL dialect.\nInstead of calling the library simply:\n\n```js\nformat('select [col] from tbl');\n// Throws: Parse error: Unexpected \"[col] from\" at line 1 column 8\n```\n\npick the proper dialect, like:\n\n```js\nformat('select [col] from tbl', { language: 'transactsql' });\n```\n\nOr when using the VSCode extension: Settings -\u003e SQL-Formatter-VSCode: SQLFlavourOverride.\n\n### Module parse failed: Unexpected token\n\nThis typically happens when bundling an application with Webpack.\nThe cause is that Babel (through `babel-loader`) is not configured\nto support class properties syntax:\n\n```\n    | export default class ExpressionFormatter {\n    \u003e   inline = false;\n```\n\nThis syntax is widely supported in all major browsers (except old IE)\nand support for it is included to the default `@babel/preset-env`.\n\nPossible fixes:\n\n- Update to newer Babel / Webpack\n- Switch to `@babel/preset-env`\n- Include plugin `@babel/plugin-proposal-class-properties`\n\n### I'm having a problem with Prettier SQL VSCode extension\n\nThe [Prettier SQL VSCode](https://marketplace.visualstudio.com/items?itemName=inferrinizzard.prettier-sql-vscode)\nextension is no more maintained by its author.\n\nPlease use the official [SQL Formatter VSCode](https://marketplace.visualstudio.com/items?itemName=ReneSaarsoo.sql-formatter-vsc)\nextension to get the latest fixes from SQL Formatter library.\n\n### My SQL contains templating syntax which SQL Formatter fails to parse\n\nFor example, you might have an SQL like:\n\n```sql\nSELECT {col1}, {col2} FROM {tablename}\n```\n\nWhile templating is not directly supported by SQL Formatter, the workaround\nis to use [paramTypes](docs/paramTypes.md) config option to treat these\noccurrences of templating constructs as prepared-statement parameter-placeholders:\n\n```js\nformat('SELECT {col1}, {col2} FROM {tablename};', {\n  paramTypes: { custom: [{ regex: String.raw`\\{\\w+\\}` }] },\n});\n```\n\nThis won't work for all possible templating constructs,\nbut should solve the most common use cases.\n\n## The future\n\nThe development of this formatter is currently in maintenance mode.\nBugs will get fixed if feasible, but new features will likely not be added.\n\nI have started a new SQL formatting tool: [prettier-plugin-sql-cst][].\n\n- It solves several problems which can't be fixed in SQL Formatter because\n  of fundamental problems in its arhictecture.\n- It makes use of the Prettier layout algorithm,\n  doing a better job of splitting long expressions to multiple lines.\n- It takes much more opinionated approach to SQL formatting,\n  giving only a very limited set of options to adjust the code style.\n- It already has full support for SQLite and BigQuery syntax.\n  It should work for the most common SQL code in various other dialects.\n\nGive it a try if you'd like to take your SQL auto-formatting to the next level.\n\n## Contributing\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## License\n\n[MIT](LICENSE)\n\n[php library]: https://github.com/jdorn/sql-formatter\n[prettier-plugin-sql-cst]: https://github.com/nene/prettier-plugin-sql-cst\n","funding_links":[],"categories":["Tools and Utilities"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/sql-formatter-org.github.io%2Fsql-formatter%2F","html_url":"https://awesome.ecosyste.ms/projects/sql-formatter-org.github.io%2Fsql-formatter%2F","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/sql-formatter-org.github.io%2Fsql-formatter%2F/lists"}