Skip to content
miu-db

Overview

miu-db

miu-db is headless database access for the CLI, MCP hosts, and editor workflows. The miudb binary keeps saved connections, secret resolution, tunnels, adapters, query execution, schema inspection, ERD generation, and machine-readable output in one local Go core.

The user-facing product is miu-db. The command stays miudb.

Start here

Section titled “Start here”
Install Homebrew, go install, Windows zip, and local checkout verification.
Daily driver Add connections, test them, import shared config, and run bounded queries.
Agent CLI Discovery commands, JSON output, and agent-safe database workflows.
MCP server Local stdio tools and resources for Codex, Claude Code, Cursor, and VS Code.
ERD diagrams Interactive offline entity-relationship diagrams plus DBML from MySQL/Postgres.
Authentication Snowflake OAuth, BigQuery ADC, token storage, and secret-handling guarantees.
CLI contract Stable JSON envelopes, bounded query output, pagination, and redacted errors.
System architecture Config, secrets, adapters, tunnels, workers, MCP, and result paging.

What’s inside

Section titled “What’s inside”

Connect and query

Section titled “Connect and query”
  • Native store — Daily driver
    • Config lives under ~/.config/miu/db.
    • Sensitive values are classified before persistence.
    • New credentials use the miudb OS Keychain/keyring service by default.
  • Adapters — Install · Cloud adapters
    • SQLite, PostgreSQL, MySQL, Snowflake, BigQuery, and SSH tunnels.
    • Per-call session context via --session key=value where supported.
  • Query execution — Agent CLI
    • query run for one bounded statement.
    • query script for multi-statement Snowflake/MySQL scripts.
    • Pagination through cursors instead of unbounded stdout dumps.

Agent-ready contract

Section titled “Agent-ready contract”
  • JSON envelopes — CLI contract
    • stdout is data; stderr is diagnostics.
    • Stable miudb.cli/v1 responses for success and typed errors.
    • Redacted connection metadata and bounded result output.
  • MCP server — MCP server
    • miudb mcp serve --transport stdio exposes local tools and resources.
    • Connection allowlists, read-only query defaults, and output byte caps.
  • Schema inspection — Agent CLI
    • Agents can discover command shape with miudb commands and miudb describe.
    • schema_tree gives bounded schema context before writing SQL.

Diagrams and editor workflows

Section titled “Diagrams and editor workflows”
  • ERD diagrams — ERD diagrams
    • Introspect MySQL/Postgres into offline HTML, JSON, and DBML artifacts.
    • Optional agent-authored metadata adds groups and descriptions without touching live data.
  • Neovim client — System architecture
    • ui/miu-db.nvim shells out to the same Go core.
    • SQL stays in normal .sql buffers.

Operations

Section titled “Operations”
  • Activity log — Daily driver
    • Query, exec, and schema operations write JSONL metadata.
    • Result rows are never stored.
  • Deployment — Deployment
    • Single Go binary, Homebrew/GitHub Releases, and a static docs site.
    • Local checkout smoke commands use the same binary path as release builds.

A 30-second tour

Section titled “A 30-second tour”
Terminal window
miudb connections add --name local-app --db-type sqlite --path ./app.db -o json
miudb connections list --basic -o json
miudb connections test local-app -o json
miudb query run -c local-app --sql 'select 1 as one' -o json
miudb schema tree -c local-app -o json
miudb erd generate -c local-app --out-dir ./.miu-db/erd -o json
miudb mcp serve --transport stdio

Every command that agents should call emits compact JSON by default. New here? Start with Install, then connect the local MCP server from MCP server.