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.

• 30+ databases — MySQL, PostgreSQL, Oracle, SQL Server, ClickHouse, MongoDB, Redis, SQLite, MariaDB, TiDB, Hive, DB2, Snowflake, BigQuery, Elasticsearch, and more via plugins.
• SQL workspace — editing, completion, formatting, execution, saved SQL, and execution history.
• AI assistant — bring your own AI model to generate, explain, and optimize SQL in natural language.
• Database management — browse metadata, manage tables and objects (DDL/DML), and edit data in place.
• Data import and export, dashboards and charts, and an open-source CLI with MCP support.

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, 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:

• To update, pull the new image, remove the old container, and run the start command again. Keep ~/.config/chat2db-community/encryption.key across rebuilds.
• The docker run example stores application data in $HOME/.chat2db-community-docker; the Compose definition uses the chat2db-community-data named volume. These locations do not share data.
• Chat2DB Community 5.3.0 uses the independent /root/.chat2db-community directory and does not automatically migrate data from earlier images that used /root/.chat2db.

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.

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.

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

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.

Build from Source

Prerequisites

• Java runtime: Eclipse Temurin 17
• Node.js 18.17.0 or later
• Maven 3.8 or later

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:

• BigQuery — Google BigQuery via a Google Cloud service account.

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.

Contributing

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

• For bugs and feature requests, please use GitHub Issues.
• For questions, setup help, and open-ended discussions, please use GitHub Discussions.
• If your pull request is related to an issue, please link it in the PR description.

Community and Support

• GitHub Issues: report a bug or request a feature
• GitHub Discussions: ask questions and share ideas
• Discord: join our Discord server
• Email: Chat2DB@ch2db.com

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.