yelog/lazydb

LazyDB is a keyboard-first database workspace for the terminal.

LazyDB lets you browse schemas, write and run SQL, inspect relations, manage connection profiles, and expose project-scoped database access to coding agents without leaving your terminal. It is written in Rust and supports PostgreSQL, MySQL, MariaDB, Oracle, SQL Server, SQLite, Redis, and MongoDB. MongoDB uses a document explorer, bounded JSON console, and native BSON/EJSON handling; see the MongoDB guide for current scope and verification limits.

Project status: LazyDB is currently in beta. The core database workspace, connection management, SQL execution, and coding-agent interfaces are usable, but LazyDB is not yet a production-ready replacement for DataGrip.

---

Quickstart

Press F2 anywhere in the workspace to open the global Omni Bar for commands, connections, consoles, tables, and navigation. F1 or ? opens contextual help; F6 opens the console manager; F7 opens SQL execution history; F8 opens notification history; and F9 opens the Update Center. See the Omni Bar guide and the complete keyboard reference.

SQL consoles can be opened without configuring or connecting a database. You can write, format, save, and reopen SQL while offline. Binding a target does not connect automatically; running SQL establishes the selected connection and continues the execution.

Installing and running LazyDB

For a ready-to-use MariaDB instance with broad test data-type coverage, see the MariaDB test database guide.

Run the following on Mac or Linux to install LazyDB

curl -fsSL https://lazydb.yelog.org/install.sh | sh

Linux installers check the release’s published glibc requirement before downloading its archive. See Linux runtime compatibility for how to inspect your system and how the requirement is measured.

Run the following on Windows to install LazyDB:

powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://lazydb.yelog.org/install.ps1.txt -ErrorAction Stop | iex"

After an interactive installation, the installer can open the LazyDB MCP setup wizard. It supports user-level and project-level configuration and shows the target file before writing it. To defer this step, run lazydb mcp setup later, or use --mcp-setup skip with the Unix installer.

The Windows installer supports 64-bit Windows (MSVC), downloads the release metadata and ZIP archive over HTTPS, verifies the SHA-256 checksum, and adds %LOCALAPPDATA%\LazyDB\bin to the user PATH. No administrator privileges are required. Open a new terminal after installation. To install the beta channel, set $env:LAZYDB_CHANNEL = "beta" before running the command.

The command downloads and executes a script from the LazyDB site. The .txt endpoint is generated from the same installer source, but served as text for PowerShell compatibility. Review the installer source if needed, or download the Windows ZIP from the latest GitHub Release.

After installation, configure database access for Claude Code, Codex, or OpenCode from the target project:

lazydb mcp setup

Uninstalling LazyDB

Native installations can be inspected without changes and then removed with the CLI:

lazydb uninstall --dry-run
lazydb uninstall

The default uninstall removes the LazyDB launcher, native releases, current release link, installation metadata, and the PATH block managed by the LazyDB installer. It preserves connection profiles, encrypted credential material, settings, workspace files, SQL files, and unknown files. Use --yes for a non-interactive uninstall. Use --json with --dry-run or --yes for a machine-readable report.

--purge additionally removes the allowlisted LazyDB data files after profile and credential checks. It may remove saved connection definitions, local credential keys, settings, workspace state, and update-check state. Unknown files and database files are preserved. System keyring entries are removed only when they are referenced by valid LazyDB profiles and the native secret store is available:

lazydb uninstall --purge --dry-run
lazydb uninstall --purge

Uninstall does not modify project MCP configuration. Remove the lazydb entry from .mcp.json, .codex/config.toml, or opencode.json[c] in each project before or after uninstall. Homebrew, Cargo, and system-package installations must be removed through their original package manager. Windows uninstall is not provided by the native POSIX command yet. If installation metadata is missing or paths no longer match the recorded native installation, uninstall stops without deleting anything and reports the paths that need manual review.

The setup command uses a project-scoped MCP configuration and denies database writes by default. It does not install a coding agent or copy credentials. Native script installers may offer an opt-in reminder on an interactive first install. Use --mcp-setup skip or LAZYDB_MCP_SETUP=skip for unattended runs; the prompt never changes configuration automatically because the installer does not know which project should receive the MCP entry.

LazyDB can also be installed via Homebrew, Cargo, or by building from source. See

# install using Homebrew
brew install yelog/tap/lazydb

Features

• Database Explorer: Browse databases, schemas, tables, views, indexes, foreign keys, triggers, routines, sequences, and types where supported by the driver. Redis uses a dedicated key-space browser rather than a SQL catalog.
• Users & Roles: Relational connections end their first explorer level with a Users & Roles group listing database users and roles with distinct icons and colours across the Nerd Font, Unicode, and ASCII icon modes. Pressing Enter opens a dedicated, read-only DDL tab titled name@connection that has no Data/DDL selector and reuses the relation DDL editor, so syntax highlighting, scrollbars, mouse selection, and Vim bindings behave identically. PostgreSQL lists cluster roles from pg_roles; MySQL and MariaDB list server accounts with their host; SQL Server lists the bound database’s users and roles; Oracle lists the connection’s service users and roles. SQLite shows an explicit “not supported” notice, Redis has no such group, and passwords or password hashes are never reproduced.
• Capability-aware catalog editor: Explorer a creates supported children and e edits directly selected objects. PostgreSQL exposes the broadest catalog editor (schema, table, column, index, constraints, views, materialized views, sequences, databases, and roles); Oracle, MySQL, MariaDB, SQL Server, and SQLite expose their currently implemented table/view and driver-specific mutation slices. Unsupported operations stay hidden.
• Catalog reconciliation: Explorer r refreshes only the selected target; PostgreSQL relation identities can be rebound after an external table rename, while SQL catalog changes trigger a conservative database-catalog sync.
• SQL workspace: Work with multiple console tabs, Vim-style Normal/Insert modes, search, formatting, syntax highlighting, and catalog-aware completion.
• Safe execution: Run the current statement or full buffer with scoped execution, immutable previews, risk confirmation, cancellation, and read-only safeguards.
• Transactions: Use per-console AUTO or MANUAL transactions on PostgreSQL, MySQL, MariaDB, Oracle, SQL Server, and SQLite sessions, including rollback on cancellation and unknown outcome handling where the driver cannot acknowledge the final state. Redis uses atomic commands and has no SQL transaction UI.
• Relation workspaces: Preview relation data with a bounded 500-row limit, switch between Data and DDL, open DDL in a separate tab, and use staged relation editing where the selected driver advertises it. PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite have adapter mutation paths with operation- level checks; Oracle relation-grid mutation is not advertised. Existing-row update/delete requires reliable primary-key metadata, while insert support depends on the driver’s returning/output/lookup strategy.
• Redis workspace: Browse keys by database and prefix, preview strings and collections with bounded paging, search/filter key spaces, inspect TTL and metadata, and perform native key/value, collection, and TTL mutations where supported.
• Connection profiles: Create, test, save, edit, delete, disconnect, and switch PostgreSQL, MySQL, MariaDB, Oracle, SQL Server, SQLite, and Redis profiles. Profiles can be saved, ad hoc, or scoped to the current project.
• Monitoring dashboard: Inspect read-only status metrics and bounded process data for PostgreSQL, MySQL, and MariaDB, plus Redis instance metrics. SQLite and Oracle do not yet expose dashboard metrics; Redis process rows are not available; SQL Server dashboard and process metrics are gated.
• Credential protection: Use local authenticated encryption by default, or macOS Login Keychain and Linux Secret Service when available.
• Coding-agent access: Use project-aware JSON CLI commands or a local stdio MCP server from Codex, OpenCode, or Claude Code.
• Neovim integration: Run the standalone lazydb.nvim floating-terminal plugin with one LazyDB process per Neovim tab.
• Terminal-native UI: Use keyboard navigation, mouse hit regions, truecolor themes, responsive 80-column focus mode, configurable motion feedback, and mouse drag selection in rendered text views. Explicit copy commands/buttons copy complete cell, row, SQL, or detail values where documented; drag alone never writes to the clipboard.
• External themes: Pass --theme-file path/to/theme.json to load and watch a theme-file-v1 JSON theme. Invalid or unavailable files keep the built-in theme, and --color never always takes precedence.

See the configuration guide for the complete theme-file protocol, limits, fallback behavior, and Neovim plugin configuration.

Supported Databases

MariaDB shares the MySQL-compatible transport but has its own product/version gates. Current support includes SQL execution, transactions, monitoring, database-is-schema catalog browsing, CHECK metadata, native trigger DDL, and sequence catalog discovery. Relation grid editing, column/index/constraint mutation, routine/event management, system-versioned history operations, and MariaDB-specific authentication options remain gated. See the complete database capability matrix for metadata, paging, relation DDL, and version details.

Oracle uses the native Oracle client rather than SQLx. The default build includes the Oracle adapter, but a working Oracle Instant Client is still required at runtime. Redis is a supported non-relational driver with a separate browser and native command model; SQL Editor, SQL transactions, and relational catalog DDL do not apply to Redis.

Coding-Agent Access

LazyDB exposes the same native database adapters through a machine-readable JSON CLI and a local stdio MCP server. Agent-visible profiles come from the current Git project and global profiles. Profiles assigned only to other projects are hidden.

Read-only agent workflow:

lazydb agent connections --project .
lazydb agent context --project .
lazydb agent schema-search users --project . --connection orders-dev
lazydb agent query --project . --connection orders-dev \
  --sql 'SELECT * FROM users LIMIT 20'

Create a saved, project-scoped connection without opening the TUI (provide the password through the environment, not the URL or process arguments):

lazydb connections add --name orders-dev \
  --url 'postgresql://app@localhost:5432/orders' \
  --scope project --project . --password-env ORDERS_DB_PASSWORD --json

For SQL files, use an explicitly supplied project-relative path:

lazydb agent execute --project . --connection orders-dev \
  --file db/migrations/001.sql --write-policy non-production

The MCP server defaults to --write-policy deny. Database roles and grants remain the final authorization boundary; client-side MCP approval does not relax LazyDB or database permissions. See Coding-Agent Database Access for Codex, OpenCode, Claude Code, permissions, and troubleshooting.

Neovim Integration

yelog/lazydb.nvim starts the LazyDB executable in a floating terminal. Install the CLI first, then add the plugin with lazy.nvim:

return {
  {
    "yelog/lazydb.nvim",
    cmd = { "LazyDB", "LazyDBToggle", "LazyDBHide", "LazyDBStop", "LazyDBRestart" },
    opts = {
      executable = "lazydb",
      window = { width = 0.92, height = 0.90, border = "rounded" },
    },
  },
}

Use :checkhealth lazydb to verify the executable and CLI API. See the plugin repository for native package installation and the complete command reference.

The standalone LSP supports profile-backed catalog completion for Neovim. It replaces only the current identifier segment, so accepting sys_user inserts sys_user rather than an automatically generated full path. After typing a dot, completion navigates the next catalog level: database. lists schemas, database.schema. lists tables/views, and schema. resolves inside the active database. Candidate details show the database/schema source for ambiguous names; visible aliases such as u. load their relation columns on demand.

The exact path syntax follows the selected profile dialect. SQL Server supports three-part names, MySQL folds its database/schema mirror, SQLite uses attached database names such as main, and PostgreSQL does not present ordinary cross-database paths. MariaDB follows the MySQL database-as-schema model; Oracle uses service/owner scope; Redis completion is not SQL identifier completion. Profile catalog_scope and database permissions remain the visibility boundary.

Run the standalone server with:

lazydb lsp --stdio --project . --dialect postgres

The LSP provides offline SQL/MyBatis syntax diagnostics and completion, plus profile-backed catalog completion when a project/profile can be resolved. It does not execute SQL or infer application-language types. See the SQL language-server notes for the protocol boundary and troubleshooting details.

The footer and help view show contextual controls for the active context and mode. See the complete keyboard reference for the operational contract, including the distinction between application Space commands in Explorer/Results and editor Space/\\ commands in SQL Editor Normal/Visual mode, as well as profile, relation, result-grid, search, and confirmation controls.

Configuration

Connection profiles, the local credential key, and workspace state are stored in ~/lazydb/ on macOS and Linux by default. Existing installations continue to use their current root during upgrades. Set LAZYDB_CONFIG_HOME to use another directory for these files. For example, to keep using the previous macOS location:

export LAZYDB_CONFIG_HOME=$HOME/lazydb

Existing users are not moved automatically. After reviewing the plan, move a complete Unix application root with lazydb migrate-home --to "$HOME/lazydb" --dry-run, followed by the same command with --yes.

This changes the configuration root; it does not automatically copy connection profiles from the default directory. If profiles use local encrypted credentials, keep the matching credential.key with connections.toml when migrating them.

Windows continues to use %APPDATA%\\lazydb\\. The directory contains settings.toml, connections.toml, credential.key, workspace.toml, and the sql/ directory for persisted console text. Use --config PATH to select a different profile file for the current run; this does not relocate the key or workspace files. The complete built-in application defaults are in config/default.toml. This file is embedded into the binary and is the authoritative source of defaults; a user settings.toml only needs to contain overrides. Explicit command-line options take precedence.

Clipboard writes use the system clipboard by default. Set [terminal.clipboard].backend = "osc52" in settings.toml to send OSC 52 sequences instead, or use "off" to disable clipboard writes. max_bytes limits the encoded OSC 52 payload and oversized values are rejected rather than truncated. Ctrl-Shift-s releases mouse capture for terminal-native selection; Esc restores it. Ctrl-c remains the quit key outside context-specific cancellation. Terminal, SSH, and tmux clipboard behavior is environment-dependent and requires manual QA in the actual terminal path. Common options include:

lazydb --profile NAME
lazydb --read-only --profile NAME
lazydb --icons ascii
lazydb --motion reduced
lazydb --mouse off

Use --icons unicode or --icons ascii for terminals without Nerd Font support. Use --motion reduced or --motion off to reduce or disable loading animation. These display options apply to the current process only.

Read the complete Configuration Guide for every command-line option, configuration and workspace file, connection-profile field, default value, project scope, password provider, TLS mode, and read-only behavior.

The CLI also exposes machine-readable version, capabilities, and doctor commands, the JSON agent interface, mcp serve/setup/doctor, lsp --stdio, native update, safe uninstall, and migrate-home. Use --json on the commands that document a JSON report contract. Agent and MCP writes default to denied; see Coding-Agent Database Access.

Current Limitations

The following capabilities are not available yet or are intentionally gated:

• Automatic recovery-bundle export for a corrupted or partially unreadable workspace; normal console/tab persistence and console renaming are supported
• Oracle relation-grid editing and any relation operation whose adapter cannot reliably return or locate the affected row; relation operations remain capability-gated by metadata, permissions, driver strategy, and snapshot freshness
• Query plans
• SSH tunneling
• Import and export
• Windows Integrated Authentication, Kerberos, Entra authentication, Named Instances, and SQL Browser discovery for SQL Server
• SQL Server dashboard/process metrics and several specialized SQL Server types
• Advanced Oracle LOB metadata and Oracle cancellation; cancelling Oracle work is not advertised as a cancellable operation

SQL Server currently uses SQL username/password authentication over an explicit TCP host and port. Windows Integrated Authentication, Kerberos, Entra authentication, Named Instances and SQL Browser discovery are deferred. SQL Server Dashboard metrics, process metrics, and additional specialized type handling are also deferred. Cancelling SQL Server work closes the active session; if that session has an open transaction, SQL Server rolls it back.

The project is evolving quickly during beta. See the issue tracker and release notes for current priorities and version-specific changes.

Documentation

Development

Run the standard local checks before opening a pull request:

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo build --release

The test suite covers database adapters, catalogs, connections, workspace behavior, CLI behavior, and coding-agent access boundaries.

Security

• Passwords are never stored in plain text connection URLs.
• Saved credentials use local authenticated encryption or a native OS secret store when configured.
• Read-only mode is enforced by the adapter where supported; use a database role with read-only grants for the actual authorization boundary.
• MCP write access is denied by default.
• Database and user-provided error text is sanitized before terminal display.

For the detailed security model, see Configuration and Coding-Agent Database Access.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.