Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

feat: Implementing SQL toolkit (#3567)

Xingyue Huangde6676c4ffc9
diff --git a/camel/toolkits/__init__.py b/camel/toolkits/__init__.py
index 895310919..f2853f7a9 100644
--- a/camel/toolkits/__init__.py
+++ b/camel/toolkits/__init__.py
@@ -72,6 +72,7 @@ from .data_commons_toolkit import DataCommonsToolkit
from .thinking_toolkit import ThinkingToolkit
from .pyautogui_toolkit import PyAutoGUIToolkit
from .searxng_toolkit import SearxNGToolkit
+from .sql_toolkit import SQLToolkit
from .jina_reranker_toolkit import JinaRerankerToolkit
from .pulse_mcp_search_toolkit import PulseMCPSearchToolkit
from .klavis_toolkit import KlavisToolkit
@@ -154,6 +155,7 @@ __all__ = [
'ThinkingToolkit',
'PyAutoGUIToolkit',
'SearxNGToolkit',
+ 'SQLToolkit',
'JinaRerankerToolkit',
'OrigeneToolkit',
'PulseMCPSearchToolkit',
diff --git a/camel/toolkits/sql_toolkit.py b/camel/toolkits/sql_toolkit.py
new file mode 100644
index 000000000..97f169c21
--- /dev/null
+++ b/camel/toolkits/sql_toolkit.py
@@ -0,0 +1,712 @@
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import re
+from typing import (
+ TYPE_CHECKING,
+ Any,
+ ClassVar,
+ Dict,
+ List,
+ Literal,
+ Optional,
+ Union,
+)
+
+from camel.logger import get_logger
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.function_tool import FunctionTool
+from camel.utils import MCPServer
+
+if TYPE_CHECKING:
+ import sqlite3
+
+ import duckdb
+
+logger = get_logger(__name__)
+
+
+@MCPServer()
+class SQLToolkit(BaseToolkit):
+ r"""A toolkit for executing SQL queries against various SQL databases.
+
+ This toolkit provides functionality to execute SQL queries with support
+ for read-only and read-write modes. It currently supports DuckDB and
+ SQLite, with extensibility for MySQL and other SQL databases.
+
+ Args:
+ database_path (Optional[str]): Path to the database file. If None,
+ uses an in-memory database. For DuckDB and SQLite, use ":memory:"
+ for in-memory or a file path for persistent storage.
+ (default: :obj:`None`)
+ database_type (Literal["duckdb", "sqlite"]): Type of database to use.
+ Currently supports "duckdb" and "sqlite".
+ (default: :obj:`"duckdb"`)
+ read_only (bool, optional): If True, only SELECT queries are allowed.
+ Write operations (INSERT, UPDATE, DELETE, etc.) will be rejected.
+ (default: :obj:`False`)
+ timeout (Optional[float], optional): The timeout for database
+ operations in seconds. Defaults to 180 seconds if not specified.
+ (default: :obj:`180.0`)
+
+ Raises:
+ ValueError: If database_type is not supported.
+ ImportError: If required database driver is not installed.
+ """
+
+ # SQL keywords that indicate write operations
+ _WRITE_KEYWORDS: ClassVar[List[str]] = [
+ "INSERT",
+ "UPDATE",
+ "DELETE",
+ "DROP",
+ "CREATE",
+ "ALTER",
+ "TRUNCATE",
+ "REPLACE",
+ "MERGE",
+ "GRANT",
+ "REVOKE",
+ "COPY",
+ "ATTACH",
+ "DETACH",
+ "LOAD",
+ "IMPORT",
+ "EXPORT",
+ ]
+
+ # Supported database types
+ _SUPPORTED_DATABASES: ClassVar[List[str]] = ["duckdb", "sqlite"]
+
+ def __init__(
+ self,
+ database_path: Optional[str] = None,
+ database_type: Literal["duckdb", "sqlite"] = "duckdb",
+ read_only: bool = False,
+ timeout: Optional[float] = 180.0,
+ ) -> None:
+ super().__init__(timeout=timeout)
+ self._validate_database_type(database_type)
+
+ self.database_path = database_path
+ self.database_type = database_type.lower()
+ self.read_only = read_only
+
+ # Initialize database connection
+ self._connection = self._create_connection()
+
+ logger.info(
+ f"Initialized SQL toolkit with database_type: {database_type}, "
+ f"database_path: {database_path or ':memory:'}, "
+ f"read_only: {read_only}, timeout: {self.timeout}s"
+ )
+
+ def _validate_database_type(self, database_type: str) -> None:
+ r"""Validate if the database type is supported.
+
+ Args:
+ database_type (str): The database type to validate.
+
+ Raises:
+ ValueError: If the database type is not supported.
+ """
+ if database_type.lower() not in self._SUPPORTED_DATABASES:
+ raise ValueError(
+ f"Unsupported database_type: {database_type}. "
+ f"Supported types: {self._SUPPORTED_DATABASES}"
+ )
+
+ def _create_connection(
+ self,
+ ) -> "Union[duckdb.DuckDBPyConnection, sqlite3.Connection]":
+ r"""Create a database connection based on the database type.
+
+ Returns:
+ Union[duckdb.DuckDBPyConnection, sqlite3.Connection]: A database
+ connection object.
+
+ Raises:
+ ImportError: If the required database driver is not installed.
+ """
+ if self.database_type == "duckdb":
+ try:
+ import duckdb
+ except ImportError:
+ raise ImportError(
+ "duckdb package is required for DuckDB support. "
+ "Install it with: pip install duckdb"
+ )
+
+ if self.database_path is None or self.database_path == ":memory:":
+ return duckdb.connect(":memory:")
+ else:
+ # Pass read_only parameter for file-based connections
+ # This provides database-level protection in addition to
+ # application-level checks
+ return duckdb.connect(
+ self.database_path, read_only=self.read_only
+ )
+ elif self.database_type == "sqlite":
+ try:
+ import sqlite3
+ except ImportError:
+ raise ImportError(
+ "sqlite3 module is required for SQLite support. "
+ "It should be included with Python, but if missing, "
+ "ensure you're using a standard Python installation."
+ )
+
+ if self.database_path is None or self.database_path == ":memory:":
+ conn = sqlite3.connect(":memory:", check_same_thread=False)
+ else:
+ # SQLite read-only mode using URI
+ if self.read_only:
+ uri = f"file:{self.database_path}?mode=ro"
+ conn = sqlite3.connect(
+ uri, uri=True, check_same_thread=False
+ )
+ else:
+ conn = sqlite3.connect(
+ self.database_path, check_same_thread=False
+ )
+
+ # Enable row factory to return dict-like rows
+ conn.row_factory = sqlite3.Row
+ return conn
+ else:
+ raise ValueError(
+ f"Unsupported database type: {self.database_type}"
+ )
+
+ def _is_write_query(self, query: str) -> bool:
+ r"""Check if a SQL query is a write operation.
+
+ This method analyzes the query string to determine if it contains
+ any write operations. It handles comments and case-insensitive
+ matching.
+
+ Args:
+ query (str): The SQL query to check.
+
+ Returns:
+ bool: True if the query is a write operation, False otherwise.
+ """
+ # Remove SQL comments (-- and /* */ style)
+ # Remove single-line comments
+ query_no_comments = re.sub(r"--.*$", "", query, flags=re.MULTILINE)
+ # Remove multi-line comments
+ query_no_comments = re.sub(
+ r"/\*.*?\*/", "", query_no_comments, flags=re.DOTALL
+ )
+
+ # Normalize whitespace and convert to uppercase for keyword matching
+ query_normalized = " ".join(query_no_comments.split()).upper()
+
+ # Check for write keywords at the start of the query (after whitespace)
+ for keyword in self._WRITE_KEYWORDS:
+ # Match keyword at start of query or after whitespace/semicolon
+ pattern = r"(^|\s|;)" + re.escape(keyword) + r"(\s|$)"
+ if re.search(pattern, query_normalized):
+ return True
+
+ return False
+
+ def _quote_identifier(self, identifier: str) -> str:
+ r"""Safely quote a SQL identifier (table name, column name, etc.).
+
+ This method validates and quotes SQL identifiers to prevent SQL
+ injection. For DuckDB, identifiers are quoted with double quotes. Any
+ double quotes within the identifier are escaped by doubling them.
+
+ Args:
+ identifier (str): The identifier to quote (e.g., table name,
+ column name).
+
+ Returns:
+ str: The safely quoted identifier.
+
+ Raises:
+ ValueError: If the identifier is empty or contains invalid
+ characters.
+ """
+ if not identifier or not identifier.strip():
+ raise ValueError("Identifier cannot be empty")
+
+ identifier = identifier.strip()
+
+ # Validate identifier doesn't contain null bytes or other
+ # dangerous characters
+ if "\x00" in identifier:
+ raise ValueError("Identifier cannot contain null bytes")
+
+ # Escape double quotes by doubling them, then wrap in double quotes
+ escaped = identifier.replace('"', '""')
+ return f'"{escaped}"'
+
+ def execute_query(
+ self,
+ query: str,
+ params: Optional[
+ Union[
+ List[Union[str, int, float, bool, None]],
+ Dict[str, Union[str, int, float, bool, None]],
+ ]
+ ] = None,
+ ) -> Union[List[Dict[str, Any]], Dict[str, Any], str]:
+ r"""Execute a SQL query and return results.
+
+ This method executes a SQL query against the configured database and
+ returns the results. For SELECT queries, returns a list of dictionaries
+ where each dictionary represents a row. For write operations (INSERT,
+ UPDATE, DELETE, etc.), returns a status dictionary with execution info.
+
+ Args:
+ query (str): The SQL query to execute.
+ params (Optional[Union[List[Union[str, int, float, bool, None]],
+ Dict[str, Union[str, int, float, bool, None]]]], optional):
+ Parameters for parameterized queries. Can be a list for
+ positional parameters (with ? placeholders) or a dict for
+ named parameters. Values can be strings, numbers, booleans,
+ or None. Note: tuples are also accepted at runtime but should
+ be passed as lists for type compatibility.
+ (default: :obj:`None`)
+
+ Returns:
+ Union[List[Dict[str, Any]], Dict[str, Any], str]:
+ - For SELECT queries: List of dictionaries with column names as
+ keys and row values as values.
+ - For write operations (INSERT, UPDATE, DELETE, CREATE, etc.):
+ A dictionary with 'status', 'message', and optionally
+ 'rows_affected' keys.
+ - For errors: An error message string starting with "Error:".
+ """
+ if not query or not query.strip():
+ return "Error: Query cannot be empty"
+
+ # Validate query mode (check for write operations in read-only mode)
+ if self.read_only and self._is_write_query(query):
+ return (
+ "Error: Write operations are not allowed in read-only mode. "
+ "The query contains write operations (INSERT, UPDATE, DELETE, "
+ "DROP, CREATE, ALTER, TRUNCATE, etc.). Only SELECT queries "
+ "are permitted."
+ )
+
+ try:
+ logger.debug(f"Executing query: {query}...")
+
+ cursor = self._connection.cursor()
+
+ # Execute query with or without parameters
+ if params is not None:
+ cursor.execute(query, params)
+ else:
+ cursor.execute(query)
+
+ # Check if this is a write operation first
+ # DuckDB returns results for INSERT/UPDATE/DELETE (with count),
+ # but we want to return empty list for write operations
+ is_write = self._is_write_query(query)
+
+ # Check if the query returned results by checking cursor.
+ # description
+ # This handles SELECT queries, CTEs (WITH ... SELECT ...),
+ # EXPLAIN queries, SHOW queries, etc.
+ if cursor.description is not None and not is_write:
+ # Query returned results and it's not a write operation,
+ # fetch them
+ rows = cursor.fetchall()
+
+ # Convert rows to dictionaries
+ # SQLite with row_factory returns Row objects that can be
+ # converted to dict
+ # DuckDB returns tuples that need column names
+ if (
+ self.database_type == "sqlite"
+ and rows
+ and hasattr(rows[0], "keys")
+ ):
+ # SQLite Row objects can be converted directly to dict
+ results = [dict(row) for row in rows]
+ else:
+ # DuckDB or other databases: use column names from
+ # description
+ columns = [desc[0] for desc in cursor.description]
+ results = [dict(zip(columns, row)) for row in rows]
+
+ logger.debug(f"Query returned {len(results)} rows")
+ return results
+ else:
+ # Query did not return results or is a write operation
+ # (INSERT, UPDATE, DELETE, etc.)
+ # Commit the transaction
+ self._connection.commit()
+
+ # Get affected rows count if available
+ # Note: DuckDB doesn't support rowcount, SQLite does for DML
+ rows_affected = getattr(cursor, "rowcount", -1)
+ result_dict: Dict[str, Any] = {
+ "status": "success",
+ }
+ if rows_affected >= 0:
+ result_dict["rows_affected"] = rows_affected
+ result_dict["message"] = (
+ f"Query executed successfully. "
+ f"{rows_affected} row(s) affected."
+ )
+ logger.debug(
+ f"Write query executed successfully, "
+ f"{rows_affected} rows affected"
+ )
+ else:
+ result_dict["message"] = "Query executed successfully."
+ logger.debug("Query executed successfully")
+ return result_dict
+
+ except Exception as e:
+ error_msg = str(e)
+ logger.error(f"Query execution failed: {error_msg}")
+ # Rollback on error
+ try:
+ self._connection.rollback()
+ except Exception as rollback_error:
+ logger.debug(f"Rollback failed: {rollback_error!s}")
+ return f"Error: Query execution failed: {error_msg}"
+
+ def list_tables(self) -> Union[List[str], str]:
+ r"""List all tables in the database.
+
+ This method queries the database to discover all available tables.
+ It uses database-specific queries to retrieve table names.
+
+ Returns:
+ Union[List[str], str]: A list of table names in the database,
+ or an error message string if the operation fails.
+ """
+ try:
+ if self.database_type == "duckdb":
+ # DuckDB uses SHOW TABLES
+ result = self.execute_query("SHOW TABLES")
+ # Check if result is an error message or unexpected dict
+ if isinstance(result, str):
+ return result
+ if isinstance(result, dict):
+ return (
+ f"Error: Unexpected result from SHOW TABLES: {result}"
+ )
+ # Result format: [{'name': 'table1'}, {'name': 'table2'}]
+ return [row["name"] for row in result]
+ elif self.database_type == "sqlite":
+ # SQLite uses sqlite_master system table
+ result = self.execute_query(
+ "SELECT name FROM sqlite_master "
+ "WHERE type='table' AND name NOT LIKE 'sqlite_%'"
+ )
+ # Check if result is an error message or unexpected dict
+ if isinstance(result, str):
+ return result
+ if isinstance(result, dict):
+ return f"Error: Unexpected result from query: {result}"
+ # Result format: [{'name': 'table1'}, {'name': 'table2'}]
+ return [row["name"] for row in result]
+ else:
+ # For other databases, could use information_schema or similar
+ return (
+ f"Error: list_tables not yet implemented for "
+ f"{self.database_type}"
+ )
+ except Exception as e:
+ logger.error(f"Failed to list tables: {e!s}")
+ return f"Error: Failed to list tables: {e!s}"
+
+ def _get_table_schema(self, table_name: str) -> Union[Dict[str, Any], str]:
+ r"""Internal helper method to get table schema information.
+
+ Args:
+ table_name (str): The name of the table to describe.
+
+ Returns:
+ Union[Dict[str, Any], str]: A dictionary containing 'columns',
+ 'primary_keys', and 'foreign_keys', or an error message string
+ if the operation fails.
+ """
+ if not table_name or not table_name.strip():
+ return "Error: Table name cannot be empty"
+
+ try:
+ if self.database_type == "duckdb":
+ # Get column information using DESCRIBE
+ # Safely quote the table name to prevent SQL injection
+ quoted_table_name = self._quote_identifier(table_name)
+ columns = self.execute_query(f"DESCRIBE {quoted_table_name}")
+
+ # Check if result is an error message
+ if isinstance(columns, str):
+ return columns
+ # Also check if result is a status dict (not a list of columns)
+ if isinstance(columns, dict):
+ return f"Error: Unexpected result from DESCRIBE: {columns}"
+
+ # Extract primary keys
+ primary_keys = [
+ col["column_name"]
+ for col in columns
+ if col.get("key") == "PRI"
+ ]
+
+ # Get foreign keys from information_schema
+ # This query retrieves FK relationships by joining system
+ # tables:
+ # - table_constraints: finds FOREIGN KEY constraints
+ # - referential_constraints: links FK to referenced constraint
+ # - key_column_usage: gets column names (used twice for source/
+ # target)
+ foreign_keys = []
+ try:
+ fk_query = """
+ SELECT
+ kcu.column_name,
+ kcu2.table_name AS references_table,
+ kcu2.column_name AS references_column
+ FROM information_schema.table_constraints AS tc
+ JOIN information_schema.referential_constraints AS rc
+ ON tc.constraint_name = rc.constraint_name
+ JOIN information_schema.key_column_usage AS kcu
+ ON tc.constraint_name = kcu.constraint_name
+ JOIN information_schema.table_constraints AS tc2
+ ON rc.unique_constraint_name = tc2.constraint_name
+ JOIN information_schema.key_column_usage AS kcu2
+ ON tc2.constraint_name = kcu2.constraint_name
+ WHERE tc.constraint_type = 'FOREIGN KEY'
+ AND tc.table_name = ?
+ """
+ fk_results = self.execute_query(
+ fk_query, params=[table_name]
+ )
+ # Only process if result is a list of rows
+ if isinstance(fk_results, list):
+ foreign_keys = [
+ {
+ "column": fk["column_name"],
+ "references_table": fk["references_table"],
+ "references_column": fk["references_column"],
+ }
+ for fk in fk_results
+ ]
+ except Exception as e:
+ # If foreign key query fails, log but don't fail
+ logger.debug(
+ f"Could not retrieve foreign keys "
+ f"for {table_name}: {e!s}"
+ )
+
+ return {
+ "columns": columns,
+ "primary_keys": primary_keys,
+ "foreign_keys": foreign_keys,
+ }
+ elif self.database_type == "sqlite":
+ # SQLite uses PRAGMA table_info for column information
+ quoted_table_name = self._quote_identifier(table_name)
+ pragma_result = self.execute_query(
+ f"PRAGMA table_info({quoted_table_name})"
+ )
+
+ # Check if result is an error message
+ if isinstance(pragma_result, str):
+ return pragma_result
+ # Also check if result is a status dict (not a list of rows)
+ if isinstance(pragma_result, dict):
+ return (
+ f"Error: Unexpected result from "
+ f"PRAGMA: {pragma_result}"
+ )
+
+ # Convert PRAGMA format to match DuckDB format
+ sqlite_columns: List[Dict[str, Any]] = []
+ sqlite_pks: List[str] = []
+ for row in pragma_result:
+ is_primary_key = row["pk"] > 0
+ col_info: Dict[str, Any] = {
+ "column_name": row["name"],
+ "column_type": row["type"],
+ "null": "YES" if row["notnull"] == 0 else "NO",
+ "key": "PRI" if is_primary_key else None,
+ "default": row["dflt_value"],
+ "extra": None,
+ }
+ sqlite_columns.append(col_info)
+ if is_primary_key:
+ sqlite_pks.append(row["name"])
+
+ # Get foreign keys using PRAGMA foreign_key_list (much
+ # simpler!)
+ sqlite_fks: List[Dict[str, Any]] = []
+ try:
+ fk_result = self.execute_query(
+ f"PRAGMA foreign_key_list({quoted_table_name})"
+ )
+ # Only process if result is a list of rows
+ if isinstance(fk_result, list):
+ sqlite_fks = [
+ {
+ "column": fk["from"],
+ "references_table": fk["table"],
+ "references_column": fk["to"],
+ }
+ for fk in fk_result
+ ]
+ except Exception as e:
+ # If foreign key query fails, log but don't fail
+ logger.debug(
+ f"Could not retrieve foreign keys for "
+ f"{table_name}: {e!s}"
+ )
+
+ return {
+ "columns": sqlite_columns,
+ "primary_keys": sqlite_pks,
+ "foreign_keys": sqlite_fks,
+ }
+ else:
+ # For other databases, could use information_schema or similar
+ return (
+ f"Error: get_table_info not yet implemented for "
+ f"{self.database_type}"
+ )
+ except Exception as e:
+ logger.error(f"Failed to get table schema for {table_name}: {e!s}")
+ return f"Error: Failed to get table schema for {table_name}: {e!s}"
+
+ def get_table_info(
+ self, table_name: Optional[str] = None
+ ) -> Union[Dict[str, Any], str]:
+ r"""Get comprehensive information about table(s) in the database.
+
+ This method provides a summary of table information including schema,
+ primary keys, foreign keys, and row counts. If table_name is provided,
+ returns info for that specific table. Otherwise, returns info for all
+ tables.
+
+ Args:
+ table_name (Optional[str], optional): Name of a specific table to
+ get info for. If None, returns info for all tables.
+ (default: :obj:`None`)
+
+ Returns:
+ Union[Dict[str, Any], str]: A dictionary containing table
+ information, or an error message string if the operation fails.
+ If table_name is provided, returns info for that table with
+ keys: 'table_name', 'columns', 'primary_keys', 'foreign_keys',
+ 'row_count'. Otherwise, returns a dictionary mapping table
+ names to their info dictionaries.
+ """
+ # Validate table_name if provided
+ if table_name is not None and (
+ not table_name or not table_name.strip()
+ ):
+ return "Error: Table name cannot be empty"
+
+ try:
+ if table_name:
+ # Get info for specific table
+ schema_info = self._get_table_schema(table_name)
+ # Check if result is an error message
+ if isinstance(schema_info, str):
+ return schema_info
+
+ # Get row count - safely quote table name to prevent SQL
+ # injection
+ quoted_table_name = self._quote_identifier(table_name)
+ count_result = self.execute_query(
+ f"SELECT COUNT(*) as row_count FROM {quoted_table_name}"
+ )
+ # Check if result is an error message or not a list
+ if isinstance(count_result, str):
+ return count_result
+ if not isinstance(count_result, list):
+ return (
+ f"Error: Unexpected result from COUNT: {count_result}"
+ )
+ row_count = count_result[0]["row_count"] if count_result else 0
+
+ return {
+ "table_name": table_name,
+ "columns": schema_info["columns"],
+ "primary_keys": schema_info["primary_keys"],
+ "foreign_keys": schema_info["foreign_keys"],
+ "row_count": row_count,
+ }
+ else:
+ # Get info for all tables
+ tables = self.list_tables()
+ # Check if result is an error message
+ if isinstance(tables, str):
+ return tables
+
+ result = {}
+ for table in tables:
+ schema_info = self._get_table_schema(table)
+ # Check if result is an error message
+ if isinstance(schema_info, str):
+ return schema_info
+
+ # Safely quote table name to prevent SQL injection
+ quoted_table = self._quote_identifier(table)
+ count_result = self.execute_query(
+ f"SELECT COUNT(*) as row_count FROM {quoted_table}"
+ )
+ # Check if result is an error message or not a list
+ if isinstance(count_result, str):
+ return count_result
+ if not isinstance(count_result, list):
+ return (
+ f"Error: Unexpected result from COUNT: "
+ f"{count_result}"
+ )
+ row_count = (
+ count_result[0]["row_count"] if count_result else 0
+ )
+ result[table] = {
+ "table_name": table,
+ "columns": schema_info["columns"],
+ "primary_keys": schema_info["primary_keys"],
+ "foreign_keys": schema_info["foreign_keys"],
+ "row_count": row_count,
+ }
+ return result
+ except Exception as e:
+ logger.error(f"Failed to get table info: {e!s}")
+ return f"Error: Failed to get table info: {e!s}"
+
+ def get_tools(self) -> List[FunctionTool]:
+ r"""Get the list of available tools in the toolkit.
+
+ Returns:
+ List[FunctionTool]: A list of FunctionTool objects representing the
+ available functions in the toolkit.
+ """
+ return [
+ FunctionTool(self.execute_query),
+ FunctionTool(self.list_tables),
+ FunctionTool(self.get_table_info),
+ ]
+
+ def __del__(self) -> None:
+ r"""Clean up database connection on deletion."""
+ if hasattr(self, "_connection") and self._connection:
+ try:
+ self._connection.close()
+ except Exception as e:
+ logger.debug(f"Error closing connection in __del__: {e}")
diff --git a/examples/toolkits/sql_toolkit.py b/examples/toolkits/sql_toolkit.py
new file mode 100644
index 000000000..095f49a6b
--- /dev/null
+++ b/examples/toolkits/sql_toolkit.py
@@ -0,0 +1,674 @@
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
+import os
+import tempfile
+
+from camel.agents import ChatAgent
+from camel.configs import ChatGPTConfig
+from camel.models import ModelFactory
+from camel.toolkits.sql_toolkit import SQLToolkit
+from camel.types import ModelPlatformType, ModelType
+
+# Example 1: Initialize SQL Toolkit with in-memory database
+sql_toolkit = SQLToolkit(database_path=":memory:", read_only=False)
+
+# Create a table
+sql_toolkit.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT, age INTEGER, email TEXT)"
+)
+
+# Insert data
+sql_toolkit.execute_query(
+ "INSERT INTO users VALUES (1, 'Alice', 25, '[email protected]')"
+)
+sql_toolkit.execute_query(
+ "INSERT INTO users VALUES (2, 'Bob', 30, '[email protected]')"
+)
+sql_toolkit.execute_query(
+ "INSERT INTO users VALUES (3, 'Charlie', 28, '[email protected]')"
+)
+
+# Query data
+result = sql_toolkit.execute_query("SELECT * FROM users")
+print("All users:")
+print(result)
+
+'''
+===============================================================================
+All users:
+[{'id': 1, 'name': 'Alice', 'age': 25, 'email': '[email protected]'},
+ {'id': 2, 'name': 'Bob', 'age': 30, 'email': '[email protected]'},
+ {'id': 3, 'name': 'Charlie', 'age': 28, 'email': '[email protected]'}]
+===============================================================================
+'''
+
+# Example 2: SELECT with WHERE clause
+result = sql_toolkit.execute_query(
+ "SELECT name, age FROM users WHERE age > 26"
+)
+print("\nUsers older than 26:")
+print(result)
+
+'''
+===============================================================================
+Users older than 26:
+[{'name': 'Bob', 'age': 30}, {'name': 'Charlie', 'age': 28}]
+===============================================================================
+'''
+
+# Example 3: JOIN query
+# Create orders table
+sql_toolkit.execute_query(
+ "CREATE TABLE orders "
+ "(id INTEGER, user_id INTEGER, product TEXT, amount REAL)"
+)
+sql_toolkit.execute_query("INSERT INTO orders VALUES (1, 1, 'Laptop', 999.99)")
+sql_toolkit.execute_query("INSERT INTO orders VALUES (2, 1, 'Mouse', 29.99)")
+sql_toolkit.execute_query(
+ "INSERT INTO orders VALUES (3, 2, 'Keyboard', 79.99)"
+)
+
+# JOIN query
+result = sql_toolkit.execute_query(
+ """
+ SELECT u.name, o.product, o.amount
+ FROM users u
+ JOIN orders o ON u.id = o.user_id
+ ORDER BY o.amount DESC
+ """
+)
+print("\nUser orders:")
+print(result)
+
+'''
+===============================================================================
+User orders:
+[{'name': 'Alice', 'product': 'Laptop', 'amount': 999.99},
+ {'name': 'Bob', 'product': 'Keyboard', 'amount': 79.99},
+ {'name': 'Alice', 'product': 'Mouse', 'amount': 29.99}]
+===============================================================================
+'''
+
+# Example 4: Common Table Expression (CTE)
+result = sql_toolkit.execute_query(
+ """
+ WITH user_totals AS (
+ SELECT u.name, SUM(o.amount) as total_spent
+ FROM users u
+ JOIN orders o ON u.id = o.user_id
+ GROUP BY u.name
+ )
+ SELECT * FROM user_totals
+ ORDER BY total_spent DESC
+ """
+)
+print("\nTotal spending per user:")
+print(result)
+
+'''
+===============================================================================
+Total spending per user:
+[{'name': 'Alice', 'total_spent': 1029.98},
+ {'name': 'Bob', 'total_spent': 79.99}]
+===============================================================================
+'''
+
+# Example 5: UPDATE and DELETE operations
+sql_toolkit.execute_query("UPDATE users SET age = 26 WHERE name = 'Alice'")
+result = sql_toolkit.execute_query(
+ "SELECT name, age FROM users WHERE name = 'Alice'"
+)
+print("\nUpdated Alice's age:")
+print(result)
+
+sql_toolkit.execute_query("DELETE FROM users WHERE age < 27")
+result = sql_toolkit.execute_query("SELECT * FROM users")
+print("\nUsers after deletion:")
+print(result)
+
+'''
+===============================================================================
+Updated Alice's age:
+[{'name': 'Alice', 'age': 26}]
+
+Users after deletion:
+[{'id': 2, 'name': 'Bob', 'age': 30, 'email': '[email protected]'},
+ {'id': 3, 'name': 'Charlie', 'age': 28, 'email': '[email protected]'}]
+===============================================================================
+'''
+
+# Example 6: Read-only mode
+# Create a new toolkit in read-only mode
+readonly_toolkit = SQLToolkit(database_path=":memory:", read_only=True)
+
+# First, set up some data (need to do this before enabling read-only)
+# Actually, we need to create data first, then switch to read-only
+readonly_toolkit.read_only = False
+readonly_toolkit.execute_query(
+ "CREATE TABLE products (id INTEGER, name TEXT, price REAL)"
+)
+readonly_toolkit.execute_query(
+ "INSERT INTO products VALUES (1, 'Widget', 19.99)"
+)
+readonly_toolkit.read_only = True
+
+# SELECT works in read-only mode
+result = readonly_toolkit.execute_query("SELECT * FROM products")
+print("\nProducts (read-only mode):")
+print(result)
+
+# INSERT would fail in read-only mode
+try:
+ readonly_toolkit.execute_query(
+ "INSERT INTO products VALUES (2, 'Gadget', 29.99)"
+ )
+except ValueError as e:
+ print(f"\nRead-only mode correctly blocked INSERT: {e}")
+
+'''
+===============================================================================
+Products (read-only mode):
+[{'id': 1, 'name': 'Widget', 'price': 19.99}]
+
+Read-only mode correctly blocked INSERT: Write operations are not allowed in
+read-only mode. The query contains write operations (INSERT, UPDATE, DELETE,
+DROP, CREATE, ALTER, TRUNCATE, etc.). Only SELECT queries are permitted.
+===============================================================================
+'''
+
+# Example 7: EXPLAIN query
+result = sql_toolkit.execute_query(
+ "EXPLAIN SELECT * FROM users WHERE age > 25"
+)
+print("\nQuery execution plan:")
+print(result)
+
+'''
+===============================================================================
+Query execution plan:
+[{'explain_key': 'logical_plan', 'explain_value': '...'},
+ {'explain_key': 'physical_plan', 'explain_value': '...'}]
+===============================================================================
+'''
+
+# Example 8: File-based database (persistent storage)
+# Create a temporary file for the database
+with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as tmp_file:
+ db_path = tmp_file.name
+
+# Remove the empty file so DuckDB can create a new database
+try:
+ os.unlink(db_path)
+except Exception:
+ pass
+
+# Create toolkit with file-based database
+file_toolkit = SQLToolkit(database_path=db_path, read_only=False)
+
+# Create table and insert data
+file_toolkit.execute_query(
+ "CREATE TABLE inventory (id INTEGER, item TEXT, quantity INTEGER)"
+)
+file_toolkit.execute_query("INSERT INTO inventory VALUES (1, 'Apples', 100)")
+file_toolkit.execute_query("INSERT INTO inventory VALUES (2, 'Bananas', 150)")
+
+# Close connection
+file_toolkit._connection.close()
+
+# Reopen connection to same file - data persists!
+file_toolkit2 = SQLToolkit(database_path=db_path, read_only=False)
+result = file_toolkit2.execute_query("SELECT * FROM inventory")
+print("\nPersistent inventory data:")
+print(result)
+
+# Cleanup
+file_toolkit2._connection.close()
+try:
+ os.unlink(db_path)
+except Exception:
+ pass
+
+'''
+===============================================================================
+Persistent inventory data:
+[{'id': 1, 'item': 'Apples', 'quantity': 100},
+ {'id': 2, 'item': 'Bananas', 'quantity': 150}]
+===============================================================================
+'''
+
+# Example 9: Using SQLite Database
+print("\n" + "=" * 80)
+print("Example 9: Using SQLite Database")
+print("=" * 80)
+
+# SQLite is built into Python and works similarly to DuckDB
+# Just specify database_type="sqlite" to use SQLite instead of DuckDB
+sqlite_toolkit = SQLToolkit(
+ database_path=":memory:", database_type="sqlite", read_only=False
+)
+
+# Create a table
+sqlite_toolkit.execute_query(
+ "CREATE TABLE products (id INTEGER PRIMARY KEY, name TEXT, price REAL)"
+)
+
+# Insert data
+sqlite_toolkit.execute_query(
+ "INSERT INTO products (name, price) VALUES ('Laptop', 999.99)"
+)
+sqlite_toolkit.execute_query(
+ "INSERT INTO products (name, price) VALUES ('Mouse', 29.99)"
+)
+
+# Query data
+result = sqlite_toolkit.execute_query("SELECT * FROM products")
+print("\nSQLite products:")
+print(result)
+
+# List tables
+tables = sqlite_toolkit.list_tables()
+print(f"\nSQLite tables: {tables}")
+
+# Get table info
+table_info = sqlite_toolkit.get_table_info("products")
+print("\nSQLite table info:")
+print(f" Columns: {len(table_info['columns'])}")
+print(f" Primary keys: {table_info['primary_keys']}")
+print(f" Row count: {table_info['row_count']}")
+
+'''
+===============================================================================
+SQLite products:
+[{'id': 1, 'name': 'Laptop', 'price': 999.99},
+ {'id': 2, 'name': 'Mouse', 'price': 29.99}]
+
+SQLite tables: ['products']
+
+SQLite table info:
+ Columns: 3
+ Primary keys: ['id']
+ Row count: 2
+===============================================================================
+'''
+
+# Example 10: Schema Discovery - Using built-in toolkit methods
+print("\n" + "=" * 80)
+print("Example 10: Schema Discovery (Using Toolkit Methods)")
+print("=" * 80)
+# Note: This example uses DuckDB (default), but SQLite works the same way
+
+# Create a new database with multiple tables including primary and foreign keys
+schema_toolkit = SQLToolkit(database_path=":memory:", read_only=False)
+
+# Set up sample database with relationships
+schema_toolkit.execute_query(
+ "CREATE TABLE departments (id INTEGER PRIMARY KEY, name TEXT, budget REAL)"
+)
+schema_toolkit.execute_query(
+ """
+ CREATE TABLE employees (
+ id INTEGER PRIMARY KEY,
+ name TEXT,
+ department_id INTEGER,
+ salary REAL,
+ FOREIGN KEY (department_id) REFERENCES departments(id)
+ )
+ """
+)
+schema_toolkit.execute_query(
+ """
+ CREATE TABLE projects (
+ id INTEGER PRIMARY KEY,
+ name TEXT,
+ employee_id INTEGER,
+ FOREIGN KEY (employee_id) REFERENCES employees(id)
+ )
+ """
+)
+schema_toolkit.execute_query(
+ "INSERT INTO departments VALUES (1, 'Engineering', 1000000.0)"
+)
+schema_toolkit.execute_query(
+ "INSERT INTO employees VALUES (1, 'Alice', 1, 95000.0)"
+)
+
+# Method 1: List all tables using the toolkit method
+tables = schema_toolkit.list_tables()
+print("\nAll tables in database:")
+print(tables)
+
+'''
+===============================================================================
+All tables in database:
+['departments', 'employees', 'projects']
+===============================================================================
+'''
+
+# Method 2: Get table schema with primary and foreign keys
+schema_info = schema_toolkit.get_table_info("employees")
+print("\nSchema of 'employees' table (with primary and foreign keys):")
+print(f"Table Name: {schema_info['table_name']}")
+print(f"Columns: {schema_info['columns']}")
+print(f"Primary Keys: {schema_info['primary_keys']}")
+print(f"Foreign Keys: {schema_info['foreign_keys']}")
+print(f"Row Count: {schema_info['row_count']}")
+
+'''
+===============================================================================
+Schema of 'employees' table (with primary and foreign keys):
+Columns: [{'column_name': 'id', 'column_type': 'INTEGER', ...}, ...]
+Primary Keys: ['id']
+Foreign Keys: [{'column': 'department_id', 'references_table': ...}]
+===============================================================================
+'''
+
+# Method 3: Get comprehensive info for a specific table
+table_info = schema_toolkit.get_table_info("employees")
+print("\nComplete info for 'employees' table:")
+print(f"Table: {table_info['table_name']}")
+print(f"Primary Keys: {table_info['primary_keys']}")
+print(f"Foreign Keys: {table_info['foreign_keys']}")
+print(f"Row Count: {table_info['row_count']}")
+
+'''
+===============================================================================
+Complete info for 'employees' table:
+Table: employees
+Primary Keys: ['id']
+Foreign Keys: [{'column': 'department_id', 'references_table': ...}]
+Row Count: 1
+===============================================================================
+'''
+
+# Method 4: Get info for all tables at once (includes relationships)
+all_tables_info = schema_toolkit.get_table_info()
+print("\nInfo for all tables (with relationships):")
+for table_name, info in all_tables_info.items():
+ print(f"\n{table_name}:")
+ print(f" Primary Keys: {info['primary_keys']}")
+ print(f" Foreign Keys: {info['foreign_keys']}")
+ print(f" Row Count: {info['row_count']}")
+
+'''
+===============================================================================
+Info for all tables (with relationships):
+departments:
+ Primary Keys: ['id']
+ Foreign Keys: []
+ Row Count: 1
+
+employees:
+ Primary Keys: ['id']
+ Foreign Keys: [{'column': 'department_id', 'references_table': ...}]
+ Row Count: 1
+
+projects:
+ Primary Keys: ['id']
+ Foreign Keys: [{'column': 'employee_id', 'references_table': ...}]
+ Row Count: 0
+===============================================================================
+'''
+
+print("\n" + "=" * 80)
+print("SQL Toolkit examples completed successfully!")
+print("=" * 80)
+
+# Example 11: Using SQL Toolkit with ChatAgent - Schema Discovery First
+print("\n" + "=" * 80)
+print("Example 11: Using SQL Toolkit with ChatAgent (with Schema Discovery)")
+print("=" * 80)
+
+# Create a model using OpenAI
+model = ModelFactory.create(
+ model_platform=ModelPlatformType.OPENAI,
+ model_type=ModelType.GPT_4O_MINI,
+ model_config_dict=ChatGPTConfig(
+ temperature=0.0,
+ ).as_dict(),
+)
+
+# Create a new in-memory database for the agent
+agent_sql_toolkit = SQLToolkit(database_path=":memory:", read_only=False)
+
+# Set up initial data
+agent_sql_toolkit.execute_query(
+ "CREATE TABLE employees "
+ "(id INTEGER, name TEXT, department TEXT, salary REAL)"
+)
+agent_sql_toolkit.execute_query(
+ "INSERT INTO employees VALUES (1, 'Alice', 'Engineering', 95000.0)"
+)
+agent_sql_toolkit.execute_query(
+ "INSERT INTO employees VALUES (2, 'Bob', 'Marketing', 75000.0)"
+)
+agent_sql_toolkit.execute_query(
+ "INSERT INTO employees VALUES (3, 'Charlie', 'Engineering', 100000.0)"
+)
+agent_sql_toolkit.execute_query(
+ "INSERT INTO employees VALUES (4, 'Diana', 'Sales', 80000.0)"
+)
+
+# Create a chat agent with the SQL toolkit
+# Important: The agent can discover the schema using built-in methods!
+agent = ChatAgent(
+ system_message=(
+ "You are a helpful database assistant. You can execute SQL queries "
+ "to help users analyze and manage their data.\n\n"
+ "IMPORTANT: Before answering questions about the data, you should "
+ "first discover the database schema using these tools:\n"
+ "1. Use 'list_tables' to list all tables in the database\n"
+ "2. Use 'get_table_info' with a table name to get comprehensive "
+ "info including schema (columns, primary keys, foreign keys) and "
+ "row counts\n"
+ " - Call with a table name for specific table info\n"
+ " - Call without arguments to get info for all tables\n\n"
+ "The schema information includes primary keys and foreign key "
+ "relationships, which will help you write correct JOIN queries.\n\n"
+ "After understanding the schema, you can write appropriate SQL "
+ "queries using 'execute_query' to answer user questions."
+ ),
+ model=model,
+ tools=[*agent_sql_toolkit.get_tools()],
+)
+
+# Example: Agent discovers schema first, then answers question
+print("\nUser: What tables are in the database and what's their structure?")
+response_schema = agent.step(
+ "What tables are in the database and what's their structure?"
+)
+print(f"Agent: {response_schema.msgs[0].content}")
+
+# Now the agent knows the schema, it can answer questions
+print("\nUser: What is the average salary by department?")
+response1 = agent.step("What is the average salary by department?")
+print(f"Agent: {response1.msgs[0].content}")
+
+'''
+===============================================================================
+User: What tables are in the database and what's their structure?
+Agent: I'll first discover the database schema using the built-in
+schema discovery tools.
+
+[Agent calls: list_tables()]
+[Agent calls: get_table_info("employees")]
+
+The database contains the following table:
+- employees:
+ * Columns: id (INTEGER), name (TEXT), department (TEXT), salary (REAL)
+ * Primary Keys: []
+ * Foreign Keys: []
+
+Now I understand the schema and can answer questions about the data.
+
+User: What is the average salary by department?
+Agent: I'll query the database to find the average salary by department.
+
+[Agent executes SQL query:
+ SELECT department, AVG(salary) as avg_salary FROM employees GROUP BY dept]
+
+Here are the average salaries by department:
+
+| Department | Average Salary |
+|--------------|----------------|
+| Engineering | $97,500.00 |
+| Marketing | $75,000.00 |
+| Sales | $80,000.00 |
+
+The Engineering department has the highest average salary at $97,500.
+===============================================================================
+'''
+
+# Example query: Find employees in Engineering
+print("\nUser: Show me all employees in the Engineering department.")
+response2 = agent.step("Show me all employees in the Engineering department.")
+print(f"Agent: {response2.msgs[0].content}")
+
+'''
+===============================================================================
+User: Show me all employees in the Engineering department.
+Agent: I'll query the database to find all Engineering employees.
+
+[Agent executes SQL query:
+ SELECT * FROM employees WHERE department = 'Engineering']
+
+Here are all employees in the Engineering department:
+
+| ID | Name | Department | Salary |
+|----|---------|-------------|----------|
+| 1 | Alice | Engineering | $95,000 |
+| 3 | Charlie | Engineering | $100,000 |
+
+There are 2 employees in the Engineering department.
+===============================================================================
+'''
+
+# Example query: Add a new employee
+print(
+ "\nUser: Add a new employee named Eve to the Sales department "
+ "with a salary of 85000."
+)
+response3 = agent.step(
+ "Add a new employee named Eve to the Sales department "
+ "with a salary of 85000."
+)
+print(f"Agent: {response3.msgs[0].content}")
+
+# Verify the new employee was added
+print("\nUser: Show me all employees in Sales now.")
+response4 = agent.step("Show me all employees in Sales now.")
+print(f"Agent: {response4.msgs[0].content}")
+
+'''
+===============================================================================
+User: Add a new employee named Eve to the Sales department with salary 85000.
+Agent: I'll add the new employee to the database.
+
+[Agent executes SQL query: INSERT INTO employees (name, department, salary)
+VALUES ('Eve', 'Sales', 85000.0)]
+
+The new employee Eve has been successfully added to the Sales department
+with a salary of $85,000.
+
+User: Show me all employees in Sales now.
+Agent: I'll query the database to show all employees in the Sales department.
+
+[Agent executes SQL query: SELECT * FROM employees WHERE department = 'Sales']
+
+Here are all employees in the Sales department:
+
+| ID | Name | Department | Salary |
+|----|-------|------------|----------|
+| 4 | Diana | Sales | $80,000 |
+| 5 | Eve | Sales | $85,000 |
+
+There are now 2 employees in the Sales department.
+===============================================================================
+'''
+
+# Example 12: Agent with Read-Only SQL Toolkit
+print("\n" + "=" * 80)
+print("Example 12: Agent with Read-Only SQL Toolkit")
+print("=" * 80)
+
+# Create a read-only toolkit (after setting up data)
+readonly_agent_toolkit = SQLToolkit(database_path=":memory:", read_only=False)
+readonly_agent_toolkit.execute_query(
+ "CREATE TABLE products (id INTEGER, name TEXT, price REAL, stock INTEGER)"
+)
+readonly_agent_toolkit.execute_query(
+ "INSERT INTO products VALUES (1, 'Widget', 19.99, 100)"
+)
+readonly_agent_toolkit.execute_query(
+ "INSERT INTO products VALUES (2, 'Gadget', 29.99, 50)"
+)
+readonly_agent_toolkit.read_only = True # Switch to read-only mode
+
+readonly_agent = ChatAgent(
+ system_message=(
+ "You are a helpful database assistant in read-only mode. You can "
+ "only query data, not modify it.\n\n"
+ "IMPORTANT: Before answering questions, you should discover the "
+ "database schema using these tools:\n"
+ "1. Use 'list_tables' to list all tables\n"
+ "2. Use 'get_table_info' to get comprehensive table information "
+ "including schema (columns, primary keys, foreign keys) and row "
+ "counts\n"
+ " - Call with a table name for specific table info\n"
+ " - Call without arguments to get info for all tables\n\n"
+ "After understanding the schema, use 'execute_query' to run SELECT "
+ "queries only. Write operations (INSERT, UPDATE, DELETE, etc.) are "
+ "not allowed in read-only mode."
+ ),
+ model=model,
+ tools=[*readonly_agent_toolkit.get_tools()],
+)
+
+print("\nUser: What products do we have in stock?")
+response5 = readonly_agent.step("What products do we have in stock?")
+print(f"Agent: {response5.msgs[0].content}")
+
+print("\nUser: Try to add a new product called 'Thingamajig' for $39.99.")
+response6 = readonly_agent.step(
+ "Try to add a new product called 'Thingamajig' for $39.99."
+)
+print(f"Agent: {response6.msgs[0].content}")
+
+'''
+===============================================================================
+User: What products do we have in stock?
+Agent: I'll first discover the database schema, then query the products.
+
+[Agent calls: list_tables()]
+[Agent calls: get_table_info("products")]
+[Agent executes SQL query: SELECT * FROM products]
+
+Here are all products in stock:
+
+| ID | Name | Price | Stock |
+|----|--------|--------|-------|
+| 1 | Widget | $19.99 | 100 |
+| 2 | Gadget | $29.99 | 50 |
+
+User: Try to add a new product called 'Thingamajig' for $39.99.
+Agent: I'm in read-only mode, so I cannot modify the database. I can only
+query existing data. If you need to add a product, please use a database
+connection with write permissions.
+
+[Agent attempts to execute INSERT query but it's blocked by read-only mode]
+===============================================================================
+'''
+
+print("\n" + "=" * 80)
+print("All SQL Toolkit examples completed successfully!")
+print("=" * 80)
diff --git a/pyproject.toml b/pyproject.toml
index 6a2f14cb9..ce276b98c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -221,6 +221,7 @@ storage = [
"pgvector>=0.2.4,<0.3",
"surrealdb>=1.0.6",
"chromadb>=0.6.0,<1.0.0",
+ "duckdb>=1.4.3",
]
owl = [
"numpy>=1.2,<=2.2",
@@ -438,6 +439,7 @@ all = [
"onnxruntime<=1.19.2",
"google-cloud-aiplatform>=1.111.0",
"httplib2>=0.31.0",
+ "duckdb>=1.4.3",
]
[project.urls]
diff --git a/test/toolkits/test_sql_toolkit.py b/test/toolkits/test_sql_toolkit.py
new file mode 100644
index 000000000..8daef6761
--- /dev/null
+++ b/test/toolkits/test_sql_toolkit.py
@@ -0,0 +1,1001 @@
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import os
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from camel.toolkits import SQLToolkit
+
+
+def sql_toolkit_memory():
+ r"""Create a SQLToolkit instance with in-memory database."""
+ toolkit = SQLToolkit(database_path=":memory:", read_only=False)
+ yield toolkit
+ # Cleanup is handled by __del__
+
+
+def sql_toolkit_readonly():
+ r"""Create a SQLToolkit instance in read-only mode."""
+ # First create toolkit in read-write mode to set up test data
+ toolkit = SQLToolkit(database_path=":memory:", read_only=False)
+ # Set up some test data first
+ toolkit.execute_query("CREATE TABLE users (id INTEGER, name TEXT)")
+ toolkit.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+ toolkit.execute_query("INSERT INTO users VALUES (2, 'Bob')")
+ # Switch to read-only mode
+ toolkit.read_only = True
+ yield toolkit
+
+
+def sql_toolkit_sqlite():
+ r"""Create a SQLToolkit instance with SQLite in-memory database."""
+ toolkit = SQLToolkit(
+ database_path=":memory:", database_type="sqlite", read_only=False
+ )
+ yield toolkit
+ # Cleanup is handled by __del__
+
+
+def sql_toolkit_file():
+ r"""Create a SQLToolkit instance with file-based database."""
+ # Create a temporary file path
+ with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as tmp_file:
+ db_path = tmp_file.name
+ # Close and remove the empty file so DuckDB can create a new database
+ try:
+ Path(db_path).unlink()
+ except Exception:
+ pass
+
+ toolkit = SQLToolkit(database_path=db_path, read_only=False)
+ yield toolkit
+
+ # Cleanup
+ try:
+ toolkit._connection.close()
+ except Exception:
+ pass
+ try:
+ Path(db_path).unlink()
+ except Exception:
+ pass
+
+
+def test_initialization_default():
+ r"""Test the initialization of SQLToolkit with default parameters."""
+ toolkit = SQLToolkit()
+
+ assert toolkit.database_type in SQLToolkit._SUPPORTED_DATABASES
+ assert toolkit.read_only is False
+ assert toolkit.timeout == 180.0
+ assert toolkit._connection is not None
+
+
+def test_initialization_with_custom_parameters():
+ r"""Test the initialization of SQLToolkit with custom parameters."""
+ toolkit = SQLToolkit(
+ database_path=":memory:",
+ database_type="duckdb",
+ read_only=True,
+ timeout=30.0,
+ )
+
+ assert toolkit.database_type in SQLToolkit._SUPPORTED_DATABASES
+ assert toolkit.read_only is True
+ assert toolkit.timeout == 30.0
+ assert toolkit._connection is not None
+
+
+def test_initialization_invalid_database_type():
+ r"""Test that initialization fails with unsupported database type."""
+ with pytest.raises(ValueError, match="Unsupported database_type"):
+ SQLToolkit(database_type="postgresql")
+
+
+def test_create_table(sql_toolkit_memory):
+ r"""Test creating a table in read-write mode."""
+ result = sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ assert isinstance(result, dict)
+ assert result["status"] == "success"
+
+
+def test_insert_data(sql_toolkit_memory):
+ r"""Test inserting data in read-write mode."""
+ # Create table first
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ # Insert data
+ result = sql_toolkit_memory.execute_query(
+ "INSERT INTO users VALUES (1, 'Alice')"
+ )
+ assert isinstance(result, dict)
+ assert result["status"] == "success"
+ assert "message" in result
+
+
+def test_select_query(sql_toolkit_memory):
+ r"""Test SELECT query execution."""
+ # Set up test data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (2, 'Bob')")
+
+ # Execute SELECT query
+ results = sql_toolkit_memory.execute_query("SELECT * FROM users")
+
+ assert len(results) == 2
+ assert results[0]["id"] == 1
+ assert results[0]["name"] == "Alice"
+ assert results[1]["id"] == 2
+ assert results[1]["name"] == "Bob"
+
+
+def test_select_with_where(sql_toolkit_memory):
+ r"""Test SELECT query with WHERE clause."""
+ # Set up test data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (2, 'Bob')")
+
+ # Execute SELECT with WHERE
+ results = sql_toolkit_memory.execute_query(
+ "SELECT * FROM users WHERE id = 1"
+ )
+
+ assert len(results) == 1
+ assert results[0]["id"] == 1
+ assert results[0]["name"] == "Alice"
+
+
+def test_select_empty_result(sql_toolkit_memory):
+ r"""Test SELECT query that returns no results."""
+ # Create empty table
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+
+ # Execute SELECT on empty table
+ results = sql_toolkit_memory.execute_query("SELECT * FROM users")
+
+ assert results == []
+
+
+def test_update_query(sql_toolkit_memory):
+ r"""Test UPDATE query in read-write mode."""
+ # Set up test data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+
+ # Update data
+ result = sql_toolkit_memory.execute_query(
+ "UPDATE users SET name = 'Alice Updated' WHERE id = 1"
+ )
+ assert isinstance(result, dict)
+ assert result["status"] == "success"
+ assert "message" in result
+
+ # Verify update
+ results = sql_toolkit_memory.execute_query("SELECT * FROM users")
+ assert results[0]["name"] == "Alice Updated"
+
+
+def test_delete_query(sql_toolkit_memory):
+ r"""Test DELETE query in read-write mode."""
+ # Set up test data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (2, 'Bob')")
+
+ # Delete data
+ result = sql_toolkit_memory.execute_query("DELETE FROM users WHERE id = 1")
+ assert isinstance(result, dict)
+ assert result["status"] == "success"
+ assert "message" in result
+
+ # Verify deletion
+ results = sql_toolkit_memory.execute_query("SELECT * FROM users")
+ assert len(results) == 1
+ assert results[0]["id"] == 2
+
+
+def test_readonly_mode_allows_select(sql_toolkit_readonly):
+ r"""Test that read-only mode allows SELECT queries."""
+ results = sql_toolkit_readonly.execute_query("SELECT * FROM users")
+
+ assert len(results) == 2
+ assert results[0]["id"] == 1
+ assert results[1]["id"] == 2
+
+
+def test_readonly_mode_blocks_insert(sql_toolkit_readonly):
+ r"""Test that read-only mode blocks INSERT queries."""
+ result = sql_toolkit_readonly.execute_query(
+ "INSERT INTO users VALUES (3, 'Charlie')"
+ )
+ assert isinstance(result, str)
+ assert "Write operations are not allowed" in result
+
+
+def test_readonly_mode_blocks_update(sql_toolkit_readonly):
+ r"""Test that read-only mode blocks UPDATE queries."""
+ result = sql_toolkit_readonly.execute_query(
+ "UPDATE users SET name = 'Updated' WHERE id = 1"
+ )
+ assert isinstance(result, str)
+ assert "Write operations are not allowed" in result
+
+
+def test_readonly_mode_blocks_delete(sql_toolkit_readonly):
+ r"""Test that read-only mode blocks DELETE queries."""
+ result = sql_toolkit_readonly.execute_query(
+ "DELETE FROM users WHERE id = 1"
+ )
+ assert isinstance(result, str)
+ assert "Write operations are not allowed" in result
+
+
+def test_readonly_mode_blocks_create(sql_toolkit_readonly):
+ r"""Test that read-only mode blocks CREATE TABLE queries."""
+ result = sql_toolkit_readonly.execute_query(
+ "CREATE TABLE new_table (id INTEGER)"
+ )
+ assert isinstance(result, str)
+ assert "Write operations are not allowed" in result
+
+
+def test_readonly_mode_blocks_drop(sql_toolkit_memory):
+ r"""Test that read-only mode blocks DROP queries."""
+ # Set up test data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+
+ # Switch to read-only mode
+ sql_toolkit_memory.read_only = True
+
+ result = sql_toolkit_memory.execute_query("DROP TABLE users")
+ assert isinstance(result, str)
+ assert "Write operations are not allowed" in result
+
+
+def test_readonly_mode_blocks_alter(sql_toolkit_memory):
+ r"""Test that read-only mode blocks ALTER queries."""
+ # Set up test data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+
+ # Switch to read-only mode
+ sql_toolkit_memory.read_only = True
+
+ result = sql_toolkit_memory.execute_query(
+ "ALTER TABLE users ADD COLUMN email TEXT"
+ )
+ assert isinstance(result, str)
+ assert "Write operations are not allowed" in result
+
+
+def test_readonly_mode_blocks_truncate(sql_toolkit_memory):
+ r"""Test that read-only mode blocks TRUNCATE queries."""
+ # Set up test data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+
+ # Switch to read-only mode
+ sql_toolkit_memory.read_only = True
+
+ result = sql_toolkit_memory.execute_query("TRUNCATE TABLE users")
+ assert isinstance(result, str)
+ assert "Write operations are not allowed" in result
+
+
+def test_query_with_comments(sql_toolkit_memory):
+ r"""Test that queries with comments are handled correctly."""
+ # Set up test data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+
+ # Query with single-line comment
+ results = sql_toolkit_memory.execute_query(
+ "SELECT * FROM users -- This is a comment"
+ )
+ assert len(results) == 1
+
+ # Query with multi-line comment
+ results = sql_toolkit_memory.execute_query(
+ "SELECT * FROM users /* This is a multi-line comment */"
+ )
+ assert len(results) == 1
+
+
+def test_query_case_insensitive_keywords(sql_toolkit_memory):
+ r"""Test that write keyword detection is case-insensitive."""
+ # Set up test data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+
+ # Switch to read-only mode
+ sql_toolkit_memory.read_only = True
+
+ # Test lowercase insert
+ result = sql_toolkit_memory.execute_query(
+ "insert into users values (1, 'Alice')"
+ )
+ assert isinstance(result, str)
+ assert "Write operations are not allowed" in result
+
+ # Test mixed case update
+ result = sql_toolkit_memory.execute_query(
+ "UpDaTe users SET name = 'Bob' WHERE id = 1"
+ )
+ assert isinstance(result, str)
+ assert "Write operations are not allowed" in result
+
+
+def test_join_query(sql_toolkit_memory):
+ r"""Test JOIN query execution."""
+ # Set up test data with two tables
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE orders (id INTEGER, user_id INTEGER, amount REAL)"
+ )
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (2, 'Bob')")
+ sql_toolkit_memory.execute_query("INSERT INTO orders VALUES (1, 1, 100.0)")
+ sql_toolkit_memory.execute_query("INSERT INTO orders VALUES (2, 1, 50.0)")
+
+ # Execute JOIN query
+ results = sql_toolkit_memory.execute_query(
+ """
+ SELECT u.name, o.amount
+ FROM users u
+ JOIN orders o ON u.id = o.user_id
+ ORDER BY o.amount DESC
+ """
+ )
+
+ assert len(results) == 2
+ assert results[0]["name"] == "Alice"
+ assert results[0]["amount"] == 100.0
+ assert results[1]["name"] == "Alice"
+ assert results[1]["amount"] == 50.0
+
+
+def test_multiple_queries_sequence(sql_toolkit_memory):
+ r"""Test executing multiple queries in sequence."""
+ # Create table
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+
+ # Insert multiple rows
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (2, 'Bob')")
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (3, 'Charlie')")
+
+ # Query all
+ results = sql_toolkit_memory.execute_query("SELECT * FROM users")
+ assert len(results) == 3
+
+ # Update one
+ sql_toolkit_memory.execute_query(
+ "UPDATE users SET name = 'Bob Updated' WHERE id = 2"
+ )
+
+ # Query again
+ results = sql_toolkit_memory.execute_query("SELECT * FROM users")
+ assert len(results) == 3
+ assert results[1]["name"] == "Bob Updated"
+
+
+def test_invalid_query_syntax(sql_toolkit_memory):
+ r"""Test handling of invalid SQL syntax."""
+ result = sql_toolkit_memory.execute_query("INVALID SQL SYNTAX")
+ assert isinstance(result, str)
+ assert "Error:" in result
+
+
+def test_empty_query(sql_toolkit_memory):
+ r"""Test handling of empty query."""
+ result = sql_toolkit_memory.execute_query("")
+ assert isinstance(result, str)
+ assert "Query cannot be empty" in result
+
+
+def test_file_based_database(sql_toolkit_file):
+ r"""Test file-based database persistence."""
+ # Create table and insert data
+ sql_toolkit_file.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_file.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+
+ # Close connection
+ sql_toolkit_file._connection.close()
+
+ # Reopen connection to same file
+ db_path = sql_toolkit_file.database_path
+ new_toolkit = SQLToolkit(database_path=db_path, read_only=False)
+
+ # Verify data persists
+ results = new_toolkit.execute_query("SELECT * FROM users")
+ assert len(results) == 1
+ assert results[0]["id"] == 1
+ assert results[0]["name"] == "Alice"
+
+ # Cleanup
+ new_toolkit._connection.close()
+
+
+def test_file_based_duckdb_readonly_mode():
+ r"""Test that file-based DuckDB connections pass read_only parameter."""
+ import tempfile
+ from pathlib import Path
+
+ # Create a temporary file path
+ with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as tmp_file:
+ db_path = tmp_file.name
+ # Close and remove the empty file so DuckDB can create a new database
+ try:
+ Path(db_path).unlink()
+ except Exception:
+ pass
+
+ try:
+ # Create database and add data
+ toolkit = SQLToolkit(
+ database_path=db_path, database_type="duckdb", read_only=False
+ )
+ toolkit.execute_query("CREATE TABLE products (id INTEGER, name TEXT)")
+ toolkit.execute_query("INSERT INTO products VALUES (1, 'Widget')")
+ toolkit._connection.close()
+
+ # Open in read-only mode - should pass read_only=True to duckdb
+ readonly_toolkit = SQLToolkit(
+ database_path=db_path, database_type="duckdb", read_only=True
+ )
+
+ # Should be able to read
+ result = readonly_toolkit.execute_query("SELECT * FROM products")
+ assert len(result) == 1
+ assert result[0]["name"] == "Widget"
+
+ # Should not be able to write (application-level check)
+ result = readonly_toolkit.execute_query(
+ "INSERT INTO products VALUES (2, 'Gadget')"
+ )
+ assert isinstance(result, str)
+ assert "Write operations are not allowed" in result
+
+ # The read_only parameter should also be passed to duckdb.connect(),
+ # providing database-level protection. If we try to write directly
+ # through the connection, DuckDB should also block it.
+ # However, our application-level check catches it first, so this test
+ # primarily verifies that the parameter is passed correctly.
+
+ readonly_toolkit._connection.close()
+ finally:
+ # Cleanup
+ if os.path.exists(db_path):
+ os.unlink(db_path)
+
+
+def test_get_tools(sql_toolkit_memory):
+ r"""Test that get_tools returns the correct function tools."""
+ tools = sql_toolkit_memory.get_tools()
+
+ assert len(tools) == 3
+ tool_names = [tool.get_function_name() for tool in tools]
+ assert "execute_query" in tool_names
+ assert "list_tables" in tool_names
+ assert "get_table_info" in tool_names
+
+
+def test_list_tables(sql_toolkit_memory):
+ r"""Test listing all tables in the database."""
+ # Create some tables
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE orders (id INTEGER, user_id INTEGER)"
+ )
+
+ tables = sql_toolkit_memory.list_tables()
+ assert isinstance(tables, list)
+ assert "users" in tables
+ assert "orders" in tables
+
+
+def test_list_tables_empty(sql_toolkit_memory):
+ r"""Test listing tables when database is empty."""
+ tables = sql_toolkit_memory.list_tables()
+ assert tables == []
+
+
+def test_describe_table(sql_toolkit_memory):
+ r"""Test describing a table schema."""
+ # Create a table
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT, age INTEGER)"
+ )
+
+ schema_info = sql_toolkit_memory.get_table_info("users")
+ assert isinstance(schema_info, dict)
+ assert "table_name" in schema_info
+ assert "row_count" in schema_info
+ assert "columns" in schema_info
+ assert "primary_keys" in schema_info
+ assert "foreign_keys" in schema_info
+ assert schema_info["table_name"] == "users"
+
+ columns = schema_info["columns"]
+ assert isinstance(columns, list)
+ assert len(columns) == 3
+
+ # Check column names
+ column_names = [col["column_name"] for col in columns]
+ assert "id" in column_names
+ assert "name" in column_names
+ assert "age" in column_names
+
+ # Check primary keys (should be empty for this table)
+ assert schema_info["primary_keys"] == []
+ assert schema_info["foreign_keys"] == []
+
+
+def test_describe_table_nonexistent(sql_toolkit_memory):
+ r"""Test getting info for a non-existent table."""
+ result = sql_toolkit_memory.get_table_info("nonexistent_table")
+ assert isinstance(result, str)
+ assert "Error:" in result
+
+
+def test_describe_table_empty_name(sql_toolkit_memory):
+ r"""Test getting info for a table with empty name."""
+ result = sql_toolkit_memory.get_table_info("")
+ assert isinstance(result, str)
+ assert "Table name cannot be empty" in result
+
+
+def test_get_table_info_specific_table(sql_toolkit_memory):
+ r"""Test getting info for a specific table."""
+ # Create and populate a table
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (2, 'Bob')")
+
+ info = sql_toolkit_memory.get_table_info("users")
+ assert info["table_name"] == "users"
+ assert info["row_count"] == 2
+ assert "columns" in info
+ assert "primary_keys" in info
+ assert "foreign_keys" in info
+ assert len(info["columns"]) == 2
+
+
+def test_get_table_info_all_tables(sql_toolkit_memory):
+ r"""Test getting info for all tables."""
+ # Create multiple tables
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE orders (id INTEGER, amount REAL)"
+ )
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+
+ info = sql_toolkit_memory.get_table_info()
+ assert isinstance(info, dict)
+ assert "users" in info
+ assert "orders" in info
+ assert info["users"]["row_count"] == 1
+ assert info["orders"]["row_count"] == 0
+ assert "primary_keys" in info["users"]
+ assert "foreign_keys" in info["users"]
+
+
+def test_schema_discovery_readonly_mode(sql_toolkit_memory):
+ r"""Test that schema discovery methods work in read-only mode."""
+ # Set up data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+
+ # Switch to read-only mode
+ sql_toolkit_memory.read_only = True
+
+ # Schema discovery should work in read-only mode
+ tables = sql_toolkit_memory.list_tables()
+ assert "users" in tables
+
+ schema_info = sql_toolkit_memory.get_table_info("users")
+ assert isinstance(schema_info, dict)
+ assert len(schema_info["columns"]) == 2
+
+ info = sql_toolkit_memory.get_table_info("users")
+ assert info["table_name"] == "users"
+
+
+def test_describe_table_with_primary_key(sql_toolkit_memory):
+ r"""Test getting info for a table with primary key."""
+ # Create a table with primary key
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)"
+ )
+
+ schema_info = sql_toolkit_memory.get_table_info("users")
+ assert "primary_keys" in schema_info
+ assert "id" in schema_info["primary_keys"]
+ assert len(schema_info["primary_keys"]) == 1
+
+
+def test_describe_table_with_foreign_key(sql_toolkit_memory):
+ r"""Test describing a table with foreign key."""
+ # Create parent table
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE departments (id INTEGER PRIMARY KEY, name TEXT)"
+ )
+ # Create child table with foreign key
+ sql_toolkit_memory.execute_query(
+ """
+ CREATE TABLE employees (
+ id INTEGER PRIMARY KEY,
+ name TEXT,
+ department_id INTEGER,
+ FOREIGN KEY (department_id) REFERENCES departments(id)
+ )
+ """
+ )
+
+ schema_info = sql_toolkit_memory.get_table_info("employees")
+ assert "foreign_keys" in schema_info
+ assert len(schema_info["foreign_keys"]) == 1
+ fk = schema_info["foreign_keys"][0]
+ assert fk["column"] == "department_id"
+ assert fk["references_table"] == "departments"
+ assert fk["references_column"] == "id"
+
+
+def test_query_with_whitespace(sql_toolkit_memory):
+ r"""Test that queries with extra whitespace are handled correctly."""
+ # Set up test data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+
+ # Query with extra whitespace
+ results = sql_toolkit_memory.execute_query(
+ " SELECT * FROM users "
+ )
+
+ assert len(results) == 1
+ assert results[0]["id"] == 1
+
+
+def test_select_star_vs_specific_columns(sql_toolkit_memory):
+ r"""Test SELECT with specific columns vs SELECT *."""
+ # Set up test data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT, email TEXT)"
+ )
+ sql_toolkit_memory.execute_query(
+ "INSERT INTO users VALUES (1, 'Alice', '[email protected]')"
+ )
+
+ # SELECT *
+ results_all = sql_toolkit_memory.execute_query("SELECT * FROM users")
+ assert len(results_all[0]) == 3
+ assert "id" in results_all[0]
+ assert "name" in results_all[0]
+ assert "email" in results_all[0]
+
+ # SELECT specific columns
+ results_specific = sql_toolkit_memory.execute_query(
+ "SELECT id, name FROM users"
+ )
+ assert len(results_specific[0]) == 2
+ assert "id" in results_specific[0]
+ assert "name" in results_specific[0]
+ assert "email" not in results_specific[0]
+
+
+def test_cte_query(sql_toolkit_memory):
+ r"""Test Common Table Expression (CTE) queries that start with WITH."""
+ # Set up test data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT, age INTEGER)"
+ )
+ sql_toolkit_memory.execute_query(
+ "INSERT INTO users VALUES (1, 'Alice', 25)"
+ )
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (2, 'Bob', 30)")
+ sql_toolkit_memory.execute_query(
+ "INSERT INTO users VALUES (3, 'Charlie', 25)"
+ )
+
+ # CTE query that starts with WITH, not SELECT
+ results = sql_toolkit_memory.execute_query(
+ """
+ WITH adults AS (
+ SELECT * FROM users WHERE age >= 25
+ )
+ SELECT * FROM adults
+ """
+ )
+
+ assert len(results) == 3
+ assert all(row["age"] >= 25 for row in results)
+
+
+def test_explain_query(sql_toolkit_memory):
+ r"""Test EXPLAIN queries that start with EXPLAIN, not SELECT."""
+ # Set up test data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+
+ # EXPLAIN query returns results but doesn't start with SELECT
+ results = sql_toolkit_memory.execute_query("EXPLAIN SELECT * FROM users")
+
+ # EXPLAIN should return results (query plan)
+ assert isinstance(results, list)
+ # Results should have at least one row with query plan information
+ assert len(results) > 0
+
+
+def test_cte_with_join(sql_toolkit_memory):
+ r"""Test CTE queries with JOIN operations."""
+ # Set up test data
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE orders (id INTEGER, user_id INTEGER, amount REAL)"
+ )
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+ sql_toolkit_memory.execute_query("INSERT INTO orders VALUES (1, 1, 100.0)")
+ sql_toolkit_memory.execute_query("INSERT INTO orders VALUES (2, 1, 50.0)")
+
+ # CTE with JOIN
+ results = sql_toolkit_memory.execute_query(
+ """
+ WITH user_orders AS (
+ SELECT u.name, o.amount
+ FROM users u
+ JOIN orders o ON u.id = o.user_id
+ )
+ SELECT * FROM user_orders
+ """
+ )
+
+ assert len(results) == 2
+ assert results[0]["name"] == "Alice"
+ assert results[0]["amount"] == 100.0
+ assert results[1]["amount"] == 50.0
+
+
+def test_sql_injection_protection_table_name(sql_toolkit_memory):
+ r"""Test that table names are properly quoted to prevent SQL injection."""
+ # Create a normal table
+ sql_toolkit_memory.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT)"
+ )
+ sql_toolkit_memory.execute_query("INSERT INTO users VALUES (1, 'Alice')")
+
+ # Try to inject SQL through table name
+ # This should be safely quoted and not execute the injected SQL
+ malicious_table_name = "users; DROP TABLE users; --"
+
+ # This should return an error because the table doesn't exist
+ # (the malicious SQL should be treated as part of the table name)
+ result = sql_toolkit_memory.get_table_info(malicious_table_name)
+ assert isinstance(result, str)
+ assert "Error:" in result
+
+ # Verify the original table still exists (wasn't dropped)
+ tables = sql_toolkit_memory.list_tables()
+ assert "users" in tables
+
+ # Test with table name containing quotes
+ table_with_quotes = 'table"name'
+ sql_toolkit_memory.execute_query('CREATE TABLE "table""name" (id INTEGER)')
+ # Should work correctly with quoted identifier
+ schema = sql_toolkit_memory.get_table_info(table_with_quotes)
+ # get_table_info returns a dict with table info
+ assert "columns" in schema
+ assert "table_name" in schema
+ assert len(schema["columns"]) > 0
+
+ # Test with table name containing special characters
+ table_special = "table_name_123"
+ sql_toolkit_memory.execute_query(
+ 'CREATE TABLE "table_name_123" (id INTEGER)'
+ )
+ schema = sql_toolkit_memory.get_table_info(table_special)
+ # get_table_info returns a dict with table info
+ assert "columns" in schema
+ assert "table_name" in schema
+ assert len(schema["columns"]) > 0
+
+
+def test_quote_identifier_method(sql_toolkit_memory):
+ r"""Test the _quote_identifier helper method."""
+ # Test normal identifier
+ assert sql_toolkit_memory._quote_identifier("users") == '"users"'
+
+ # Test identifier with quotes (should be escaped)
+ assert (
+ sql_toolkit_memory._quote_identifier('table"name') == '"table""name"'
+ )
+
+ # Test identifier with spaces
+ assert sql_toolkit_memory._quote_identifier("table name") == '"table name"'
+
+ # Test empty identifier (should raise error)
+ with pytest.raises(ValueError):
+ sql_toolkit_memory._quote_identifier("")
+
+ # Test identifier with null bytes (should raise error)
+ with pytest.raises(ValueError):
+ sql_toolkit_memory._quote_identifier("table\x00name")
+
+
+def test_sqlite_basic_operations(sql_toolkit_sqlite):
+ r"""Test basic SQLite operations."""
+ # Create table
+ sql_toolkit_sqlite.execute_query(
+ "CREATE TABLE users (id INTEGER, name TEXT, age INTEGER)"
+ )
+
+ # Insert data - SQLite supports rows_affected
+ insert_result = sql_toolkit_sqlite.execute_query(
+ "INSERT INTO users VALUES (1, 'Alice', 25)"
+ )
+ assert isinstance(insert_result, dict)
+ assert insert_result["status"] == "success"
+ assert insert_result["rows_affected"] == 1
+
+ # Query data
+ result = sql_toolkit_sqlite.execute_query("SELECT * FROM users")
+ assert len(result) == 1
+ assert result[0]["id"] == 1
+ assert result[0]["name"] == "Alice"
+ assert result[0]["age"] == 25
+
+ # Update data - SQLite supports rows_affected
+ update_result = sql_toolkit_sqlite.execute_query(
+ "UPDATE users SET age = 26 WHERE id = 1"
+ )
+ assert isinstance(update_result, dict)
+ assert update_result["status"] == "success"
+ assert update_result["rows_affected"] == 1
+
+
+def test_sqlite_list_tables(sql_toolkit_sqlite):
+ r"""Test listing tables in SQLite."""
+ sql_toolkit_sqlite.execute_query("CREATE TABLE table1 (id INTEGER)")
+ sql_toolkit_sqlite.execute_query("CREATE TABLE table2 (id INTEGER)")
+
+ tables = sql_toolkit_sqlite.list_tables()
+ assert "table1" in tables
+ assert "table2" in tables
+
+
+def test_sqlite_schema_discovery(sql_toolkit_sqlite):
+ r"""Test schema discovery in SQLite."""
+ sql_toolkit_sqlite.execute_query(
+ "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)"
+ )
+
+ schema_info = sql_toolkit_sqlite.get_table_info("users")
+ assert "columns" in schema_info
+ assert "primary_keys" in schema_info
+ assert "id" in schema_info["primary_keys"]
+ assert len(schema_info["columns"]) == 3
+
+
+def test_sqlite_foreign_keys(sql_toolkit_sqlite):
+ r"""Test foreign key discovery in SQLite."""
+ sql_toolkit_sqlite.execute_query(
+ "CREATE TABLE departments (id INTEGER PRIMARY KEY, name TEXT)"
+ )
+ sql_toolkit_sqlite.execute_query(
+ """
+ CREATE TABLE employees (
+ id INTEGER PRIMARY KEY,
+ name TEXT,
+ department_id INTEGER,
+ FOREIGN KEY (department_id) REFERENCES departments(id)
+ )
+ """
+ )
+
+ schema_info = sql_toolkit_sqlite.get_table_info("employees")
+ assert "foreign_keys" in schema_info
+ assert len(schema_info["foreign_keys"]) == 1
+ fk = schema_info["foreign_keys"][0]
+ assert fk["column"] == "department_id"
+ assert fk["references_table"] == "departments"
+ assert fk["references_column"] == "id"
+
+
+def test_sqlite_readonly_mode():
+ r"""Test SQLite read-only mode."""
+ import os
+ import tempfile
+
+ # Create a temporary database file
+ with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as tmp_file:
+ db_path = tmp_file.name
+
+ try:
+ # Create database and add data
+ toolkit = SQLToolkit(
+ database_path=db_path, database_type="sqlite", read_only=False
+ )
+ toolkit.execute_query("CREATE TABLE products (id INTEGER, name TEXT)")
+ toolkit.execute_query("INSERT INTO products VALUES (1, 'Widget')")
+ toolkit._connection.close()
+
+ # Open in read-only mode
+ readonly_toolkit = SQLToolkit(
+ database_path=db_path, database_type="sqlite", read_only=True
+ )
+
+ # Should be able to read
+ result = readonly_toolkit.execute_query("SELECT * FROM products")
+ assert len(result) == 1
+
+ # Should not be able to write
+ result = readonly_toolkit.execute_query(
+ "INSERT INTO products VALUES (2, 'Gadget')"
+ )
+ assert isinstance(result, str)
+ assert "Write operations are not allowed" in result
+
+ readonly_toolkit._connection.close()
+ finally:
+ # Cleanup
+ if os.path.exists(db_path):
+ os.unlink(db_path)
diff --git a/uv.lock b/uv.lock
index d06479069..2726982d2 100644
--- a/uv.lock
+++ b/uv.lock
@@ -913,6 +913,7 @@ all = [
{ name = "docker" },
{ name = "docx" },
{ name = "docx2txt" },
+ { name = "duckdb" },
{ name = "e2b-code-interpreter" },
{ name = "exa-py" },
{ name = "faiss-cpu" },
@@ -1251,6 +1252,7 @@ storage = [
{ name = "azure-storage-blob" },
{ name = "botocore" },
{ name = "chromadb" },
+ { name = "duckdb" },
{ name = "faiss-cpu" },
{ name = "google-cloud-storage" },
{ name = "grpcio" },
@@ -1368,6 +1370,8 @@ requires-dist = [
{ name = "docx2txt", marker = "extra == 'all'", specifier = ">=0.8,<0.9" },
{ name = "docx2txt", marker = "extra == 'document-tools'", specifier = ">=0.8,<0.9" },
{ name = "docx2txt", marker = "extra == 'owl'", specifier = ">=0.8,<0.9" },
+ { name = "duckdb", marker = "extra == 'all'", specifier = ">=1.4.3" },
+ { name = "duckdb", marker = "extra == 'storage'", specifier = ">=1.4.3" },
{ name = "e2b-code-interpreter", marker = "extra == 'all'", specifier = ">=1.0.3,<2" },
{ name = "e2b-code-interpreter", marker = "extra == 'dev-tools'", specifier = ">=1.0.3,<2" },
{ name = "e2b-code-interpreter", marker = "extra == 'owl'", specifier = ">=1.0.3,<2" },
@@ -2789,6 +2793,48 @@ version = "0.8"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/7d/7d/60ee3f2b16d9bfdfa72e8599470a2c1a5b759cb113c6fe1006be28359327/docx2txt-0.8.tar.gz", hash = "sha256:2c06d98d7cfe2d3947e5760a57d924e3ff07745b379c8737723922e7009236e5", size = 2814, upload-time = "2019-06-23T19:58:36.94Z" }
+[[package]]
+name = "duckdb"
+version = "1.4.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7f/da/17c3eb5458af69d54dedc8d18e4a32ceaa8ce4d4c699d45d6d8287e790c3/duckdb-1.4.3.tar.gz", hash = "sha256:fea43e03604c713e25a25211ada87d30cd2a044d8f27afab5deba26ac49e5268", size = 18478418, upload-time = "2025-12-09T10:59:22.945Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/76/3a/ea8e237e1ba40203dea4ed6a8798ea51e66a4c4f34605697025e5fa06fdd/duckdb-1.4.3-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:efa7f1191c59e34b688fcd4e588c1b903a4e4e1f4804945902cf0b20e08a9001", size = 29016021, upload-time = "2025-12-09T10:57:46.847Z" },
+ { url = "https://files.pythonhosted.org/packages/48/88/07615298a2871362b454237b6a2d7724e6ba0afba2bddedddde5bbf129d5/duckdb-1.4.3-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:4fef6a053a1c485292000bf0c338bba60f89d334f6a06fc76ba4085a5a322b76", size = 15405906, upload-time = "2025-12-09T10:57:49.213Z" },
+ { url = "https://files.pythonhosted.org/packages/fa/66/b407ab3cd4822191aa5defb27522213b6ba670437c7da09a062d8b75b0a4/duckdb-1.4.3-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:702dabbc22b27dc5b73e7599c60deef3d8c59968527c36b391773efddd8f4cf1", size = 13732991, upload-time = "2025-12-09T10:57:51.189Z" },
+ { url = "https://files.pythonhosted.org/packages/33/f0/e8edab80446d87b4e0faf3aaa440f9cfd9d0609c21a4be56174c8ba7d23c/duckdb-1.4.3-cp310-cp310-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:854b79375fa618f6ffa8d84fb45cbc9db887f6c4834076ea10d20bc106f1fd90", size = 18471503, upload-time = "2025-12-09T10:57:53.186Z" },
+ { url = "https://files.pythonhosted.org/packages/8c/7a/8d257bc847f0ac6a6639ae0a6e7f35f0b5bfbae472ee4846ee32404670a6/duckdb-1.4.3-cp310-cp310-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1bb8bd5a3dd205983726185b280a211eacc9f5bc0c4d4505bec8c87ac33a8ccb", size = 20466012, upload-time = "2025-12-09T10:57:55.702Z" },
+ { url = "https://files.pythonhosted.org/packages/cf/d1/8f6bdaf2da6a076dd63c84ed87fb82d0741c9f4acb3dd476d73ca0a08ffe/duckdb-1.4.3-cp310-cp310-win_amd64.whl", hash = "sha256:d0ff08388ef8b1d1a4c95c321d6c5fa11201b241036b1ee740f9d841df3d6ba2", size = 12328392, upload-time = "2025-12-09T10:57:57.718Z" },
+ { url = "https://files.pythonhosted.org/packages/ec/bc/7c5e50e440c8629495678bc57bdfc1bb8e62f61090f2d5441e2bd0a0ed96/duckdb-1.4.3-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:366bf607088053dce845c9d24c202c04d78022436cc5d8e4c9f0492de04afbe7", size = 29019361, upload-time = "2025-12-09T10:57:59.845Z" },
+ { url = "https://files.pythonhosted.org/packages/26/15/c04a4faf0dfddad2259cab72bf0bd4b3d010f2347642541bd254d516bf93/duckdb-1.4.3-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:8d080e8d1bf2d226423ec781f539c8f6b6ef3fd42a9a58a7160de0a00877a21f", size = 15407465, upload-time = "2025-12-09T10:58:02.465Z" },
+ { url = "https://files.pythonhosted.org/packages/cb/54/a049490187c9529932fc153f7e1b92a9e145586281fe4e03ce0535a0497c/duckdb-1.4.3-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:9dc049ba7e906cb49ca2b6d4fbf7b6615ec3883193e8abb93f0bef2652e42dda", size = 13735781, upload-time = "2025-12-09T10:58:04.847Z" },
+ { url = "https://files.pythonhosted.org/packages/14/b7/ee594dcecbc9469ec3cd1fb1f81cb5fa289ab444b80cfb5640c8f467f75f/duckdb-1.4.3-cp311-cp311-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2b30245375ea94ab528c87c61fc3ab3e36331180b16af92ee3a37b810a745d24", size = 18470729, upload-time = "2025-12-09T10:58:07.116Z" },
+ { url = "https://files.pythonhosted.org/packages/df/5f/a6c1862ed8a96d8d930feb6af5e55aadd983310aab75142468c2cb32a2a3/duckdb-1.4.3-cp311-cp311-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a7c864df027da1ee95f0c32def67e15d02cd4a906c9c1cbae82c09c5112f526b", size = 20471399, upload-time = "2025-12-09T10:58:09.714Z" },
+ { url = "https://files.pythonhosted.org/packages/5b/80/c05c0b6a6107b618927b7dcabe3bba6a7eecd951f25c9dbcd9c1f9577cc8/duckdb-1.4.3-cp311-cp311-win_amd64.whl", hash = "sha256:813f189039b46877b5517f1909c7b94a8fe01b4bde2640ab217537ea0fe9b59b", size = 12329359, upload-time = "2025-12-09T10:58:12.147Z" },
+ { url = "https://files.pythonhosted.org/packages/b0/83/9d8fc3413f854effa680dcad1781f68f3ada8679863c0c94ba3b36bae6ff/duckdb-1.4.3-cp311-cp311-win_arm64.whl", hash = "sha256:fbc63ffdd03835f660155b37a1b6db2005bcd46e5ad398b8cac141eb305d2a3d", size = 13070898, upload-time = "2025-12-09T10:58:14.301Z" },
+ { url = "https://files.pythonhosted.org/packages/5a/d7/fdc2139b94297fc5659110a38adde293d025e320673ae5e472b95d323c50/duckdb-1.4.3-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:6302452e57aef29aae3977063810ed7b2927967b97912947b9cca45c1c21955f", size = 29033112, upload-time = "2025-12-09T10:58:16.52Z" },
+ { url = "https://files.pythonhosted.org/packages/eb/d9/ca93df1ce19aef8f799e3aaacf754a4dde7e9169c0b333557752d21d076a/duckdb-1.4.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:deab351ac43b6282a3270e3d40e3d57b3b50f472d9fd8c30975d88a31be41231", size = 15414646, upload-time = "2025-12-09T10:58:19.36Z" },
+ { url = "https://files.pythonhosted.org/packages/16/90/9f2748e740f5fc05b739e7c5c25aab6ab4363e5da4c3c70419c7121dc806/duckdb-1.4.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:5634e40e1e2d972e4f75bced1fbdd9e9e90faa26445c1052b27de97ee546944a", size = 13740477, upload-time = "2025-12-09T10:58:21.778Z" },
+ { url = "https://files.pythonhosted.org/packages/5f/ec/279723615b4fb454efd823b7efe97cf2504569e2e74d15defbbd6b027901/duckdb-1.4.3-cp312-cp312-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:274d4a31aba63115f23e7e7b401e3e3a937f3626dc9dea820a9c7d3073f450d2", size = 18483715, upload-time = "2025-12-09T10:58:24.346Z" },
+ { url = "https://files.pythonhosted.org/packages/10/63/af20cd20fd7fd6565ea5a1578c16157b6a6e07923e459a6f9b0dc9ada308/duckdb-1.4.3-cp312-cp312-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4f868a7e6d9b37274a1aa34849ea92aa964e9bd59a5237d6c17e8540533a1e4f", size = 20495188, upload-time = "2025-12-09T10:58:26.806Z" },
+ { url = "https://files.pythonhosted.org/packages/8c/ab/0acb4b64afb2cc6c1d458a391c64e36be40137460f176c04686c965ce0e0/duckdb-1.4.3-cp312-cp312-win_amd64.whl", hash = "sha256:ef7ef15347ce97201b1b5182a5697682679b04c3374d5a01ac10ba31cf791b95", size = 12335622, upload-time = "2025-12-09T10:58:29.707Z" },
+ { url = "https://files.pythonhosted.org/packages/50/d5/2a795745f6597a5e65770141da6efdc4fd754e5ee6d652f74bcb7f9c7759/duckdb-1.4.3-cp312-cp312-win_arm64.whl", hash = "sha256:1b9b445970fd18274d5ac07a0b24c032e228f967332fb5ebab3d7db27738c0e4", size = 13075834, upload-time = "2025-12-09T10:58:32.036Z" },
+ { url = "https://files.pythonhosted.org/packages/fd/76/288cca43a10ddd082788e1a71f1dc68d9130b5d078c3ffd0edf2f3a8719f/duckdb-1.4.3-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:16952ac05bd7e7b39946695452bf450db1ebbe387e1e7178e10f593f2ea7b9a8", size = 29033392, upload-time = "2025-12-09T10:58:34.631Z" },
+ { url = "https://files.pythonhosted.org/packages/64/07/cbad3d3da24af4d1add9bccb5fb390fac726ffa0c0cebd29bf5591cef334/duckdb-1.4.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:de984cd24a6cbefdd6d4a349f7b9a46e583ca3e58ce10d8def0b20a6e5fcbe78", size = 15414567, upload-time = "2025-12-09T10:58:37.051Z" },
+ { url = "https://files.pythonhosted.org/packages/c4/19/57af0cc66ba2ffb8900f567c9aec188c6ab2a7b3f2260e9c6c3c5f9b57b1/duckdb-1.4.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:1e5457dda91b67258aae30fb1a0df84183a9f6cd27abac1d5536c0d876c6dfa1", size = 13740960, upload-time = "2025-12-09T10:58:39.658Z" },
+ { url = "https://files.pythonhosted.org/packages/73/dd/23152458cf5fd51e813fadda60b9b5f011517634aa4bb9301f5f3aa951d8/duckdb-1.4.3-cp313-cp313-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:006aca6a6d6736c441b02ff5c7600b099bb8b7f4de094b8b062137efddce42df", size = 18484312, upload-time = "2025-12-09T10:58:42.054Z" },
+ { url = "https://files.pythonhosted.org/packages/1a/7b/adf3f611f11997fc429d4b00a730604b65d952417f36a10c4be6e38e064d/duckdb-1.4.3-cp313-cp313-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a2813f4635f4d6681cc3304020374c46aca82758c6740d7edbc237fe3aae2744", size = 20495571, upload-time = "2025-12-09T10:58:44.646Z" },
+ { url = "https://files.pythonhosted.org/packages/40/d5/6b7ddda7713a788ab2d622c7267ec317718f2bdc746ce1fca49b7ff0e50f/duckdb-1.4.3-cp313-cp313-win_amd64.whl", hash = "sha256:6db124f53a3edcb32b0a896ad3519e37477f7e67bf4811cb41ab60c1ef74e4c8", size = 12335680, upload-time = "2025-12-09T10:58:46.883Z" },
+ { url = "https://files.pythonhosted.org/packages/e8/28/0670135cf54525081fded9bac1254f78984e3b96a6059cd15aca262e3430/duckdb-1.4.3-cp313-cp313-win_arm64.whl", hash = "sha256:a8b0a8764e1b5dd043d168c8f749314f7a1252b5a260fa415adaa26fa3b958fd", size = 13075161, upload-time = "2025-12-09T10:58:49.47Z" },
+ { url = "https://files.pythonhosted.org/packages/b6/f4/a38651e478fa41eeb8e43a0a9c0d4cd8633adea856e3ac5ac95124b0fdbf/duckdb-1.4.3-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:316711a9e852bcfe1ed6241a5f654983f67e909e290495f3562cccdf43be8180", size = 29042272, upload-time = "2025-12-09T10:58:51.826Z" },
+ { url = "https://files.pythonhosted.org/packages/16/de/2cf171a66098ce5aeeb7371511bd2b3d7b73a2090603b0b9df39f8aaf814/duckdb-1.4.3-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:9e625b2b4d52bafa1fd0ebdb0990c3961dac8bb00e30d327185de95b68202131", size = 15419343, upload-time = "2025-12-09T10:58:54.439Z" },
+ { url = "https://files.pythonhosted.org/packages/35/28/6b0a7830828d4e9a37420d87e80fe6171d2869a9d3d960bf5d7c3b8c7ee4/duckdb-1.4.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:130c6760f6c573f9c9fe9aba56adba0fab48811a4871b7b8fd667318b4a3e8da", size = 13748905, upload-time = "2025-12-09T10:58:56.656Z" },
+ { url = "https://files.pythonhosted.org/packages/15/4d/778628e194d63967870873b9581c8a6b4626974aa4fbe09f32708a2d3d3a/duckdb-1.4.3-cp314-cp314-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:20c88effaa557a11267706b01419c542fe42f893dee66e5a6daa5974ea2d4a46", size = 18487261, upload-time = "2025-12-09T10:58:58.866Z" },
+ { url = "https://files.pythonhosted.org/packages/c6/5f/87e43af2e4a0135f9675449563e7c2f9b6f1fe6a2d1691c96b091f3904dd/duckdb-1.4.3-cp314-cp314-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1b35491db98ccd11d151165497c084a9d29d3dc42fc80abea2715a6c861ca43d", size = 20497138, upload-time = "2025-12-09T10:59:01.241Z" },
+ { url = "https://files.pythonhosted.org/packages/94/41/abec537cc7c519121a2a83b9a6f180af8915fabb433777dc147744513e74/duckdb-1.4.3-cp314-cp314-win_amd64.whl", hash = "sha256:23b12854032c1a58d0452e2b212afa908d4ce64171862f3792ba9a596ba7c765", size = 12836056, upload-time = "2025-12-09T10:59:03.388Z" },
+ { url = "https://files.pythonhosted.org/packages/b1/5a/8af5b96ce5622b6168854f479ce846cf7fb589813dcc7d8724233c37ded3/duckdb-1.4.3-cp314-cp314-win_arm64.whl", hash = "sha256:90f241f25cffe7241bf9f376754a5845c74775e00e1c5731119dc88cd71e0cb2", size = 13527759, upload-time = "2025-12-09T10:59:05.496Z" },
+]
+
[[package]]
name = "durationpy"
version = "0.10"