lazysql: a terminal SQL client in the Lazygit mould

What lazysql solves, and who it is for

Most SQL clients assume a mouse. lazysql assumes a keyboard. The README says the project is heavily inspired by Lazygit, and that the author wanted a tool like that but for SQL and could not find one that fit. That is the whole pitch: a terminal UI where connections, databases, tables and a SQL editor sit in panes you move between with Vim bindings, rather than windows you drag.

The target user is someone who already runs their database work from a shell. If you keep a terminal open next to your editor, the cost of switching to a GUI client is real, and lazysql removes it. It manages multiple connections, opens tabs, and puts a SQL editor behind CTRL + e. The README lists these as the checked features, and the repository layout matches: there are drivers/, components/, keymap/ and app/ directories, so the keybindings and the provider drivers are separate packages rather than one file.

The author is direct about the project's stage. The README calls it ALPHA and invites complaints about the spaghetti code, and states that he uses lazysql daily in a full-time job in its current buggy state. Take that at face value. This is a tool with a single primary maintainer, a recent release cadence (v0.5.7 on 2026-09-11, v0.5.8 and v0.5.9 on 2026-09-22), and a last push on 2026-09-22. It is not a product with a support contract.

How lazysql connects: TOML, drivers and the pool

The mechanism is ordinary Go database/sql underneath a TUI. go.mod lists the drivers directly: github.com/go-sql-driver/mysql, github.com/lib/pq for PostgreSQL, github.com/microsoft/go-mssqldb, modernc.org/sqlite and github.com/ClickHouse/clickhouse-go/v2. Those five are what you can actually connect to. Anything else is not in the dependency list, so treat the provider field as limited to what is compiled in.

Configuration is a TOML file with a [[database]] array, one entry per connection, plus an [application] table for defaults. The README shows a Production database entry with Provider = 'postgres', a URL containing ${user} and ${port} placeholders, ReadOnly = true, and a Commands array that runs `ssh -tt remote-bastion -L ${port}:localhost:5432` and waits for the port before connecting. That last part is the most interesting design decision in the file: the connection string can depend on a shell command that has to finish first, which is how you reach a database behind a bastion without a separate tunnel script.

ReadOnly is the safety valve. The README states that when it is true, all mutation queries (INSERT, UPDATE, DELETE, DROP and similar) are blocked. That is a client-side guard, not a database permission, so it protects against your own typo rather than against a compromised credential.

Pool settings live in [application] and can be overridden per database. max_open_connections and max_idle_connections default to 8; an explicit 0 falls back to that default; idle greater than open is rejected. SQLite is special-cased to 1/1 to preserve in-memory database behaviour, ignoring the general pool settings. The sidebar tree depends on DBName: set it and the tree is pinned to one database; omit it and the tree lists every database the connecting user has CONNECT privileges on, which matters on PostgreSQL where the connection string requires a database name even when the same login reaches several.

Installing lazysql and opening your first connection

There are four documented install paths. Homebrew is the shortest on macOS and Linux.

brew install lazysql

If you have a Go toolchain, the README gives the module path directly.

go install github.com/jorgerojas26/lazysql@latest

Windows, macOS and Linux users without either can download a binary from the releases page. Arch users have a third-party AUR package, which the README marks as maintained by the community; the documented commands are `paru -S lazysql` or `yay -S lazysql`, or a manual `git clone https://aur.archlinux.org/lazysql.git` followed by `makepkg -si`.

Once installed, the configuration file location depends on your platform. If XDG_CONFIG_HOME is set, it is ${XDG_CONFIG_HOME}/lazysql/config.toml. Otherwise it is ~/.config/lazysql/config.toml on Linux, ~/Library/Application Support/lazysql/config.toml on macOS, and %APPDATA%\lazysql\config.toml on Windows. The README's example entry looks like this:

[[database]]
Name = 'Development database'
Provider = 'postgres'
DBName = 'foo'
URL = 'postgres://postgres:urlencodedpassword@localhost:5432/foo'

Note the field name: URL, and the password must be URL-encoded. Start lazysql and the connection picker lists that entry. Press `a` to add a connection through the in-app form, or `e` to edit an existing one. Backspace returns to the connection list. From a connection, CTRL + e opens the SQL editor. If you want the sidebar to show every database on the instance rather than just the one in the URL, either delete the DBName line or tick "Show all databases in this instance" in the connection form, which the README says saves the connection with DBName left empty.

The limits the README admits, and the ones it does not

The clearest limitation is stated by the author rather than discovered by you: the project is in alpha and he describes it as buggy. That is unusual candour and it should shape how you use it. Treat lazysql as a convenience layer over a database you can still reach another way. If the TUI hangs, you want a psql or mysql prompt open in another pane.

ReadOnly is a client-side block on mutation statements. It is not a database role and it is not enforced if you run the same query through another client. The README does not claim otherwise, but it is worth being precise: the guarantee ends at the lazysql process.

Provider coverage is bounded by go.mod. There are five drivers. If your database is not MySQL, PostgreSQL, MSSQL, SQLite or ClickHouse, lazysql is the wrong tool, and no amount of TOML will add a driver.

The README documents the pool rules in some detail, including that invalid combinations are rejected, but it does not document what happens when a query exceeds exact_count_timeout_ms or max_query_rows. Those keys appear in the example configuration with values of 200 and 1000, and the surrounding text does not say whether the client truncates the result, falls back to an estimate, or errors. If you plan to run large exploratory queries, that is the first behaviour to check yourself.

Rollback and transaction handling are not described in the README at all. The SQL editor is mentioned as a feature, but there is no section on autocommit, explicit transactions, or what happens to an open transaction when you switch tabs. For a tool you might point at a production database with ReadOnly = true, that silence is the real risk, not the alpha label.

lazysql against Harlequin, and against a plain psql prompt

Harlequin is the obvious comparison, and the one people search for. Both are terminal SQL clients. The difference is in the shape of the thing. Harlequin is a Python application built around a terminal interface with an adapter model, so adding a database means installing an adapter package. lazysql is a single Go binary with the drivers compiled in, so adding a database means recompiling, and installing means one command and no Python environment. If you already manage Python virtualenvs, that difference is small. If you do not, a static binary is a real convenience.

The second difference is configuration. Harlequin takes connection details from the command line and from environment variables in the DuckDB and dbt world it grew out of. lazysql takes a TOML file with named connections, per-connection read-only flags, and a Commands array that can open an SSH tunnel before connecting. That last feature has no equivalent in most terminal clients, and it is the strongest argument for lazysql if your databases sit behind a bastion host.

Against a plain psql or mysql prompt, lazysql buys you a tree view, tabs and fuzzy connection switching, and costs you the maturity of the official client. psql will never surprise you with a rendering bug in the sidebar. It will also never show you a schema tree you can navigate with h/j/k/l. That is the trade, and it is a reasonable one for exploratory work and a poor one for scripted or automated access, where the official CLI is the correct answer.

Licence, maintenance and the cost of upgrading

lazysql is MIT licensed, with the licence text in LICENSE.txt. MIT is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and permission notice travel with it. That is a statement about the licence text, not legal advice; if you are embedding lazysql in a product, read LICENSE.txt yourself.

The dependency tree is where licence review gets more interesting. go.mod pulls in the Azure SDK for Go (github.com/Azure/azure-sdk-for-go/sdk/azidentity and related modules) as indirect dependencies, which is what the MSSQL driver needs for Azure AD authentication. Those arrive transitively and carry their own licences. If your organisation has a strict allowlist, the indirect block in go.mod is the file to scan, not just the top-level requires.

Maintenance cost is the alpha status. The repository shows three releases in September 2026, including two on the same day, and the last push was on 2026-09-22. That cadence means bug fixes arrive quickly, and it also means the surface can move under you. There is no documented upgrade procedure in the README, and no configuration migration note. In practice that means reading the release notes for each version before you upgrade, and keeping a copy of your config.toml, because the file format includes keys such as schema_bulk_load_threshold and exact_count_threshold whose defaults have clearly been tuned over time.

What the repository layout tells you before you install

The top-level directories are worth a minute of your time. drivers/ holds the per-provider code, which is why the set of supported databases is a compile-time decision. keymap/ holds the keybindings, so if a binding annoys you it is a file to edit rather than a setting buried in the TUI. commands/ and components/ are the TUI layer, and app/ is the wiring. There is a docker-compose.yml with mysql, postgres and mssql services that the README labels as a manual database test environment; it expects a LAZYSQL_FIXTURE_PASSWORD environment variable and binds MySQL to 127.0.0.1:3307 and PostgreSQL to 127.0.0.1:5433, with seed SQL mounted from testdata/. If you want to try lazysql without pointing it at anything real, that compose file is the intended route, and the non-standard host ports mean it will not collide with a database already running on your machine.

There is also a .lazysql.example.toml at the repository root. The README's example configuration is the documentation, but that file is the copy you can actually start from. Reading both is faster than guessing at field names, because the README's example shows Name, Provider, DBName, URL, ReadOnly and Commands, while the application table's keys are easy to mistype.

Editorial conclusion

Adopt lazysql if you already live in a terminal, want Vim keybindings and a SQL editor one keystroke away, and are willing to treat it as alpha software that the author states he uses daily in a buggy state. Do not adopt it if you need a stable GUI, a query planner, or a client that documents every behaviour before you rely on it. Before you commit, verify the two things the README leaves open: how rollback and error handling behave, and whether your provider is covered by the drivers listed in go.mod. Then check that the connection you add with `a` in the connection picker saves the DBName you expect.

Frequently asked questions

Official sources

1. Issues
2. jorgerojas26/lazysql on GitHub
3. License: MIT
4. README
5. Releases