Patched patchwork/steps/CallSQL/README.md

Author: patched.codes[bot]

patchwork/steps/CallSQL/README.md

@@ -0,0 +1,73 @@
+# CallSQL Module Documentation
+
+## Overview
+
+The CallSQL module is part of the Patchwork system, designed to interact with SQL databases by performing specific SQL queries. This module is ideal for users who need to automate database queries and handle SQL interactions programmatically. The module consists of a core execution script `CallSQL.py`, an initialization file `__init__.py`, and type definitions in `typed.py`.
+
+## Core Components
+
+### CallSQL.py
+
+This is the main script for executing SQL queries. It uses the SQLAlchemy library to establish a connection to the database and execute the SQL command provided by the user. It handles the following tasks:
+
+1. **Connection Setup**: Uses SQLAlchemy to build the connection to the database based on input parameters, including the database dialect, driver, username, password, host, and port.
+2. **Query Execution**: Renders SQL templates with Mustache syntax and executes them.
+3. **Error Handling**: Captures and logs any SQL execution errors, returning failed status if required.
+
+#### Inputs
+
+This module takes the following inputs through a dictionary structure:
+
+- **`db_dialect`**: (Required) The dialect of the database (e.g., `'postgresql'`).
+- **`db_query`**: (Required) The SQL query or template to execute.
+- **`db_driver`**: The specific database driver to use.
+- **`db_username`**: The username for database connection.
+- **`db_password`**: The password for database connection.
+- **`db_host`**: The server host; defaults to `'localhost'`.
+- **`db_port`**: The connection port; defaults to `5432`.
+- **`db_name`**: The name of the database to connect to.
+- **`db_params`**: Additional parameters for the connection in dictionary format.
+- **`db_driver_args`**: Additional driver-specific arguments.
+- **`db_query_template_values`**: Dictionary of values to render SQL templates.
+
+#### Outputs
+
+- **`results`**: A dictionary containing a list of query result rows, with each row being a dictionary of column names and values.
+
+### typed.py
+
+This file contains the type definitions for the inputs and outputs, ensuring type safety and clarity for users.
+
+#### `CallSQLInputs`
+
+Defines both required and optional parameters required to execute a SQL query within the CallSQL module.
+
+#### `CallSQLOutputs`
+
+Defines the structure of the query results, which are returned as a list of dictionaries.
+
+## Example Usage
+
+To use the CallSQL functionality, create an instance of the `CallSQL` class with the relevant parameters. Here's a basic example:
+
+```python
+inputs = {
+    "db_dialect": "postgresql",
+    "db_query": "SELECT * FROM my_table WHERE id = :id",
+    "db_username": "user",
+    "db_password": "pass",
+    "db_host": "localhost",
+    "db_port": 5432,
+    "db_name": "my_database",
+    "db_query_template_values": {"id": 1}
+}
+
+call_sql_step = CallSQL(inputs)
+results = call_sql_step.run()
+```
+
+This example initializes the CallSQL step with necessary parameters and executes the query, returning the results for further processing.
+
+## Conclusion
+
+The CallSQL module provides a robust way to execute SQL statements with dynamic query capabilities through Mustache templating. It is designed for flexibility and ease of use in SQL database operations within the Patchwork ecosystem.