SQL Query Splitter

4.12.0 · active · verified Wed Apr 22

dbgate-query-splitter is a utility library designed to efficiently break down long SQL queries into individual statements. Currently at version 4.12.0, it is actively maintained with a focus on high performance and a zero-dependency footprint. The library supports a wide array of SQL dialects including MySQL, PostgreSQL, SQLite, Microsoft SQL Server, and Oracle, handling complex syntax elements like comments, dollar strings, GO separators, custom delimiters, and `SET SQLTERMINATOR`. A key differentiator is its robust streaming support for Node.js environments, allowing processing of large SQL files without loading them entirely into memory. It also provides an option to return rich metadata, including line and column numbers, for each split statement, which is useful for tooling and error reporting.

Common errors

```
TypeError: Cannot destructure property 'splitQueryStream' of 'dbgate-query-splitter__WEBPACK_IMPORTED_MODULE_0__' as it is undefined.
```
cause Attempting to import `splitQueryStream` directly from the main `dbgate-query-splitter` package using ESM syntax, but it's located in a subpath.

fix Change your import statement to `import { splitQueryStream } from 'dbgate-query-splitter/lib/splitQueryStream';`
```
TypeError: splitQuery is not a function
```
cause Incorrect CommonJS `require` syntax when trying to access named exports, or attempting to use `require` on an ESM-only package (less likely for this package which supports both).

fix For CommonJS, use `const { splitQuery } = require('dbgate-query-splitter');`. For ESM, ensure `import { splitQuery } from 'dbgate-query-splitter';` is used in an ESM context.

Warnings

breaking The API for `splitQueryStream` was simplified in version 4.9.0. Explicitly piping a `byline` stream is no longer required and should be removed from your code.
Fix: Remove any manual `byline` piping when using `splitQueryStream`. The function now directly accepts a Node.js readable stream and returns an object stream.
gotcha When using `splitQueryStream`, ensure you are importing it from `dbgate-query-splitter/lib/splitQueryStream` and not directly from the main package. This specific import path is necessary for the streaming functionality.
Fix: Correct the import statement: `import { splitQueryStream } from 'dbgate-query-splitter/lib/splitQueryStream';` (ESM) or `const { splitQueryStream } = require('dbgate-query-splitter/lib/splitQueryStream');` (CJS).
gotcha The `splitQuery` function requires a second argument specifying the dialect options. Forgetting this argument or passing `null`/`undefined` will result in incorrect splitting or runtime errors.
Fix: Always provide a valid splitter options object, e.g., `mysqlSplitterOptions`, `mssqlSplitterOptions`, or a custom configuration object, as the second argument to `splitQuery`.

Install

npm install dbgate-query-splitter npm
yarn add dbgate-query-splitter yarn
pnpm add dbgate-query-splitter pnpm

Imports

splitQuery
wrong:
```
const splitQuery = require('dbgate-query-splitter').splitQuery;
```
correct:
```
import { splitQuery } from 'dbgate-query-splitter';
```
Primary function for splitting a complete string query. Use named import for ESM. CommonJS users often misuse object destructuring from a direct require.
mysqlSplitterOptions
wrong:
```
import mysqlSplitterOptions from 'dbgate-query-splitter/mysqlSplitterOptions';
```
correct:
```
import { mysqlSplitterOptions } from 'dbgate-query-splitter';
```
Dialect-specific options are named exports from the main package. Do not try to import them from subpaths.
splitQueryStream
wrong:
```
import { splitQueryStream } from 'dbgate-query-splitter';
```
correct:
```
import { splitQueryStream } from 'dbgate-query-splitter/lib/splitQueryStream';
```
The streaming functionality `splitQueryStream` is located in a specific subpath. Incorrectly importing from the main package path will result in undefined or module not found errors.

Quickstart

Demonstrates splitting a multi-statement SQL string using MSSQL dialect options and retrieving rich position information for each statement.

import { splitQuery, mssqlSplitterOptions } from 'dbgate-query-splitter';

const complexSqlQuery = `
-- This is a comment
SELECT * FROM Users WHERE isActive = 1;
GO

-- Another statement block
DECLARE @myVar INT = 10;
SELECT @myVar AS Result;
GO

/*
  Multi-line comment
  followed by an empty statement
*/
SELECT COUNT(*) FROM Products;
`;

// Split the query, returning rich information including positions for MS SQL Server dialect
const statements = splitQuery(complexSqlQuery, {
  ...mssqlSplitterOptions,
  returnRichInfo: true,
});

statements.forEach(stmt => {
  console.log(`Statement:\n'${stmt.text}'\n  Start: { line: ${stmt.start.line}, column: ${stmt.start.column} }\n  End:   { line: ${stmt.end.line}, column: ${stmt.end.column} }\n`);
});

/* Expected output (simplified):
Statement:
'SELECT * FROM Users WHERE isActive = 1;'...
Statement:
'DECLARE @myVar INT = 10;\nSELECT @myVar AS Result;'...
Statement:
'SELECT COUNT(*) FROM Products;'...
*/

view raw JSON →