Skip to content

Architecture

miudb is one pure-Go static binary (CGO_ENABLED=0 in releases). Three entry points share one service layer, core.Services, which resolves a connection, opens it through an adapter, bounds the result, and logs the call.

miu-db architecture: the miudb CLI, miudb mcp serve, and miudb serve all call core.Services. core.Services resolves the connection ref and secrets from the config store, opens and queries through the adapter registry, saves and fetches extra rows in the page store, and writes events to the activity log. Adapters reach SQLite, Postgres, MySQL, Snowflake, and BigQuery directly, or through an SSH tunnel for Postgres and MySQL when one is enabled.

Click the diagram for the interactive version.

LayerPackageJob
Entrycmd/miudb, internal/cliCobra commands, flags, the miudb.cli/v1 envelope, exit codes, upgrade
Entryinternal/mcpserverMCP stdio tools and resources, read-only guard, allowlist, byte caps, signed cursors
Entryinternal/protocolmiudb serve: JSON-RPC or NDJSON over stdio with call events
Coreinternal/coreServices: the one seam the three entry points call
Configinternal/configConnection store, SecretRef resolvers (keyring, file, gopass, command, env), OAuth token store, redaction
Authinternal/authSnowflake OAuth loopback flow with PKCE
Queryinternal/query, internal/resultRun, script, and page; leftover rows saved under $TMPDIR/miudb-pages
Adaptersinternal/adapter, internal/adapters/*Provider interface and registry; SQLite, Postgres, MySQL, Snowflake, BigQuery
Tunnelinternal/tunnelSSH local forwards for Postgres and MySQL, ~/.ssh/config aliases
Schemainternal/schema, internal/erdSchema tree; ERD introspection (SQLite, Postgres, MySQL), HTML, DBML
Activityinternal/activityJSONL event writer and reader
Clientui/miu-db.nvimNeovim client over miudb serve; SQL stays in normal buffers

Rules that keep the layers honest:

  • Entry points hold no database logic; they call core.Services.
  • Frontends, including the Neovim plugin, never import adapter internals.
  • Raw credentials are never logged or serialized. Errors and envelopes pass through the redaction helpers in internal/config and the output scrubber in internal/cli.
  • New connections store secrets through SecretRef providers, not inline.
  1. The entry point parses input and mints a session id for the activity log.
  2. Store.FindResolved matches the ref (group/name or a unique name) and resolves secrets, refreshing a Snowflake OAuth token when it is within 5 minutes of expiry.
  3. The registry picks the adapter by db_type. Postgres and MySQL open an SSH forward first when the connection has a tunnel.
  4. The query service runs the SQL, keeps the first --limit rows, saves the rest to the page store, and returns page.next_cursor. Per-call --session keys are overlaid on a copy of the connection options, never saved.
  5. The service writes one activity event, and the entry point renders the envelope or MCP result.
AreaChoice
LanguageGo 1.25, module github.com/vanducng/miu-db
CLICobra
MCPmodelcontextprotocol/go-sdk, stdio transport
Driversmodernc.org/sqlite, jackc/pgx/v5, go-sql-driver/mysql, snowflakedb/gosnowflake, cloud.google.com/go/bigquery
Secrets99designs/keyring (encrypted file backend without cgo), optional gopass CLI
Tunnelsgolang.org/x/crypto/ssh
TestsTable tests, JSON Schema contract checks (santhosh-tekuri/jsonschema), env-gated live-DB tests
Releaserelease-please, GoReleaser, Homebrew tap vanducng/tap
DocsAstro Starlight on GitHub Pages