Running the same SQL checks in a browser, CLI and pull request
I wanted one set of SQL checks to work in three places: while exploring a query, from a terminal and during code review. That became SQL Atlas. It is a local, deterministic SQL analyzer with a browser interface, a CLI and a GitHub Action. This article covers the interfaces, the CI contract and the limits of static SQL analysis. One analyzer, three interfaces The analyzer returns structured data…
SQL Atlas is a local, deterministic SQL analyzer designed to work across three different interfaces: a web browser, a command-line interface (CLI), and a GitHub Action. The analyzer produces structured data instead of directly printing messages, allowing each interface to format the data in a way that suits its intended use case.
The browser interface presents findings to users, linking them to learning material when necessary. The CLI returns text, JSON, or Markdown output with stable exit codes, making it suitable for integration with other tools and workflows. The GitHub Action converts the findings into file annotations and a job summary, enabling developers to see the results directly in their pull requests.
The CLI supports a wide range of database systems, including PostgreSQL, MySQL, Oracle, SQLite, SQL Server, and a generic mode. It can output results in various formats, such as text for human readers, JSON for other programs, or Markdown for issues and reports. The CLI communicates exit codes to indicate the success or failure of the analysis, with 0 meaning success, 1 signifying a policy failure, and 2 indicating an invalid command or input.
The GitHub Action runs as a bundled Node 24 program without downloading dependencies at runtime. A minimal workflow setup could include checking out the repository, running the SQL Atlas package with specific paths and configurations, and then using the outputs to provide pull request feedback. The Action writes the full result to a job summary, and exposes file count, finding count, and the lowest score as outputs.
By default, the policy only fails on critical findings, but teams can start with report-only mode and adjust stricter thresholds later.
It is important to note that SQL Atlas does not connect to a database and cannot determine factors such as table sizes, data distribution, available indexes, planner settings, or the real execution plan. As a result, some warnings may require further investigation using EXPLAIN, representative data, and production-like measurements. The browser includes a local PostgreSQL EXPLAIN JSON viewer for this purpose, but the analyzer deliberately keeps its claims narrow.
To ensure the reliability of the analyzer and the automation interfaces, the project includes testing across its CI builds. The web app, CLI, and GitHub Action bundle undergo testing, with CI workflows verifying the output of a known SQL file and checking that the committed Action bundle has no uncommitted differences. The CLI package has no runtime dependencies, and the public npm package has been verified from an empty directory with a clean cache, including both the executable version and a real stdin analysis.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — it may contain errors, so check the original before relying on it.
