Skip to content
Back to search

DBchat

A powerful MCP server that lets you have natural language conversations with your database. Ask it to do complex analysis, generate beautiful visualizations, or build custom interactive dashboards based your data. Works with any JDBC-compatible database with support for most SQL DBs like PostgreSQL, MySQL, Oracle, SQL Server, SQLite, MongoDB, etc

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/skanga--dbchat/badge.svg)](/listings/skanga--dbchat)

HTML

<a href="/listings/skanga--dbchat"><img src="/api/listings/skanga--dbchat/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Step 1: Download DBChat

Download the latest release from [GitHub Releases](https://github.com/skanga/dbchat/releases): - [dbchat-4.2.1-basic.jar](https://github.com/skanga/dbchat/releases/download/v4.2.1/dbchat-4.2.1-basic.jar) - Basic version (PostgreSQL, SQLite, H2, HSQLDB, CSV). We recommend that you start here. - [dbchat-4.2.1-standard.jar](https://github.com/skanga/dbchat/releases/download/v4.2.1/dbchat-4.2.1-standard.jar) - Standard version (add MySQL, MariaDB, ClickHouse) - [dbchat-4.2.1-enterprise.jar](https://github.com/skanga/dbchat/releases/download/v4.2.1/dbchat-4.2.1-enterprise.jar) - Enterprise version (add Oracle, SQL Server, DB2) - [dbchat-4.2.1-cloud-analytics.jar](https://github.com/skanga/dbchat/releases/download/v4.2.1/dbchat-4.2.1-cloud-analytics.jar) - Cloud Analytics version (add Redshift, Snowflake, BigQuery) - [dbchat-4.2.1-all.jar](https://github.com/skanga/dbchat/releases/download/v4.2.1/dbchat-4.2.1-all.jar) - All databases included (400MB+)

In the examples below, replace `<variant>` with the jar you downloaded, such as `basic`, `standard`, `enterprise`, `cloud-analytics`, or `all`.

For a hands-on walkthrough after setup, see [TUTORIAL.md](TUTORIAL.md) and if you only want to see the results of a sample TUTORIAL run then see [TUTORIAL-DEMO.html](http://htmlpreview.github.io/?https://github.com/skanga/DBchat/blob/main/TUTORIAL-DEMO.html). For visualization-focused usage patterns, see [VISUALIZATION.md](VISUALIZATION.md).

NOTE: Advanced users can also build a custom jar with only the drivers you need. See [INSTALL.md](INSTALL.md) for details.

IMPORTANT: Make sure that you are properly LICENSED to use any JDBC driver you install. The DBChat license does not cover any third party code or binaries.

Step 2: Install Claude Desktop (similar setup for any other MCP client)

1. Download [Claude Desktop](https://claude.ai/download) (free) 2. Sign in with your Claude account 3. **Important**: The Claude website does not support MCP. For MCP with Anthropic models you need to use Claude Desktop or Claude Code.

Step 2 (alternate):

If you are not using Claude Desktop but want to use another MCP client like Cursor, Windsurf, VS Code, Continue, etc then please refer to the [MCP Setup](MCP-SETUP.md) document for more details

Step 3: Set Up Your Database Connection

Create a configuration file `dbchat.conf`:

# Basic database connection
DB_URL=jdbc:mysql://localhost:3306/your_database
DB_USER=your_username
DB_PASSWORD=your_password
DB_DRIVER=com.mysql.cj.jdbc.Driver

# Optional: Enable web interface (not needed for Claude desktop)
HTTP_MODE=false
HTTP_PORT=8080

**Examples for Common/Popular Databases:**

**MySQL:**

DB_URL=jdbc:mysql://localhost:3306/your_database
DB_USER=your_username
DB_PASSWORD=your_password
DB_DRIVER=com.mysql.cj.jdbc.Driver

**PostgreSQL:**

DB_URL=jdbc:postgresql://localhost:5432/your_database
DB_USER=your_username
DB_PASSWORD=your_password
DB_DRIVER=org.postgresql.Driver

**SQLite:**

DB_URL=jdbc:sqlite:/path/to/your/database.db
DB_USER=
DB_PASSWORD=
DB_DRIVER=org.sqlite.JDBC

**H2 database (in memory - no database setup required):**

DB_URL=jdbc:h2:mem:testdb
DB_USER=sa
DB_PASSWORD=
DB_DRIVER=org.h2.Driver

**Oracle:**

DB_URL=jdbc:oracle:thin:@localhost:1521:xe
DB_USER=system
DB_PASSWORD=password
DB_DRIVER=oracle.jdbc.driver.OracleDriver

**Redis:**

DB_URL=jdbc:redis://localhost:6379
DB_USER=
DB_PASSWORD=your_redis_password
DB_DRIVER=com.dbvis.jdbc.redis.RedisDriver

Step 4: Configure Claude Desktop

1. Open Claude Desktop 2. Go to **Settings** → **Developer** → **Edit Config** 3. Add your database server:

{
  "mcpServers": {
    "database": {
      "command": "java",
      "args": [
        "-jar", 
        "/absolute/path/to/dbchat-4.2.1-<variant>.jar",
        "--config_file=/absolute/path/to/dbchat.conf"
      ]
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 826 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # DBChat - Talk to Your Database using AI
  2. Transform your database into an intelligent conversational partner. Ask questions in plain English, get instant answers, and create beautiful visualizations - all through Claude Desktop or any other MCP Client.
  3. ## 🌟 What is DBChat?
  4. DBChat is a bridge that connects any MCP client like Claude Desktop, Gemini-CLI, etc to your database, enabling natural language database interactions. Instead of writing SQL queries, simply ask the chatbot questions about your data and get instant, intelligent responses.
  5. If you want a guided product tour, see [TUTORIAL.md](TUTORIAL.md). But if you only want to see the results of a sample TUTORIAL run then see [TUTORIAL-DEMO.html](http://htmlpreview.github.io/?https://github.com/skanga/DBchat/blob/main/TUTORIAL-DEMO.html).
  6. If you want to focus on charts and visual output, see [VISUALIZATION.md](VISUALIZATION.md).
  7. **Before DBChat:**
  8. ```sql
  9. SELECT c.name, COUNT(o.id) as order_count, SUM(o.total) as revenue
  10. FROM customers c
  11. LEFT JOIN orders o ON c.id = o.customer_id
  12. WHERE o.created_at >= '2024-01-01'
  13. GROUP BY c.id, c.name
  14. ORDER BY revenue DESC
  15. LIMIT 10;
  16. ```
  17. **With DBChat:**
  18. ```
  19. "Show me our top 10 customers by revenue this year"
  20. ```
  21. ## 🎯 Why Use DBChat?
  22. ### 🗣️ Natural Language Database Queries
  23. - **Ask questions in plain English**: "How many customers signed up last month?"
  24. - **Get conversational responses**: The LLM explains the data and provides business insights
  25. - **No SQL knowledge required**: Perfect for business users and analysts
  26. ### 📊 Instant Data Visualizations
  27. - **Automatic chart creation**: Claude generates beautiful charts from your data
  28. - **Multiple chart types**: Line charts, bar charts, pie charts, scatter plots, and more
  29. - **Interactive visuals**: Drill down into your data with follow-up questions
  30. ### 🔍 Smart Data Exploration
  31. - **Database discovery**: "What tables do we have?" "Show me the customer table structure"
  32. - **Relationship understanding**: The AI model explains how your tables connect
  33. - **Data quality improvements**: Find duplicates, missing data, and anomalies
  34. ### 💼 Business Intelligence Made Easy
  35. - **Executive dashboards**: "Create a sales summary for our board meeting"
  36. - **Trend analysis**: "Show me user growth over the past 6 months"
  37. - **Performance metrics**: "Which products are underperforming?"
  38. ## ✨ Advanced Features
  39. DBChat now includes powerful features for interactive demos, onboarding, collaborative analysis, and sophisticated business intelligence workflows.
  40. ### 🚀 MCP Prompts Support
  41. Revolutionary structured workflow system for guided database analysis and business intelligence.
  42. - **Professional Business Scenarios**: Pre-built scenarios for Retail/E-commerce, Finance/Banking, and Logistics with realistic business contexts
  43. - **Interactive Demo Templates**: Complete 15-20 minute guided workflows with:
  44. - Business narratives with protagonists and deadlines
  45. - Step-by-step analytical progression
  46. - Multiple choice decision points
  47. - Expected outcomes and insights for each step
  48. - **Three Sophisticated Prompt Types**:
  49. - `mcp-demo` - Complete interactive demo with business scenarios
  50. - `business-intelligence` - Comprehensive BI analysis framework
  51. - `database-analysis` - Enhanced database exploration workflow
  52. - **MCP Protocol Integration**: Full compliance with MCP prompts protocol including `prompts/list` and `prompts/get` handlers
  53. - **How to start**: Use any prompt-aware MCP client and select from available structured prompts for guided analysis
  54. ### 🎯 Interactive Multiple Choice Workflow System
  55. Sophisticated workflow engine for structured data exploration and analysis.
  56. - **Structured Progressions**: Step-by-step workflows with contextual multiple choice options
  57. - **Scenario-Specific Content**: Tailored workflows for retail, finance, and logistics business domains
  58. - **State Management**: Tracks user choices and workflow progression throughout analysis sessions
  59. - **New MCP Tools**:
  60. - `start_workflow` - Initiates interactive analysis workflows with business context
  61. - `workflow_choice` - Processes user selections and advances workflow steps
  62. - **MCP Resources**: `workflow://status` resource shows active workflow status and progress
  63. - **Integration Ready**: Seamlessly works with demo data setup and insights collection systems
  64. ### 🛠️ Automatic Demo Data Setup
  65. Intelligent database population system for demonstrations and onboarding.
  66. - **Realistic Business Scenarios**: Choose from Retail, Finance, or Logistics domains
  67. - **Database-Agnostic**: Works across all supported database types and configurations
  68. - **Comprehensive Data Models**:
  69. - **Retail**: Customers, Products, Orders, Inventory with realistic relationships
  70. - **Finance**: Accounts, Transactions, Customers, Loans with financial data patterns
  71. - **Logistics**: Shipments, Routes, Warehouses, Deliveries with supply chain data
  72. - **Instant Setup**: Creates five related tables per scenario with representative synthetic data sized for demos and guided analysis
  73. - **Sample Analytics**: Pre-built queries and analysis examples for each scenario
  74. - **Cleanup Capabilities**: Automatic reset and cleanup functionality for fresh demonstrations
  75. ### 🧠 Enhanced Insights Collection System
  76. Professional business intelligence capture and reporting system.
  77. - **Structured Insight Model**: Comprehensive insights with categories, priorities, timestamps, and metadata
  78. - **`append_insight` Tool**: Advanced tool for capturing structured business findings with:
  79. - Content validation and sanitization
  80. - Automatic categorization with visual indicators
  81. - Priority assignment (high/medium/low)
  82. - Security audit logging
  83. - **Professional Memo Generation**:
  84. - **Comprehensive Memos**: Executive summaries, categorized findings, priority insights, timeline analysis
  85. - **Quick Summaries**: Fast consumption format for rapid business updates
  86. - **Multi-format Support**: Both detailed and summary formats available
  87. - **MCP Resources Integration**:
  88. - `insights://memo` - Professional business intelligence report
  89. - `insights://summary` - Quick overview of collected insights
  90. - Dynamic resource discovery as insights are captured
  91. - **Persistent Storage**: Auto-save to JSON with load/restore capabilities and export functionality
  92. - **Real-time Statistics**: Live tracking of insight counts, categories, and analytical progress
  93. ## 🗃️ Supported Databases
  94. DBChat works with virtually any database (as long as it has a JDBC driver)
  95. ### Popular Databases
  96. - **MySQL** / **MariaDB** - Web applications and e-commerce
  97. - **Oracle** - Enterprise applications
  98. - **PostgreSQL** - Advanced applications and analytics
  99. - **SQL Server** - Microsoft environments
  100. - **H2** - Testing and development
  101. - **SQLite** - Local applications and prototypes
  102. - **HSQLDB** - Testing and development
  103. ### NoSQL & Caching
  104. - **Redis** - In-memory data store
  105. - **MongoDB** - Document-oriented database
  106. - **Cassandra** - Wide-column store
  107. ### Analytics & Cloud
  108. - **Snowflake** - Cloud data platform
  109. - **Databricks** - Cloud data platform
  110. - **Amazon Redshift** - AWS data warehouse
  111. - **Google BigQuery** - Google analytics
  112. - **ClickHouse** - Real-time analytics
  113. ### Flat-file Based Data
  114. - **CSV Files** - Spreadsheet data and exports
  115. - **Excel Files** - Can be exported to CSV and queried
  116. *See [INSTALL.md](INSTALL.md) for the complete list and build options.*
  117. ## 🚀 Quick Start
  118. ### Step 1: Download DBChat
  119. Download the latest release from [GitHub Releases](https://github.com/skanga/dbchat/releases):
  120. - [dbchat-4.2.1-basic.jar](https://github.com/skanga/dbchat/releases/download/v4.2.1/dbchat-4.2.1-basic.jar) - Basic version (PostgreSQL, SQLite, H2, HSQLDB, CSV). We recommend that you start here.
  121. - [dbchat-4.2.1-standard.jar](https://github.com/skanga/dbchat/releases/download/v4.2.1/dbchat-4.2.1-standard.jar) - Standard version (add MySQL, MariaDB, ClickHouse)
  122. - [dbchat-4.2.1-enterprise.jar](https://github.com/skanga/dbchat/releases/download/v4.2.1/dbchat-4.2.1-enterprise.jar) - Enterprise version (add Oracle, SQL Server, DB2)
  123. - [dbchat-4.2.1-cloud-analytics.jar](https://github.com/skanga/dbchat/releases/download/v4.2.1/dbchat-4.2.1-cloud-analytics.jar) - Cloud Analytics version (add Redshift, Snowflake, BigQuery)
  124. - [dbchat-4.2.1-all.jar](https://github.com/skanga/dbchat/releases/download/v4.2.1/dbchat-4.2.1-all.jar) - All databases included (400MB+)
  125. In the examples below, replace `<variant>` with the jar you downloaded, such as `basic`, `standard`, `enterprise`, `cloud-analytics`, or `all`.
  126. For a hands-on walkthrough after setup, see [TUTORIAL.md](TUTORIAL.md) and if you only want to see the results of a sample TUTORIAL run then see [TUTORIAL-DEMO.html](http://htmlpreview.github.io/?https://github.com/skanga/DBchat/blob/main/TUTORIAL-DEMO.html). For visualization-focused usage patterns, see [VISUALIZATION.md](VISUALIZATION.md).
  127. NOTE: Advanced users can also build a custom jar with only the drivers you need. See [INSTALL.md](INSTALL.md) for details.
  128. IMPORTANT: Make sure that you are properly LICENSED to use any JDBC driver you install. The DBChat license does not cover any third party code or binaries.
  129. ### Step 2: Install Claude Desktop (similar setup for any other MCP client)
  130. 1. Download [Claude Desktop](https://claude.ai/download) (free)
  131. 2. Sign in with your Claude account
  132. 3. **Important**: The Claude website does not support MCP. For MCP with Anthropic models you need to use Claude Desktop or Claude Code.
  133. ### Step 2 (alternate):
  134. If you are not using Claude Desktop but want to use another MCP client like Cursor, Windsurf, VS Code, Continue, etc then please refer to the [MCP Setup](MCP-SETUP.md) document for more details
  135. ### Step 3: Set Up Your Database Connection
  136. Create a configuration file `dbchat.conf`:
  137. ```properties
  138. # Basic database connection
  139. DB_URL=jdbc:mysql://localhost:3306/your_database
  140. DB_USER=your_username
  141. DB_PASSWORD=your_password
  142. DB_DRIVER=com.mysql.cj.jdbc.Driver
  143. # Optional: Enable web interface (not needed for Claude desktop)
  144. HTTP_MODE=false
  145. HTTP_PORT=8080
  146. ```
  147. **Examples for Common/Popular Databases:**
  148. **MySQL:**
  149. ```properties
  150. DB_URL=jdbc:mysql://localhost:3306/your_database
  151. DB_USER=your_username
  152. DB_PASSWORD=your_password
  153. DB_DRIVER=com.mysql.cj.jdbc.Driver
  154. ```
  155. **PostgreSQL:**
  156. ```properties
  157. DB_URL=jdbc:postgresql://localhost:5432/your_database
  158. DB_USER=your_username
  159. DB_PASSWORD=your_password
  160. DB_DRIVER=org.postgresql.Driver
  161. ```
  162. **SQLite:**
  163. ```properties
  164. DB_URL=jdbc:sqlite:/path/to/your/database.db
  165. DB_USER=
  166. DB_PASSWORD=
  167. DB_DRIVER=org.sqlite.JDBC
  168. ```
  169. **H2 database (in memory - no database setup required):**
  170. ```properties
  171. DB_URL=jdbc:h2:mem:testdb
  172. DB_USER=sa
  173. DB_PASSWORD=
  174. DB_DRIVER=org.h2.Driver
  175. ```
  176. **Oracle:**
  177. ```properties
  178. DB_URL=jdbc:oracle:thin:@localhost:1521:xe
  179. DB_USER=system
  180. DB_PASSWORD=password
  181. DB_DRIVER=oracle.jdbc.driver.OracleDriver
  182. ```
  183. **Redis:**
  184. ```properties
  185. DB_URL=jdbc:redis://localhost:6379
  186. DB_USER=
  187. DB_PASSWORD=your_redis_password
  188. DB_DRIVER=com.dbvis.jdbc.redis.RedisDriver
  189. ```
  190. ### Step 4: Configure Claude Desktop
  191. 1. Open Claude Desktop
  192. 2. Go to **Settings** → **Developer** → **Edit Config**
  193. 3. Add your database server:
  194. ```json
  195. {
  196. "mcpServers": {
  197. "database": {
  198. "command": "java",
  199. "args": [
  200. "-jar",
  201. "/absolute/path/to/dbchat-4.2.1-<variant>.jar",
  202. "--config_file=/absolute/path/to/dbchat.conf"
  203. ]
  204. }
  205. }
  206. }
  207. ```
  208. **Alternative without config file:**
  209. ```json
  210. {
  211. "mcpServers": {
  212. "database": {
  213. "command": "java",
  214. "args": ["-jar", "/absolute/path/to/dbchat-4.2.1-<variant>.jar"],
  215. "env": {
  216. "DB_URL": "jdbc:mysql://localhost:3306/your_database",
  217. "DB_USER": "your_username",
  218. "DB_PASSWORD": "your_password",
  219. "DB_DRIVER": "com.mysql.cj.jdbc.Driver"
  220. }
  221. }
  222. }
  223. }
  224. ```
  225. **Windows Example:**
  226. ```json
  227. {
  228. "mcpServers": {
  229. "database": {
  230. "command": "java",
  231. "args": [
  232. "-jar",
  233. "C:/Users/YourName/Downloads/dbchat-4.2.1-<variant>.jar",
  234. "--config_file=C:/Users/YourName/dbchat.conf"
  235. ]
  236. }
  237. }
  238. }
  239. ```
  240. NOTE: If java is not in your PATH then use the full path to java (JDK 17+) in the command.
  241. ### Step 5: Connect Multiple Databases
  242. You can use many databases concurrently!
  243. ```json
  244. {
  245. "mcpServers": {
  246. "production-db": {
  247. "command": "java",
  248. "args": ["-jar", "/path/to/dbchat-4.2.1-<variant>.jar"],
  249. "env": {
  250. "DB_URL": "jdbc:mysql://prod-server:3306/production",
  251. "DB_USER": "readonly_user",
  252. "DB_PASSWORD": "secure_password",
  253. "DB_DRIVER": "com.mysql.cj.jdbc.Driver",
  254. "SELECT_ONLY": "true"
  255. }
  256. },
  257. "analytics-db": {
  258. "command": "java",
  259. "args": ["-jar", "/path/to/dbchat-4.2.1-<variant>.jar"],
  260. "env": {
  261. "DB_URL": "jdbc:postgresql://analytics:5432/warehouse",
  262. "DB_USER": "analyst",
  263. "DB_PASSWORD": "password",
  264. "DB_DRIVER": "org.postgresql.Driver"
  265. }
  266. }
  267. }
  268. }
  269. ```
  270. ### Step 6: Restart Claude Desktop
  271. Close and reopen Claude Desktop. You should see a database connection indicator in the chat input.
  272. ## 💬 Start Talking to Your Database
  273. ### Data Exploration
  274. ```
  275. "What tables do we have in the database?"
  276. "Show me the structure of the customers table"
  277. "How many records are in each table?"
  278. ```
  279. ### Business Questions
  280. ```
  281. "How many new customers did we get last month?"
  282. "What are our top 5 selling products this quarter?"
  283. "Show me revenue by month for the past year"
  284. ```
  285. ### Data Analysis
  286. ```
  287. "Find customers who haven't ordered in 6 months"
  288. "Are there any duplicate email addresses?"
  289. "What's the average order value by customer segment?"
  290. ```
  291. ### Visualizations
  292. ```
  293. "Create a chart showing monthly sales trends"
  294. "Make a pie chart of orders by product category"
  295. "Show me a bar chart of customer signups by region"
  296. ```
  297. ### Advanced Analytics
  298. ```
  299. "Calculate customer lifetime value for each segment"
  300. "Identify seasonal trends in our sales data"
  301. "Find correlations between customer age and purchase behavior"
  302. ```
  303. ## 📱 More Real-World Examples
  304. ### E-commerce Analytics
  305. ```
  306. "Show me our conversion funnel from visitors to purchases"
  307. "Which products have the highest return rates?"
  308. "Create a dashboard showing daily sales performance"
  309. ```
  310. ### Customer Success
  311. ```
  312. "Find customers at risk of churning"
  313. "Show me customer satisfaction trends"
  314. "Identify our most valuable customer segments"
  315. ```
  316. ### Financial Reporting
  317. ```
  318. "Generate a P&L summary for this quarter"
  319. "Show cash flow trends over the past 12 months"
  320. "Create an expense breakdown by department"
  321. ```
  322. ### Operations Management
  323. ```
  324. "Monitor inventory levels across all warehouses"
  325. "Show shipping performance by carrier"
  326. "Identify bottlenecks in our fulfillment process"
  327. ```
  328. ## 📊 Data Visualization Examples
  329. DBChat enables Claude to create stunning visualizations directly from your database:
  330. ### Sales Dashboard
  331. - **Monthly Revenue Trends**: Line charts showing growth over time
  332. - **Top Products**: Bar charts of bestsellers
  333. - **Regional Performance**: Heat maps of sales by location
  334. - **Customer Segments**: Pie charts of revenue distribution
  335. ### Analytics Reports
  336. - **User Growth**: Area charts showing acquisition trends
  337. - **Performance Metrics**: Multi-axis charts combining different KPIs
  338. - **Comparative Analysis**: Side-by-side visualizations of different periods
  339. ### Operational Dashboards
  340. - **Inventory Levels**: Real-time stock visualization
  341. - **System Performance**: Time-series charts of key metrics
  342. - **Quality Metrics**: Statistical charts showing trends and outliers
  343. ## 🛡️ Security Features
  344. ### Read-Only Mode
  345. Protect your data with read-only access:
  346. ```properties
  347. SELECT_ONLY=true
  348. ```
  349. ### Query Limits
  350. Control resource usage:
  351. ```properties
  352. MAX_ROWS_LIMIT=1000
  353. QUERY_TIMEOUT_SECONDS=30
  354. MAX_SQL_LENGTH=10000
  355. ```
  356. ### Local Processing
  357. - All data stays on your machine
  358. - No external API calls
  359. - Encrypted environment variables
  360. - Secure local communication
  361. ## 🌐 Web Interface (Optional)
  362. Enable HTTP mode for web-based access:
  363. ```properties
  364. # Turn on HTTP listener
  365. HTTP_MODE=true
  366. # Listen on port 8080
  367. HTTP_PORT=8080
  368. # Bind to all interfaces (allows external access)
  369. BIND_ADDRESS=0.0.0.0
  370. # NOTE: If no bind address is given we bind to localhost only (default, most secure)
  371. ```
  372. Then access at `http://localhost:8080/`. For example try `http://localhost:8080/health` to check health status
  373. For similar config via CLI args use:
  374. ```
  375. # Bind to localhost only (default, most secure)
  376. java -jar dbchat-4.2.1-<variant>.jar --http_mode=true --http_port=8080
  377. # Bind to all interfaces (allows external access)
  378. java -jar dbchat-4.2.1-<variant>.jar --http_mode=true --bind_address=0.0.0.0 --http_port=8080
  379. # Bind to specific interface
  380. java -jar dbchat-4.2.1-<variant>.jar --http_mode=true --bind_address=192.168.1.100 --http_port=8080
  381. ```
  382. ## 🔧 Configuration Methods and Priority
  383. For maximum flexibility, DBChat supports multiple configuration methods like CLI arguments, config file, Environment vars,
  384. System Properties and Built-in Defaults. Understanding the priority order is crucial for troubleshooting and advanced setups.
  385. ### Configuration Priority Order (Highest to Lowest)
  386. 1. **Command Line Arguments** (Highest Priority)
  387. 2. **Configuration File**
  388. 3. **Environment Variables**
  389. 4. **System Properties**
  390. 5. **Built-in Defaults** (Lowest Priority)
  391. This means command line arguments will always override config files, which override environment variables, and so on.
  392. ### Method 1: Command Line Arguments
  393. **Format**: `--parameter_name=value`
  394. **Use case**: Quick overrides, testing, one-time configurations
  395. ```bash
  396. java -jar dbchat-4.2.1-<variant>.jar \
  397. --db_url="jdbc:mysql://localhost:3306/mydb" \
  398. --db_user="username" \
  399. --db_password="password" \
  400. --db_driver="com.mysql.cj.jdbc.Driver" \
  401. --http_mode=true \
  402. --http_port=8080 \
  403. --select_only=true
  404. ```
  405. **Available parameters:**
  406. - `--config_file=/path/to/config.conf`
  407. - `--db_url="jdbc:..."`
  408. - `--db_user="username"`
  409. - `--db_password="password"`
  410. - `--db_driver="com.mysql.cj.jdbc.Driver"`
  411. - `--http_mode=true`
  412. - `--http_port=8080`
  413. - `--max_connections=20`
  414. - `--connection_timeout_ms=30000`
  415. - `--query_timeout_seconds=60`
  416. - `--select_only=true`
  417. - `--max_sql_length=50000`
  418. - `--max_rows_limit=10000`
  419. ### Method 2: Configuration Files
  420. **Format**: `KEY=VALUE` (one per line)
  421. **Use case**: Production environments, complex configurations, version control
  422. Create a file (e.g., `dbchat.conf`):
  423. ```properties
  424. # Database Connection
  425. DB_URL=jdbc:postgresql://localhost:5432/myapp
  426. DB_USER=dbuser
  427. DB_PASSWORD=my secure password with spaces
  428. DB_DRIVER=org.postgresql.Driver
  429. # Connection Pool Settings
  430. MAX_CONNECTIONS=20
  431. CONNECTION_TIMEOUT_MS=60000
  432. IDLE_TIMEOUT_MS=300000
  433. MAX_LIFETIME_MS=1800000
  434. LEAK_DETECTION_THRESHOLD_MS=60000
  435. # Query Settings
  436. QUERY_TIMEOUT_SECONDS=45
  437. SELECT_ONLY=false
  438. MAX_SQL_LENGTH=50000
  439. MAX_ROWS_LIMIT=50000
  440. # Server Settings
  441. HTTP_MODE=true
  442. HTTP_PORT=8080
  443. ```
  444. **Usage:**
  445. ```bash
  446. java -jar dbchat-4.2.1-<variant>.jar --config_file=dbchat.conf
  447. ```
  448. **Config file features:**
  449. - Comments start with `#`
  450. - Empty lines are ignored
  451. - Values can be quoted: `DB_PASSWORD="password with spaces"`
  452. - Keys are case-insensitive
  453. - Supports all the same parameters as command line
  454. ### Method 3: Environment Variables
  455. **Format**: `UPPERCASE_WITH_UNDERSCORES`
  456. **Use case**: Docker, cloud deployment, CI/CD, secure credential management
  457. ```bash
  458. export DB_URL="jdbc:mysql://localhost:3306/mydb"
  459. export DB_USER="username"
  460. export DB_PASSWORD="password"
  461. export DB_DRIVER="com.mysql.cj.jdbc.Driver"
  462. export HTTP_MODE="true"
  463. export HTTP_PORT="8080"
  464. export SELECT_ONLY="true"
  465. java -jar dbchat-4.2.1-<variant>.jar
  466. ```
  467. **All environment variables:**
  468. - `CONFIG_FILE` - Path to configuration file
  469. - `DB_URL` - Database connection URL
  470. - `DB_USER` - Database username
  471. - `DB_PASSWORD` - Database password
  472. - `DB_DRIVER` - JDBC driver class
  473. - `HTTP_MODE` - Enable HTTP mode (true/false)
  474. - `HTTP_PORT` - HTTP server port
  475. - `MAX_CONNECTIONS` - Connection pool size
  476. - `CONNECTION_TIMEOUT_MS` - Connection timeout
  477. - `QUERY_TIMEOUT_SECONDS` - Query timeout
  478. - `SELECT_ONLY` - Read-only mode (true/false)
  479. - `MAX_SQL_LENGTH` - Maximum query length
  480. - `MAX_ROWS_LIMIT` - Maximum result rows
  481. - `IDLE_TIMEOUT_MS` - Connection idle timeout
  482. - `MAX_LIFETIME_MS` - Connection max lifetime
  483. - `LEAK_DETECTION_THRESHOLD_MS` - Leak detection threshold
  484. ### Method 4: System Properties
  485. **Format**: `-Dparameter.name=value` (underscores become dots)
  486. **Use case**: JVM-specific configuration, IDE run configurations
  487. ```bash
  488. java -Ddb.url="jdbc:mysql://localhost:3306/mydb" \
  489. -Ddb.user="username" \
  490. -Ddb.password="password" \
  491. -Ddb.driver="com.mysql.cj.jdbc.Driver" \
  492. -Dhttp.mode="true" \
  493. -Dhttp.port="8080" \
  494. -jar dbchat-4.2.1-<variant>.jar
  495. ```
  496. **Property naming**: Environment variable `DB_URL` becomes system property `db.url`
  497. ### Method 5: Built-in Defaults
  498. **When**: No configuration provided
  499. **Values**: Safe defaults for development
  500. ```properties
  501. DB_URL=jdbc:h2:mem:testdb
  502. DB_USER=sa
  503. DB_PASSWORD=
  504. DB_DRIVER=org.h2.Driver
  505. HTTP_MODE=false
  506. HTTP_PORT=8080
  507. MAX_CONNECTIONS=10
  508. CONNECTION_TIMEOUT_MS=30000
  509. QUERY_TIMEOUT_SECONDS=30
  510. SELECT_ONLY=true
  511. MAX_SQL_LENGTH=10000
  512. MAX_ROWS_LIMIT=10000
  513. ```
  514. ### Configuration Examples
  515. #### Example 1: Priority Override
  516. ```bash
  517. # Config file has HTTP_PORT=8080
  518. echo "HTTP_PORT=8080" > config.conf
  519. # Environment variable sets different port
  520. export HTTP_PORT=9090
  521. # Command line overrides both
  522. java -jar dbchat-4.2.1-<variant>.jar --config_file=config.conf --http_port=7070
  523. # Result: Uses port 7070 (command line wins)
  524. ```
  525. #### Example 2: Mixed Configuration
  526. ```bash
  527. # Use config file for database settings
  528. echo "DB_URL=jdbc:mysql://localhost:3306/mydb" > prod.conf
  529. echo "DB_USER=produser" >> prod.conf
  530. echo "SELECT_ONLY=true" >> prod.conf
  531. # Override password via environment (more secure)
  532. export DB_PASSWORD="secure_password"
  533. # Override port via command line (for this run only)
  534. java -jar dbchat-4.2.1-<variant>.jar --config_file=prod.conf --http_port=9090
  535. ```
  536. #### Example 3: Claude Desktop Configuration
  537. Note that most MCP clients use a similar configuration, but you'll need to refer to your MCP
  538. client docs for details on how it can be configured. It is safest not to assume any PATH settings
  539. and provide absolute paths for java, the dbchat jar and (optionally) the dbchat config file.
  540. ```json
  541. {
  542. "mcpServers": {
  543. "database": {
  544. "command": "java",
  545. "args": [
  546. "-jar", "/path/to/dbchat-4.2.1-<variant>.jar",
  547. "--config_file=/path/to/production.conf",
  548. "--select_only=true"
  549. ],
  550. "env": {
  551. "DB_PASSWORD": "secure_password_from_env"
  552. }
  553. }
  554. }
  555. }
  556. ```
  557. ### Configuration Parameters Reference
  558. #### Database Connection
  559. - `DB_URL` - JDBC connection string (required)
  560. - `DB_USER` - Database username
  561. - `DB_PASSWORD` - Database password
  562. - `DB_DRIVER` - JDBC driver class (required)
  563. #### Connection Pool
  564. - `MAX_CONNECTIONS=10` - Maximum concurrent connections
  565. - `CONNECTION_TIMEOUT_MS=30000` - Connection acquisition timeout
  566. - `IDLE_TIMEOUT_MS=600000` - Connection idle timeout (10 minutes)
  567. - `MAX_LIFETIME_MS=1800000` - Connection max lifetime (30 minutes)
  568. - `LEAK_DETECTION_THRESHOLD_MS=60000` - Connection leak detection (1 minute)
  569. #### Query Settings
  570. - `QUERY_TIMEOUT_SECONDS=30` - SQL query execution timeout
  571. - `SELECT_ONLY=true` - Read-only mode (blocks INSERT/UPDATE/DELETE)
  572. - `MAX_SQL_LENGTH=10000` - Maximum characters in SQL query
  573. - `MAX_ROWS_LIMIT=10000` - Maximum rows returned per query
  574. #### Server Settings
  575. - `HTTP_MODE=false` - Enable HTTP web interface
  576. - `HTTP_PORT=8080` - HTTP server port
  577. ### Security Best Practices
  578. #### Credential Management
  579. ```bash
  580. # Good: Use environment variables for passwords
  581. export DB_PASSWORD="secure_password"
  582. java -jar dbchat-4.2.1-<variant>.jar --config_file=app.conf
  583. # Good: Use config file with restricted permissions
  584. chmod 600 secure.conf
  585. java -jar dbchat-4.2.1-<variant>.jar --config_file=secure.conf
  586. # Avoid: Passwords in command line (visible in process list)
  587. java -jar dbchat-4.2.1-<variant>.jar --db_password="visible_password"
  588. ```
  589. #### Configuration File Security
  590. ```bash
  591. # Create secure config file
  592. umask 077
  593. cat > secure.conf << EOF
  594. DB_PASSWORD=secure_password
  595. EOF
  596. # Verify permissions
  597. ls -la secure.conf
  598. # Should show: -rw------- (owner read/write only)
  599. ```
  600. ### Troubleshooting Configuration
  601. #### Check Effective Configuration
  602. Enable debug logging to see which values are being used:
  603. ```bash
  604. java -Dlogging.level.root=DEBUG -jar dbchat-4.2.1-<variant>.jar --config_file=myconfig.conf
  605. ```
  606. #### Common Issues
  607. 1. **Config file not found**: Use absolute paths
  608. 2. **Permission denied**: Check file permissions
  609. 3. **Wrong values used**: Check priority order
  610. 4. **Environment variables not set**: Use `env | grep DB_` to verify
  611. #### Validation Commands
  612. ```bash
  613. # Test database connection with current config
  614. java -jar dbchat-4.2.1-<variant>.jar --help
  615. # Verify config file syntax
  616. grep -v "^#" myconfig.conf | grep -v "^$"
  617. # Check environment variables
  618. env | grep -E "(DB_|HTTP_|MAX_|SELECT_)"
  619. ```
  620. ## 🚫 Troubleshooting
  621. ### Claude Desktop Not Connecting
  622. 1. **Check paths**: Use absolute paths in configuration
  623. 2. **Java version**: Ensure Java 17+ is installed
  624. 3. **File permissions**: Verify JAR file is readable
  625. 4. **Restart Claude**: Close and reopen Claude Desktop
  626. ### Database Connection Issues
  627. 1. **Test connection**: Verify database is running
  628. 2. **Check credentials**: Ensure username/password are correct
  629. 3. **Network access**: Confirm database allows connections
  630. 4. **Driver support**: Use the correct JAR version for your database
  631. ### Performance Issues
  632. 1. **Limit results**: Use `MAX_ROWS_LIMIT=1000`
  633. 2. **Query timeout**: Set `QUERY_TIMEOUT_SECONDS=30`
  634. 3. **Connection pool**: Adjust `MAX_CONNECTIONS=10`
  635. ### Common Error Messages
  636. **"ClassNotFoundException"**
  637. - Download the correct JAR version for your database
  638. - Check that the database driver is included
  639. **"Connection refused"**
  640. - Verify database server is running
  641. - Check connection URL, username, and password
  642. - Ensure database allows connections from your machine
  643. **"Server not responding"**
  644. - Check Claude Desktop configuration syntax
  645. - Verify Java is accessible in PATH
  646. - Review Claude Desktop logs
  647. ## 🎯 Best Practices
  648. ### Getting Started
  649. 1. **Start with read-only**: Use `SELECT_ONLY=true` initially
  650. 2. **Test with sample data**: Try the H2 database first
  651. 3. **Begin with simple questions**: Start with basic table exploration
  652. 4. **Build complexity gradually**: Move to advanced analytics over time
  653. ### Security
  654. 1. **Use dedicated database users**: Create read-only users for DBChat
  655. 2. **Limit access**: Only grant necessary table permissions
  656. 3. **Monitor usage**: Review query logs regularly
  657. 4. **Backup data**: Always maintain database backups
  658. ### Performance
  659. 1. **Set reasonable limits**: Use `MAX_ROWS_LIMIT` and timeouts
  660. 2. **Index important columns**: Ensure queries can run efficiently
  661. 3. **Monitor resources**: Watch CPU and memory usage
  662. 4. **Optimize queries**: Let Claude suggest query improvements
  663. ## 📚 Learn More
  664. - **Model Context Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
  665. - **Claude Desktop**: [claude.ai/download](https://claude.ai/download)
  666. - **Developer Guide**: See [INSTALL.md](INSTALL.md) for technical details
  667. - **GitHub Repository**: [github.com/skanga/dbchat](https://github.com/skanga/dbchat)
  668. ## 🚀 Ready to Transform Your Data Experience?
  669. 1. **Download** the appropriate JAR file for your database(s)
  670. 2. **Install** an MCP Client like Claude Desktop (free)
  671. 3. **Configure** your database connection
  672. 4. **Add** DBChat to MCP Client settings
  673. 5. **Start asking** questions about your data!
  674. Transform your relationship with data. No more complex SQL queries, no more waiting for reports. Just natural conversations with your database, powered by Claude's intelligence and DBChat's seamless integration.
  675. **Get started today and discover what your data has been trying to tell you.**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.