# sqlit: a lazygit-style TUI for SQL databases

> sqlit puts connection management, a SQL editor, query history and result filtering in one terminal window, with drivers for SQLite, PostgreSQL, MySQL, SQL Server and a long list of others. The interesting part is not the editor, it is the connection layer.

**Maxteabag/sqlit** — A user friendly TUI for SQL databases. Written in python. Supports SQL server, Mysql, PostreSQL, SQLite, Turso and more.

- Repository: https://github.com/Maxteabag/sqlit
- Stars: 4,871 · Forks: 167
- Language: Python
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/maxteabag-sqlit

## What sqlit solves, and for whom

The README states the motivation plainly: the author did not want to install a gigabyte-heavy GUI to run a few queries, and did not want to launch an Electron editor for the same job. The stated target is the developer who wants to query a database from a terminal without their RAM being eaten alive. That framing matters, because it tells you which job sqlit is competing for. It is not competing with a database IDE that offers execution plans, schema diffs or data modelling. It is competing with the habit of opening a heavyweight client, connecting, running one SELECT, and closing it again.

The design borrows its posture from lazygit. The README calls sqlit "the lazygit of SQL databases", and the shape of the tool follows that: you run one command, a picker appears, you choose a saved connection, and you are in. There is a connection manager, a query editor with syntax highlighting and history, a results grid you can filter, and a database browser for tables, views, procedures, indexes, triggers and sequences. Each of those is a feature a GUI would also have. The difference is that all of it is keyboard-driven and starts in the terminal you already have open.

Who is this for, concretely? A backend developer who has four connection profiles (local SQLite, staging Postgres, a MySQL service, a remote SQL Server behind a jump host) and wants to switch between them without retyping credentials. Also a person who occasionally needs to poke at a database they do not own, and would rather not install a client for each engine. The pyproject.toml classifier says "Development Status :: 4 - Beta", so treat it as a tool that works but is still moving.

## How the connection layer actually works

The core mechanism is a saved connection profile plus a driver that is loaded on demand. The dependencies in pyproject.toml split into two groups. The base install pulls in textual, textual-fastdatatable, pyperclip, keyring, docker and sqlparse. Everything engine-specific sits in an optional "all" extra: psycopg2-binary, mssql-python, PyMySQL, oracledb, ibm_db, hdbcli, teradatasql, pyexasol, trino, presto-python-client, google-cloud-bigquery, google-cloud-spanner, duckdb, clickhouse-connect, libsql, firebirdsql, sshtunnel, paramiko, snowflake-connector-python, redshift-connector, pyathena and adbc-driver-flightsql, among others. That split is the whole architecture in one file: the TUI is small, the drivers are heavy, and you only pay for the ones you need.

The README advertises a dependency wizard that auto-installs missing drivers. That is the practical consequence of the split. You install sqlit-tui, try to connect to Oracle, and the tool offers to fetch oracledb rather than making you read the extras list. Two entries in the extras carry comments about minimum versions chosen to avoid known CVEs (duckdb and requests), which is a small but real signal that the author is tracking advisories on the dependency side.

Credentials go to the OS keyring through the keyring package, or can be fetched at connect time with a password command. Docker discovery is a separate path: the docker package is a base dependency, and the README says sqlit finds running database containers and connects on Enter, inferring the details itself. SSH tunnels are handled by sshtunnel and paramiko, so the tunnel is established by sqlit rather than by you. The result is that a connection is a first-class object with a name, and every other feature (history, autocomplete, the query CLI) hangs off that name.

## Installing sqlit-tui and running a first query

The README recommends pipx, and gives uv, pip, AUR and Nix as alternatives. The package name on PyPI is sqlit-tui, not sqlit, which is worth noting because the command you type afterwards is sqlit.

```bash
pipx install sqlit-tui
```

With that done, the fastest way to see the interface is the mock mode. The README gives this example for exploring the UI without a real database:

```bash
sqlit --mock=sqlite-demo
```

You should land in the TUI with a populated demo database. The README says keybindings are shown at the bottom of the screen, so the first thing to check is that bar rather than a help file. When you are ready for a real connection, add one non-interactively. This is the SQLite form, which needs no server:

```bash
sqlit connections add sqlite --name "MyLocalDB" --file-path "/path/to/database.db"
```

For a server-backed engine the flags change. The README's PostgreSQL example passes server, username and password:

```bash
sqlit connections add postgresql --name "MyPostgres" --server "localhost" --username "user" --password "pass"
```

Once a connection exists, the CLI mode runs a query without opening the TUI, and can emit CSV or JSON. The README shows both a string query and a file:

```bash
sqlit query -c "MyConnection" -q "SELECT * FROM Users" --format csv
sqlit query -c "MyConnection" -f "script.sql" --format json
```

The README also documents connecting by URL, where the scheme picks the engine, and a temporary connection that is not saved:

```bash
sqlit postgresql://user:pass@localhost:5432/mydb
sqlit connect sqlite --file-path "/path/to/database.db"
```

That is the whole first-run path. Note that the README does not document a rollback or an undo for connection edits, so treat saved profiles as something you manage deliberately.

## The breadth of engines is also the weak point

sqlit claims support for a very long list: SQL Server, PostgreSQL, MySQL, SQLite, MariaDB, FirebirdSQL, Oracle, DuckDB, CockroachDB, ClickHouse, Snowflake, Databricks, Supabase, CloudFlare D1, Turso, Athena, BigQuery, Spanner, RedShift, IBM Db2, SAP HANA, Teradata, Exasol, Trino, Presto, Apache Flight SQL, Apache Impala, SurrealDB and osquery. That breadth is the selling point and the risk at the same time.

Each engine is a different Python driver with different connection semantics, different type systems and different error surfaces. A TUI can normalise the connection form, and sqlit does: server, port, username, password, database, file path, plus engine-specific flags such as the Athena region and S3 staging directory or the Turso server URL. What it cannot normalise is everything above that. A results grid that handles millions of rows for one driver will behave differently for another, and autocomplete that reads catalog metadata from PostgreSQL may return less for an engine with a thinner information schema. The README does not publish a per-engine feature matrix, so the honest position is that support for an engine means you can connect and query it, not that every feature is equally deep everywhere.

The second limitation is the beta label. pyproject.toml classifies the project as Beta, and the release history shows rapid iteration: v1.6.2 on 2026-08-26, v1.6.3 on 2026-08-27, v1.6.4 on 2026-09-05. Frequent patch releases on a tool that stores your connection profiles means you should expect the profile format to move. The last push to the default branch was on 2026-09-10, and the repository is not archived.

Where is sqlit the wrong tool? Anywhere you need a plan. It is a client, not a profiler; if you are chasing a slow query you want EXPLAIN output in a tool built for it. It is also the wrong choice for a one-off script in CI, where the CLI mode is useful but the TUI-oriented dependency set is not. And if your team mandates a shared, audited query interface, a personal saved-connection file is not that.

## How sqlit differs from a SQLite browser or a full IDE

The obvious comparison for a terminal user is the SQLite command line shell, and the difference is scope rather than approach. The shell is one engine and one file, with no connection manager, no history store, no result filter and no tunnel. sqlit targets many engines behind one interface and adds the surrounding workflow. If you only ever open one SQLite file, the shell is smaller and already installed.

The more interesting comparison is a GUI client such as DBeaver or a SQL extension inside an editor. The README's argument against that class of tool is resource cost and startup time, and it is a fair argument on its own terms: an Electron editor or a large Java client does more than run queries, and you pay for the rest. sqlit's counter-offer is narrower and faster to open. What you give up is the parts of those tools that are genuinely hard to build in a TUI: visual schema diagrams, data export wizards, per-engine administration panels, and the long tail of engine-specific features that a general client accumulates over years.

There is a third category worth naming: the database's own CLI, such as psql or mysql. Those are more capable than sqlit for their own engine, and they are scriptable in ways a TUI is not. sqlit's advantage over them is the shared connection registry and the uniform keyboard model across engines. If you spend your day in psql and never touch another engine, sqlit adds a layer you may not want. If you switch between four engines a week, the uniformity is the point.

## Licence, maintenance and upgrade cost

sqlit is MIT licensed, stated both in the README badge and in pyproject.toml (license = "MIT", plus the OSI classifier). MIT is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and licence text travel with the copies. There is no copyleft obligation on your own code. One thing to be aware of is that the licence covers sqlit, not the drivers it pulls in. psycopg2-binary, oracledb, snowflake-connector-python, google-cloud-bigquery and the rest carry their own licences, and some of those are not MIT. If you are packaging sqlit into a distributed product, the extras list in pyproject.toml is the file to audit, not the top-level licence field. That is a packaging observation, not legal advice.

On upgrade cost, the picture is mixed. The base dependency set is small and pinned where it matters: textual has a floor of 6.10.0, textual-fastdatatable is pinned exactly at 0.19.0, and the rest are minimums. That exact pin on the data table suggests the author has been bitten by a breaking change there, and it means an upgrade of that package is a deliberate act rather than something that happens under you. The engine drivers are all minimum-version constraints, so a fresh install can pick up newer drivers than the author tested. If you depend on one engine, pin its driver yourself.

The project is not archived and the last push was on 2026-09-10, with three releases in the two weeks before that. There is a CONTRIBUTING.md, a flake.nix and a flake.lock for Nix users, an aur/ directory for Arch packaging, and a tests/ directory. The README does not document a deprecation policy or a compatibility guarantee for saved connection profiles, so an upgrade that rewrites the profile format is a possibility you should plan for by keeping the connection details somewhere you control.

## Conclusion

Adopt sqlit if you already live in a terminal and want one place to hold connection profiles, SSH tunnels and a query scratchpad across several engines. Do not adopt it as a replacement for a schema migration tool, a query planner or a DBA console; it is an interactive client. Before committing, verify that the driver for your engine is in the optional-dependencies list in pyproject.toml, that your target version of Python is 3.10 or newer, and that an SSH tunnel profile actually connects from your network, since the README documents the flags but not the failure behaviour.

## FAQ

### How do I install sqlit?

The README recommends pipx install sqlit-tui, and also lists uv tool install sqlit-tui, pip install sqlit-tui, yay -S sqlit on Arch and nix run github:Maxteabag/sqlit. The PyPI package is sqlit-tui while the command you run afterwards is sqlit.

### Which databases does sqlit support?

The README lists SQL Server, PostgreSQL, MySQL, SQLite, MariaDB, FirebirdSQL, Oracle, DuckDB, CockroachDB, ClickHouse, Snowflake, Databricks, Supabase, CloudFlare D1, Turso, Athena, BigQuery, Spanner, RedShift, IBM Db2, SAP HANA, Teradata, Exasol, Trino, Presto, Apache Flight SQL, Apache Impala, SurrealDB and osquery. Engine drivers live in the optional "all" extra in pyproject.toml, and the README mentions a dependency wizard that installs missing drivers.

### Can I run sqlit without connecting to a real database?

Yes. The README gives sqlit --mock=sqlite-demo as a way to explore the UI with mock data before you set up any connection.

### Can sqlit run a query without opening the TUI?

The README documents a CLI mode: sqlit query -c "MyConnection" -q "SELECT * FROM Users" runs a query, and --format csv or --format json changes the output. It also accepts a file with -f instead of an inline query string.

### Where does sqlit store database passwords?

The README says passwords are stored in your OS keyring, and that a password can instead be fetched at connect time with a --password-command such as op read. The keyring package is a base dependency in pyproject.toml.

## Sources

- [Issues](https://github.com/Maxteabag/sqlit/issues)
- [License: MIT](https://github.com/Maxteabag/sqlit/blob/main/LICENSE)
- [Maxteabag/sqlit on GitHub](https://github.com/Maxteabag/sqlit)
- [README](https://github.com/Maxteabag/sqlit/blob/main/README.md)
- [Releases](https://github.com/Maxteabag/sqlit/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/maxteabag-sqlit