{"id":16336,"library":"dbgate-query-splitter","title":"SQL Query Splitter","description":"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.","status":"active","version":"4.12.0","language":"javascript","source_language":"en","source_url":"https://github.com/dbgate/dbgate-query-splitter","tags":["javascript","SQL","query","split","parse","typescript"],"install":[{"cmd":"npm install dbgate-query-splitter","lang":"bash","label":"npm"},{"cmd":"yarn add dbgate-query-splitter","lang":"bash","label":"yarn"},{"cmd":"pnpm add dbgate-query-splitter","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary function for splitting a complete string query. Use named import for ESM. CommonJS users often misuse object destructuring from a direct require.","wrong":"const splitQuery = require('dbgate-query-splitter').splitQuery;","symbol":"splitQuery","correct":"import { splitQuery } from 'dbgate-query-splitter';"},{"note":"Dialect-specific options are named exports from the main package. Do not try to import them from subpaths.","wrong":"import mysqlSplitterOptions from 'dbgate-query-splitter/mysqlSplitterOptions';","symbol":"mysqlSplitterOptions","correct":"import { mysqlSplitterOptions } from 'dbgate-query-splitter';"},{"note":"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.","wrong":"import { splitQueryStream } from 'dbgate-query-splitter';","symbol":"splitQueryStream","correct":"import { splitQueryStream } from 'dbgate-query-splitter/lib/splitQueryStream';"}],"quickstart":{"code":"import { splitQuery, mssqlSplitterOptions } from 'dbgate-query-splitter';\n\nconst complexSqlQuery = `\n-- This is a comment\nSELECT * FROM Users WHERE isActive = 1;\nGO\n\n-- Another statement block\nDECLARE @myVar INT = 10;\nSELECT @myVar AS Result;\nGO\n\n/*\n  Multi-line comment\n  followed by an empty statement\n*/\nSELECT COUNT(*) FROM Products;\n`;\n\n// Split the query, returning rich information including positions for MS SQL Server dialect\nconst statements = splitQuery(complexSqlQuery, {\n  ...mssqlSplitterOptions,\n  returnRichInfo: true,\n});\n\nstatements.forEach(stmt => {\n  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`);\n});\n\n/* Expected output (simplified):\nStatement:\n'SELECT * FROM Users WHERE isActive = 1;'...\nStatement:\n'DECLARE @myVar INT = 10;\\nSELECT @myVar AS Result;'...\nStatement:\n'SELECT COUNT(*) FROM Products;'...\n*/","lang":"typescript","description":"Demonstrates splitting a multi-statement SQL string using MSSQL dialect options and retrieving rich position information for each statement."},"warnings":[{"fix":"Remove any manual `byline` piping when using `splitQueryStream`. The function now directly accepts a Node.js readable stream and returns an object stream.","message":"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.","severity":"breaking","affected_versions":">=4.9.0"},{"fix":"Correct the import statement: `import { splitQueryStream } from 'dbgate-query-splitter/lib/splitQueryStream';` (ESM) or `const { splitQueryStream } = require('dbgate-query-splitter/lib/splitQueryStream');` (CJS).","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Always provide a valid splitter options object, e.g., `mysqlSplitterOptions`, `mssqlSplitterOptions`, or a custom configuration object, as the second argument to `splitQuery`.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import { splitQueryStream } from 'dbgate-query-splitter/lib/splitQueryStream';`","cause":"Attempting to import `splitQueryStream` directly from the main `dbgate-query-splitter` package using ESM syntax, but it's located in a subpath.","error":"TypeError: Cannot destructure property 'splitQueryStream' of 'dbgate-query-splitter__WEBPACK_IMPORTED_MODULE_0__' as it is undefined."},{"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.","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).","error":"TypeError: splitQuery is not a function"}],"ecosystem":"npm"}