{"id":50563240,"url":"https://github.com/vanducng/miu-db","last_synced_at":"2026-06-08T23:01:25.272Z","repository":{"id":360721834,"uuid":"1249991456","full_name":"vanducng/miu-db","owner":"vanducng","description":"A headless database CLI for humans and agents.","archived":false,"fork":false,"pushed_at":"2026-06-04T11:21:36.000Z","size":11887,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T13:14:27.520Z","etag":null,"topics":["bigquery","database","mysql","postgresql","snowflake","sql","sqlite","terminal","textual","tui"],"latest_commit_sha":null,"homepage":"https://miudb.vanducng.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vanducng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T07:53:52.000Z","updated_at":"2026-06-04T11:20:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vanducng/miu-db","commit_stats":null,"previous_names":["vanducng/miu-db"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/vanducng/miu-db","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanducng%2Fmiu-db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanducng%2Fmiu-db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanducng%2Fmiu-db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanducng%2Fmiu-db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vanducng","download_url":"https://codeload.github.com/vanducng/miu-db/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanducng%2Fmiu-db/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34083848,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bigquery","database","mysql","postgresql","snowflake","sql","sqlite","terminal","textual","tui"],"created_at":"2026-06-04T13:00:18.880Z","updated_at":"2026-06-08T23:01:25.266Z","avatar_url":"https://github.com/vanducng.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"miudb logo\" width=\"128\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003emiudb\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003eA headless database CLI for humans and agents.\u003c/p\u003e\n\n`miudb` is the Go core for miu-db. It keeps the database layer focused on\nconnections, credentials, tunnels, adapters, query execution, schema inspection,\nMCP, and machine-readable output.\n\n## Install\n\nOne command, auto-detects OS and architecture.\n\n**macOS / Linux:**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/vanducng/miu-db/main/scripts/install.sh | sh\n```\n\n**Windows** (PowerShell):\n\n```powershell\nirm https://raw.githubusercontent.com/vanducng/miu-db/main/scripts/install.ps1 | iex\n```\n\nBoth honor `MIUDB_VERSION` (pin a release) and `MIUDB_INSTALL_DIR`. Other options:\n\n- **Homebrew** — `brew install vanducng/tap/miudb`\n- **Go** — `go install github.com/vanducng/miu-db/cmd/miudb@latest`\n\nVerify:\n\n```bash\nmiudb version --output json\nmiudb commands --output json\n```\n\nUpgrade in place later (downloads the matching release, verifies its checksum,\nand replaces the binary):\n\n```bash\nmiudb upgrade            # to the latest release\nmiudb upgrade --check    # report whether a newer version exists\nmiudb upgrade --version v0.2.4\n```\n\nAll commands take `-o`/`--output`: `json` (default, compact) or `pretty`.\nHomebrew installs should upgrade with `brew upgrade miudb`.\n\n## Native Store\n\nThe default native config lives under:\n\n```text\n~/.config/miu/db/connections.json\n```\n\nSensitive values are classified before persistence. New connections store\ndatabase and SSH passwords outside `connections.json` by default using the\n`miudb` OS Keychain/keyring service.\n\n```bash\nmiudb connections add \\\n  --name local-app \\\n  --db-type sqlite \\\n  --path ./app.db \\\n  --secret-store keyring \\\n  --output json\n```\n\n```bash\nmiudb connections list --output json\nmiudb connections list --basic --output json   # scannable: ref/name/group/db_type/host\nmiudb connections test local-app --output json\nmiudb query run -c local-app --sql 'select 1 as one' --output json\n```\n\nConnections are addressed by **`group/name`** (e.g. `team/prod-db`) when names\nrepeat across groups; a bare `name` works when it is unique. The `ref` column\nfrom `--basic` is exactly what you pass to `--connection` (short flag `-c`).\n\nUse `--session key=value` (repeatable) to set temporary, per-call session context.\nKeys are provider-specific and rejected when unsupported; they do not persist\nacross calls. For example, switch the Snowflake role for one query:\n\n```bash\nmiudb query run -c snowflake-prod \\\n  --session role=ANALYST_ROLE \\\n  --sql 'select current_role()' --output json\n```\n\n`query run` executes a single statement. To run several statements in one call,\nuse `query script` (Snowflake and MySQL only). It returns `data.results` — an\narray with one entry per statement (`kind` is `rows` or `exec`). Fail-fast by\ndefault; pass `--atomic` to wrap the script in a transaction (DML-only\natomicity). Other datasources are rejected with a clear error.\n\n```bash\nmiudb query script -c snowflake-prod \\\n  --session role=SECURITYADMIN \\\n  --sql \"SHOW USERS LIKE 'alice'; SHOW ROLES LIKE 'analyst'\" --output json\n```\n\nSupported secret stores for new connections:\n\n- `keyring`: OS Keychain/keyring service named `miudb` by default.\n- `file`: `~/.config/miu/db/credentials.json` with mode `0600`.\n- `inline`: keep the value in the connection file.\n- `none`: discard the supplied secret and require another resolver later.\n\nIf `credentials.json` is absent, `miudb` also reads an existing\n`credentials-export.json` in the same directory for migrated connections.\n\nFuture secret providers can plug into the same `SecretRef` model, including\n1Password and Bitwarden.\n\n## Share and Import\n\nTo onboard a new machine or teammate, share a connections JSON file and import\nit. Import merges by name: matching connections are overwritten and the existing\n`connections.json` is backed up first to `connections.json.bak-\u003ctimestamp\u003e`.\n\n```bash\nmiudb connections import ./shared-connections.json --output json\nmiudb connections import ./shared-connections.json --dry-run --output json\n```\n\nSecrets are imported as they appear in the file. A self-contained file with\ninline passwords needs no extra setup on the target machine; treat it as a\nsecret (mode `0600`, secure channel only). Use `--dry-run` to preview the\nadded/overwritten connections before writing.\n\n## OAuth Authentication\n\nSnowflake and BigQuery support token-based authentication with a one-time\ninteractive login. All subsequent queries refresh and use the stored token\nsilently.\n\n**Snowflake** — add the connection once, then log in:\n\n```bash\nmiudb connections add \\\n  --name sf-prod \\\n  --db-type snowflake \\\n  --host \u003caccount\u003e.snowflakecomputing.com \\\n  --username \u003cuser\u003e \\\n  --option authenticator=oauth \\\n  --option oauth_client_id=\u003cclient-id\u003e \\\n  --option oauth_authorization_url=https://\u003caccount\u003e.snowflakecomputing.com/oauth/authorize \\\n  --option oauth_token_request_url=https://\u003caccount\u003e.snowflakecomputing.com/oauth/token-request \\\n  --option oauth_scope=session:role:ANALYST \\\n  --output json\n\nmiudb auth login sf-prod --output json\nmiudb auth status sf-prod --output json\nmiudb query run --connection sf-prod --sql 'SELECT CURRENT_ROLE()' --output json\n```\n\nNo `--password` is required for OAuth connections.\n\n**BigQuery** — authenticate once with gcloud, then add the connection:\n\n```bash\ngcloud auth application-default login\n\nmiudb connections add \\\n  --name bq-analytics \\\n  --db-type bigquery \\\n  --option project=my-gcp-project \\\n  --option dataset=analytics \\\n  --output json\n```\n\nSee [the authentication docs](https://miudb.vanducng.dev/authentication/) for\nthe Snowflake `CREATE SECURITY INTEGRATION` snippet, all option keys, and\nsecret-handling guarantees.\n\n## Adapters\n\nDaily-driver adapters:\n\n- SQLite\n- PostgreSQL\n- MySQL\n- Snowflake (password, JWT, OAuth)\n- BigQuery (ADC, service account)\n\nSSH tunnel-backed connections are supported for TCP adapters.\n\n## MCP\n\nUse miudb as a local stdio MCP server for coding-agent hosts:\n\n```bash\nmiudb mcp serve --transport stdio\n```\n\nThe MCP server exposes redacted connection inventory, schema inspection,\nbounded read-only query execution, pagination, and `miudb://` resources.\n\n### Add to a host\n\n**Claude Code** — one command:\n\n```bash\nclaude mcp add --transport stdio miudb -- miudb mcp serve --transport stdio\n```\n\n**Cursor** — add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):\n\n```json\n{\n  \"mcpServers\": {\n    \"miudb\": { \"command\": \"miudb\", \"args\": [\"mcp\", \"serve\", \"--transport\", \"stdio\"] }\n  }\n}\n```\n\n**Codex** — add to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.miudb]\ncommand = \"miudb\"\nargs = [\"mcp\", \"serve\", \"--transport\", \"stdio\"]\n```\n\nIf the host can't find `miudb`, use the full path from `which miudb`. See\n[the MCP docs](https://miudb.vanducng.dev/mcp/) for VS Code, per-connection\nscoping, and tool reference.\n\n## Activity Log\n\nEvery query, exec, and schema operation is recorded as a JSONL event under:\n\n```text\n~/.config/miu/db/activity/{date}/{session_id}.jsonl\n```\n\nEach line captures SQL text, `sql_shape` (literals replaced with `?`),\nconnection name, group, db\\_type, latency, rows\\_returned count, and error\ninfo. **Result rows are never stored** — only counts and metadata.\n\n### Browse logs\n\n```bash\n# all events from the last day\nmiudb activity --since 1d --output json\n\n# all events for a specific connection\nmiudb activity --connection local-app --since 7d --output json\n\n# only failures\nmiudb activity --failed --since 24h --output json\n\n# reconstruct a full session trace (spans multiple date dirs if needed)\nmiudb activity --session \u003csession_id\u003e --output json\n```\n\n### Prune old logs\n\n```bash\nmiudb activity prune --older-than 30d          # delete dirs older than 30 days\nmiudb activity prune --older-than 30d --dry-run # preview without deleting\n```\n\n### Opt out\n\nDisable for a single invocation:\n\n```bash\nmiudb query run --connection local-app --sql 'select 1' --no-activity-log\n```\n\nDisable globally via environment variable:\n\n```bash\nMIUDB_ACTIVITY_LOG=off miudb query run --connection local-app --sql 'select 1'\n```\n\nDisable per-connection by setting `\"log_sql\": false` in `connections.json`:\n\n```json\n{ \"name\": \"local-app\", \"db_type\": \"sqlite\", \"log_sql\": false, ... }\n```\n\nWith `log_sql: false`, `sql_shape` (normalized, no literals) is still\nrecorded; only the raw SQL text is omitted.\n\n### `--session` flag distinction\n\n`query run --session key=value` sets a temporary, per-call connection context\n(e.g. Snowflake role). This is unrelated to the activity log session\\_id, which\nis a machine-generated identifier minted once per CLI invocation or MCP server\nstart. The flags share a name for historical reasons; renaming one is a\nseparate, deferred decision.\n\n### Power-user SQL path (DuckDB)\n\nFor ad-hoc analytics across all sessions, load the raw JSONL directly in DuckDB:\n\n```sql\nselect session_id, connection, op, sql_shape, latency_ms, rows_returned, ts\nfrom read_json_auto('~/.config/miu/db/activity/**/*.jsonl')\norder by ts desc\nlimit 100;\n```\n\n## Development\n\n```bash\ngo test ./...\ngo build -buildvcs=false -o ./.miu-db/miudb ./cmd/miudb\n./.miu-db/miudb commands --output json\n```\n\nSee [the architecture docs](https://miudb.vanducng.dev/golang-architecture/) and\n[the agent CLI docs](https://miudb.vanducng.dev/agent-cli/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanducng%2Fmiu-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvanducng%2Fmiu-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanducng%2Fmiu-db/lists"}