Chat2DB README

The project's README from github.com/OtterMind/Chat2DB. As one markdown file: README.md.

Chat2DB
Powered by OtterMind

An AI-powered database client and SQL workspace for developers, DBAs, analysts, and data teams.

README in English 简体中文版自述文件 日本語のREADME README en español 한국어 README

What is Chat2DB?

Chat2DB Community is a free, cross-platform database client for Windows, macOS, and Linux. It runs entirely on your machine and combines a full-featured SQL workspace with an AI assistant that you connect to your own model.

Chat2DB workspace with SQL editor and AI assistant — click to watch the intro video

Screenshots

Dashboards and charts ER diagrams
Dashboards and charts ER diagram
Visual data management Data import and export
Visual data management Data import and export

Quick Start

Option 1: Desktop App

Download the installer for your platform from GitHub Releases, install it, and start connecting to your databases. No further setup is required.

Option 2: Docker

Requirements: Docker 19.03.0+, Docker Compose 2.0.0+ (Compose V2, only for the Compose variant), 2+ CPU cores, 4+ GiB RAM.

First create the encryption key (see Encryption Key for why it matters), then start the container:

# Run once from a repository checkout. Re-running reuses the same valid key.
git clone https://github.com/OtterMind/Chat2DB.git && cd Chat2DB
./script/security/init-community-encryption-key.sh

docker run --detach \
  --name chat2db-community \
  --restart unless-stopped \
  --publish 127.0.0.1:10825:10825 \
  --volume "$HOME/.chat2db-community-docker:/root/.chat2db-community" \
  --env CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE=/run/secrets/chat2db-community-encryption.key \
  --volume "$HOME/.config/chat2db-community/encryption.key:/run/secrets/chat2db-community-encryption.key:ro" \
  chat2db/chat2db:latest

Then open http://localhost:10825 in your browser.

Alternatively, use the bundled Compose definition:

./script/security/init-community-encryption-key.sh
docker compose --file docker/docker-compose.yml up --detach

Notes:

Security Notes

Chat2DB Community is a single-user, local-first application. It has no user accounts or authorization boundaries between users. Keep the HTTP service bound to 127.0.0.1 or ::1 and do not expose it to other users or untrusted networks.

Custom JDBC drivers are executable Java code — install them only from sources you trust. Imported configuration files, archives, SQL files, database contents, and AI responses remain untrusted data. See the Security Policy for the complete trust boundary and vulnerability reporting process.

If you find this project useful, please give us a Star ⭐️ — it really helps!

Star Chat2DB on GitHub

Encryption Key

Chat2DB Community encrypts stored datasource passwords and AI model API keys with AES-256-GCM using a per-installation key. Create it once from a repository checkout (requires openssl):

./script/security/init-community-encryption-key.sh

The key is written to ~/.config/chat2db-community/encryption.key. Back this file up separately and keep it across upgrades and container rebuilds — replacing or losing it makes previously stored datasource passwords and AI model API keys unreadable. Web/headless startup fails when no valid key is provided; only Desktop mode creates a missing key automatically.

Key configuration reference (custom paths, resolution order, validation)

The key must be valid Base64 that decodes to exactly 32 bytes. The bundled initializer generates the standard padded form: 44 Base64 characters ending in =. It is cryptographic key material, not a human-readable password. Datasource passwords and AI API keys use the same key with separate authenticated AAD values, so ciphertext from one purpose cannot be decrypted as the other.

To use a custom path, pass it to the script and configure the same path when starting Chat2DB:

./script/security/init-community-encryption-key.sh /secure/path/chat2db-community.key

java -Dloader.path=chat2db-community-server/chat2db-community-start/target/lib \
    -Dchat2db.runtime.mode=community \
    -Dchat2db.mode=WEB \
    -Dchat2db.gui=false \
    -Dchat2db.network.status=OFFLINE \
    -Dchat2db.community.encryption-key-file=/secure/path/chat2db-community.key \
    -Dserver.address=127.0.0.1 \
    -Dserver.port=10825 \
    -jar chat2db-community-server/chat2db-community-start/target/chat2db-community.jar

The script's key-file path priority is the positional argument, CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE, then the default path. It reuses a valid regular file, rejects symbolic links and non-regular files, and refuses to overwrite an invalid file. Keep the key readable only by the Chat2DB process owner.

Key configuration is resolved in this order:

  1. JVM property chat2db.community.encryption-key containing the Base64 key.
  2. Environment variable CHAT2DB_COMMUNITY_ENCRYPTION_KEY containing the Base64 key.
  3. JVM property chat2db.community.encryption-key-file containing a key-file path.
  4. Environment variable CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE containing a key-file path.
  5. Default file ~/.config/chat2db-community/encryption.key.

The first configured value is authoritative. A blank value, malformed Base64, a key that does not decode to 32 bytes, or an invalid key file fails startup instead of falling through to the next source. File-based configuration is recommended because it avoids placing the key value directly in process arguments or environment variables.

Automatic key-file creation depends on chat2db.mode, not chat2db.gui. Community Desktop mode (chat2db.runtime.mode=community with chat2db.mode=DESKTOP) creates the selected key file when no inline key is configured and the file is missing. Any non-Desktop mode, including normal Web/headless startup, never creates a missing key and fails until a valid key is provided or initialized. The resolved key is cached for the process lifetime, so changing key configuration requires an application restart.

Build from Source

Prerequisites

Clone the Repository

git clone https://github.com/OtterMind/Chat2DB.git

Frontend

Use Yarn with the checked-in lockfile.

cd Chat2DB/chat2db-community-client
yarn install --frozen-lockfile
yarn run start:community:hot

Backend

cd Chat2DB
mvn -B clean package -Dmaven.test.skip=true -Dchat2db.finalName=chat2db-community \
    -f chat2db-community-server/pom.xml \
    -pl chat2db-community-start -am
./script/security/init-community-encryption-key.sh
java -Dloader.path=chat2db-community-server/chat2db-community-start/target/lib \
    -Dchat2db.gui=false \
    -Dchat2db.runtime.mode=community \
    -Dchat2db.mode=WEB \
    -Dchat2db.network.status=OFFLINE \
    -Dchat2db.community.encryption-key-file="$HOME/.config/chat2db-community/encryption.key" \
    -Dserver.address=127.0.0.1 \
    -Dserver.port=10825 \
    -Dspring.profiles.active=dev \
    -jar chat2db-community-server/chat2db-community-start/target/chat2db-community.jar

Build a Local Docker Image

./docker/docker-build.sh 5.3.0 chat2db/chat2db:5.3.0

Database guides

Step-by-step guides for connecting Chat2DB Community to specific databases:

Community vs Commercial Editions

The Community edition contains the full local database client described above, including custom AI model support. The commercial Pro and Enterprise editions build on the same core and add hosted AI services, user accounts, cloud storage and multi-device sync, and team collaboration and governance features. See chat2db.ai for details.

Contributing

We welcome bug reports, feature requests, documentation improvements, testing feedback, and pull requests from the community.

Before opening an issue or submitting a pull request, please read our Contributing Guide. It explains how to report bugs, suggest improvements, and make contributions easier for maintainers to review.

Community and Support

Acknowledgments

Thanks to everyone who has contributed to Chat2DB.

Chat2DB contributors

License

Chat2DB Community version 5.3.0 and later is available under the license terms in this repository. This is a source-available license based on the Apache License 2.0 with additional conditions. Chat2DB releases published before version 5.3.0, including version 0.3.7 and the earlier historical tags, remain under the Apache License 2.0.

Chat2DB (OtterMind/Chat2DB)

Searching Database…

28.3K ·GitHub
Chat2DB
Что это такое?Chat2DB — это бесплатный кроссплатформенный клиент для баз данных и SQL-редактор, который работает локально. Он подойдёт разработчикам, администраторам баз данных, аналитикам и командам, работающим с данными. Внутри — полноценный SQL-клиент плюс AI-ассистент, к которому можно подключить свою собственную модель.
Это десктопное приложение или веб-сервис?И то и другое, плюс ещё и CLI: есть установщики для Windows, macOS и Linux, Docker-образ с веб-интерфейсом, а также открытый CLI. Всё работает локально на вашем компьютере.
Как его запустить?Проще всего поставить десктопную версию: скачайте установщик для своей платформы со страницы GitHub Releases, установите и подключайтесь — больше ничего настраивать не нужно. Как вариант, можно запустить Docker-образ (нужен Docker 19.03+, 2+ ядра процессора и 4+ ГиБ оперативной памяти) и открыть веб-интерфейс в браузере.
Есть ли подводные камни при настройке, о которых стоит знать?Режимы Docker, web и headless не запустятся, пока вы не создадите ключ шифрования входящим в комплект скриптом; только в Desktop-режиме такой ключ создаётся автоматически. Обязательно сделайте резервную копию файла с ключом: если его потерять или заменить, сохранённые пароли к источникам данных и API-ключи AI-сервисов станут нечитаемыми.
Мои данные остаются локально, а можно ли вынести всё на общий сервер?Приложение рассчитано на локальную работу и на одного пользователя: здесь нет ни учётных записей, ни разграничения прав между пользователями. В README прямо сказано, что HTTP-сервис нужно держать привязанным к 127.0.0.1 или ::1 и никогда не открывать его другим пользователям и недоверенным сетям.
Это полностью open source?Строго говоря, уже нет: начиная с версии 5.3.0 используется лицензия source-available на основе Apache 2.0 с дополнительными условиями. Релизы, вышедшие до 5.3.0, по-прежнему распространяются под Apache 2.0.
Что я могу делать с его помощью, кроме выполнения запросов?Можно просматривать метаданные и управлять таблицами и другими объектами (DDL/DML), редактировать данные прямо в таблице, импортировать и экспортировать данные, смотреть ER-диаграммы, строить дашборды и графики, а также пользоваться автодополнением SQL, форматированием, сохранёнными SQL-запросами и полной историей выполнения.
Чем бесплатная версия Community отличается от платных?В Community входит полноценный локальный клиент, включая поддержку своих AI-моделей. Коммерческие редакции Pro и Enterprise построены на том же ядре, но добавляют хостинговые AI-сервисы, учётные записи пользователей, облачное хранилище с синхронизацией между устройствами, а также функции для командной работы и управления доступом.
Что на практике означает поддержка MCP в CLI?Открытый CLI поддерживает MCP (Model Context Protocol) — стандартный способ подключения AI-инструментов к внешним системам. Благодаря этому агенты для написания кода и другие AI-ассистенты могут работать с вашими базами данных через CLI, а не только через графический интерфейс.
What are similar projects?dbx, GoNavi, tusk, TablePro, dbeaver, beekeeper-studio, tabularis, dsh-data-agent
Which topics is it in?sql-client, database-management, jdbc, sql-editor, text-to-sql, database-gui, oracle, sql-server, database-client, diagram, clickhouse, mongodb
Creator
OtterMind
Size
57.6 MB
Stars
28.3K
Updated
CommitOct 16Releasev5.3.8Oct 09
Age
3y
Commits · 90 Days