# How to Install the Dify Database Query Plugin from GitHub: Complete Setup Guide

> Easily install the Dify Database Query Plugin from GitHub. Follow our complete guide to quickly set up the db_query package using the repository URL or a local upload.

- Repository: [Junjie.M/dify-plugin-tools-dbquery](https://github.com/junjiem/dify-plugin-tools-dbquery)
- Tags: how-to-guide
- Published: 2026-03-05

---

**You can install the Dify Database Query Plugin directly from GitHub using Dify's "Install via GitHub" feature by pasting the repository URL `https://github.com/junjiem/dify-plugin-tools-dbquery` and selecting the `db_query` package, or by downloading the `.difypkg` release asset and uploading it as a local package file.**

The **Dify Database Query Plugin** is an open-source tool-type plugin that enables Large Language Models to execute SQL queries against MySQL, Oracle, PostgreSQL, and Microsoft SQL Server databases. When you install the Dify database query plugin from GitHub, you gain a secure, containerized way to let AI agents retrieve structured data without exposing database credentials to external APIs.

## What Is the Dify Database Query Plugin?

This plugin acts as a bridge between Dify's LLM orchestration platform and your relational databases. According to the source code in [`junjiem/dify-plugin-tools-dbquery`](https://github.com/junjiem/dify-plugin-tools-dbquery), the tool supports:

- **MySQL** (including SSL connections)
- **Oracle** (version 11g and later)
- **PostgreSQL**
- **Microsoft SQL Server**

The plugin architecture consists of YAML configuration files that declare the tool interface and a Python implementation that handles connection pooling, SQL validation, and result formatting.

## Installation Prerequisites

Before you install the Dify database query plugin from GitHub, ensure your environment meets these requirements:

- **Dify Platform**: Version 0.6.0 or later with plugin support enabled
- **Python Runtime**: The plugin requires Python 3.12 (specified in [[`manifest.yaml`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/manifest.yaml)](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/manifest.yaml))
- **Network Access**: Outbound HTTPS access to GitHub (for Method 1) or ability to transfer files to your Dify host (for Method 2)

## Method 1: Install Directly from GitHub (Recommended)

The fastest way to install the Dify database query plugin from GitHub is using Dify's native GitHub integration. This method automatically pulls the latest release and validates the plugin signature.

1. Navigate to your Dify instance's **Plugin Management** page
2. Click **Install via GitHub**
3. Paste the repository URL: `https://github.com/junjiem/dify-plugin-tools-dbquery`
4. Select the `db_query` package from the dropdown (this corresponds to the directory containing [[`manifest.yaml`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/manifest.yaml)](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/manifest.yaml))
5. Choose a specific tag (e.g., `v1.0.0`) or commit hash for reproducible deployments
6. Click **Install** and wait for the validation to complete

The plugin will appear in your tool library immediately after installation. The [[`manifest.yaml`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/manifest.yaml)](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/manifest.yaml) file declares the runtime environment and registers the tool provider located at [[`provider/db_query.yaml`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/provider/db_query.yaml)](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/provider/db_query.yaml).

## Method 2: Install from Local Package File

If your Dify instance cannot reach GitHub due to network restrictions, you can install the Dify database query plugin from a locally downloaded package file.

1. Visit the [Releases page](https://github.com/junjiem/dify-plugin-tools-dbquery/releases) of the repository
2. Download the latest `.difypkg` asset (e.g., `db_query.difypkg`)
3. Transfer the file to your local machine with Dify access
4. In Dify, go to **Plugin Management** → **Install from Local Package File**
5. Upload the `.difypkg` file and click **Install**

This method bypasses external GitHub API calls while maintaining the same plugin integrity checks. The package contains the compiled Python bytecode and all dependencies specified in [[`requirements.txt`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/requirements.txt)](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/requirements.txt), including `sqlparse` for SQL validation and `tabulate` for markdown formatting.

## Plugin Architecture and Key Files

Understanding the source structure helps troubleshoot installation issues and customize the tool behavior after you install the Dify database query plugin from GitHub.

### manifest.yaml – Plugin Metadata

The [[`manifest.yaml`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/manifest.yaml)](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/manifest.yaml) file declares the plugin type (`plugin`), runtime (`python3.12`), and entry point. It references the tool provider configuration at [`provider/db_query.yaml`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/provider/db_query.yaml), establishing the plugin's identity within the Dify ecosystem.

### provider/db_query.yaml – Tool Registration

This file registers the `sql_query` tool and points to the implementation logic. It acts as the bridge between Dify's tool orchestration layer and the actual SQL execution code, ensuring the plugin appears in the Dify UI tool palette after installation.

### tools/sql_query.yaml – Parameter Definitions

The [[`tools/sql_query.yaml`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/tools/sql_query.yaml)](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/tools/sql_query.yaml) schema defines all input parameters:

- `db_type`: Enum selecting `mysql`, `oracle`, `postgresql`, or `mssql`
- `db_host`, `db_port`, `db_username`, `db_password`: Connection credentials
- `db_name`: Target database/schema
- `query_sql`: The SQL statement to execute
- `output_format`: Either `markdown` (table) or `json` (raw records)

### tools/sql_query.py – Core Implementation

The [[`tools/sql_query.py`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/tools/sql_query.py)](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/tools/sql_query.py) file contains the `SqlQueryTool` class that:

1. Validates input parameters against the YAML schema
2. Instantiates a `DbUtil` connection using the appropriate database driver
3. Executes the SQL query with timeout protection
4. Formats results as markdown tables (using `tabulate`) or JSON arrays
5. Handles errors gracefully, returning structured error messages to the LLM

### main.py – Entry Point

The [[`main.py`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/main.py)](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/main.py) file initializes the Dify plugin environment and starts the HTTP server that listens for tool invocation requests from the Dify platform. This is the executable target referenced in [`manifest.yaml`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/manifest.yaml).

## How to Use the Plugin After Installation

Once you successfully install the Dify database query plugin from GitHub, you can invoke it through three primary interfaces.

### Using the Dify Chatflow Interface

In the Dify visual workflow builder:

1. Add a **Tool** node to your chatflow
2. Select **Database Query** → **SQL Query** from the tool library
3. Configure the parameters:
   - Set `db_type` to your database engine (`mysql`, `postgresql`, `oracle`, or `mssql`)
   - Enter connection details (host, port, credentials)
   - Input your SQL query in `query_sql`
   - Choose `output_format` (`markdown` for readable tables, `json` for structured data)
4. Connect the tool node to your LLM node or end user

The plugin returns results directly in the conversation flow, allowing the LLM to analyze query results or present them to users.

### Local Python Debug Script

For development and testing, you can run the plugin locally without the full Dify platform using the debug mode:

```python

# debug_plugin.py

import json
from dify_plugin import Plugin, DifyPluginEnv

# Initialize plugin environment (matches db_query/main.py)

plugin = Plugin(DifyPluginEnv(MAX_REQUEST_TIMEOUT=120))

# Import the tool implementation

from db_query.tools.sql_query import SqlQueryTool

# Configure test parameters

payload = {
    "db_type": "postgresql",
    "db_host": "pg.example.com",
    "db_port": 5432,
    "db_username": "readonly",
    "db_password": "s3cr3t",
    "db_name": "analytics",
    "query_sql": "SELECT date, count(*) FROM events GROUP BY date;",
    "output_format": "json",
}

# Invoke the tool directly

tool = SqlQueryTool()
message_generator = tool._invoke(payload)
result = next(message_generator)

# Output the result

print(result.content)

```

Run this script with `python debug_plugin.py` to verify database connectivity and query logic before deploying to production.

### HTTP API Endpoint

When running as a Dify daemon, the plugin exposes an HTTP endpoint for programmatic access:

```bash
curl -X POST http://localhost:5003/api/v1/tools/sql_query \
  -H "Authorization: Bearer <YOUR_DEBUG_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "db_type": "mysql",
    "db_host": "db.mycompany.com",
    "db_port": 3306,
    "db_username": "readonly_user",
    "db_password": "secure_password",
    "db_name": "sales",
    "query_sql": "SELECT product, SUM(revenue) FROM orders GROUP BY product;",
    "output_format": "markdown"
  }'

```

The response contains either a markdown table or JSON array depending on your `output_format` parameter.

## Summary

- **Install the Dify database query plugin from GitHub** using Dify's native GitHub integration by pasting the repository URL `https://github.com/junjiem/dify-plugin-tools-dbquery` and selecting the `db_query` package.
- **Alternative offline installation** involves downloading the `.difypkg` release asset and uploading it via the Local Package File option in Plugin Management.
- **Core architecture** consists of [`manifest.yaml`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/manifest.yaml) (metadata), [`provider/db_query.yaml`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/provider/db_query.yaml) (registration), [`tools/sql_query.yaml`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/tools/sql_query.yaml) (parameters), and [`tools/sql_query.py`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/tools/sql_query.py) (execution logic).
- **Post-installation usage** supports three interfaces: visual Chatflow builder, local Python debug scripts, and direct HTTP API calls.
- **Database support** includes MySQL, Oracle (11g+), PostgreSQL, and Microsoft SQL Server with output formats in markdown or JSON.

## Frequently Asked Questions

### What databases are supported by the Dify Database Query Plugin?

The plugin supports **MySQL**, **Oracle** (version 11g and later), **PostgreSQL**, and **Microsoft SQL Server**. This is defined in the `db_type` parameter enum within [[`tools/sql_query.yaml`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/tools/sql_query.yaml)](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/tools/sql_query.yaml), and the connection handling is implemented in [[`tools/sql_query.py`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/tools/sql_query.py)](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/tools/sql_query.py) using database-specific drivers.

### Can I install the plugin without internet access?

Yes, you can install the Dify database query plugin from GitHub in offline environments by downloading the `.difypkg` file from the [Releases page](https://github.com/junjiem/dify-plugin-tools-dbquery/releases), transferring it to your air-gapped Dify instance, and using the **Install from Local Package File** option in the Plugin Management interface. This method bypasses all external GitHub API calls while maintaining the same security validation.

### What Python version is required to run this plugin?

The plugin requires **Python 3.12**, as specified in the `runtime` field of [[`manifest.yaml`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/manifest.yaml)](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/manifest.yaml). The plugin container image already bundles Python 3.12 and all dependencies listed in [[`requirements.txt`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/requirements.txt)](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/requirements.txt) (including `sqlparse`, `tabulate`, and `dify-plugin`), so no additional host-side Python setup is required when using the standard installation methods.

### How do I troubleshoot connection errors after installation?

First, verify your credentials in the tool configuration match the `db_type` specified (e.g., Oracle connections require specific port formatting). Check the Dify daemon logs for errors originating from [[`tools/sql_query.py`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/tools/sql_query.py)](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/tools/sql_query.py), which handles `DbUtil` connection timeouts and authentication failures. For persistent issues, run the local debug script (see the Python debug example above) to isolate whether the problem is network connectivity, Python dependency issues (verify [`requirements.txt`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/requirements.txt) packages are installed), or database permission constraints.