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

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, 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/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/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/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/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 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/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/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, 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/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/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/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.

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:

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

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 (metadata), provider/db_query.yaml (registration), tools/sql_query.yaml (parameters), and 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/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/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, 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/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/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/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 packages are installed), or database permission constraints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}