masumedb/masume

Engines: PostgreSQL, MySQL, MariaDB, SQL Server, ClickHouse, SQLite, Cassandra, ScyllaDB, Redis, MongoDB, and hosted services such as Neon, Supabase, PlanetScale, Turso, Redshift, and Amazon DocumentDB. See the full list.

mise

mise use -g github:masumedb/masume@latest

Update: mise upgrade github:masumedb/masume

npm (npx masume runs without installing)

npm install -g masume

Update: npm update -g masume

Go (Go 1.27 or later)

go install github.com/masumedb/masume@latest

Update: run the same command again.

Homebrew

brew install masumedb/tap/masume

Update: brew upgrade masumedb/tap/masume

Scoop

scoop bucket add masumedb https://github.com/masumedb/scoop-bucket
scoop install masumedb/masume

Update: scoop update then scoop update masume

Script (installs to ~/.local/bin)

curl -fsSL https://raw.githubusercontent.com/masumedb/masume/master/install.sh | sh

Update: run the script again. masume does not update itself.

Debian and Ubuntu

sudo dpkg -i masume_<version>_linux_<arch>.deb

Update: install the newer package with the same command.

Fedora and RHEL

sudo rpm -i masume_<version>_linux_<arch>.rpm

Update: sudo rpm -U masume_<version>_linux_<arch>.rpm

Alpine (the packages are unsigned)

sudo apk add --allow-untrusted masume_<version>_linux_<arch>.apk

Update: install the newer package with the same command.

From source

git clone https://github.com/masumedb/masume.git
cd masume
mise install
mise run install

Update: git pull, then mise run install.

The packages and archives are on the releases page. For an archive, unpack the tar.gz, or the zip on Windows, and put masume on the PATH.

masume

masume opens the connection picker. n adds a profile, and Enter connects. Ctrl+N returns to the picker from a connection. ? shows the keys, and Ctrl+K opens the command palette. When $DATABASE_URL is set, masume opens that connection instead.

A connection can also come from the command line:

• masume postgres://ada@127.0.0.1:5432/shop opens a URL.
• masume ./notes.db opens a SQLite file.
• masume --detect lists the databases in running Docker or Podman containers and in the pods of the current kubectl context.

The first interactive run creates a starter configuration file. A profile can also be written by hand:

[profile.shop]
engine   = "postgres"
host     = "127.0.0.1"
port     = 5432
database = "shop"
user     = "ada"
auth     = "prompt"
env      = "dev"
mode     = "write"

auth = "prompt" prompts for the password at connection time. The password is kept only in memory unless it is saved to the keyring. See configuration for every setting.

The explorer lists the database objects. Table views show data, columns, indexes, constraints, DDL, and query plans. An ER diagram shows a table and the tables linked to it by foreign keys.

The editor has syntax highlighting and completion from the database catalog. Local checks, and server checks where the engine supports them, mark errors before execution. A statement with :name placeholders opens a form for the values. Query plans are drawn as a tree with estimated or measured costs.

Query history and saved queries keep the statements. MongoDB takes a subset of shell syntax, Redis takes commands, one per line, and Cassandra takes CQL with the keyspace as the schema.

• Tabs: query, table, notebook, and query builder tabs. The next connect restores them with their text, sort, and filters. See tabs and history.
• Split view: two tabs side by side or stacked, from one connection or from two. See split view.
• Query builder: tables, joins, filters, groups, and sorts drawn as a diagram, with the SQL under it. See query builder.
• Command palette: every command by name, with its key. Ctrl+K opens it.
• Keys and mouse: every key can be rebound. The mouse selects, scrolls, and drags the pane borders. See keys and mouse controls.
• Settings screen: theme, icons, keys, AI, and MCP settings, written to the config file. See settings.

• Grid: sort, filter on the server or on loaded rows, follow a foreign key, or freeze a column. See sorting and filters.
• Staged edits: insert, edit, duplicate, and delete rows in supported tables, then review the SQL before it runs. See editing rows.
• Write plans: row counts and reverse SQL for supported writes. See write plans.
• Transactions: begin, commit, and rollback. With autocommit off, running a statement starts a transaction.
• Masking: hides columns with sensitive names in the grid only. Copies, exports, and value viewers show the original values.
• Copy and export: CSV and JSON files. Clipboard formats also include Markdown, INSERT statements, row JSON, and column IN clauses. See copy and export.
• Import: CSV or JSON into an existing or new SQL table, and JSON documents into a MongoDB collection. See importing files.
• Dump and restore: schema and data as a SQL file. See dump and restore.
• Data search: a text in every column of every table of a schema. See data search.
• Result compare: pin a result and compare another one with it, row by row. See result compare.
• Schema compare: tables, columns, indexes, and constraints of two schemas, on one connection or two. See schema compare.
• Server dashboard: sessions and metrics the engine supports. See server activity.

A notebook contains cells of prose, values, statements, and charts on one connection. Each cell keeps its result and its view. A notebook is a Markdown file, and masume nb run runs it. See notebooks.

The AI chat uses the current connection and asks for confirmation before each query, including reads. It works with Anthropic, OpenAI, Grok, and OpenAI-compatible providers, or a coding agent such as Claude Code. [ai] enabled = false hides the chat. See AI chat.

masume --mcp serves the allowed profiles to an external agent over stdio. It opens its own connections, with an access level per profile and one for the whole server. See MCP server.

Both use the same database tools with different policies. See security limits.

• Password sources: prompt, keyring, environment variables, commands, and named secret stores. Profile files do not store database passwords. See credentials.
• Read-only profiles: checked in the client, and also enforced by the server on engines that support it. See read-only access.
• SSH tunnels and unix sockets: see SSH tunnel and unix socket.
• Container detection: masume --detect finds databases in running Docker or Podman containers, and in Kubernetes pods through kubectl port-forward. See databases in a container.
• Themes: built-in themes, custom themes, or terminal colours. See themes.

A repository can share connections and saved queries in .masume.toml. masume reads the nearest one in or above the working directory:

[profile.dev]
engine   = "postgres"
host     = "127.0.0.1"
database = "shop"
user     = "shop"
env      = "dev"

[query.recent-orders]
sql         = "select * from orders order by created_at desc limit 50"
description = "the newest 50 orders"

See project file and project security.

masume run -p shop-prod -f json 'select count(*) from orders'
masume run -p shop -e ./reports/daily.sql --param day=2026-09-02
masume run ./notes.db -f csv 'select * from notes limit 100000' > notes.csv
masume run -p shop -f parquet 'select * from orders' > orders.parquet

See headless mode for formats, exit codes, dump, restore, schema compare, and notebooks.

masume                                   open the client
masume TARGET                            open a connection, postgres://you@host/shop
masume --profile NAME                    open a user or project profile
masume --detect                          open detected container and pod databases
masume run [TARGET | -p NAME] STATEMENT  run statements
masume nb run [TARGET | -p NAME] FILE    run a notebook
masume dump [TARGET | -p NAME] FILE      dump schema and data
masume restore [TARGET | -p NAME] FILE   restore a dump
masume diff SOURCE TARGET                compare the schemas of two connections
masume --mcp                             serve allowed MCP profiles
masume --mcp --profile NAME              serve one allowed MCP profile
masume --mcp --check                     check enabled MCP profiles
masume --version                         print the version

A URL query key without a profile key of its own is passed to the driver. See connection targets and driver options.

See CONTRIBUTING.md.

Apache License 2.0. See LICENSE.