Analyze files and database results locally
Received a CSV or Parquet export to investigate? Import it and query it with SQL
in the same desktop IDE, using embedded DuckDB. A spreadsheet fits this workflow
when exported as CSV. You do not need to load the file into your source database
or write a separate script.
You can also import a database query result and join it with the file locally,
including results from another supported connection.
Example: sales are in PostgreSQL, targets are in a CSV. Import both and use
a local SQL join to find the region that missed its target without uploading
the file to PostgreSQL. Try the demo with fictional data.
- Run a source query and open Analyze locally.
- Choose Full query result to load the full source query, or choose a sample.
- Add a CSV or Parquet dataset and join it with the imported result using SQL.
- Inspect the result and export the full local query output.
A full export contains the rows available in your imported datasets. If you
imported a sample, the export still represents that sample.
Read about import coverage and provenance.
SQL editing and database exploration
The editor has metadata and CTE-aware completion, dialect quick fixes, and
supported execution plans. Browse schemas and definitions, inspect results,
and edit rows when primary-key checks establish a safe update path.
Compatible AI clients can propose SQL changes through the
local MCP integration, with an approval dialog before applying them.
Use /catalog in the editor to find SQL templates for the active dialect, including
/catalog insert for an Insert row example. Oracle Explain displays available
row, byte, cost, and time estimates alongside plan predicates.
Database support
| Database / mechanism | Connection | Metadata autocomplete | Query execution |
|---|
| PostgreSQL | ✅ | ✅ | ✅ |
| MySQL | ✅ | ✅ | ✅ |
| MariaDB | ✅ | ✅ | ✅ |
| SQL Server | ✅ | ✅ | ✅ |
| Oracle | ✅ | ✅ | ✅ |
| MongoDB | ✅ | ✅ Sampled fields | Native Extended JSON + read-only SQL |
| Generic JDBC | 🧪 Experimental | Driver-dependent | SQL; driver-dependent |
| ODBC | 🧪 Experimental | Driver-dependent | SQL; driver-dependent |
Generic JDBC uses a driver JAR, JDBC URL, and driver class supplied by the user.
ODBC uses a DSN or connection string and requires a separately installed 64-bit
database driver. Both expose basic metadata and bounded query execution, with
behavior depending on the selected driver. Plans, indexes, definitions, and
result-grid row edits are not currently available for generic JDBC or ODBC.
MongoDB supports native queries and explicit writes, metadata autocomplete,
and SELECT conversion with /mongo. SQL mode is read-only and uses native
execution with DuckDB for complex queries. See MongoDB usage.
See the database support guide for connection details and limitations.
Install
Download the package for your platform from the latest GitHub release.
| Platform | Package | Status |
|---|
| Windows 10/11 x64 | .exe installer | Available |
| Windows 10/11 x64 | x64-portable.zip archive | Available |
| Debian/Ubuntu amd64 | .deb package | Available |
| macOS 15+ Apple Silicon / Intel | .dmg installer | Included starting with v0.7.1 |
| Linux ARM, AppImage, RPM | — | Not packaged yet |
Release assets include a SHA256SUMS file so downloads can be verified. End users
do not need to install Node.js, Java, or Rust. Native database connections do not
require a separate database client or vendor client SDK; generic JDBC and ODBC
require the database drivers described above.
Windows portable archive
The portable archive runs without an installer or administrator rights. Extract
the whole omni-sql folder (running it from inside the ZIP does not work) and
start omni-sql.exe. It needs the Microsoft Edge WebView2 Runtime, which ships
with Windows 11 and current Windows 10 installations.
The portable copy keeps its data in your Windows profile, exactly like the
installed app, so both share connections, history and settings:
| Data | Location |
|---|
| Tabs, history, theme and editor settings | %LOCALAPPDATA%\dev.omnisql (WebView storage) |
| Logs | %LOCALAPPDATA%\dev.omnisql\logs |
| Local DuckDB analysis and runtime cache | %APPDATA%\dev.omnisql |
| Connections and metadata cache | %USERPROFILE%\.local\share\omni-sql |
| Passwords | Windows Credential Manager |
Copying the folder to another machine or Windows account therefore does not move
connections or passwords. When an update is available, the portable copy opens the
release page instead of running the installer: close omni-sql, extract the new
archive and replace the old folder. To remove it, delete the folder, and the
locations above if you no longer need the data.
macOS first launch
Choose the aarch64.dmg download for Apple Silicon (M1 or newer), or x64.dmg
for an Intel Mac. Open the disk image, drag omni-sql to Applications,
and launch it from there.
Initial macOS packages use a free ad-hoc signature and are not notarized by Apple.
If macOS blocks the first launch because the developer cannot be verified, open
System Settings → Privacy & Security → Open Anyway, then confirm opening
omni-sql. Follow Apple's instructions for an
app downloaded from a source you trust. No paid Apple account is needed to install.
Node.js, Java and the ODBC driver manager are bundled. ODBC connections still
require a separately installed driver for the database, as on other platforms.
omni-sql is early-stage software. Test it with development data before using it
against important environments, and please report unexpected behavior.
Quick start
For files only, install the app, choose Import file, and select a CSV or
Parquet file. Query the imported table in the Local DuckDB SQL tab.
To work with a database:
- Install the package for your platform.
- Open omni-sql and create a connection.
- Select a database type, enter the connection details, and choose Test connection.
- Configure SSL and schema settings when needed, then connect.
- Browse metadata or open a SQL tab and start writing.
- Run the selection or current statement, then inspect, filter, sort, page, or export the results.
- Open Analyze locally to import a displayed result, stream a full query or sample, or add CSV/Parquet datasets for local joins.
For full imports, sampling, S3, driver precision, and export behavior, read the
local analysis guide and data provenance guide.
Need help connecting? Read Database support or Troubleshooting.
Features in action
Complete columns projected by a CTE
omni-sql combines database metadata with the SQL in the editor to suggest columns
projected by common table expressions.
Adapt SQL through a dialect quick fix
Supported diagnostics can offer a quick fix that rewrites the statement for the
active database dialect without leaving the editor.
Positioning
omni-sql combines SQL editing with local analysis of imported database results
and files. Mature tools such as DBeaver and DataGrip cover broader administration
and ecosystem needs. You can use omni-sql alongside them for local DuckDB analysis.
| Choose omni-sql when you want… | Consider a broader tool when you need… |
|---|
| Local DuckDB joins across imported database results and files | Deep vendor-specific administration |
| One editor across five major relational databases | Built-in data modeling and migration tools |
| CTE and metadata-aware SQL completion | A large plugin ecosystem or enterprise support |
| A local desktop app with no account | Built-in data modeling, migration, or team features |
| An MIT-licensed project you can inspect and contribute to | An established, long-supported product |
MCP integration
omni-sql includes a local MCP server that lets compatible AI clients work with the
SQL tab you already have open. An assistant can read the active statement and its
database context, inspect schema metadata and indexes, explain a query without
executing it, prepare an edit for review, or execute SQL after explicit approval in the desktop.
AI client ──MCP/STDIO or HTTP──▶ local omni-sql bridge ──▶ active desktop tab
│
└─ edits and SQL execution require approval
| Tool | What it does |
|---|
getActiveSql | Reads the SQL and dialect from the active tab. |
getActiveConnectionContext | Reads safe connection context without credentials. |
getSchemaSummary | Lists schemas, relations, and columns available to the active connection. |
getTableIndexes | Inspects indexes for one table. |
explainSql | Produces a non-executing query plan. |
getLatestSqlExecutionError | Reads the latest execution error from the active tab. |
proposeSqlEdit | Opens a before/after proposal that you can apply or reject in omni-sql. |
executeSql | Runs SQL on the active connection after explicit desktop approval, returning bounded results. |
The default transport is local STDIO. The generated launcher configuration is
available from the MCP item in the status bar after the backend is ready. Copy
its command and args exactly into your MCP client; runtime paths are temporary
and are regenerated whenever omni-sql starts.
Optional Streamable HTTP can be started from MCP > Configuration > HTTP with
a separate token and a loopback endpoint (default http://127.0.0.1:41922/mcp).
SQL execution can modify data or structure and always requires desktop approval.
The integration cannot read stored passwords or connection strings, access files
through dedicated tools, or bypass the approval dialog. See the MCP guide for Codex,
Claude Desktop, and ChatGPT Desktop setup, optional Streamable HTTP transport,
verification steps, limits, and the complete security model.
Roadmap
Current database support, including experimental JDBC and ODBC connections, is
listed in Database support. CTE-aware autocomplete and
MongoDB native/SQL workflows are already available.
- 📋 More installer formats and platforms: Linux ARM, AppImage, and RPM.
Documentation
Built with Tauri, React, Fluent UI, Monaco Editor, TypeScript, Rust, and Kotlin.
Help the project grow
If omni-sql is useful to you, star the repository
to help other developers discover it. You can report a bug,
share a database compatibility result, or suggest a focused improvement. Pull requests
are welcome—please read CONTRIBUTING.md first.
Tried installing or running your first database + file join?
Share your first-run experience,
including successful attempts. Tell us your platform, database, and where you
got stuck.
License
MIT
