Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(backend): add SQL query block with multi-database support for CoPilot analytics (#12569)

Zamil Majdyfff101e0374c
diff --git a/autogpt_platform/backend/backend/blocks/sql_query_block.py b/autogpt_platform/backend/backend/blocks/sql_query_block.py
new file mode 100644
index 0000000000..c4b6e7a8bc
--- /dev/null
+++ b/autogpt_platform/backend/backend/blocks/sql_query_block.py
@@ -0,0 +1,323 @@
+import asyncio
+from typing import Any, Literal
+
+from pydantic import SecretStr
+from sqlalchemy.engine.url import URL
+from sqlalchemy.exc import DBAPIError, OperationalError, ProgrammingError
+
+from backend.blocks._base import (
+ Block,
+ BlockCategory,
+ BlockOutput,
+ BlockSchemaInput,
+ BlockSchemaOutput,
+)
+from backend.blocks.sql_query_helpers import (
+ _DATABASE_TYPE_DEFAULT_PORT,
+ _DATABASE_TYPE_TO_DRIVER,
+ DatabaseType,
+ _execute_query,
+ _sanitize_error,
+ _validate_query_is_read_only,
+ _validate_single_statement,
+)
+from backend.data.model import (
+ CredentialsField,
+ CredentialsMetaInput,
+ SchemaField,
+ UserPasswordCredentials,
+)
+from backend.integrations.providers import ProviderName
+from backend.util.request import resolve_and_check_blocked
+
+TEST_CREDENTIALS = UserPasswordCredentials(
+ id="01234567-89ab-cdef-0123-456789abcdef",
+ provider="database",
+ username=SecretStr("test_user"),
+ password=SecretStr("test_pass"),
+ title="Mock Database credentials",
+)
+
+TEST_CREDENTIALS_INPUT = {
+ "provider": TEST_CREDENTIALS.provider,
+ "id": TEST_CREDENTIALS.id,
+ "type": TEST_CREDENTIALS.type,
+ "title": TEST_CREDENTIALS.title,
+}
+
+DatabaseCredentials = UserPasswordCredentials
+DatabaseCredentialsInput = CredentialsMetaInput[
+ Literal[ProviderName.DATABASE],
+ Literal["user_password"],
+]
+
+
+def DatabaseCredentialsField() -> DatabaseCredentialsInput:
+ return CredentialsField(
+ description="Database username and password",
+ )
+
+
+class SQLQueryBlock(Block):
+ class Input(BlockSchemaInput):
+ database_type: DatabaseType = SchemaField(
+ default=DatabaseType.POSTGRES,
+ description="Database engine",
+ advanced=False,
+ )
+ host: SecretStr = SchemaField(
+ description=(
+ "Database hostname or IP address. "
+ "Treated as a secret to avoid leaking infrastructure details. "
+ "Private/internal IPs are blocked (SSRF protection)."
+ ),
+ placeholder="db.example.com",
+ secret=True,
+ )
+ port: int | None = SchemaField(
+ default=None,
+ description=(
+ "Database port (leave empty for default: "
+ "PostgreSQL: 5432, MySQL: 3306, MSSQL: 1433)"
+ ),
+ ge=1,
+ le=65535,
+ )
+ database: str = SchemaField(
+ description="Name of the database to connect to",
+ placeholder="my_database",
+ )
+ query: str = SchemaField(
+ description="SQL query to execute",
+ placeholder="SELECT * FROM analytics.daily_active_users LIMIT 10",
+ )
+ read_only: bool = SchemaField(
+ default=True,
+ description=(
+ "When enabled (default), only SELECT queries are allowed "
+ "and the database session is set to read-only mode. "
+ "Disable to allow write operations (INSERT, UPDATE, DELETE, etc.)."
+ ),
+ )
+ timeout: int = SchemaField(
+ default=30,
+ description="Query timeout in seconds (max 120)",
+ ge=1,
+ le=120,
+ )
+ max_rows: int = SchemaField(
+ default=1000,
+ description="Maximum number of rows to return (max 10000)",
+ ge=1,
+ le=10000,
+ )
+ credentials: DatabaseCredentialsInput = DatabaseCredentialsField()
+
+ class Output(BlockSchemaOutput):
+ results: list[dict[str, Any]] = SchemaField(
+ description="Query results as a list of row dictionaries"
+ )
+ columns: list[str] = SchemaField(
+ description="Column names from the query result"
+ )
+ row_count: int = SchemaField(description="Number of rows returned")
+ truncated: bool = SchemaField(
+ description=(
+ "True when the result set was capped by max_rows, "
+ "indicating additional rows exist in the database"
+ )
+ )
+ affected_rows: int = SchemaField(
+ description="Number of rows affected by a write query (INSERT/UPDATE/DELETE)"
+ )
+ error: str = SchemaField(description="Error message if the query failed")
+
+ def __init__(self):
+ super().__init__(
+ id="4dc35c0f-4fd8-465e-9616-5a216f1ba2bc",
+ description=(
+ "Execute a SQL query. Read-only by default for safety "
+ "-- disable to allow write operations. "
+ "Supports PostgreSQL, MySQL, and MSSQL via SQLAlchemy."
+ ),
+ categories={BlockCategory.DATA},
+ input_schema=SQLQueryBlock.Input,
+ output_schema=SQLQueryBlock.Output,
+ test_input={
+ "query": "SELECT 1 AS test_col",
+ "database_type": DatabaseType.POSTGRES,
+ "host": "localhost",
+ "database": "test_db",
+ "timeout": 30,
+ "max_rows": 1000,
+ "credentials": TEST_CREDENTIALS_INPUT,
+ },
+ test_credentials=TEST_CREDENTIALS,
+ test_output=[
+ ("results", [{"test_col": 1}]),
+ ("columns", ["test_col"]),
+ ("row_count", 1),
+ ("truncated", False),
+ ],
+ test_mock={
+ "execute_query": lambda *_args, **_kwargs: (
+ [{"test_col": 1}],
+ ["test_col"],
+ -1,
+ False,
+ ),
+ "check_host_allowed": lambda *_args, **_kwargs: ["127.0.0.1"],
+ },
+ )
+
+ @staticmethod
+ async def check_host_allowed(host: str) -> list[str]:
+ """Validate that the given host is not a private/blocked address.
+
+ Returns the list of resolved IP addresses so the caller can pin the
+ connection to the validated IP (preventing DNS rebinding / TOCTOU).
+ Raises ValueError or OSError if the host is blocked.
+ Extracted as a method so it can be mocked during block tests.
+ """
+ return await resolve_and_check_blocked(host)
+
+ @staticmethod
+ def execute_query(
+ connection_url: URL | str,
+ query: str,
+ timeout: int,
+ max_rows: int,
+ read_only: bool = True,
+ database_type: DatabaseType = DatabaseType.POSTGRES,
+ ) -> tuple[list[dict[str, Any]], list[str], int, bool]:
+ """Execute a SQL query and return (rows, columns, affected_rows, truncated).
+
+ Delegates to ``_execute_query`` in ``sql_query_helpers``.
+ Extracted as a method so it can be mocked during block tests.
+ """
+ return _execute_query(
+ connection_url=connection_url,
+ query=query,
+ timeout=timeout,
+ max_rows=max_rows,
+ read_only=read_only,
+ database_type=database_type,
+ )
+
+ async def run(
+ self,
+ input_data: Input,
+ *,
+ credentials: DatabaseCredentials,
+ **_kwargs: Any,
+ ) -> BlockOutput:
+ # Validate query structure and read-only constraints.
+ error = self._validate_query(input_data)
+ if error:
+ yield "error", error
+ return
+
+ # Validate host and resolve for SSRF protection.
+ host, pinned_host, error = await self._resolve_host(input_data)
+ if error:
+ yield "error", error
+ return
+
+ # Build connection URL and execute.
+ port = input_data.port or _DATABASE_TYPE_DEFAULT_PORT[input_data.database_type]
+ username = credentials.username.get_secret_value()
+ connection_url = URL.create(
+ drivername=_DATABASE_TYPE_TO_DRIVER[input_data.database_type],
+ username=username,
+ password=credentials.password.get_secret_value(),
+ host=pinned_host,
+ port=port,
+ database=input_data.database,
+ )
+ conn_str = connection_url.render_as_string(hide_password=True)
+ db_name = input_data.database
+
+ def _sanitize(err: Exception) -> str:
+ return _sanitize_error(
+ str(err).strip(),
+ conn_str,
+ host=pinned_host,
+ original_host=host,
+ username=username,
+ port=port,
+ database=db_name,
+ )
+
+ try:
+ results, columns, affected, truncated = await asyncio.to_thread(
+ self.execute_query,
+ connection_url=connection_url,
+ query=input_data.query,
+ timeout=input_data.timeout,
+ max_rows=input_data.max_rows,
+ read_only=input_data.read_only,
+ database_type=input_data.database_type,
+ )
+ yield "results", results
+ yield "columns", columns
+ yield "row_count", len(results)
+ yield "truncated", truncated
+ if affected >= 0:
+ yield "affected_rows", affected
+ except OperationalError as e:
+ yield (
+ "error",
+ self._classify_operational_error(
+ _sanitize(e),
+ input_data.timeout,
+ ),
+ )
+ except ProgrammingError as e:
+ yield "error", f"SQL error: {_sanitize(e)}"
+ except DBAPIError as e:
+ yield "error", f"Database error: {_sanitize(e)}"
+ except ModuleNotFoundError:
+ yield (
+ "error",
+ (
+ f"Database driver not available for "
+ f"{input_data.database_type.value}. "
+ f"Please contact the platform administrator."
+ ),
+ )
+
+ @staticmethod
+ def _validate_query(input_data: "SQLQueryBlock.Input") -> str | None:
+ """Validate query structure and read-only constraints."""
+ stmt_error, parsed_stmt = _validate_single_statement(input_data.query)
+ if stmt_error:
+ return stmt_error
+ assert parsed_stmt is not None
+ if input_data.read_only:
+ return _validate_query_is_read_only(parsed_stmt)
+ return None
+
+ async def _resolve_host(
+ self, input_data: "SQLQueryBlock.Input"
+ ) -> tuple[str, str, str | None]:
+ """Validate and resolve the database host. Returns (host, pinned_ip, error)."""
+ host = input_data.host.get_secret_value().strip()
+ if not host:
+ return "", "", "Database host is required."
+ if host.startswith("/"):
+ return host, "", "Unix socket connections are not allowed."
+ try:
+ resolved_ips = await self.check_host_allowed(host)
+ except (ValueError, OSError) as e:
+ return host, "", f"Blocked host: {str(e).strip()}"
+ return host, resolved_ips[0], None
+
+ @staticmethod
+ def _classify_operational_error(sanitized_msg: str, timeout: int) -> str:
+ """Classify an already-sanitized OperationalError for user display."""
+ lower = sanitized_msg.lower()
+ if "timeout" in lower or "cancel" in lower:
+ return f"Query timed out after {timeout}s."
+ if "connect" in lower:
+ return f"Failed to connect to database: {sanitized_msg}"
+ return f"Database error: {sanitized_msg}"
diff --git a/autogpt_platform/backend/backend/blocks/sql_query_block_test.py b/autogpt_platform/backend/backend/blocks/sql_query_block_test.py
new file mode 100644
index 0000000000..646f401c09
--- /dev/null
+++ b/autogpt_platform/backend/backend/blocks/sql_query_block_test.py
@@ -0,0 +1,1851 @@
+"""Tests for SQLQueryBlock: single-statement validation, URL validation,
+error sanitization, SSRF protection, and read/write mode behavior."""
+
+from datetime import date, datetime, time
+from decimal import Decimal
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from pydantic import SecretStr
+from sqlalchemy import create_engine, text
+from sqlalchemy.exc import OperationalError
+
+from backend.blocks.sql_query_block import SQLQueryBlock, UserPasswordCredentials
+from backend.blocks.sql_query_helpers import (
+ _CONNECT_TIMEOUT_SECONDS,
+ DatabaseType,
+ _configure_session,
+ _execute_query,
+ _run_in_transaction,
+ _sanitize_error,
+ _serialize_value,
+ _validate_query_is_read_only,
+ _validate_single_statement,
+)
+
+
+class TestValidateSingleStatement:
+ """Tests for _validate_single_statement multi-statement prevention."""
+
+ @pytest.mark.parametrize(
+ "query",
+ [
+ "SELECT 1",
+ "SELECT * FROM users",
+ "INSERT INTO t VALUES (1)",
+ "UPDATE t SET x = 1",
+ "DELETE FROM t WHERE id = 1",
+ "CREATE TABLE t (id INT)",
+ "DROP TABLE t",
+ "SELECT * FROM users;",
+ " SELECT 1 ",
+ ],
+ )
+ def test_valid_single_statements(self, query: str):
+ error, stmt = _validate_single_statement(query)
+ assert error is None
+ assert stmt is not None
+
+ @pytest.mark.parametrize(
+ "query",
+ [
+ "SELECT * FROM users; DELETE FROM users",
+ "SELECT * FROM users; DROP TABLE users",
+ "SELECT 1; INSERT INTO users VALUES (1)",
+ "INSERT INTO t VALUES (1); DROP TABLE t",
+ "SELECT '--'; SET LOCAL statement_timeout = 0; SELECT pg_sleep(1000)",
+ "SELECT 1; SET search_path TO public",
+ "SELECT 1; RESET ALL",
+ ],
+ )
+ def test_multi_statement_rejected(self, query: str):
+ error, stmt = _validate_single_statement(query)
+ assert error == "Only single statements are allowed."
+ assert stmt is None
+
+ def test_empty_query(self):
+ error, stmt = _validate_single_statement("")
+ assert error == "Query is empty."
+ assert stmt is None
+
+ def test_whitespace_only_query(self):
+ error, stmt = _validate_single_statement(" ")
+ assert error == "Query is empty."
+ assert stmt is None
+
+ def test_semicolon_only(self):
+ error, stmt = _validate_single_statement(";")
+ assert error == "Query is empty."
+ assert stmt is None
+
+ def test_comment_only_query(self):
+ error, stmt = _validate_single_statement("-- just a comment")
+ assert error == "Query is empty."
+ assert stmt is None
+
+
+class TestValidateQueryIsReadOnly:
+ """Tests for _validate_query_is_read_only read-only enforcement."""
+
+ @pytest.mark.parametrize(
+ "query",
+ [
+ "SELECT 1",
+ "SELECT * FROM users",
+ "SELECT * FROM users WHERE id = 1",
+ " SELECT 1 ",
+ # MySQL INTO @variable syntax is read-only (session variable assignment)
+ "SELECT COUNT(*) INTO @total FROM users",
+ "SELECT name, age INTO @n, @a FROM users WHERE id = 1",
+ ],
+ )
+ def test_valid_select_queries(self, query: str):
+ _, stmt = _validate_single_statement(query)
+ assert stmt is not None
+ assert _validate_query_is_read_only(stmt) is None
+
+ @pytest.mark.parametrize(
+ "query",
+ [
+ "INSERT INTO t VALUES (1)",
+ "UPDATE t SET x = 1",
+ "DELETE FROM t WHERE id = 1",
+ "DROP TABLE t",
+ "CREATE TABLE t (id INT)",
+ ],
+ )
+ def test_non_select_rejected(self, query: str):
+ _, stmt = _validate_single_statement(query)
+ assert stmt is not None
+ result = _validate_query_is_read_only(stmt)
+ assert result is not None
+
+ @pytest.mark.parametrize(
+ "query",
+ [
+ # SELECT INTO table creates a new table (PostgreSQL/MSSQL)
+ "SELECT * INTO new_table FROM users",
+ # SELECT INTO OUTFILE/DUMPFILE writes to the filesystem (MySQL)
+ "SELECT * INTO OUTFILE '/tmp/data.csv' FROM users",
+ "SELECT * INTO DUMPFILE '/tmp/data.bin' FROM users",
+ ],
+ )
+ def test_select_into_non_variable_rejected(self, query: str):
+ _, stmt = _validate_single_statement(query)
+ assert stmt is not None
+ result = _validate_query_is_read_only(stmt)
+ assert result is not None
+ assert "INTO" in result
+
+
+class TestSerializeValue:
+ """Tests for _serialize_value type conversion."""
+
+ def test_decimal_integer(self):
+ assert _serialize_value(Decimal("42")) == 42
+ assert isinstance(_serialize_value(Decimal("42")), int)
+
+ def test_decimal_fractional(self):
+ # Fractional decimals are serialized as strings to preserve exact precision
+ assert _serialize_value(Decimal("3.14")) == "3.14"
+ assert isinstance(_serialize_value(Decimal("3.14")), str)
+
+ def test_decimal_high_precision(self):
+ # High-precision values must not lose precision via float conversion
+ val = Decimal("123456789.123456789012345678")
+ result = _serialize_value(val)
+ assert result == "123456789.123456789012345678"
+ assert isinstance(result, str)
+
+ def test_datetime(self):
+ dt = datetime(2024, 1, 1, 12, 0, 0)
+ assert _serialize_value(dt) == "2024-01-01T12:00:00"
+
+ def test_date(self):
+ d = date(2024, 6, 15)
+ assert _serialize_value(d) == "2024-06-15"
+
+ def test_time(self):
+ t = time(14, 30, 45)
+ assert _serialize_value(t) == "14:30:45"
+
+ def test_memoryview(self):
+ mv = memoryview(b"\xde\xad\xbe\xef")
+ assert _serialize_value(mv) == "deadbeef"
+
+ def test_bytes(self):
+ assert _serialize_value(b"\xca\xfe") == "cafe"
+
+ def test_passthrough_string(self):
+ assert _serialize_value("hello") == "hello"
+
+ def test_passthrough_int(self):
+ assert _serialize_value(42) == 42
+
+ def test_passthrough_none(self):
+ assert _serialize_value(None) is None
+
+ def test_passthrough_list(self):
+ assert _serialize_value([1, 2, 3]) == [1, 2, 3]
+
+
+class TestSanitizeError:
+ """Tests for _sanitize_error credential and infrastructure scrubbing."""
+
+ def test_connection_string_replaced(self):
+ conn = "postgresql://user:secret@host:5432/db"
+ error = f"could not connect to server: {conn}"
+ result = _sanitize_error(error, conn)
+ assert "secret" not in result
+ assert "<connection_string>" in result
+
+ def test_password_param_scrubbed(self):
+ conn = "postgresql://user:secret@host:5432/db"
+ error = "FATAL: password=secret123 authentication failed"
+ result = _sanitize_error(error, conn)
+ assert "secret123" not in result
+ assert "password=***" in result
+
+ def test_url_credentials_scrubbed(self):
+ conn = "postgresql://user:secret@host:5432/db"
+ error = "connection to postgresql://admin:[email protected]:5432/testprod failed"
+ result = _sanitize_error(error, conn)
+ assert "hunter2" not in result
+ assert "***:***@" in result
+
+ def test_clean_error_unchanged(self):
+ conn = "postgresql://user:secret@host:5432/db"
+ error = "relation 'foo' does not exist"
+ result = _sanitize_error(error, conn)
+ assert result == error
+
+ def test_mysql_connection_string_replaced(self):
+ conn = "mysql://admin:[email protected]:3306/mydb"
+ error = f"Can't connect to MySQL server: {conn}"
+ result = _sanitize_error(error, conn)
+ assert "s3cret" not in result
+ assert "<connection_string>" in result
+
+ def test_hostname_scrubbed(self):
+ """Database hostname must be replaced with <host>."""
+ conn = "postgresql://user:[email protected]:5432/db"
+ error = (
+ 'connection to server at "db.example.supabase.invalid" '
+ "(198.51.100.1), port 5432 failed: FATAL: "
+ 'password authentication failed for user "postgres"'
+ )
+ result = _sanitize_error(
+ error, conn, host="198.51.100.1", username="postgres", port=5432
+ )
+ assert "198.51.100.1" not in result
+ assert "postgres" not in result
+ assert "5432" not in result
+ assert "<host>" in result
+ assert "<user>" in result
+ assert "password authentication failed" in result
+
+ def test_ip_addresses_scrubbed(self):
+ """Any IPv4 address in the error must be replaced with <ip>."""
+ conn = "postgresql://user:[email protected]:5432/db"
+ error = "could not connect to 10.0.0.5 (192.168.1.100): Connection refused"
+ result = _sanitize_error(error, conn, host="10.0.0.5")
+ assert "10.0.0.5" not in result
+ assert "192.168.1.100" not in result
+ assert "<host>" in result or "<ip>" in result
+
+ def test_username_scrubbed(self):
+ """Database username must be replaced with <user>."""
+ conn = "postgresql://testuser:[email protected]:5432/testdb"
+ error = 'FATAL: role "analytics_ro" does not exist'
+ result = _sanitize_error(error, conn, username="analytics_ro")
+ assert "analytics_ro" not in result
+ assert "<user>" in result
+
+ def test_username_single_quoted_scrubbed(self):
+ """Single-quoted usernames (MySQL/MSSQL) must be scrubbed."""
+ conn = "mysql+pymysql://app_user:[email protected]:3306/db"
+ error = "Access denied for user 'app_user'@'1.2.3.4'"
+ result = _sanitize_error(error, conn, username="app_user", host="1.2.3.4")
+ assert "app_user" not in result
+ assert "<user>" in result
+
+ def test_username_mssql_login_failed_scrubbed(self):
+ """MSSQL 'Login failed for user' with single quotes must be scrubbed."""
+ conn = "mssql+pymssql://sa:[email protected]:1433/db"
+ error = "Login failed for user 'sa'. Reason: Password did not match."
+ result = _sanitize_error(error, conn, username="sa")
+ assert "'sa'" not in result
+ assert "<user>" in result
+
+ def test_port_scrubbed(self):
+ """Database port must be replaced with <port>."""
+ conn = "postgresql://user:[email protected]:6543/db"
+ error = "could not connect to <host> (<ip>), port 6543 failed"
+ result = _sanitize_error(error, conn, port=6543)
+ assert "6543" not in result
+ assert "<port>" in result
+
+ def test_port_colon_format_scrubbed(self):
+ """Port in host:port format must also be replaced."""
+ conn = "postgresql://user:[email protected]:6543/db"
+ error = "could not connect to <host>:6543"
+ result = _sanitize_error(error, conn, port=6543)
+ assert "6543" not in result
+ assert ":<port>" in result
+
+ def test_realistic_postgres_error_fully_sanitized(self):
+ """Full realistic Postgres connection error must not leak any infra details."""
+ conn = "postgresql://testuser:[email protected]:5432/testdb"
+ error = (
+ "(psycopg2.OperationalError) connection to server at "
+ '"db.example.supabase.invalid" (198.51.100.1), '
+ "port 5432 failed: FATAL: "
+ 'password authentication failed for user "postgres"'
+ )
+ result = _sanitize_error(
+ error,
+ conn,
+ host="198.51.100.1",
+ original_host="db.example.supabase.invalid",
+ username="postgres",
+ port=5432,
+ )
+ assert "198.51.100.1" not in result
+ assert "adfjtextkuilwuhzdjpf" not in result
+ assert "supabase" not in result
+ assert "postgres" not in result
+ assert "5432" not in result
+ # The actual error type is preserved for the LLM
+ assert "password authentication failed" in result
+
+ def test_database_name_scrubbed(self):
+ """Database name must be replaced with <database>."""
+ conn = "postgresql://user:[email protected]:5432/analytics_prod"
+ error = 'database "analytics_prod" does not exist'
+ result = _sanitize_error(error, conn, database="analytics_prod")
+ assert "analytics_prod" not in result
+ assert "<database>" in result
+
+ def test_database_name_word_boundary_prevents_mangling(self):
+ """Common database names must not mangle unrelated words."""
+ conn = "postgresql://user:[email protected]:5432/test"
+ error = 'FATAL: database "test" does not exist (tested connection)'
+ result = _sanitize_error(error, conn, database="test")
+ assert "tested" in result
+ assert '"<database>"' in result
+
+
+# ---------------------------------------------------------------------------
+# Helpers for run()-level integration tests
+# ---------------------------------------------------------------------------
+
+
+def _make_credentials(
+ username: str = "user", password: str = "pass"
+) -> UserPasswordCredentials:
+ return UserPasswordCredentials(
+ id="01234567-89ab-cdef-0123-456789abcdef",
+ provider="database",
+ username=SecretStr(username),
+ password=SecretStr(password),
+ title="test creds",
+ )
+
+
+def _make_input(
+ creds: UserPasswordCredentials,
+ query: str = "SELECT 1",
+ database_type: DatabaseType = DatabaseType.POSTGRES,
+ host: str = "db.example.com",
+ port: int | None = 5432,
+ database: str = "db",
+ read_only: bool = False,
+ timeout: int = 30,
+ max_rows: int = 100,
+) -> SQLQueryBlock.Input:
+ """Build a test input. Note: ``read_only`` defaults to ``False`` here (unlike the
+ block's default of ``True``) so write-mode tests don't need to specify it.
+ Set ``read_only=True`` explicitly when testing read-only behaviour."""
+ return SQLQueryBlock.Input(
+ query=query,
+ database_type=database_type,
+ host=SecretStr(host),
+ port=port,
+ database=database,
+ read_only=read_only,
+ timeout=timeout,
+ max_rows=max_rows,
+ credentials={ # type: ignore[arg-type]
+ "provider": "database",
+ "id": creds.id,
+ "type": "user_password",
+ "title": "t",
+ },
+ )
+
+
+async def _collect_outputs(
+ block: SQLQueryBlock,
+ input_data: SQLQueryBlock.Input,
+ credentials: UserPasswordCredentials,
+) -> dict[str, Any]:
+ """Run the block and collect all yielded (name, value) pairs."""
+ outputs: dict[str, Any] = {}
+ async for name, value in block.run(input_data, credentials=credentials):
+ outputs[name] = value
+ return outputs
+
+
+# ---------------------------------------------------------------------------
+# Integration tests: SQLQueryBlock.run() -- SSRF, error handling
+# ---------------------------------------------------------------------------
+
+
+class TestSQLQueryBlockRunSSRF:
+ """SSRF protection tests exercised through the block's run() method."""
+
+ async def test_private_ip_127_rejected(self):
+ """Scenario 6: loopback 127.0.0.1 must be blocked."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, host="127.0.0.1")
+ # Mock check_host_allowed to simulate the real SSRF check raising
+ block.check_host_allowed = AsyncMock( # type: ignore[assignment]
+ side_effect=ValueError(
+ "Access to blocked or private IP address 127.0.0.1 "
+ "for hostname 127.0.0.1 is not allowed."
+ )
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "Blocked host" in outputs["error"]
+
+ async def test_private_ip_10_rejected(self):
+ """Scenario 7: internal 10.x.x.x must be blocked."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, host="10.0.0.1")
+ block.check_host_allowed = AsyncMock( # type: ignore[assignment]
+ side_effect=ValueError(
+ "Access to blocked or private IP address 10.0.0.1 "
+ "for hostname 10.0.0.1 is not allowed."
+ )
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "Blocked host" in outputs["error"]
+
+ async def test_unix_socket_rejected(self):
+ """Scenario 8: Unix socket paths in host must be blocked."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, host="/var/run/postgresql")
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "Unix socket" in outputs["error"]
+
+ async def test_missing_hostname_rejected(self):
+ """Scenario 9: Empty hostname must be rejected."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, host=" ")
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "host" in outputs["error"].lower()
+
+ async def test_private_ip_172_rejected(self):
+ """172.16.x.x private range must be blocked."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, host="172.16.0.1")
+ block.check_host_allowed = AsyncMock( # type: ignore[assignment]
+ side_effect=ValueError(
+ "Access to blocked or private IP address 172.16.0.1 "
+ "for hostname 172.16.0.1 is not allowed."
+ )
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "Blocked host" in outputs["error"]
+
+ async def test_private_ip_192_168_rejected(self):
+ """192.168.x.x private range must be blocked."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, host="192.168.1.1")
+ block.check_host_allowed = AsyncMock( # type: ignore[assignment]
+ side_effect=ValueError(
+ "Access to blocked or private IP address 192.168.1.1 "
+ "for hostname 192.168.1.1 is not allowed."
+ )
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "Blocked host" in outputs["error"]
+
+
+class TestSQLQueryBlockRunErrorHandling:
+ """Error handling: connection failures and timeouts."""
+
+ async def test_connection_failure_sanitized_no_credentials(self):
+ """Connection error must not leak credentials."""
+ block = SQLQueryBlock()
+ creds = _make_credentials(username="admin", password="supersecret")
+ input_data = _make_input(creds)
+ # Mock SSRF check to allow the host
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ # Mock execute_query to raise an OperationalError with credentials in msg
+ conn_url = "postgresql://admin:[email protected]:5432/db"
+ block.execute_query = lambda **_kwargs: (_ for _ in ()).throw( # type: ignore[assignment]
+ OperationalError(
+ f"could not connect to server: Connection refused\n"
+ f'\tIs the server running on host "{conn_url}"?',
+ params=None,
+ orig=Exception("connection refused"),
+ )
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "supersecret" not in outputs["error"]
+ assert "connect" in str(outputs["error"]).lower()
+
+ async def test_connection_error_no_hostname_or_ip_leak(self):
+ """Connection error output must not leak hostname, IP, username, or port."""
+ block = SQLQueryBlock()
+ creds = _make_credentials(username="postgres", password="secret")
+ input_data = _make_input(
+ creds, host="db.test.supabase.invalid", port=5432, database="mydb"
+ )
+ block.check_host_allowed = AsyncMock(return_value=["198.51.100.1"]) # type: ignore[assignment]
+ block.execute_query = lambda **_kwargs: (_ for _ in ()).throw( # type: ignore[assignment]
+ OperationalError(
+ 'connection to server at "db.test.supabase.invalid" (198.51.100.1), '
+ "port 5432 failed: FATAL: "
+ 'password authentication failed for user "postgres"',
+ params=None,
+ orig=Exception("auth failed"),
+ )
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ error = outputs["error"]
+ assert "db.test.supabase.invalid" not in error
+ assert "198.51.100.1" not in error
+ assert '"postgres"' not in error
+ assert "password authentication failed" in error
+
+ async def test_query_timeout_clean_error(self):
+ """Timeout yields clean user-facing message."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, query="SELECT pg_sleep(1000)", timeout=5)
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ block.execute_query = lambda **_kwargs: (_ for _ in ()).throw( # type: ignore[assignment]
+ OperationalError(
+ "canceling statement due to statement timeout",
+ params=None,
+ orig=Exception("timeout"),
+ )
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "timed out" in str(outputs["error"]).lower()
+ assert "5s" in str(outputs["error"])
+
+ async def test_successful_select_returns_results(self):
+ """Happy path: mocked SELECT returns correct structure."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, query="SELECT id, name FROM users LIMIT 2")
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ mock_rows = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
+ mock_cols = ["id", "name"]
+ block.execute_query = lambda **_kwargs: (mock_rows, mock_cols, -1, False) # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert outputs["results"] == mock_rows
+ assert outputs["columns"] == mock_cols
+ assert outputs["row_count"] == 2
+ assert outputs["truncated"] is False
+ # SELECT does not produce affected_rows
+ assert "affected_rows" not in outputs
+
+ async def test_multi_statement_rejected_at_run_level(self):
+ """Multi-statement queries are rejected before any connection attempt."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds, query="SELECT 1; DROP TABLE users", read_only=False
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "single statements" in str(outputs["error"]).lower()
+
+ async def test_special_chars_in_password(self):
+ """Passwords with special characters should work without encoding issues."""
+ block = SQLQueryBlock()
+ creds = _make_credentials(username="analytics_ly", password="Qw13!@#1!\\a2")
+ input_data = _make_input(creds)
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ mock_rows = [{"id": 1}]
+ mock_cols = ["id"]
+ block.execute_query = lambda **_kwargs: (mock_rows, mock_cols, -1, False) # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ assert outputs["results"] == mock_rows
+
+
+# ---------------------------------------------------------------------------
+# Write mode tests (read_only=False)
+# ---------------------------------------------------------------------------
+
+
+class TestSQLQueryBlockWriteMode:
+ """Tests for read_only=False (write mode) behavior."""
+
+ async def test_insert_allowed(self):
+ """INSERT should succeed when read_only=False."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="INSERT INTO users (name) VALUES ('Alice')",
+ read_only=False,
+ )
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ block.execute_query = lambda **_kwargs: ([], [], 1, False) # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ assert outputs["results"] == []
+ assert outputs["row_count"] == 0
+ assert outputs["affected_rows"] == 1
+
+ async def test_update_allowed(self):
+ """UPDATE should succeed when read_only=False."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="UPDATE users SET name = 'Bob' WHERE id = 1",
+ read_only=False,
+ )
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ block.execute_query = lambda **_kwargs: ([], [], 1, False) # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ assert outputs["affected_rows"] == 1
+
+ async def test_delete_allowed(self):
+ """DELETE should succeed when read_only=False."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="DELETE FROM users WHERE id = 1",
+ read_only=False,
+ )
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ block.execute_query = lambda **_kwargs: ([], [], 1, False) # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ assert outputs["affected_rows"] == 1
+
+ async def test_create_table_allowed(self):
+ """CREATE TABLE should succeed when read_only=False."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="CREATE TABLE new_table (id INT PRIMARY KEY, name TEXT)",
+ read_only=False,
+ )
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ block.execute_query = lambda **_kwargs: ([], [], 0, False) # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+
+ async def test_drop_table_allowed(self):
+ """DROP TABLE should succeed when read_only=False."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="DROP TABLE old_table",
+ read_only=False,
+ )
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ block.execute_query = lambda **_kwargs: ([], [], 0, False) # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+
+ async def test_multi_statement_rejected_even_in_write_mode(self):
+ """Multi-statement injection is blocked regardless of read_only setting."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="INSERT INTO t VALUES (1); DROP TABLE t",
+ read_only=False,
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "single statements" in str(outputs["error"]).lower()
+
+ async def test_ssrf_protection_still_active_in_write_mode(self):
+ """SSRF checks apply regardless of read_only setting."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ host="127.0.0.1",
+ query="INSERT INTO t VALUES (1)",
+ read_only=False,
+ )
+ block.check_host_allowed = AsyncMock( # type: ignore[assignment]
+ side_effect=ValueError("Access to blocked IP 127.0.0.1 is not allowed.")
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "Blocked host" in outputs["error"]
+
+ async def test_affected_rows_returned_for_write(self):
+ """Write queries return affected_rows count."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="UPDATE users SET active = true WHERE last_login > '2024-01-01'",
+ read_only=False,
+ )
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ block.execute_query = lambda **_kwargs: ([], [], 42, False) # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ assert outputs["affected_rows"] == 42
+
+ async def test_select_in_write_mode_no_affected_rows(self):
+ """SELECT in write mode still returns results, not affected_rows."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="SELECT id, name FROM users LIMIT 2",
+ read_only=False,
+ )
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ mock_rows = [{"id": 1, "name": "Alice"}]
+ mock_cols = ["id", "name"]
+ block.execute_query = lambda **_kwargs: (mock_rows, mock_cols, -1, False) # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert outputs["results"] == mock_rows
+ assert outputs["columns"] == mock_cols
+ assert outputs["row_count"] == 1
+ # affected_rows should not be yielded for SELECT (returns_rows=True -> -1)
+ assert "affected_rows" not in outputs
+
+
+# ---------------------------------------------------------------------------
+# Read-only mode tests (read_only=True)
+# ---------------------------------------------------------------------------
+
+
+class TestSQLQueryBlockReadOnlyMode:
+ """Tests for read_only=True behavior."""
+
+ async def test_select_works_in_read_only_mode(self):
+ """SELECT should succeed in read-only mode."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="SELECT 1 AS col",
+ read_only=True,
+ )
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ block.execute_query = lambda **_kwargs: ([{"col": 1}], ["col"], -1, False) # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ assert outputs["results"] == [{"col": 1}]
+
+ async def test_insert_rejected_in_read_only_mode(self):
+ """INSERT should be rejected in read-only mode."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="INSERT INTO t VALUES (1)",
+ read_only=True,
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "SELECT" in outputs["error"]
+
+ async def test_read_only_default_is_true(self):
+ """read_only should default to True on the Input schema."""
+ creds = _make_credentials()
+ # Do not pass read_only; rely on the default
+ input_data = SQLQueryBlock.Input(
+ query="SELECT 1",
+ database_type=DatabaseType.POSTGRES,
+ host=SecretStr("db.example.com"),
+ port=5432,
+ database="db",
+ timeout=30,
+ max_rows=100,
+ credentials={ # type: ignore[arg-type]
+ "provider": "database",
+ "id": creds.id,
+ "type": "user_password",
+ "title": "t",
+ },
+ )
+ assert input_data.read_only is True
+
+
+# ---------------------------------------------------------------------------
+# Default port tests (Thread 25: port should auto-detect per database_type)
+# ---------------------------------------------------------------------------
+
+
+class TestSQLQueryBlockDefaultPort:
+ """Port should default based on the selected database_type."""
+
+ async def test_mysql_default_port_3306(self):
+ """MySQL should default to port 3306 when port is None."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="SELECT 1",
+ database_type=DatabaseType.MYSQL,
+ port=None,
+ read_only=False,
+ )
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ captured_conn_str = {}
+
+ def fake_execute(
+ **kwargs: Any,
+ ) -> tuple[list[dict[str, Any]], list[str], int, bool]:
+ captured_conn_str["value"] = str(kwargs["connection_url"])
+ return [{"id": 1}], ["id"], -1, False
+
+ block.execute_query = fake_execute # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ assert ":3306/" in captured_conn_str["value"]
+
+ async def test_mssql_default_port_1433(self):
+ """MSSQL should default to port 1433 when port is None."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="SELECT 1",
+ database_type=DatabaseType.MSSQL,
+ port=None,
+ read_only=False,
+ )
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ captured_conn_str = {}
+
+ def fake_execute(
+ **kwargs: Any,
+ ) -> tuple[list[dict[str, Any]], list[str], int, bool]:
+ captured_conn_str["value"] = str(kwargs["connection_url"])
+ return [{"id": 1}], ["id"], -1, False
+
+ block.execute_query = fake_execute # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ assert ":1433/" in captured_conn_str["value"]
+
+ async def test_postgres_default_port_5432(self):
+ """PostgreSQL should default to port 5432 when port is None."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="SELECT 1",
+ database_type=DatabaseType.POSTGRES,
+ port=None,
+ read_only=False,
+ )
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ captured_conn_str = {}
+
+ def fake_execute(
+ **kwargs: Any,
+ ) -> tuple[list[dict[str, Any]], list[str], int, bool]:
+ captured_conn_str["value"] = str(kwargs["connection_url"])
+ return [{"id": 1}], ["id"], -1, False
+
+ block.execute_query = fake_execute # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ assert ":5432/" in captured_conn_str["value"]
+
+ async def test_explicit_port_overrides_default(self):
+ """Explicitly provided port should be used regardless of database_type."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="SELECT 1",
+ database_type=DatabaseType.MYSQL,
+ port=3307,
+ read_only=False,
+ )
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ captured_conn_str = {}
+
+ def fake_execute(
+ **kwargs: Any,
+ ) -> tuple[list[dict[str, Any]], list[str], int, bool]:
+ captured_conn_str["value"] = str(kwargs["connection_url"])
+ return [{"id": 1}], ["id"], -1, False
+
+ block.execute_query = fake_execute # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ assert ":3307/" in captured_conn_str["value"]
+
+
+# ---------------------------------------------------------------------------
+# DNS pinning tests (Thread 24: TOCTOU / DNS rebinding prevention)
+# ---------------------------------------------------------------------------
+
+
+class TestSQLQueryBlockDNSPinning:
+ """Connection should use the resolved IP, not the original hostname."""
+
+ async def test_connection_uses_resolved_ip(self):
+ """The connection string should contain the resolved IP, not the hostname."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, host="evil.example.com")
+ block.check_host_allowed = AsyncMock(return_value=["93.184.216.34"]) # type: ignore[assignment]
+ captured_conn_str = {}
+
+ def fake_execute(
+ **kwargs: Any,
+ ) -> tuple[list[dict[str, Any]], list[str], int, bool]:
+ captured_conn_str["value"] = str(kwargs["connection_url"])
+ return [{"id": 1}], ["id"], -1, False
+
+ block.execute_query = fake_execute # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ # The resolved IP should be in the connection string, not the hostname
+ assert "93.184.216.34" in captured_conn_str["value"]
+ assert "evil.example.com" not in captured_conn_str["value"]
+
+
+# ---------------------------------------------------------------------------
+# Security gap tests: IPv6 SSRF, writable CTEs, timeout/max_rows enforcement,
+# and password scrubbing in error messages.
+# ---------------------------------------------------------------------------
+
+
+class TestSQLQueryBlockIPv6SSRF:
+ """IPv6 loopback and link-local addresses must be blocked."""
+
+ async def test_ipv6_loopback_rejected(self):
+ """IPv6 loopback (::1) must be blocked just like 127.0.0.1."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, host="::1")
+ block.check_host_allowed = AsyncMock( # type: ignore[assignment]
+ side_effect=ValueError(
+ "Access to blocked or private IP address ::1 "
+ "for hostname ::1 is not allowed."
+ )
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "Blocked host" in outputs["error"]
+
+ async def test_ipv6_link_local_rejected(self):
+ """IPv6 link-local (fe80::) must be blocked."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, host="fe80::1")
+ block.check_host_allowed = AsyncMock( # type: ignore[assignment]
+ side_effect=ValueError(
+ "Access to blocked or private IP address fe80::1 "
+ "for hostname fe80::1 is not allowed."
+ )
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "Blocked host" in outputs["error"]
+
+ async def test_ipv6_mapped_ipv4_loopback_rejected(self):
+ """IPv4-mapped IPv6 loopback (::ffff:127.0.0.1) must be blocked."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, host="::ffff:127.0.0.1")
+ block.check_host_allowed = AsyncMock( # type: ignore[assignment]
+ side_effect=ValueError(
+ "Access to blocked or private IP address ::ffff:127.0.0.1 "
+ "for hostname ::ffff:127.0.0.1 is not allowed."
+ )
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "Blocked host" in outputs["error"]
+
+ async def test_ipv6_unique_local_rejected(self):
+ """IPv6 unique-local (fd00::) must be blocked like RFC1918."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, host="fd00::1")
+ block.check_host_allowed = AsyncMock( # type: ignore[assignment]
+ side_effect=ValueError(
+ "Access to blocked or private IP address fd00::1 "
+ "for hostname fd00::1 is not allowed."
+ )
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "Blocked host" in outputs["error"]
+
+
+class TestWritableCTEBlocked:
+ """Writable CTEs (WITH ... DELETE/INSERT/UPDATE ... RETURNING) must be
+ blocked even though sqlparse classifies them as SELECT type."""
+
+ @pytest.mark.parametrize(
+ "query,expected_keyword",
+ [
+ (
+ "WITH deleted AS (DELETE FROM users RETURNING *) SELECT * FROM deleted",
+ "DELETE",
+ ),
+ (
+ "WITH ins AS (INSERT INTO t VALUES (1) RETURNING *) SELECT * FROM ins",
+ "INSERT",
+ ),
+ (
+ "WITH upd AS (UPDATE t SET x=1 RETURNING *) SELECT * FROM upd",
+ "UPDATE",
+ ),
+ ],
+ )
+ def test_writable_cte_rejected_in_read_only(
+ self, query: str, expected_keyword: str
+ ):
+ """A CTE containing a data-modifying statement must be caught by
+ the keyword-based defense-in-depth check even if stmt.get_type()
+ returns 'SELECT'."""
+ error, stmt = _validate_single_statement(query)
+ assert error is None
+ assert stmt is not None
+ ro_error = _validate_query_is_read_only(stmt)
+ assert ro_error is not None
+ assert expected_keyword in ro_error
+
+ def test_writable_cte_with_truncate_rejected(self):
+ """TRUNCATE inside a CTE must also be blocked."""
+ query = "WITH t AS (TRUNCATE users RETURNING *) SELECT * FROM t"
+ error, stmt = _validate_single_statement(query)
+ # sqlparse may reject this as invalid or we catch it in read-only check
+ if error is None and stmt is not None:
+ ro_error = _validate_query_is_read_only(stmt)
+ assert ro_error is not None
+
+
+class TestTimeoutEnforcement:
+ """Timeout parameter must be forwarded to execute_query."""
+
+ async def test_timeout_forwarded_to_execute(self):
+ """The timeout value from input must reach execute_query."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, query="SELECT 1", timeout=7)
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ captured_kwargs: dict[str, Any] = {}
+
+ def fake_execute(
+ **kwargs: Any,
+ ) -> tuple[list[dict[str, Any]], list[str], int, bool]:
+ captured_kwargs.update(kwargs)
+ return [{"id": 1}], ["id"], -1, False
+
+ block.execute_query = fake_execute # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ assert captured_kwargs["timeout"] == 7
+
+ async def test_timeout_generates_clean_error(self):
+ """When execute_query raises a timeout OperationalError, the block
+ yields a clean user-facing 'timed out' message with the configured
+ timeout value."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, query="SELECT pg_sleep(9999)", timeout=3)
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ block.execute_query = lambda **_kwargs: (_ for _ in ()).throw( # type: ignore[assignment]
+ OperationalError(
+ "canceling statement due to statement timeout",
+ params=None,
+ orig=Exception("timeout"),
+ )
+ )
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "timed out" in outputs["error"].lower()
+ assert "3s" in outputs["error"]
+
+
+class TestMaxRowsEnforcement:
+ """max_rows parameter must be forwarded and used to truncate results."""
+
+ async def test_max_rows_forwarded_to_execute(self):
+ """The max_rows value from input must reach execute_query."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(creds, query="SELECT 1", max_rows=42)
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ captured_kwargs: dict[str, Any] = {}
+
+ def fake_execute(
+ **kwargs: Any,
+ ) -> tuple[list[dict[str, Any]], list[str], int, bool]:
+ captured_kwargs.update(kwargs)
+ return [{"id": 1}], ["id"], -1, False
+
+ block.execute_query = fake_execute # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ assert captured_kwargs["max_rows"] == 42
+
+ async def test_max_rows_truncates_large_result(self):
+ """When execute_query returns exactly max_rows items, row_count
+ reflects the truncated count."""
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ max_rows = 5
+ input_data = _make_input(
+ creds, query="SELECT * FROM big_table", max_rows=max_rows
+ )
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ # Simulate the database returning exactly max_rows rows (truncated)
+ mock_rows = [{"id": i} for i in range(max_rows)]
+ block.execute_query = lambda **_kwargs: (mock_rows, ["id"], -1, True) # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ assert outputs["row_count"] == max_rows
+ assert len(outputs["results"]) == max_rows
+ assert outputs["truncated"] is True
+
+
+class TestPasswordInErrorMessages:
+ """Connection errors must not leak passwords, even when the password
+ appears in driver-specific formats."""
+
+ def test_password_key_value_scrubbed(self):
+ """password=<value> in error text must be replaced with ***."""
+ conn = "postgresql://user:P@ssw0rd!@host:5432/db"
+ error = "FATAL: password=P@ssw0rd! authentication failed"
+ result = _sanitize_error(error, conn)
+ assert "P@ssw0rd!" not in result
+ assert "password=***" in result
+
+ def test_url_embedded_password_scrubbed(self):
+ """://user:pass@ in error text must be replaced."""
+ conn = "postgresql://admin:[email protected]:5432/db"
+ error = (
+ "could not connect: postgresql://admin:[email protected]:5432/db refused"
+ )
+ result = _sanitize_error(error, conn)
+ assert "hunter2" not in result
+
+ def test_ipv6_address_in_error_scrubbed(self):
+ """Bracketed IPv6 addresses (e.g. [::1]) in error messages must be
+ scrubbed to prevent leaking internal network topology."""
+ conn = "postgresql://user:pass@[::1]:5432/db"
+ error = 'could not connect to server at "[::1]", port 5432'
+ result = _sanitize_error(error, conn, host="::1", port=5432)
+ assert "[::1]" not in result
+ assert "5432" not in result
+
+ def test_ipv6_link_local_in_error_scrubbed(self):
+ """Bracketed IPv6 link-local with zone ID (e.g. [fe80::1%eth0]) must
+ be scrubbed."""
+ conn = "postgresql://user:pass@[fe80::1%25eth0]:5432/db"
+ error = 'connection to "[fe80::1%eth0]" refused'
+ result = _sanitize_error(error, conn, host="fe80::1%eth0")
+ assert "[fe80::1%eth0]" not in result
+
+ def test_multiple_password_formats_scrubbed(self):
+ """Error containing password in multiple formats must be fully scrubbed."""
+ conn = "postgresql://testadmin:[email protected]:5432/testdb"
+ error = (
+ "connection to postgresql://testadmin:[email protected]:5432/testdb failed: "
+ "password=fakepw authentication failed for user 'testadmin'"
+ )
+ result = _sanitize_error(
+ error, conn, host="test.example.invalid", username="testadmin", port=5432
+ )
+ assert "fakepw" not in result
+ assert "testadmin" not in result
+ assert "test.example.invalid" not in result
+
+
+# ---------------------------------------------------------------------------
+# SQL injection within single statements -- BY DESIGN these pass validation.
+#
+# The block uses ``text(query)`` (raw SQL) without parameterization. This is
+# intentional: the block is designed for trusted admin / analytics use where
+# the copilot or autopilot constructs queries against analytics databases.
+# The security boundary is:
+# 1. Single-statement enforcement (prevents multi-query injection)
+# 2. Read-only keyword filtering (prevents data modification in default mode)
+# 3. SSRF host validation (prevents access to internal networks)
+# 4. Database-level read-only session (defense-in-depth)
+#
+# Within those constraints, the raw query is forwarded as-is to the database.
+# These tests document that single-statement injection patterns are NOT blocked
+# at the application layer -- the database's own auth/permissions are the final
+# gate.
+# ---------------------------------------------------------------------------
+
+
+class TestSQLInjectionWithinSingleStatement:
+ """Document that single-statement SQL injection patterns pass validation.
+
+ The block executes raw SQL via ``text(query)`` without parameterization.
+ This is BY DESIGN for trusted admin/analytics use. These tests verify and
+ document that the validation layer does NOT attempt to catch injection
+ within a single SELECT statement -- that responsibility falls to database
+ permissions and the read-only session mode.
+ """
+
+ @pytest.mark.parametrize(
+ "query",
+ [
+ # Classic tautology injection
+ "SELECT * FROM users WHERE id = '1' OR '1'='1'",
+ # UNION-based injection to read other tables
+ "SELECT name FROM users WHERE id = 1 UNION SELECT password FROM credentials",
+ # Boolean-based blind injection
+ "SELECT * FROM users WHERE username = 'admin' AND 1=1",
+ # Comment-based injection (single-line comment)
+ "SELECT * FROM users WHERE username = 'admin' --' AND password = 'x'",
+ # Subquery injection
+ "SELECT * FROM users WHERE id = (SELECT MAX(id) FROM users)",
+ # LIKE wildcard injection
+ "SELECT * FROM users WHERE name LIKE '%'",
+ ],
+ )
+ def test_single_statement_injection_passes_validation(self, query: str):
+ """Single-statement injection patterns pass the single-statement
+ validator because they are syntactically valid single statements.
+ The block relies on database permissions for fine-grained access control."""
+ error, stmt = _validate_single_statement(query)
+ assert error is None, f"Expected query to pass validation: {query}"
+ assert stmt is not None
+
+ @pytest.mark.parametrize(
+ "query",
+ [
+ "SELECT * FROM users WHERE id = '1' OR '1'='1'",
+ "SELECT name FROM users UNION SELECT secret FROM keys",
+ "SELECT * FROM users WHERE username = 'admin' AND 1=1",
+ ],
+ )
+ def test_single_statement_injection_passes_read_only_check(self, query: str):
+ """Single-statement SELECT-based injections also pass the read-only
+ check since they are valid SELECT queries (or UNION of SELECTs).
+ The database's own permission model is the final defense layer."""
+ error, stmt = _validate_single_statement(query)
+ assert error is None
+ assert stmt is not None
+ ro_error = _validate_query_is_read_only(stmt)
+ assert ro_error is None, f"Expected read-only check to pass: {query}"
+
+ def test_injection_with_write_keyword_blocked_in_read_only(self):
+ """Even within a single statement, if an injection smuggles a
+ disallowed keyword (e.g. INSERT via subquery), the read-only
+ keyword check catches it."""
+ # This is a contrived example -- real injection would look different,
+ # but it tests the keyword defense-in-depth layer.
+ query = "SELECT * FROM users WHERE id IN (SELECT id FROM t) UNION SELECT * FROM (DELETE FROM users RETURNING id) AS x"
+ error, stmt = _validate_single_statement(query)
+ # sqlparse may split this or reject it; if it parses as single, the
+ # read-only check must still catch DELETE.
+ if error is None and stmt is not None:
+ ro_error = _validate_query_is_read_only(stmt)
+ assert ro_error is not None
+ assert "DELETE" in ro_error
+
+
+# ---------------------------------------------------------------------------
+# URL.create() special character handling
+#
+# The existing test_special_chars_in_password mocks execute_query, so it
+# never exercises URL.create(). These tests verify that URL.create()
+# correctly handles special characters in credentials without raising
+# exceptions or corrupting the URL.
+# ---------------------------------------------------------------------------
+
+
+class TestURLCreateSpecialCharacters:
+ """Verify URL.create() correctly handles special characters in credentials.
+
+ The block uses ``URL.create()`` (not manual string formatting) to build
+ connection URLs. This avoids URL-encoding issues with special characters
+ in passwords. These tests verify the URL is constructed correctly by
+ inspecting the URL object properties, without needing a real database.
+ """
+
+ @pytest.mark.parametrize(
+ "password",
+ [
+ "p@ss:word/with#special!chars",
+ "has spaces in it",
+ "symbols!@#$%^&*()",
+ "url_tricky://user:pass@host/",
+ "percent%20encoded%3F",
+ "unicode_café_naïve",
+ "backslash\\and\ttab",
+ "empty", # control case
+ ],
+ )
+ def test_url_create_preserves_password(self, password: str):
+ """URL.create() must preserve the exact password without corruption."""
+ from sqlalchemy.engine.url import URL
+
+ url = URL.create(
+ drivername="postgresql",
+ username="testuser",
+ password=password,
+ host="1.2.3.4",
+ port=5432,
+ database="testdb",
+ )
+ # The URL object stores the password without URL-encoding
+ assert url.password == password
+ assert url.username == "testuser"
+ assert url.host == "1.2.3.4"
+ assert url.port == 5432
+ assert url.database == "testdb"
+
+ @pytest.mark.parametrize(
+ "username",
+ [
+ "user:name",
+ "user/slash",
+ "admin#hash",
+ ],
+ )
+ def test_url_create_preserves_username(self, username: str):
+ """URL.create() must preserve special characters in usernames."""
+ from sqlalchemy.engine.url import URL
+
+ url = URL.create(
+ drivername="postgresql",
+ username=username,
+ password="pass",
+ host="1.2.3.4",
+ port=5432,
+ database="testdb",
+ )
+ assert url.username == username
+
+ @pytest.mark.parametrize(
+ "db_type,expected_driver",
+ [
+ (DatabaseType.POSTGRES, "postgresql"),
+ (DatabaseType.MYSQL, "mysql+pymysql"),
+ (DatabaseType.MSSQL, "mssql+pymssql"),
+ ],
+ )
+ def test_url_create_correct_driver_per_db_type(
+ self, db_type: DatabaseType, expected_driver: str
+ ):
+ """URL.create() must use the correct drivername for each database type."""
+ from sqlalchemy.engine.url import URL
+
+ from backend.blocks.sql_query_block import _DATABASE_TYPE_TO_DRIVER
+
+ drivername = _DATABASE_TYPE_TO_DRIVER[db_type]
+ url = URL.create(
+ drivername=drivername,
+ username="user",
+ password="pass",
+ host="1.2.3.4",
+ port=5432,
+ database="testdb",
+ )
+ assert url.drivername == expected_driver
+
+ @pytest.mark.asyncio
+ async def test_special_chars_reach_url_create(self):
+ """End-to-end: credentials with special chars are correctly passed to
+ URL.create() (verified by capturing the connection_url kwarg)."""
+ block = SQLQueryBlock()
+ special_pass = "p@ss:w0rd/#!&=+()"
+ special_user = "admin@corp"
+ creds = _make_credentials(username=special_user, password=special_pass)
+ input_data = _make_input(creds)
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+ captured: dict[str, Any] = {}
+
+ def fake_execute(
+ **kwargs: Any,
+ ) -> tuple[list[dict[str, Any]], list[str], int, bool]:
+ captured.update(kwargs)
+ return [{"id": 1}], ["id"], -1, False
+
+ block.execute_query = fake_execute # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" not in outputs
+ conn_url = captured["connection_url"]
+ # URL.create() produces a URL object, not a string
+ assert hasattr(conn_url, "password"), "connection_url should be a URL object"
+ assert conn_url.password == special_pass
+ assert conn_url.username == special_user
+
+
+# ---------------------------------------------------------------------------
+# Tests for newly-added disallowed keywords (LOAD, REPLACE, MERGE, BULK, EXEC)
+# ---------------------------------------------------------------------------
+
+
+class TestNewDisallowedKeywords:
+ """LOAD, REPLACE, MERGE, BULK, and EXEC must be blocked in read-only mode."""
+
+ @pytest.mark.parametrize(
+ "query,expected_keyword",
+ [
+ # MySQL file exfiltration
+ (
+ "SELECT * FROM (LOAD DATA LOCAL INFILE '/etc/passwd' INTO TABLE t) AS x",
+ "LOAD",
+ ),
+ # MySQL REPLACE (INSERT-or-UPDATE)
+ (
+ "SELECT * FROM (REPLACE INTO t VALUES (1, 'a')) AS x",
+ "REPLACE",
+ ),
+ # ANSI MERGE (UPSERT)
+ (
+ "SELECT * FROM (MERGE INTO t USING s ON t.id = s.id WHEN MATCHED THEN UPDATE SET t.v = s.v) AS x",
+ "MERGE",
+ ),
+ # MSSQL BULK INSERT -- sqlparse may match INSERT before BULK,
+ # but the query is still blocked by the disallowed keyword check.
+ (
+ "SELECT * FROM (BULK INSERT t FROM '/data.csv') AS x",
+ "BULK",
+ ),
+ # MSSQL EXEC stored procedure
+ (
+ "SELECT * FROM (EXEC sp_who2) AS x",
+ "EXEC",
+ ),
+ ],
+ )
+ def test_keyword_blocked_in_subquery_read_only(
+ self, query: str, expected_keyword: str
+ ):
+ """If sqlparse parses the statement as SELECT, the keyword check
+ must still catch the disallowed keyword inside it."""
+ error, stmt = _validate_single_statement(query)
+ if error is None and stmt is not None:
+ ro_error = _validate_query_is_read_only(stmt)
+ assert (
+ ro_error is not None
+ ), f"Expected '{expected_keyword}' to be blocked but query passed: {query}"
+ assert "Disallowed SQL keyword" in ro_error
+
+ @pytest.mark.parametrize(
+ "query",
+ [
+ "LOAD DATA LOCAL INFILE '/etc/passwd' INTO TABLE t",
+ "REPLACE INTO users (id, name) VALUES (1, 'Alice')",
+ "MERGE INTO target USING source ON target.id = source.id "
+ "WHEN MATCHED THEN UPDATE SET target.name = source.name",
+ "BULK INSERT my_table FROM '/tmp/data.csv'",
+ "EXEC sp_who2",
+ ],
+ )
+ def test_standalone_keyword_rejected_as_non_select(self, query: str):
+ """Standalone statements using these keywords are rejected because
+ their statement type is not SELECT."""
+ error, stmt = _validate_single_statement(query)
+ if error is None and stmt is not None:
+ ro_error = _validate_query_is_read_only(stmt)
+ assert ro_error is not None
+
+ def test_bare_keyword_column_names_blocked(self):
+ """Bare column names that match disallowed keywords (load, replace,
+ merge) ARE blocked because sqlparse classifies them as Keyword tokens.
+ Users should quote such column names (e.g. "load") to avoid this."""
+ query = "SELECT load, replace, merge FROM metrics"
+ error, stmt = _validate_single_statement(query)
+ assert error is None
+ assert stmt is not None
+ ro_error = _validate_query_is_read_only(stmt)
+ assert ro_error is not None
+
+ def test_quoted_keyword_column_names_allowed(self):
+ """Double-quoted column names that happen to match disallowed keywords
+ must NOT trigger false positives (sqlparse classifies them as Names)."""
+ query = 'SELECT "load", "replace", "merge" FROM metrics'
+ error, stmt = _validate_single_statement(query)
+ assert error is None
+ assert stmt is not None
+ ro_error = _validate_query_is_read_only(stmt)
+ assert ro_error is None
+
+ def test_load_in_string_literal_allowed(self):
+ """String literal containing 'LOAD' must not be blocked."""
+ query = "SELECT * FROM logs WHERE message = 'LOAD DATA INFILE test'"
+ error, stmt = _validate_single_statement(query)
+ assert error is None
+ assert stmt is not None
+ ro_error = _validate_query_is_read_only(stmt)
+ assert ro_error is None
+
+
+# ---------------------------------------------------------------------------
+# Decimal NaN / Infinity serialization tests
+# ---------------------------------------------------------------------------
+
+
+class TestSerializeDecimalSpecialValues:
+ """Decimal NaN and Infinity must be serialized as strings, not crash."""
+
+ def test_decimal_nan(self):
+ result = _serialize_value(Decimal("NaN"))
+ assert isinstance(result, str)
+ assert "NaN" in result
+
+ def test_decimal_infinity(self):
+ result = _serialize_value(Decimal("Infinity"))
+ assert isinstance(result, str)
+ assert "Infinity" in result
+
+ def test_decimal_negative_infinity(self):
+ result = _serialize_value(Decimal("-Infinity"))
+ assert isinstance(result, str)
+ assert "-Infinity" in result
+
+ def test_decimal_snan(self):
+ result = _serialize_value(Decimal("sNaN"))
+ assert isinstance(result, str)
+
+
+# ---------------------------------------------------------------------------
+# ModuleNotFoundError path test
+# ---------------------------------------------------------------------------
+
+
+class TestModuleNotFoundError:
+ """The block must yield a clean error when a database driver is missing."""
+
+ async def test_missing_driver_yields_clean_error(self):
+ block = SQLQueryBlock()
+ creds = _make_credentials()
+ input_data = _make_input(
+ creds,
+ query="SELECT 1",
+ database_type=DatabaseType.MSSQL,
+ read_only=False,
+ )
+ block.check_host_allowed = AsyncMock(return_value=["1.2.3.4"]) # type: ignore[assignment]
+
+ def raise_module_not_found(**_kwargs: Any) -> None:
+ raise ModuleNotFoundError("No module named 'pymssql'")
+
+ block.execute_query = raise_module_not_found # type: ignore[assignment]
+ outputs = await _collect_outputs(block, input_data, creds)
+ assert "error" in outputs
+ assert "driver not available" in outputs["error"].lower()
+ assert "mssql" in outputs["error"].lower()
+
+
+# ---------------------------------------------------------------------------
+# Integration tests: _execute_query, _configure_session, _run_in_transaction
+# using an in-memory SQLite database.
+#
+# SQLite does not support SET commands, so _configure_session is a no-op for
+# the "sqlite" dialect. These tests validate the execution pipeline itself:
+# transaction management, fetchmany truncation, COMMIT vs ROLLBACK, and the
+# new truncated flag.
+# ---------------------------------------------------------------------------
+
+
+def _extract_sql_texts(conn_mock: MagicMock) -> list[str]:
+ """Extract the raw SQL strings from a mocked connection's execute calls."""
+ return [c[0][0].text for c in conn_mock.execute.call_args_list]
+
+
+class TestConfigureSessionDialects:
+ """Verify _configure_session emits correct SET commands per dialect."""
+
+ def test_postgresql_sets_timeout_and_read_only(self):
+ conn = MagicMock()
+ _configure_session(conn, "postgresql", "30000", read_only=True)
+ sqls = _extract_sql_texts(conn)
+ assert any("statement_timeout" in s and "30000" in s for s in sqls)
+ assert any("default_transaction_read_only" in s for s in sqls)
+
+ def test_postgresql_timeout_only_when_not_read_only(self):
+ conn = MagicMock()
+ _configure_session(conn, "postgresql", "5000", read_only=False)
+ assert conn.execute.call_count == 1
+ sqls = _extract_sql_texts(conn)
+ assert "statement_timeout" in sqls[0]
+
+ def test_mysql_sets_max_execution_time_and_read_only(self):
+ conn = MagicMock()
+ _configure_session(conn, "mysql", "10000", read_only=True)
+ sqls = _extract_sql_texts(conn)
+ assert any("MAX_EXECUTION_TIME" in s and "10000" in s for s in sqls)
+ assert any("READ ONLY" in s for s in sqls)
+
+ def test_mysql_timeout_only_when_not_read_only(self):
+ conn = MagicMock()
+ _configure_session(conn, "mysql", "10000", read_only=False)
+ assert conn.execute.call_count == 1
+ sqls = _extract_sql_texts(conn)
+ assert "MAX_EXECUTION_TIME" in sqls[0]
+
+ def test_mssql_sets_lock_timeout(self):
+ conn = MagicMock()
+ _configure_session(conn, "mssql", "15000", read_only=True)
+ sqls = _extract_sql_texts(conn)
+ assert any("LOCK_TIMEOUT" in s and "15000" in s for s in sqls)
+ assert conn.execute.call_count == 1
+
+ def test_unknown_dialect_is_noop(self):
+ conn = MagicMock()
+ _configure_session(conn, "sqlite", "5000", read_only=True)
+ conn.execute.assert_not_called()
+
+
+class TestRunInTransactionSQLite:
+ """Integration tests for _run_in_transaction using a real SQLite engine."""
+
+ def _make_sqlite_engine(self):
+ return create_engine("sqlite:///:memory:")
+
+ def test_select_returns_rows(self):
+ engine = self._make_sqlite_engine()
+ with engine.connect() as conn:
+ conn = conn.execution_options(isolation_level="AUTOCOMMIT")
+ conn.execute(text("CREATE TABLE t (id INTEGER, name TEXT)"))
+ conn.execute(text("INSERT INTO t VALUES (1, 'Alice')"))
+ conn.execute(text("INSERT INTO t VALUES (2, 'Bob')"))
+ results, columns, affected, truncated = _run_in_transaction(
+ conn,
+ "sqlite",
+ "SELECT * FROM t ORDER BY id",
+ max_rows=100,
+ read_only=True,
+ )
+ engine.dispose()
+ assert columns == ["id", "name"]
+ assert len(results) == 2
+ assert results[0] == {"id": 1, "name": "Alice"}
+ assert results[1] == {"id": 2, "name": "Bob"}
+ assert affected == -1
+ assert truncated is False
+
+ def test_fetchmany_truncation(self):
+ engine = self._make_sqlite_engine()
+ with engine.connect() as conn:
+ conn = conn.execution_options(isolation_level="AUTOCOMMIT")
+ conn.execute(text("CREATE TABLE t (id INTEGER)"))
+ for i in range(10):
+ conn.execute(text(f"INSERT INTO t VALUES ({i})"))
+ results, columns, affected, truncated = _run_in_transaction(
+ conn,
+ "sqlite",
+ "SELECT * FROM t ORDER BY id",
+ max_rows=3,
+ read_only=True,
+ )
+ engine.dispose()
+ assert len(results) == 3
+ assert truncated is True
+ assert results[0]["id"] == 0
+ assert results[2]["id"] == 2
+
+ def test_fetchmany_exact_count_not_truncated(self):
+ """When result count equals max_rows, truncated is True because
+ there *might* be more rows (we cannot know without fetching more)."""
+ engine = self._make_sqlite_engine()
+ with engine.connect() as conn:
+ conn = conn.execution_options(isolation_level="AUTOCOMMIT")
+ conn.execute(text("CREATE TABLE t (id INTEGER)"))
+ for i in range(5):
+ conn.execute(text(f"INSERT INTO t VALUES ({i})"))
+ results, _, _, truncated = _run_in_transaction(
+ conn,
+ "sqlite",
+ "SELECT * FROM t",
+ max_rows=5,
+ read_only=True,
+ )
+ engine.dispose()
+ assert len(results) == 5
+ assert truncated is True
+
+ def test_fewer_rows_than_max_not_truncated(self):
+ engine = self._make_sqlite_engine()
+ with engine.connect() as conn:
+ conn = conn.execution_options(isolation_level="AUTOCOMMIT")
+ conn.execute(text("CREATE TABLE t (id INTEGER)"))
+ conn.execute(text("INSERT INTO t VALUES (1)"))
+ results, _, _, truncated = _run_in_transaction(
+ conn,
+ "sqlite",
+ "SELECT * FROM t",
+ max_rows=100,
+ read_only=True,
+ )
+ engine.dispose()
+ assert len(results) == 1
+ assert truncated is False
+
+ def test_rollback_on_read_only(self):
+ """When read_only=True the transaction is rolled back, so writes are
+ not persisted."""
+ engine = self._make_sqlite_engine()
+ with engine.connect() as conn:
+ conn = conn.execution_options(isolation_level="AUTOCOMMIT")
+ conn.execute(text("CREATE TABLE t (id INTEGER)"))
+ conn.execute(text("INSERT INTO t VALUES (1)"))
+ _run_in_transaction(
+ conn,
+ "sqlite",
+ "INSERT INTO t VALUES (2)",
+ max_rows=100,
+ read_only=True,
+ )
+ # The INSERT should have been rolled back
+ result = conn.execute(text("SELECT COUNT(*) FROM t"))
+ count = result.scalar()
+ engine.dispose()
+ assert count == 1
+
+ def test_commit_on_write_mode(self):
+ """When read_only=False the transaction is committed."""
+ engine = self._make_sqlite_engine()
+ with engine.connect() as conn:
+ conn = conn.execution_options(isolation_level="AUTOCOMMIT")
+ conn.execute(text("CREATE TABLE t (id INTEGER)"))
+ conn.execute(text("INSERT INTO t VALUES (1)"))
+ _run_in_transaction(
+ conn,
+ "sqlite",
+ "INSERT INTO t VALUES (2)",
+ max_rows=100,
+ read_only=False,
+ )
+ result = conn.execute(text("SELECT COUNT(*) FROM t"))
+ count = result.scalar()
+ engine.dispose()
+ assert count == 2
+
+ def test_rollback_on_exception(self):
+ """On query error the transaction is rolled back and the exception
+ re-raised."""
+ engine = self._make_sqlite_engine()
+ with engine.connect() as conn:
+ conn = conn.execution_options(isolation_level="AUTOCOMMIT")
+ conn.execute(text("CREATE TABLE t (id INTEGER)"))
+ with pytest.raises(Exception):
+ _run_in_transaction(
+ conn,
+ "sqlite",
+ "SELECT * FROM nonexistent_table",
+ max_rows=100,
+ read_only=True,
+ )
+ engine.dispose()
+
+ def test_mssql_begin_transaction_syntax(self):
+ """MSSQL dialect uses 'BEGIN TRANSACTION' instead of 'BEGIN'."""
+ conn = MagicMock()
+ result_mock = MagicMock()
+ result_mock.returns_rows = True
+ result_mock.keys.return_value = ["id"]
+ result_mock.fetchmany.return_value = [(1,)]
+ result_mock.rowcount = 1
+ conn.execute.return_value = result_mock
+
+ _run_in_transaction(conn, "mssql", "SELECT 1", max_rows=10, read_only=True)
+
+ sqls = _extract_sql_texts(conn)
+ assert sqls[0] == "BEGIN TRANSACTION"
+
+ def test_non_mssql_begin_syntax(self):
+ """Non-MSSQL dialects use 'BEGIN' (not 'BEGIN TRANSACTION')."""
+ conn = MagicMock()
+ result_mock = MagicMock()
+ result_mock.returns_rows = True
+ result_mock.keys.return_value = ["id"]
+ result_mock.fetchmany.return_value = [(1,)]
+ result_mock.rowcount = 1
+ conn.execute.return_value = result_mock
+
+ _run_in_transaction(conn, "postgresql", "SELECT 1", max_rows=10, read_only=True)
+
+ sqls = _extract_sql_texts(conn)
+ assert sqls[0] == "BEGIN"
+
+
+class TestExecuteQueryIntegration:
+ """Integration tests for _execute_query using mocked engine internals.
+
+ Note: SQLite does not accept ``connect_timeout`` as a connect_arg, so
+ we cannot pass ``sqlite:///:memory:`` directly to ``_execute_query``.
+ Instead we mock ``create_engine`` to return a real SQLite engine while
+ bypassing the connect_args validation.
+ """
+
+ def test_connect_timeout_constant_used(self):
+ """The _CONNECT_TIMEOUT_SECONDS constant must be passed to create_engine."""
+ with patch("backend.blocks.sql_query_helpers.create_engine") as mock_ce:
+ mock_engine = MagicMock()
+ mock_conn = MagicMock()
+ mock_result = MagicMock()
+ mock_result.returns_rows = True
+ mock_result.keys.return_value = ["x"]
+ mock_result.fetchmany.return_value = [(1,)]
+ mock_result.rowcount = 1
+ mock_conn.execute.return_value = mock_result
+ mock_conn.execution_options.return_value = mock_conn
+ mock_engine.connect.return_value.__enter__ = lambda _: mock_conn
+ mock_engine.connect.return_value.__exit__ = lambda *_: None
+ mock_engine.dialect.name = "postgresql"
+ mock_ce.return_value = mock_engine
+
+ _execute_query(
+ "postgresql://u:p@h/d",
+ "SELECT 1",
+ timeout=10,
+ max_rows=100,
+ read_only=True,
+ )
+
+ mock_ce.assert_called_once()
+ _, kwargs = mock_ce.call_args
+ assert kwargs["connect_args"]["connect_timeout"] == _CONNECT_TIMEOUT_SECONDS
diff --git a/autogpt_platform/backend/backend/blocks/sql_query_helpers.py b/autogpt_platform/backend/backend/blocks/sql_query_helpers.py
new file mode 100644
index 0000000000..298628c437
--- /dev/null
+++ b/autogpt_platform/backend/backend/blocks/sql_query_helpers.py
@@ -0,0 +1,430 @@
+import re
+from datetime import date, datetime, time
+from decimal import Decimal
+from enum import Enum
+from typing import Any
+
+import sqlparse
+from sqlalchemy import create_engine, text
+from sqlalchemy.engine.url import URL
+
+
+class DatabaseType(str, Enum):
+ POSTGRES = "postgres"
+ MYSQL = "mysql"
+ MSSQL = "mssql"
+
+
+# Defense-in-depth: reject queries containing data-modifying keywords.
+# These are checked against parsed SQL tokens (not raw text) so column names
+# and string literals do not cause false positives.
+_DISALLOWED_KEYWORDS = {
+ "INSERT",
+ "UPDATE",
+ "DELETE",
+ "DROP",
+ "ALTER",
+ "CREATE",
+ "TRUNCATE",
+ "GRANT",
+ "REVOKE",
+ "COPY",
+ "EXECUTE",
+ "CALL",
+ "SET",
+ "RESET",
+ "DISCARD",
+ "NOTIFY",
+ "DO",
+ # MySQL file exfiltration: LOAD DATA LOCAL INFILE reads server/client files
+ "LOAD",
+ # MySQL REPLACE is INSERT-or-UPDATE; data modification
+ "REPLACE",
+ # ANSI MERGE (UPSERT) modifies data
+ "MERGE",
+ # MSSQL BULK INSERT loads external files into tables
+ "BULK",
+ # MSSQL EXEC / EXEC sp_name runs stored procedures (arbitrary code)
+ "EXEC",
+}
+
+# Map DatabaseType enum values to the expected SQLAlchemy driver prefix.
+_DATABASE_TYPE_TO_DRIVER = {
+ DatabaseType.POSTGRES: "postgresql",
+ DatabaseType.MYSQL: "mysql+pymysql",
+ DatabaseType.MSSQL: "mssql+pymssql",
+}
+
+# Connection timeout in seconds passed to the DBAPI driver (connect_timeout /
+# login_timeout). This bounds how long the driver waits to establish a TCP
+# connection to the database server. It is separate from the per-statement
+# timeout configured via SET commands inside _configure_session().
+_CONNECT_TIMEOUT_SECONDS = 10
+
+# Default ports for each database type.
+_DATABASE_TYPE_DEFAULT_PORT = {
+ DatabaseType.POSTGRES: 5432,
+ DatabaseType.MYSQL: 3306,
+ DatabaseType.MSSQL: 1433,
+}
+
+
+def _sanitize_error(
+ error_msg: str,
+ connection_string: str,
+ *,
+ host: str = "",
+ original_host: str = "",
+ username: str = "",
+ port: int = 0,
+ database: str = "",
+) -> str:
+ """Remove connection string, credentials, and infrastructure details
+ from error messages so they are safe to expose to the LLM.
+
+ Scrubs:
+ - The full connection string
+ - URL-embedded credentials (``://user:pass@``)
+ - ``password=<value>`` key-value pairs
+ - The database hostname / IP used for the connection
+ - The original (pre-resolution) hostname provided by the user
+ - Any IPv4 addresses that appear in the message
+ - Any bracketed IPv6 addresses (e.g. ``[::1]``, ``[fe80::1%eth0]``)
+ - The database username
+ - The database port number
+ - The database name
+ """
+ sanitized = error_msg.replace(connection_string, "<connection_string>")
+ sanitized = re.sub(r"password=[^\s&]+", "password=***", sanitized)
+ sanitized = re.sub(r"://[^@]+@", "://***:***@", sanitized)
+
+ # Replace the known host (may be an IP already) before the generic IP pass.
+ # Also replace the original (pre-DNS-resolution) hostname if it differs.
+ if original_host and original_host != host:
+ sanitized = sanitized.replace(original_host, "<host>")
+ if host:
+ sanitized = sanitized.replace(host, "<host>")
+
+ # Replace any remaining IPv4 addresses (e.g. resolved IPs the driver logs)
+ sanitized = re.sub(r"\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}", "<ip>", sanitized)
+
+ # Replace bracketed IPv6 addresses (e.g. "[::1]", "[fe80::1%eth0]")
+ sanitized = re.sub(r"\[[0-9a-fA-F:]+(?:%[^\]]+)?\]", "<ip>", sanitized)
+
+ # Replace the database username (handles double-quoted, single-quoted,
+ # and unquoted formats across PostgreSQL, MySQL, and MSSQL error messages).
+ if username:
+ sanitized = re.sub(
+ r"""for user ["']?""" + re.escape(username) + r"""["']?""",
+ "for user <user>",
+ sanitized,
+ )
+ # Catch remaining bare occurrences in various quote styles:
+ # - PostgreSQL: "FATAL: role "myuser" does not exist"
+ # - MySQL: "Access denied for user 'myuser'@'host'"
+ # - MSSQL: "Login failed for user 'myuser'"
+ sanitized = sanitized.replace(f'"{username}"', "<user>")
+ sanitized = sanitized.replace(f"'{username}'", "<user>")
+
+ # Replace the port number (handles "port 5432" and ":5432" formats)
+ if port:
+ port_str = re.escape(str(port))
+ sanitized = re.sub(
+ r"(?:port |:)" + port_str + r"(?![0-9])",
+ lambda m: ("port " if m.group().startswith("p") else ":") + "<port>",
+ sanitized,
+ )
+
+ # Replace the database name to avoid leaking internal infrastructure names.
+ # Use word-boundary regex to prevent mangling when the database name is a
+ # common substring (e.g. "test", "data", "on").
+ if database:
+ sanitized = re.sub(r"\b" + re.escape(database) + r"\b", "<database>", sanitized)
+
+ return sanitized
+
+
+def _extract_keyword_tokens(parsed: sqlparse.sql.Statement) -> list[str]:
+ """Extract keyword tokens from a parsed SQL statement.
+
+ Uses sqlparse token type classification to collect Keyword/DML/DDL/DCL
+ tokens. String literals and identifiers have different token types, so
+ they are naturally excluded from the result.
+ """
+ return [
+ token.normalized.upper()
+ for token in parsed.flatten()
+ if token.ttype
+ in (
+ sqlparse.tokens.Keyword,
+ sqlparse.tokens.Keyword.DML,
+ sqlparse.tokens.Keyword.DDL,
+ sqlparse.tokens.Keyword.DCL,
+ )
+ ]
+
+
+def _has_disallowed_into(stmt: sqlparse.sql.Statement) -> bool:
+ """Check if a statement contains a disallowed ``INTO`` clause.
+
+ ``SELECT ... INTO @variable`` is a valid read-only MySQL syntax that stores
+ a query result into a session-scoped user variable. All other forms of
+ ``INTO`` are data-modifying or file-writing and must be blocked:
+
+ * ``SELECT ... INTO new_table`` (PostgreSQL / MSSQL – creates a table)
+ * ``SELECT ... INTO OUTFILE`` (MySQL – writes to the filesystem)
+ * ``SELECT ... INTO DUMPFILE`` (MySQL – writes to the filesystem)
+ * ``INSERT INTO ...`` (already blocked by INSERT being in the
+ disallowed set, but we reject INTO as well for defense-in-depth)
+
+ Returns ``True`` if the statement contains a disallowed ``INTO``.
+ """
+ flat = list(stmt.flatten())
+ for i, token in enumerate(flat):
+ if not (
+ token.ttype in (sqlparse.tokens.Keyword,)
+ and token.normalized.upper() == "INTO"
+ ):
+ continue
+
+ # Look at the first non-whitespace token after INTO.
+ j = i + 1
+ while j < len(flat) and flat[j].ttype is sqlparse.tokens.Text.Whitespace:
+ j += 1
+
+ if j >= len(flat):
+ # INTO at the very end – malformed, block it.
+ return True
+
+ next_token = flat[j]
+ # MySQL user variable: either a single Name starting with "@"
+ # (e.g. ``@total``) or a bare ``@`` Operator token followed by a Name.
+ if next_token.ttype is sqlparse.tokens.Name and next_token.value.startswith(
+ "@"
+ ):
+ continue
+ if next_token.ttype is sqlparse.tokens.Operator and next_token.value == "@":
+ continue
+
+ # Everything else (table name, OUTFILE, DUMPFILE, etc.) is disallowed.
+ return True
+
+ return False
+
+
+def _validate_query_is_read_only(stmt: sqlparse.sql.Statement) -> str | None:
+ """Validate that a parsed SQL statement is read-only (SELECT/WITH only).
+
+ Accepts an already-parsed statement from ``_validate_single_statement``
+ to avoid re-parsing. Checks:
+ 1. Statement type must be SELECT (sqlparse classifies WITH...SELECT as SELECT)
+ 2. No disallowed keywords (INSERT, UPDATE, DELETE, DROP, etc.)
+ 3. No disallowed INTO clauses (allows MySQL ``SELECT ... INTO @variable``)
+
+ Returns an error message if the query is not read-only, None otherwise.
+ """
+ # sqlparse returns 'SELECT' for SELECT and WITH...SELECT queries
+ if stmt.get_type() != "SELECT":
+ return "Only SELECT queries are allowed."
+
+ # Defense-in-depth: check parsed keyword tokens for disallowed keywords
+ for kw in _extract_keyword_tokens(stmt):
+ # Normalize multi-word tokens (e.g. "SET LOCAL" -> "SET")
+ base_kw = kw.split()[0] if " " in kw else kw
+ if base_kw in _DISALLOWED_KEYWORDS:
+ return f"Disallowed SQL keyword: {kw}"
+
+ # Contextual check for INTO: allow MySQL @variable syntax, block everything else
+ if _has_disallowed_into(stmt):
+ return "Disallowed SQL keyword: INTO"
+
+ return None
+
+
+def _validate_single_statement(
+ query: str,
+) -> tuple[str | None, sqlparse.sql.Statement | None]:
+ """Validate that the query contains exactly one non-empty SQL statement.
+
+ Returns (error_message, parsed_statement). If error_message is not None,
+ the query is invalid and parsed_statement will be None.
+ """
+ stripped = query.strip().rstrip(";").strip()
+ if not stripped:
+ return "Query is empty.", None
+
+ # Parse the SQL using sqlparse for proper tokenization
+ statements = sqlparse.parse(stripped)
+
+ # Filter out empty statements and comment-only statements
+ statements = [
+ s
+ for s in statements
+ if s.tokens
+ and str(s).strip()
+ and not all(
+ t.is_whitespace or t.ttype in sqlparse.tokens.Comment for t in s.flatten()
+ )
+ ]
+
+ if not statements:
+ return "Query is empty.", None
+
+ # Reject multiple statements -- prevents injection via semicolons
+ if len(statements) > 1:
+ return "Only single statements are allowed.", None
+
+ return None, statements[0]
+
+
+def _serialize_value(value: Any) -> Any:
+ """Convert database-specific types to JSON-serializable Python types."""
+ if isinstance(value, Decimal):
+ # NaN / Infinity are not valid JSON numbers; serialize as strings.
+ if value.is_nan() or value.is_infinite():
+ return str(value)
+ # Use int for whole numbers; use str for fractional to preserve exact
+ # precision (float would silently round high-precision analytics values).
+ if value == value.to_integral_value():
+ return int(value)
+ return str(value)
+ if isinstance(value, (datetime, date, time)):
+ return value.isoformat()
+ if isinstance(value, memoryview):
+ return bytes(value).hex()
+ if isinstance(value, bytes):
+ return value.hex()
+ return value
+
+
+def _configure_session(
+ conn: Any,
+ dialect_name: str,
+ timeout_ms: str,
+ read_only: bool,
+) -> None:
+ """Set session-level timeout and read-only mode for the given dialect.
+
+ Timeout limitations by database:
+
+ * **PostgreSQL** – ``statement_timeout`` reliably cancels any running
+ statement (SELECT or DML) after the configured duration.
+ * **MySQL** – ``MAX_EXECUTION_TIME`` only applies to **read-only SELECT**
+ statements. DML (INSERT/UPDATE/DELETE) and DDL are *not* bounded by
+ this hint; they rely on the server's ``wait_timeout`` /
+ ``interactive_timeout`` instead. There is no session-level setting in
+ MySQL that reliably cancels long-running writes.
+ * **MSSQL** – ``SET LOCK_TIMEOUT`` only limits how long the server waits
+ to acquire a **lock**. CPU-bound queries (e.g. large scans, hash
+ joins) that do not block on locks will *not* be cancelled. MSSQL has
+ no session-level ``statement_timeout`` equivalent; the closest
+ mechanism is Resource Governor (requires sysadmin configuration) or
+ ``CONTEXT_INFO``-based external monitoring.
+
+ Note: SQLite is not supported by this block. The ``_configure_session``
+ function is a no-op for unrecognised dialect names, so an SQLite engine
+ would skip all SET commands silently. The block's ``DatabaseType`` enum
+ intentionally excludes SQLite.
+ """
+ if dialect_name == "postgresql":
+ conn.execute(text("SET statement_timeout = " + timeout_ms))
+ if read_only:
+ conn.execute(text("SET default_transaction_read_only = ON"))
+ elif dialect_name == "mysql":
+ # NOTE: MAX_EXECUTION_TIME only applies to SELECT statements.
+ # Write queries (INSERT/UPDATE/DELETE) are not bounded by this
+ # setting; they rely on the database's wait_timeout instead.
+ # See docstring above for full limitations.
+ conn.execute(text("SET SESSION MAX_EXECUTION_TIME = " + timeout_ms))
+ if read_only:
+ conn.execute(text("SET SESSION TRANSACTION READ ONLY"))
+ elif dialect_name == "mssql":
+ # MSSQL: SET LOCK_TIMEOUT limits lock-wait time (ms) only.
+ # CPU-bound queries without lock contention are NOT cancelled.
+ # See docstring above for full limitations.
+ conn.execute(text("SET LOCK_TIMEOUT " + timeout_ms))
+ # MSSQL lacks a session-level read-only mode like
+ # PostgreSQL/MySQL. Read-only enforcement is handled by
+ # the SQL validation layer (_validate_query_is_read_only)
+ # and the ROLLBACK in the finally block.
+
+
+def _run_in_transaction(
+ conn: Any,
+ dialect_name: str,
+ query: str,
+ max_rows: int,
+ read_only: bool,
+) -> tuple[list[dict[str, Any]], list[str], int, bool]:
+ """Execute a query inside an explicit transaction, returning results.
+
+ Returns ``(rows, columns, affected_rows, truncated)`` where *truncated*
+ is ``True`` when ``fetchmany`` returned exactly ``max_rows`` rows,
+ indicating that additional rows may exist in the result set.
+ """
+ # MSSQL uses T-SQL "BEGIN TRANSACTION"; others use "BEGIN".
+ begin_stmt = "BEGIN TRANSACTION" if dialect_name == "mssql" else "BEGIN"
+ conn.execute(text(begin_stmt))
+ try:
+ result = conn.execute(text(query))
+ affected = result.rowcount if not result.returns_rows else -1
+ columns = list(result.keys()) if result.returns_rows else []
+ rows = result.fetchmany(max_rows) if result.returns_rows else []
+ truncated = len(rows) == max_rows
+ results = [
+ {col: _serialize_value(val) for col, val in zip(columns, row)}
+ for row in rows
+ ]
+ except Exception:
+ try:
+ conn.execute(text("ROLLBACK"))
+ except Exception:
+ pass
+ raise
+ else:
+ conn.execute(text("ROLLBACK" if read_only else "COMMIT"))
+ return results, columns, affected, truncated
+
+
+def _execute_query(
+ connection_url: URL | str,
+ query: str,
+ timeout: int,
+ max_rows: int,
+ read_only: bool = True,
+ database_type: DatabaseType = DatabaseType.POSTGRES,
+) -> tuple[list[dict[str, Any]], list[str], int, bool]:
+ """Execute a SQL query and return (rows, columns, affected_rows, truncated).
+
+ Uses SQLAlchemy to connect to any supported database.
+ For SELECT queries, rows are limited to ``max_rows`` via DBAPI fetchmany.
+ ``truncated`` is ``True`` when the result set was capped by ``max_rows``.
+ For write queries, affected_rows contains the rowcount from the driver.
+ When ``read_only`` is True, the database session is set to read-only
+ mode and the transaction is always rolled back.
+ """
+ # Determine driver-specific connection timeout argument.
+ # pymssql uses "login_timeout", while PostgreSQL/MySQL use "connect_timeout".
+ timeout_key = (
+ "login_timeout" if database_type == DatabaseType.MSSQL else "connect_timeout"
+ )
+ engine = create_engine(
+ connection_url, connect_args={timeout_key: _CONNECT_TIMEOUT_SECONDS}
+ )
+ try:
+ with engine.connect() as conn:
+ # Use AUTOCOMMIT so SET commands take effect immediately.
+ conn = conn.execution_options(isolation_level="AUTOCOMMIT")
+
+ # Compute timeout in milliseconds. The value is Pydantic-validated
+ # (ge=1, le=120), but we use int() as defense-in-depth.
+ # NOTE: SET commands do not support bind parameters in most
+ # databases, so we use str(int(...)) for safe interpolation.
+ timeout_ms = str(int(timeout * 1000))
+
+ _configure_session(conn, engine.dialect.name, timeout_ms, read_only)
+ return _run_in_transaction(
+ conn, engine.dialect.name, query, max_rows, read_only
+ )
+ finally:
+ engine.dispose()
diff --git a/autogpt_platform/backend/backend/integrations/providers.py b/autogpt_platform/backend/backend/integrations/providers.py
index 377e001cec..1a11ebde3c 100644
--- a/autogpt_platform/backend/backend/integrations/providers.py
+++ b/autogpt_platform/backend/backend/integrations/providers.py
@@ -15,6 +15,7 @@ class ProviderName(str, Enum):
ANTHROPIC = "anthropic"
APOLLO = "apollo"
COMPASS = "compass"
+ DATABASE = "database"
DISCORD = "discord"
D_ID = "d_id"
E2B = "e2b"
diff --git a/autogpt_platform/backend/poetry.lock b/autogpt_platform/backend/poetry.lock
index 1672bebcf9..cb2df32add 100644
--- a/autogpt_platform/backend/poetry.lock
+++ b/autogpt_platform/backend/poetry.lock
@@ -5720,6 +5720,75 @@ dev = ["coverage[toml] (==7.10.7)", "cryptography (>=3.4.0)", "pre-commit", "pyt
docs = ["sphinx", "sphinx-rtd-theme", "zope.interface"]
tests = ["coverage[toml] (==7.10.7)", "pytest (>=8.4.2,<9.0.0)"]
+[[package]]
+name = "pymssql"
+version = "2.3.13"
+description = "DB-API interface to Microsoft SQL Server for Python. (new Cython-based version)"
+optional = false
+python-versions = ">=3.9"
+groups = ["main"]
+files = [
+ {file = "pymssql-2.3.13-cp310-cp310-macosx_14_0_arm64.whl", hash = "sha256:476f6f06b2ae5dfbfa0b169a6ecdd0d9ddfedb07f2d6dc97d2dd630ff2d6789a"},
+ {file = "pymssql-2.3.13-cp310-cp310-macosx_15_0_x86_64.whl", hash = "sha256:17942dc9474693ab2229a8a6013e5b9cb1312a5251207552141bb85fcce8c131"},
+ {file = "pymssql-2.3.13-cp310-cp310-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4d87237500def5f743a52e415cd369d632907212154fcc7b4e13f264b4e30021"},
+ {file = "pymssql-2.3.13-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:612ac062027d2118879f11a5986e9d9d82d07ca3545bb98c93200b68826ea687"},
+ {file = "pymssql-2.3.13-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:f1897c1b767cc143e77d285123ae5fd4fa7379a1bfec5c515d38826caf084eb6"},
+ {file = "pymssql-2.3.13-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:48631c7b9fd14a1bd5675c521b6082590bf700b7961c65638d237817b3fde735"},
+ {file = "pymssql-2.3.13-cp310-cp310-win_amd64.whl", hash = "sha256:79c759db6e991eeae473b000c2e0a7fb8da799b2da469fe5a10d30916315e0b5"},
+ {file = "pymssql-2.3.13-cp311-cp311-macosx_14_0_arm64.whl", hash = "sha256:152be40c0d7f5e4b1323f7728b0a01f3ee0082190cfbadf84b2c2e930d57e00e"},
+ {file = "pymssql-2.3.13-cp311-cp311-macosx_15_0_x86_64.whl", hash = "sha256:d94da3a55545c5b6926cb4d1c6469396f0ae32ad5d6932c513f7a0bf569b4799"},
+ {file = "pymssql-2.3.13-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:51e42c5defc3667f0803c7ade85db0e6f24b9a1c5a18fcdfa2d09c36bff9b065"},
+ {file = "pymssql-2.3.13-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4aa18944a121f996178e26cadc598abdbf73759f03dc3cd74263fdab1b28cd96"},
+ {file = "pymssql-2.3.13-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:910404e0ec85c4cc7c633ec3df9b04a35f23bb74a844dd377a387026ae635e3a"},
+ {file = "pymssql-2.3.13-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:4b834c34e7600369eee7bc877948b53eb0fe6f3689f0888d005ae47dd53c0a66"},
+ {file = "pymssql-2.3.13-cp311-cp311-win_amd64.whl", hash = "sha256:5c2e55b6513f9c5a2f58543233ed40baaa7f91c79e64a5f961ea3fc57a700b80"},
+ {file = "pymssql-2.3.13-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:cf4f32b4a05b66f02cb7d55a0f3bcb0574a6f8cf0bee4bea6f7b104038364733"},
+ {file = "pymssql-2.3.13-cp312-cp312-macosx_15_0_x86_64.whl", hash = "sha256:2b056eb175955f7fb715b60dc1c0c624969f4d24dbdcf804b41ab1e640a2b131"},
+ {file = "pymssql-2.3.13-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:319810b89aa64b99d9c5c01518752c813938df230496fa2c4c6dda0603f04c4c"},
+ {file = "pymssql-2.3.13-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c0ea72641cb0f8bce7ad8565dbdbda4a7437aa58bce045f2a3a788d71af2e4be"},
+ {file = "pymssql-2.3.13-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:1493f63d213607f708a5722aa230776ada726ccdb94097fab090a1717a2534e0"},
+ {file = "pymssql-2.3.13-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:eb3275985c23479e952d6462ae6c8b2b6993ab6b99a92805a9c17942cf3d5b3d"},
+ {file = "pymssql-2.3.13-cp312-cp312-win_amd64.whl", hash = "sha256:a930adda87bdd8351a5637cf73d6491936f34e525a5e513068a6eac742f69cdb"},
+ {file = "pymssql-2.3.13-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:30918bb044242865c01838909777ef5e0f1b9ecd7f5882346aefa57f4414b29c"},
+ {file = "pymssql-2.3.13-cp313-cp313-macosx_15_0_x86_64.whl", hash = "sha256:1c6d0b2d7961f159a07e4f0d8cc81f70ceab83f5e7fd1e832a2d069e1d67ee4e"},
+ {file = "pymssql-2.3.13-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:16c5957a3c9e51a03276bfd76a22431e2bc4c565e2e95f2cbb3559312edda230"},
+ {file = "pymssql-2.3.13-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0fddd24efe9d18bbf174fab7c6745b0927773718387f5517cf8082241f721a68"},
+ {file = "pymssql-2.3.13-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:123c55ee41bc7a82c76db12e2eb189b50d0d7a11222b4f8789206d1cda3b33b9"},
+ {file = "pymssql-2.3.13-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:e053b443e842f9e1698fcb2b23a4bff1ff3d410894d880064e754ad823d541e5"},
+ {file = "pymssql-2.3.13-cp313-cp313-win_amd64.whl", hash = "sha256:5c045c0f1977a679cc30d5acd9da3f8aeb2dc6e744895b26444b4a2f20dad9a0"},
+ {file = "pymssql-2.3.13-cp314-cp314-macosx_14_0_arm64.whl", hash = "sha256:fc5482969c813b0a45ce51c41844ae5bfa8044ad5ef8b4820ef6de7d4545b7f2"},
+ {file = "pymssql-2.3.13-cp314-cp314-macosx_15_0_x86_64.whl", hash = "sha256:ff5be7ab1d643dbce2ee3424d2ef9ae8e4146cf75bd20946bc7a6108e3ad1e47"},
+ {file = "pymssql-2.3.13-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8d66ce0a249d2e3b57369048d71e1f00d08dfb90a758d134da0250ae7bc739c1"},
+ {file = "pymssql-2.3.13-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d663c908414a6a032f04d17628138b1782af916afc0df9fefac4751fa394c3ac"},
+ {file = "pymssql-2.3.13-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:aa5e07eff7e6e8bd4ba22c30e4cb8dd073e138cd272090603609a15cc5dbc75b"},
+ {file = "pymssql-2.3.13-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:db77da1a3fc9b5b5c5400639d79d7658ba7ad620957100c5b025be608b562193"},
+ {file = "pymssql-2.3.13-cp314-cp314-win_amd64.whl", hash = "sha256:7d7037d2b5b907acc7906d0479924db2935a70c720450c41339146a4ada2b93d"},
+ {file = "pymssql-2.3.13-cp39-cp39-macosx_14_0_arm64.whl", hash = "sha256:b0af51904764811da0bfe4b057b1d72dee11a399ce9ed5770875162772740c8a"},
+ {file = "pymssql-2.3.13-cp39-cp39-macosx_15_0_x86_64.whl", hash = "sha256:0a7e6431925572bc75fb47929ae8ca5b0aac26abfe8b98d4c08daf117b5657f1"},
+ {file = "pymssql-2.3.13-cp39-cp39-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7f9b1d5aef2b5f47a7f9d9733caee4d66772681e8f798a0f5e4739a8bdab408c"},
+ {file = "pymssql-2.3.13-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c690f1869dadbf4201b7f51317fceff6e5d8f5175cec6a4a813e06b0dca2d6ed"},
+ {file = "pymssql-2.3.13-cp39-cp39-musllinux_1_2_aarch64.whl", hash = "sha256:e7c31f192da9d30f0e03ad99e548120a8740a675302e2f04fa8c929f7cbee771"},
+ {file = "pymssql-2.3.13-cp39-cp39-musllinux_1_2_x86_64.whl", hash = "sha256:f5d995a80996235ed32102a93067ce6a7143cce3bfd4e5042bf600020fc08456"},
+ {file = "pymssql-2.3.13-cp39-cp39-win_amd64.whl", hash = "sha256:6a6c0783d97f57133573a03aad3017917dbdf7831a65e0d84ccf2a85e183ca66"},
+ {file = "pymssql-2.3.13.tar.gz", hash = "sha256:2137e904b1a65546be4ccb96730a391fcd5a85aab8a0632721feb5d7e39cfbce"},
+]
+
+[[package]]
+name = "pymysql"
+version = "1.1.2"
+description = "Pure Python MySQL Driver"
+optional = false
+python-versions = ">=3.8"
+groups = ["main"]
+files = [
+ {file = "pymysql-1.1.2-py3-none-any.whl", hash = "sha256:e6b1d89711dd51f8f74b1631fe08f039e7d76cf67a42a323d3178f0f25762ed9"},
+ {file = "pymysql-1.1.2.tar.gz", hash = "sha256:4961d3e165614ae65014e361811a724e2044ad3ea3739de9903ae7c21f539f03"},
+]
+
+[package.extras]
+ed25519 = ["PyNaCl (>=1.4.0)"]
+rsa = ["cryptography"]
+
[[package]]
name = "pyparsing"
version = "3.3.2"
@@ -7009,6 +7078,22 @@ postgresql-psycopgbinary = ["psycopg[binary] (>=3.0.7)"]
pymysql = ["pymysql"]
sqlcipher = ["sqlcipher3_binary"]
+[[package]]
+name = "sqlparse"
+version = "0.5.5"
+description = "A non-validating SQL parser."
+optional = false
+python-versions = ">=3.8"
+groups = ["main"]
+files = [
+ {file = "sqlparse-0.5.5-py3-none-any.whl", hash = "sha256:12a08b3bf3eec877c519589833aed092e2444e68240a3577e8e26148acc7b1ba"},
+ {file = "sqlparse-0.5.5.tar.gz", hash = "sha256:e20d4a9b0b8585fdf63b10d30066c7c94c5d7a7ec47c889a2d83a3caa93ff28e"},
+]
+
+[package.extras]
+dev = ["build"]
+doc = ["sphinx"]
+
[[package]]
name = "sse-starlette"
version = "3.2.0"
@@ -8630,4 +8715,4 @@ cffi = ["cffi (>=1.17,<2.0) ; platform_python_implementation != \"PyPy\" and pyt
[metadata]
lock-version = "2.1"
python-versions = ">=3.10,<3.14"
-content-hash = "1dd10577184ebff0d10997f4c6ba49484de79b7fa090946e8e5ce5c5bac3cdeb"
+content-hash = "61f5aa9cea5e0af57979fa72b9884d8e3aa059b93cae4a13c11e7a7f89f66654"
diff --git a/autogpt_platform/backend/pyproject.toml b/autogpt_platform/backend/pyproject.toml
index c9bf080529..2093598a5f 100644
--- a/autogpt_platform/backend/pyproject.toml
+++ b/autogpt_platform/backend/pyproject.toml
@@ -94,7 +94,10 @@ posthog = "^7.6.0"
fpdf2 = "^2.8.6"
langsmith = "^0.7.7"
openpyxl = "^3.1.5"
+pymssql = "^2.3.2"
+pymysql = "^1.1.1"
pyarrow = "^23.0.0"
+sqlparse = "^0.5.5"
[tool.poetry.group.dev.dependencies]
aiohappyeyeballs = "^2.6.1"
diff --git a/autogpt_platform/frontend/src/components/contextual/CredentialsInput/helpers.ts b/autogpt_platform/frontend/src/components/contextual/CredentialsInput/helpers.ts
index d4f23cee39..a6485b0b22 100644
--- a/autogpt_platform/frontend/src/components/contextual/CredentialsInput/helpers.ts
+++ b/autogpt_platform/frontend/src/components/contextual/CredentialsInput/helpers.ts
@@ -18,6 +18,7 @@ export const providerIcons: Partial<
aiml_api: fallbackIcon,
anthropic: fallbackIcon,
apollo: fallbackIcon,
+ database: fallbackIcon,
e2b: fallbackIcon,
github: FaGithub,
google: FaGoogle,
diff --git a/docs/integrations/README.md b/docs/integrations/README.md
index 49b9a86dde..2173e79e33 100644
--- a/docs/integrations/README.md
+++ b/docs/integrations/README.md
@@ -181,6 +181,7 @@ Below is a comprehensive list of all available blocks, categorized by their prim
| [Read Spreadsheet](block-integrations/data.md#read-spreadsheet) | Reads CSV and Excel files and outputs the data as a list of dictionaries and individual rows |
| [Related Keyword Extractor](block-integrations/dataforseo/related_keywords.md#related-keyword-extractor) | Extract individual fields from a RelatedKeyword object |
| [Retrieve Information](block-integrations/data.md#retrieve-information) | Retrieve key-value information for the current user |
+| [SQL Query](block-integrations/data.md#sql-query) | Execute a SQL query |
| [Screenshot Web Page](block-integrations/data.md#screenshot-web-page) | Takes a screenshot of a specified website using ScreenshotOne API |
## Text Processing
diff --git a/docs/integrations/block-integrations/data.md b/docs/integrations/block-integrations/data.md
index 73abef5a6b..4ee99c1340 100644
--- a/docs/integrations/block-integrations/data.md
+++ b/docs/integrations/block-integrations/data.md
@@ -240,6 +240,57 @@ Use within_agent scope for agent-specific data or across_agents for data shared
---
+## SQL Query
+
+### What it is
+Execute a SQL query. Read-only by default for safety -- disable to allow write operations. Supports PostgreSQL, MySQL, and MSSQL via SQLAlchemy.
+
+### How it works
+<!-- MANUAL: how_it_works -->
+This block connects to a database using discrete host, port, and database fields and executes a SQL query via SQLAlchemy. It validates that the query is a single statement (using sqlparse to prevent SQL injection via multi-statement attacks), enforces SSRF protections on the database host, and returns results as a list of row dictionaries.
+
+By default, only SELECT queries are allowed (read-only mode). The database session is set to read-only and the transaction is always rolled back. Disable the `read_only` option to allow write operations (INSERT, UPDATE, DELETE, CREATE, DROP, etc.).
+
+Supported database types: PostgreSQL, MySQL, and MSSQL.
+<!-- END MANUAL -->
+
+### Inputs
+
+| Input | Description | Type | Required |
+|-------|-------------|------|----------|
+| database_type | Database engine | "postgres" \| "mysql" \| "mssql" | No |
+| host | Database hostname or IP address. Treated as a secret to avoid leaking infrastructure details. Private/internal IPs are blocked (SSRF protection). | str (password) | Yes |
+| port | Database port (leave empty for default: PostgreSQL: 5432, MySQL: 3306, MSSQL: 1433) | int | No |
+| database | Name of the database to connect to | str | Yes |
+| query | SQL query to execute | str | Yes |
+| read_only | When enabled (default), only SELECT queries are allowed and the database session is set to read-only mode. Disable to allow write operations (INSERT, UPDATE, DELETE, etc.). | bool | No |
+| timeout | Query timeout in seconds (max 120) | int | No |
+| max_rows | Maximum number of rows to return (max 10000) | int | No |
+
+### Outputs
+
+| Output | Description | Type |
+|--------|-------------|------|
+| error | Error message if the query failed | str |
+| results | Query results as a list of row dictionaries | List[Dict[str, Any]] |
+| columns | Column names from the query result | List[str] |
+| row_count | Number of rows returned | int |
+| truncated | True when the result set was capped by max_rows, indicating additional rows exist in the database | bool |
+| affected_rows | Number of rows affected by a write query (INSERT/UPDATE/DELETE) | int |
+
+### Possible use case
+<!-- MANUAL: use_case -->
+**Analytics Dashboards**: Query your PostgreSQL or MySQL analytics database to pull daily active user counts, revenue metrics, or funnel data directly into your workflow.
+
+**Data Management**: Run INSERT, UPDATE, or DELETE queries to manage data in your databases as part of automated workflows.
+
+**Schema Management**: Create or modify database tables and indexes as part of provisioning or migration workflows.
+
+**Cross-Database Reporting**: Connect to multiple database types (PostgreSQL, MySQL) within a single workflow to aggregate data from different sources.
+<!-- END MANUAL -->
+
+---
+
## Screenshot Web Page
### What it is
diff --git a/docs/integrations/block-integrations/misc.md b/docs/integrations/block-integrations/misc.md
index ad33c02ad3..d43826a959 100644
--- a/docs/integrations/block-integrations/misc.md
+++ b/docs/integrations/block-integrations/misc.md
@@ -58,7 +58,7 @@ Tool and block identifiers provided in `tools` and `blocks` are validated at run
| system_context | Optional additional context prepended to the prompt. Use this to constrain autopilot behavior, provide domain context, or set output format requirements. | str | No |
| session_id | Session ID to continue an existing autopilot conversation. Leave empty to start a new session. Use the session_id output from a previous run to continue. | str | No |
| max_recursion_depth | Maximum nesting depth when the autopilot calls this block recursively (sub-agent pattern). Prevents infinite loops. | int | No |
-| tools | Tool names to filter. Works with tools_exclude to form an allow-list or deny-list. Leave empty to apply no tool filter. | List["add_understanding" \| "ask_question" \| "bash_exec" \| "browser_act" \| "browser_navigate" \| "browser_screenshot" \| "connect_integration" \| "continue_run_block" \| "create_agent" \| "create_feature_request" \| "create_folder" \| "customize_agent" \| "delete_folder" \| "delete_workspace_file" \| "edit_agent" \| "find_agent" \| "find_block" \| "find_library_agent" \| "fix_agent_graph" \| "get_agent_building_guide" \| "get_doc_page" \| "get_mcp_guide" \| "list_folders" \| "list_workspace_files" \| "move_agents_to_folder" \| "move_folder" \| "read_workspace_file" \| "run_agent" \| "run_block" \| "run_mcp_tool" \| "search_docs" \| "search_feature_requests" \| "update_folder" \| "validate_agent_graph" \| "view_agent_output" \| "web_fetch" \| "write_workspace_file" \| "Edit" \| "Glob" \| "Grep" \| "Read" \| "Task" \| "TodoWrite" \| "WebSearch" \| "Write"] | No |
+| tools | Tool names to filter. Works with tools_exclude to form an allow-list or deny-list. Leave empty to apply no tool filter. | List["add_understanding" \| "ask_question" \| "bash_exec" \| "browser_act" \| "browser_navigate" \| "browser_screenshot" \| "connect_integration" \| "continue_run_block" \| "create_agent" \| "create_feature_request" \| "create_folder" \| "customize_agent" \| "delete_folder" \| "delete_workspace_file" \| "edit_agent" \| "find_agent" \| "find_block" \| "find_library_agent" \| "fix_agent_graph" \| "get_agent_building_guide" \| "get_doc_page" \| "get_mcp_guide" \| "list_folders" \| "list_workspace_files" \| "move_agents_to_folder" \| "move_folder" \| "read_workspace_file" \| "run_agent" \| "run_block" \| "run_mcp_tool" \| "search_docs" \| "search_feature_requests" \| "update_folder" \| "validate_agent_graph" \| "view_agent_output" \| "web_fetch" \| "write_workspace_file" \| "Agent" \| "Edit" \| "Glob" \| "Grep" \| "Read" \| "Task" \| "TodoWrite" \| "WebSearch" \| "Write"] | No |
| tools_exclude | Controls how the 'tools' list is interpreted. True (default): 'tools' is a deny-list — listed tools are blocked, all others are allowed. An empty 'tools' list means allow everything. False: 'tools' is an allow-list — only listed tools are permitted. | bool | No |
| blocks | Block identifiers to filter when the copilot uses run_block. Each entry can be: a block name (e.g. 'HTTP Request'), a full block UUID, or the first 8 hex characters of the UUID (e.g. 'c069dc6b'). Works with blocks_exclude. Leave empty to apply no block filter. | List[str] | No |
| blocks_exclude | Controls how the 'blocks' list is interpreted. True (default): 'blocks' is a deny-list — listed blocks are blocked, all others are allowed. An empty 'blocks' list means allow everything. False: 'blocks' is an allow-list — only listed blocks are permitted. | bool | No |