ksql-lint

1.0.1 verified Fri May 01 auth: no javascript

ksql-lint is a CLI tool for linting KSQLDB commands/queries, designed for use in CI/CD pipelines. It uses the official KSQLDB grammar from Confluent's ANTLR parser to validate KSQLDB statements syntax. The current version (1.0.1) is released under the MIT license. Key differentiators: direct grammar-based validation, simple CLI usage, exit codes for CI integration. It supports ANTLR 4.12 and is available via npx.

Common errors

error Error: Cannot find module 'antlr4' ↓

cause Missing antlr4 runtime dependency

fix

Install locally: npm install antlr4

error SyntaxError: Unexpected token (maybe from KSQL syntax) ↓

cause Parser can't handle some KSQL extensions or older grammar

fix

Use npx ksql-lint --grammar to check version; consider updating grammar

error ksql-lint: command not found ↓

cause Package not installed

fix

Run via npx or install globally: npm install -g ksql-lint

Warnings

breaking ANTLR version may cause compatibility issues: ksql-lint uses ANTLR 4.12. Updating requires regenerating the parser from grammar. ↓

fix Regenerate parser using generate.sh with updated ANTLR version in package.json and Docker image.

gotcha Exit code 1 indicates linting errors, but does not halt execution; intended for CI. ↓

fix Ensure pipeline checks exit code; no additional action needed.

gotcha File glob patterns may not expand on all shells; quotes may be needed. ↓

fix Use quoted glob patterns like '*.ksql'

Install

npm install ksql-lint

yarn add ksql-lint

pnpm add ksql-lint

Imports

main (CLI)
wrong
```
npx ksql-lint --file ./path/*.ksql
```
correct
```
npx ksql-lint ./path/*.ksql
```
ksql-lint is primarily a CLI tool, not a library. No programmatic import is provided.
lint (programmatic)
wrong
```
const { lint } = require('ksql-lint');
```
correct
```
import { lint } from 'ksql-lint';
```
ESM module; requires Node.js with ESM support or use dynamic import. CJS not supported.
parseError / validate
wrong
```
import * as ksql from 'ksql-lint';
```
correct
```
import { lint } from 'ksql-lint';
```
Default export is not provided; use named import for lint function. Other symbols may be internal.

Quickstart

Lint all .ksql files in the migrations directory using npx, output errors to console.

npx ksql-lint ./migrations/*.ksql