Dify SQL Query Tool Output Formats: Markdown vs JSON Configuration

The Dify SQL query tool supports two output formats—Markdown tables (GitHub-flavored, default) and JSON—controlled via the output_format parameter in your tool configuration.

The junjiem/dify-plugin-tools-dbquery repository provides a flexible database query tool for Dify workflows that allows developers to retrieve SQL results in multiple output formats. Understanding these format options helps you integrate query results seamlessly into LLM prompts, APIs, or downstream data processing pipelines.

Available Output Formats

The tool implements two distinct output formats in db_query/tools/sql_query.py (lines 47-63) and the pre-authentication variant in db_query_pre_auth/tools/sql_query.py (lines 47-63).

Markdown Tables (Default)

The Markdown format renders query results as GitHub-flavored tables using Python's tabulate library with tablefmt="github". This format is ideal for LLM consumption, chat interfaces, and human-readable logs.

When output_format is set to "markdown" or omitted entirely, the tool calls self.create_text_message() with the tabulated string.

JSON Records

The JSON format returns structured data wrapped in a {"records": [...]} object. This machine-readable format is optimal for API integrations, JavaScript frontend consumption, and downstream data processing.

When output_format is set to "json", the tool yields self.create_json_message() containing the serialized rows.

How to Configure Output Formats

Select your preferred format by setting the output_format parameter in the tool configuration. The implementation normalizes this value to lowercase and explicitly checks for "json"; any other value defaults to Markdown.

Requesting Markdown Output

{
  "tool_name": "sql_query",
  "tool_parameters": {
    "db_type": "postgresql",
    "db_host": "localhost",
    "db_port": "5432",
    "db_username": "user",
    "db_password": "pass",
    "db_name": "mydb",
    "query_sql": "SELECT id, name FROM customers;",
    "output_format": "markdown"
  }
}

Result:

| id | name |
|----|------|
| 1  | Alice|
| 2  | Bob  |

Requesting JSON Output

{
  "tool_name": "sql_query",
  "tool_parameters": {
    "db_type": "postgresql",
    "db_host": "localhost",
    "db_port": "5432",
    "db_username": "user",
    "db_password": "pass",
    "db_name": "mydb",
    "query_sql": "SELECT id, name FROM customers;",
    "output_format": "json"
  }
}

Result:

{
  "records": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ]
}

Implementation Details

The format selection logic resides in db_query/tools/sql_query.py between lines 47-63. The tool retrieves the output_format parameter (defaulting to "markdown"), executes the query via DBUtil from tools/db_util.py, and branches based on the normalized format string.

For JSON output, the tool invokes self.create_json_message({"records": rows}). For Markdown or any unspecified format, it passes the rows to tabulate.tabulate(rows, headers=headers, tablefmt="github") and returns the result via self.create_text_message().

The pre-authentication variant in db_query_pre_auth/tools/sql_query.py mirrors this implementation exactly, ensuring consistent behavior across both authentication modes.

Summary

• The Dify SQL query tool supports Markdown (GitHub-flavored tables) and JSON output formats.
• Markdown is the default when output_format is omitted or set to any value other than "json".
• The format is configured via the output_format parameter in the tool configuration.
• Implementation resides in db_query/tools/sql_query.py and db_query_pre_auth/tools/sql_query.py, utilizing tabulate for Markdown and create_json_message for JSON output.

Frequently Asked Questions

What is the default output format for the Dify SQL query tool?

The default output format is Markdown. When the output_format parameter is omitted or set to any value other than "json", the tool returns query results as a GitHub-flavored Markdown table generated by the tabulate library.

How do I return SQL query results as JSON in Dify?

Set the output_format parameter to "json" in your tool configuration. The tool will then wrap the result rows in a JSON object with a records key and return it via self.create_json_message(), making it suitable for API consumption and programmatic processing.

Does the pre-authentication version support the same output formats?

Yes. The pre-authentication variant located in db_query_pre_auth/tools/sql_query.py implements identical format selection logic. Both versions support Markdown and JSON outputs using the same output_format parameter and default to Markdown tables.

Can I customize the Markdown table style beyond the default GitHub format?

No. The implementation specifically uses tabulate.tabulate with tablefmt="github" hardcoded in db_query/tools/sql_query.py. To use a different table style, you would need to modify the source code or post-process the Markdown output in your Dify workflow.

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