🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
feat: Implementing SQL toolkit (#3567)
Xingyue Huangde6676c4ffc9
diff --git a/camel/toolkits/__init__.py b/camel/toolkits/__init__.pyindex 895310919..f2853f7a9 100644--- a/camel/toolkits/__init__.py+++ b/camel/toolkits/__init__.py@@ -72,6 +72,7 @@ from .data_commons_toolkit import DataCommonsToolkitfrom .thinking_toolkit import ThinkingToolkitfrom .pyautogui_toolkit import PyAutoGUIToolkitfrom .searxng_toolkit import SearxNGToolkit+from .sql_toolkit import SQLToolkitfrom .jina_reranker_toolkit import JinaRerankerToolkitfrom .pulse_mcp_search_toolkit import PulseMCPSearchToolkitfrom .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.pynew file mode 100644index 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.pynew file mode 100644index 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.tomlindex 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.pynew file mode 100644index 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.lockindex 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"