# Dify SQL Query Tool Output Formats: Markdown vs JSON Configuration

> Explore Dify SQL query tool output formats like Markdown and JSON. Learn how to configure your query results efficiently for your plugins.

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

---

**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`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/tools/sql_query.py) (lines 47-63) and the pre-authentication variant in [`db_query_pre_auth/tools/sql_query.py`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/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

```json
{
  "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:**

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

```

### Requesting JSON Output

```json
{
  "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:**

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

```

## Implementation Details

The format selection logic resides in [`db_query/tools/sql_query.py`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/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`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/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`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/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`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/tools/sql_query.py) and [`db_query_pre_auth/tools/sql_query.py`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/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`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/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`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/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.