# Difference Between db_query and db_query_pre_auth in Dify: Complete Guide

> Understand the db_query vs db_query_pre_auth difference in Dify plugins. Learn how `db_query_pre_auth` validates credentials upfront for secure database access.

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

---

**The `db_query_pre_auth` plugin validates database credentials before tool execution, while `db_query` only validates at runtime when the SQL query is actually executed.**

Both plugins reside in the `junjiem/dify-plugin-tools-dbquery` repository and share identical core functionality for executing SQL queries against MySQL, PostgreSQL, and other databases. However, they differ fundamentally in **credential validation timing**, which impacts security, user experience, and production reliability.

## Core Differences Between db_query and db_query_pre_auth

### Credential Validation Timing

The primary distinction lies in the `_validate_credentials` method implementation:

- **`db_query`** — In [`db_query/provider/db_query.py`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/provider/db_query.py), the `_validate_credentials` method is a stub that performs no validation (`pass`). The plugin accepts any credential input without verification until the actual tool execution begins.

- **`db_query_pre_auth`** — In [`db_query_pre_auth/provider/db_query.py`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query_pre_auth/provider/db_query.py), the same method actively validates credentials by checking required fields, verifying the port is numeric, and establishing a temporary database connection using `DbUtil` to execute a test query (`db.test_sql()`). If validation fails, the tool is rejected immediately.

### User Experience and Error Handling

**db_query** defers all connection errors to runtime. Users may configure an entire workflow with invalid hostnames or passwords, only discovering the misconfiguration when the tool executes. This creates a poor debugging experience in multi-step workflows.

**db_query_pre_auth** surfaces connection issues during the credential configuration phase. When adding the tool to a Dify workflow, invalid credentials trigger immediate error messages, preventing the workflow from being saved with broken database connections.

### Security Implications

The pre-authorization version provides a security layer by ensuring only valid, reachable database connections can be configured in workflows. The standard version allows potentially malicious or malformed credential strings to persist in workflow configurations until execution time.

## Technical Implementation Details

### db_query Provider Implementation

In [`db_query/provider/db_query.py`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query/provider/db_query.py), the validation logic is intentionally minimal:

```python
def _validate_credentials(self, credentials: dict) -> None:
    """
    Validate the credentials.
    """
    pass

```

This implementation allows the plugin to load immediately without network overhead or connection testing.

### db_query_pre_auth Provider Implementation

In [`db_query_pre_auth/provider/db_query.py`](https://github.com/junjiem/dify-plugin-tools-dbquery/blob/main/db_query_pre_auth/provider/db_query.py), the validation includes comprehensive checks:

```python
def _validate_credentials(self, credentials: dict) -> None:
    """
    Validate the credentials.
    """
    # Check required fields

    if not credentials.get('db_host'):
        raise ValueError("Database host is required")
    
    # Validate port is numeric

    try:
        port = int(credentials.get('db_port', 3306))
    except ValueError:
        raise ValueError("Port must be a valid number")
    
    # Test actual connection

    try:
        db = DbUtil(credentials)
        db.test_sql()
    except Exception as e:
        raise ValueError(f"Failed to connect to database: {str(e)}")

```

This ensures only valid configurations proceed to workflow execution.

## Code Examples and Usage

### Using db_query (Runtime Validation)

When using the standard version, credentials are accepted without verification:

```python

# Dify workflow configuration

{
    "name": "db_query",
    "arguments": {
        "db_type": "mysql",
        "db_host": "my-db.host",
        "db_port": "3306",
        "db_username": "user",
        "db_password": "pwd",
        "db_name": "mydb",
        "sql": "SELECT COUNT(*) FROM orders;"
    }
}

```

Connection errors only appear when the tool executes.

### Using db_query_pre_auth (Pre-authorization)

The pre-auth version validates during configuration:

```python

# Dify workflow configuration

{
    "name": "db_query_pre_auth",
    "arguments": {
        "db_type": "postgresql",
        "db_host": "pg.host",
        "db_port": "5432",
        "db_username": "admin",
        "db_password": "secret",
        "db_name": "sales",
        "sql": "SELECT SUM(amount) FROM invoices;"
    }
}

```

If `pg.host` is unreachable or credentials are invalid, Dify rejects the configuration immediately with a descriptive error message.

## When to Use Each Version

### Use db_query for Rapid Prototyping

Choose the standard `db_query` version when:
- Developing proof-of-concept workflows where database connectivity is guaranteed
- Working in isolated development environments with known-good credentials
- Minimizing configuration-time overhead is critical
- You prefer to handle connection errors through workflow error-handling logic

### Use db_query_pre_auth for Production Workflows

Select `db_query_pre_auth` when:
- Building production workflows where invalid database connections must be caught early
- Multiple team members configure workflows and credential validation prevents misconfiguration
- Database security policies require verification of connectivity before storing credentials
- You need immediate feedback during the Dify tool configuration phase

## Summary

- **db_query** provides lightweight database querying with **runtime-only credential validation**, making it suitable for rapid development but potentially allowing invalid configurations to persist until execution.

- **db_query_pre_auth** adds a **pre-authorization validation layer** that tests database connectivity during the credential configuration phase, catching errors early and improving production reliability.

- Both plugins share identical SQL execution capabilities and support the same database types (MySQL, PostgreSQL, etc.), differing only in the `_validate_credentials` implementation within their respective provider files.

## Frequently Asked Questions

### What is the main difference between db_query and db_query_pre_auth?

The primary difference is **credential validation timing**. The `db_query` plugin accepts database credentials without verification until the SQL query executes, while `db_query_pre_auth` validates the connection by attempting a test query during the configuration phase. This prevents workflows from being saved with invalid database settings.

### Does db_query_pre_auth support all database types?

Yes, both plugins support the same database types including **MySQL**, **PostgreSQL**, **MariaDB**, and other SQL databases supported by the underlying `DbUtil` class. The pre-authorization version simply adds validation logic without restricting database compatibility.

### Can I switch from db_query to db_query_pre_auth without changing my SQL?

Yes, the SQL syntax and query structure remain identical between both versions. You can migrate from `db_query` to `db_query_pre_auth` by simply changing the tool name in your Dify workflow configuration. The pre-auth version will validate your existing credentials during the next configuration save, potentially catching previously undetected connection issues.

### Which version is more secure for production use?

**db_query_pre_auth** is recommended for production environments because it validates database connectivity before storing credentials in workflow configurations. This prevents scenarios where invalid or potentially malicious connection strings persist in production workflows until runtime. The early validation also ensures that database firewall rules and network policies are correctly configured before deployment.