Merge PR #386: Add paramTypes config option

Author: nene

README.md

@@ -157,6 +157,7 @@ All fields are optional and all fields that are not specified will be filled wit
 - [**`denseOperators`**](docs/denseOperators.md) packs operators densely without spaces.
 - [**`newlineBeforeSemicolon`**](docs/newlineBeforeSemicolon.md) places semicolon on separate line.
 - [**`params`**](docs/params.md) collection of values for placeholder replacement.
+- [**`paramsTypes`**](docs/paramTypes.md) specifies parameter placeholders types to support.
 
 ### Usage without NPM
 

docs/paramTypes.md

@@ -0,0 +1,93 @@
+# paramTypes
+
+Specifies parameter types to support when parsing SQL prepared statements.
+
+## Motivation
+
+While some SQL dialects have built-in support for prepared statements,
+others do not and instead rely on 3rd party libraries to emulate it,
+while yet others might have built-in support for prepared statements,
+but the syntax depends on the driver used to connect to the database.
+
+By default SQL Formatter supports only the built-in prepared statement
+syntax of an SQL dialect as documented in [params option documentation][params].
+For example if you're using PostgreSQL you can use the `$nr` syntax:
+
+```ts
+format('SELECT * FROM users WHERE name = $1 AND age < $2', { language: 'postgresql' });
+```
+
+However if you're connecting to the database using a Java DB connection library,
+you might expect to use `:name` placeholders for parameters:
+
+```ts
+format('SELECT * FROM users WHERE name = :name AND age < :age', { language: 'postgresql' });
+```
+
+This gets by default formatted like so:
+
+```sql
+SELECT
+  *
+FROM
+  users
+WHERE
+  name = : name
+  AND age < : age
+```
+
+To fix it, you'd need to specify with `paramTypes` config
+that you're using `:`-prefixed named placeholders:
+
+```ts
+format('SELECT * FROM users WHERE name = :name AND age < :name', {
+  language: 'postgresql',
+  paramTypes: { named: [':'] },
+});
+```
+
+After which you'll get the correct result:
+
+```sql
+SELECT
+  *
+FROM
+  users
+WHERE
+  name = :name
+  AND age < :age
+```
+
+## Option value
+
+An object with the following following optional fields:
+
+- **`positional`**: `boolean`. True to enable `?` placeholders, false to disable them.
+- **`numbered`**: `Array<"?" | ":" | "$">`. To allow for `?1`, `:2` and/or `$3` syntax for numbered placholders.
+- **`named`**: `Array<":" | "@" | "$">`. To allow for `:name`, `@name` and/or `$name` syntax for named placholders.
+- **`quoted`**: `Array<":" | "@" | "$">`. To allow for `:"name"`, `@"name"` and/or `$"name"` syntax for quoted placholders.
+  Note that the type of quotes dependes on the quoted identifiers supported by a dialect.
+  For example in MySQL using `paramTypes: {quoted: [':']}` would allow you to use `` :`name` `` syntax,
+  while in Transact-SQL `:"name"` and `:[name]` would work instead.
+  See [identifier syntax wiki page][] for information about differences in support quoted identifiers.
+
+Note that using this config will override the by default supported placeholders types.
+For example PL/SQL supports numbered (`:1`) and named (`:name`) placeholders by default.
+When you provide the following `paramTypes` configuration:
+
+```js
+paramTypes: { positional: true, numbered: [], named: [':', '@'] }
+```
+
+The result will be:
+
+- `?` positional placeholders are supported
+- `:1` numbered placeholders are no more supported
+- `:name` is still supported and `@name` named placeholder is also supported.
+
+## Parameter value substitution
+
+This config option can be used together with [params][] to substitute the placeholders with actual values.
+
+[params]: ./params.md
+[identifier syntax wiki page]: https://github.com/sql-formatter-org/sql-formatter/wiki/identifiers

docs/params.md

@@ -80,19 +80,49 @@ WHERE
   AND age = 27
 ```
 
+### Quoted placeholders
+
+Some dialects (BigQuery, Transact SQL) also support quoted names for placeholders:
+
+```js
+format('SELECT * FROM persons WHERE fname = @`first name` AND age = @`age`', {
+  params: { 'first name': "'John'", 'age': '27' },
+  language: 'bigquery',
+});
+```
+
+Results in:
+
+```sql
+SELECT
+  *
+FROM
+  persons
+WHERE
+  fname = 'John'
+  AND age = 27
+```
+
 ## Available placeholder types
 
-The placeholder types available depend on SQL dialect used:
-
-- sql - `?`, `?1`
-- bigquery - `?`, `?1`
-- db2 - `?`, `?1`, `:name`
-- hive - `?`, `?1`
-- mariadb - `?`, `?1`
-- mysql - `?`, `?1`
-- n1ql - `$name`
-- plsql - `?`, `?1`, `:name`
-- postgresql - `$`, `$1`, `:name`
-- redshift - `?`, `?1`, `@name`, `#name`, `$name`
-- sparksql - `?`, `?1`, `$name`
-- tsql - `@name`
+The placeholder types available by default depend on SQL dialect used:
+
+- sql - `?`
+- bigquery - `?`, `@name`, `` @`name` ``
+- db2 - `?`, `:name`
+- hive - _no support_
+- mariadb - `?`
+- mysql - `?`
+- n1ql - `?`, `$1`, `$name`
+- plsql - `:1`, `:name`
+- postgresql - `$1`
+- redshift - `$1`
+- sqlite - `?`, `?1`, `:name`, `@name`, `$name`
+- spark - _no support_
+- tsql - `@name`, `@"name"`, `@[name]`
+- trino - _no support_
+
+If you need to use a different placeholder syntax than the builtin one,
+you can configure the supported placeholder types using the [paramTypes][] config option.
+
+[paramtypes]: ./paramTypes.md

src/FormatOptions.ts

@@ -1,6 +1,7 @@
 import type { SqlLanguage } from './sqlFormatter';
 import { type ParamItems } from './formatter/Params';
 import Formatter from './formatter/Formatter';
+import { ParamTypes } from './lexer/TokenizerOptions';
 
 export type IndentStyle = 'standard' | 'tabularLeft' | 'tabularRight';
 
@@ -24,4 +25,5 @@ export interface FormatOptions {
   denseOperators: boolean;
   newlineBeforeSemicolon: boolean;
   params?: ParamItems | string[];
+  paramTypes?: ParamTypes;
 }

src/formatter/ExpressionFormatter.ts

@@ -215,7 +215,7 @@ export default class ExpressionFormatter {
       case TokenType.VARIABLE:
       case TokenType.NAMED_PARAMETER:
       case TokenType.QUOTED_PARAMETER:
-      case TokenType.INDEXED_PARAMETER:
+      case TokenType.NUMBERED_PARAMETER:
       case TokenType.POSITIONAL_PARAMETER:
         return this.formatLiteral(token);
       default:

src/formatter/Formatter.ts

@@ -46,7 +46,7 @@ export default class Formatter {
    * @return {string} The formatter query
    */
   public format(query: string): string {
-    const tokens = this.cachedTokenizer().tokenize(query);
+    const tokens = this.cachedTokenizer().tokenize(query, this.cfg.paramTypes || {});
     const ast = new Parser(tokens).parse();
     const formattedQuery = this.formatAst(ast);
     const finalQuery = this.postFormat(formattedQuery);

src/languages/bigquery/bigquery.formatter.ts

@@ -161,9 +161,7 @@ export default class BigQueryFormatter extends Formatter {
       ],
       identTypes: ['``'],
       identChars: { dashes: true },
-      positionalParams: true,
-      namedParamTypes: ['@'],
-      quotedParamTypes: ['@'],
+      paramTypes: { positional: true, named: ['@'], quoted: ['@'] },
       lineCommentTypes: ['--', '#'],
       operators: BigQueryFormatter.operators,
       postProcess,

src/languages/db2/db2.formatter.ts

@@ -181,8 +181,7 @@ export default class Db2Formatter extends Formatter {
       reservedFunctionNames: functions,
       stringTypes: [{ quote: "''", prefixes: ['G', 'N', 'X', 'BX', 'GX', 'UX', 'U&'] }],
       identTypes: [`""`],
-      positionalParams: true,
-      namedParamTypes: [':'],
+      paramTypes: { positional: true, named: [':'] },
       paramChars: { first: '@#$', rest: '@#$' },
       operators: Db2Formatter.operators,
     });

src/languages/mariadb/mariadb.formatter.ts

@@ -281,7 +281,7 @@ export default class MariaDbFormatter extends Formatter {
         { quote: "''", prefixes: ['@'], requirePrefix: true },
         { quote: '``', prefixes: ['@'], requirePrefix: true },
       ],
-      positionalParams: true,
+      paramTypes: { positional: true },
       lineCommentTypes: ['--', '#'],
       operators: MariaDbFormatter.operators,
       postProcess,

src/languages/mysql/mysql.formatter.ts

@@ -249,7 +249,7 @@ export default class MySqlFormatter extends Formatter {
         { quote: "''", prefixes: ['@'], requirePrefix: true },
         { quote: '``', prefixes: ['@'], requirePrefix: true },
       ],
-      positionalParams: true,
+      paramTypes: { positional: true },
       lineCommentTypes: ['--', '#'],
       operators: MySqlFormatter.operators,
       postProcess,