dbvr Community, a universal CLI for database querying, is a command-line interface for working with databases. It can act as a standalone CLI application or in conjunction with DBeaver and CloudBeaver. It provides a scriptable way to manage database projects and data sources, inspect metadata, and execute SQL from the terminal.
- Automate database workflows with a terminal-first interface built on top of the DBeaver platform
- Manage projects and data sources without opening a GUI
- Run SQL scripts and ad-hoc queries against supported databases
- Inspect database metadata such as databases, schemas, tables, and DDL
- Integrate with CI/CD and shell scripts using standard command output and files
- Reuse DBeaver ecosystem support for drivers and data-source handling
projectcommands for creating, listing, renaming, deleting, and selecting default projectsdatasourcecommands for creating, viewing, listing, updating, moving, and deleting data sourcessqlcommand to execute SQL from a literal query, a file, or standard inputmetacommands for working with database, schema, and table information
To build this repository locally, you need:
- Java
- Maven
- Local sibling checkouts of dependencies referenced by
project.deps:dbeaver-commondbeaver
The root Maven build inherits from ../dbeaver, and the product aggregate also includes sibling modules from ../../../dbeaver-common and ../../../dbeaver.
dbvr is built together with sibling repositories. Clone all of them into the
same parent directory, so the relative paths in the Maven/Tycho build resolve
correctly
git clone https://github.com/dbeaver/dbeaver-common.git
git clone https://github.com/dbeaver/dbeaver.git
git clone https://github.com/dbeaver/dbvr.git
git clone https://github.com/dbeaver/idea-rcp-launch-config-generator.git
git clone https://github.com/dbeaver/dbeaver-osgi-common.gitmvn -f product/aggregate/pom.xml \
-Dheadless-platform \
-Pproduct-dbvr-ce \
-Dbuild.all-environments \
packageThe Windows product can be wrapped into an NSIS installer, matching the official
Windows .exe distribution style. Build all environments first, install NSIS,
and provide an extracted Windows x64 JRE if you want an offline installer that
does not require Java to be installed separately:
brew install nsis aria2
mvn -f product/aggregate/pom.xml \
-Dheadless-platform \
-Dbuild.all-environments \
-Pproduct-dbvr-ce \
package
aria2c -x 8 -s 8 -k 1M \
-o temurin-21-windows-x64-jre.zip \
'https://api.adoptium.net/v3/binary/latest/21/ga/windows/x64/jre/hotspot/normal/eclipse?project=jdk'
unzip temurin-21-windows-x64-jre.zip -d /tmp/temurin-21-windows-x64-jre
DBVR_WINDOWS_JRE=/tmp/temurin-21-windows-x64-jre/jdk-21.0.11+10-jre \
scripts/build-windows-installer.shThe installer is written to:
product/community/target/installers/dbvr-ce-26.1.2-windows-x86_64.exe
To generate IntelliJ IDEA project files and RCP launch configurations, run from the dbvr repository root:
./generate_workspace.shOn Windows, use generate_workspace.cmd.
Then run
cd ../dbeavermvn generate-sourcesThe packaged product creates a dbvr executable for Linux and Windows, and a dbvr.app bundle for macOS.
After building or downloading a packaged distribution, add the executable to your PATH and run:
dbvr --helpdbvr --helpCreate a project:
dbvr project create --name MyProject --description "This is my project"List projects:
dbvr project listSet the default project:
dbvr project default MyProjectdbvr driver listShow driver properties:
dbvr driver list --show-propertiesRun an inline query using an existing datasource:
dbvr sql -ds my-datasource-id -format csv "select * from my_table"Read SQL from a file or standard input:
dbvr sql -ds my-datasource-id -format json --input-file query.sql
cat query.sql | dbvr sql -ds my-datasource -format jsonWrite results to a file:
dbvr sql -ds my-datasource-id -format csv -output-file result.csv "select * from my_table"Examples of supported metadata operations include listing databases, listing tables, and getting DDL for database objects.
dbvr meta database list -ds my-datasource-id
# or
# dbvr meta schema list -ds my-datasource-id ...
# dbvr meta table ddl -ds my-datasource-id -sn=public -tn=orders ...Exact options and available subcommands may vary by command. Use
dbvr <command> --helpto inspect the current CLI surface.
DBVR can expose selected project data sources to MCP clients such as Claude Desktop or Codex over standard input/output or local HTTP. The server never exposes every data source automatically: create the project-local allow-list at .dbeaver/mcp-aliases.json first, or add entries later through the MCP alias-management tool.
Get the stable data source ID with:
dbvr datasource listThen create .dbeaver/mcp-aliases.json in the target project:
{
"version": 1,
"aliases": [
{
"name": "analytics-ro",
"dataSourceId": "your-datasource-id",
"mode": "read_only",
"schema": "PUBLIC"
},
{
"name": "app-data",
"dataSourceId": "another-datasource-id",
"mode": "read_write"
}
]
}Start the server for that project:
dbvr mcp serve --project MyProjectConfigure the MCP client to launch the same command. For example:
{
"mcpServers": {
"dbvr": {
"command": "dbvr",
"args": ["mcp", "serve", "--project", "MyProject"]
}
}
}Aliases are case-insensitive and use data source IDs so renaming a DBeaver data source does not change access. The optional schema field stores a default schema name for metadata tools such as dbvr_list_tables and dbvr_get_table_ddl; explicit tool arguments still override it. read_only aliases accept only non-locking SELECT; read_write aliases additionally accept INSERT, UPDATE, DELETE, and MERGE. DDL, transactions, calls, and multi-statement SQL are rejected for every alias. Query results default to 200 rows and are capped at 1000 rows.
Once the server is running, MCP clients can also manage the alias allow-list:
dbvr_list_datasourceslists project data sources that can be bound to aliases. It returns IDs, names, drivers, and non-secret connection location fields, but never credentials.dbvr_add_alias(name, dataSourceId, mode, schema?)appends a new alias to.dbeaver/mcp-aliases.json, validates that the data source exists, rejects duplicate alias names case-insensitively, and makes the alias available immediately in the current MCP process.modemust beread_onlyorread_write.
Example MCP tool arguments:
{
"name": "kingbase-readonly",
"dataSourceId": "kingbase-jdbc-19f01af7801-73a684353728aa07",
"mode": "read_only",
"schema": "ADMS"
}For repeated calls from the same machine, run the server with the loopback-only HTTP transport. It remains running until stopped and keeps MCP-opened database connections for its lifetime:
dbvr mcp serve --transport http --host 127.0.0.1 --port 8765 --project MyProject --token choose-a-long-random-tokenThe endpoint is http://127.0.0.1:8765/mcp. --token is optional but recommended; send it as an Authorization: Bearer … header in the MCP client. The HTTP transport rejects non-loopback bind addresses, so it does not provide remote database access.
For Codex, keep the token in an environment variable and register the Streamable HTTP endpoint once:
export DBVR_MCP_TOKEN=choose-a-long-random-token
codex mcp add dbvr --url http://127.0.0.1:8765/mcp --bearer-token-env-var DBVR_MCP_TOKENCodex can then reuse the running HTTP server instead of starting a new JVM for each query.
- Open an issue in this repository: https://github.com/dbeaver/dbvr/issues
- Browse DBeaver resources and related platform documentation: https://github.com/dbeaver
- Use command help locally with
dbvr --helpordbvr <command> --help
This project is maintained by the DBeaver team and contributors.
Licensed under the Apache License 2.0.