> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/function-blocks/blocks-reference/input-output/communication/sql-db-operations.md).

# SQL-DB Operations

This function block lets you perform common SQL tasks (INSERT, QUERY, UPDATE, DELETE, EXECUTE) against a connected database. It provides a simple UI to select the desired operation, enter a table name when required, and feed the required inputs using sockets. Operations are executed in the background so the interface remains responsive.

## 📥 Inputs (sockets) <a href="#inputs" id="inputs"></a>

Depending on the selected SQL operation, the block exposes different input sockets. Each listed name is a socket you can connect to other blocks.

Common sockets used by all methods

* `Enable` Must be set to true to run the selected operation.
* `DB Client` A database client reference provided by a separate connection block (see Tips and Tricks).

Per-method sockets

* INSERT
  * `JSON Data` Data to insert into the selected table (JSON/dictionary).
* QUERY
  * `Query String` SQL SELECT or other query string to run.
* UPDATE
  * `JSON Data` Update values (JSON/dictionary).
  * `JSON Data(Where Conditions)` Where conditions to select rows to update.
* DELETE
  * `JSON Data(Where Conditions)` Where conditions to select rows to delete.
* EXECUTE
  * `Statement String` Raw SQL statement to execute (use with care).

Note: The block will show or hide the `Table Name` input control depending on the chosen operation.

## 📤 Outputs (sockets) <a href="#outputs" id="outputs"></a>

* `Output Data` Returns the result of the operation (for example query rows, affected row info, or operation-specific data).
* `Success?` Boolean indicating whether the operation completed successfully.

## 🕹️ Controls (widgets) <a href="#controls" id="controls"></a>

* `Select SQL Operation` Dropdown to choose one of: INSERT / QUERY / UPDATE / DELETE / EXECUTE. Changing this updates available input sockets to match the chosen operation.
* `Table Name` Text field for the target table name. Hidden automatically when not required (for example when using `EXECUTE`).

## ⚙️ Running mechanism <a href="#running-mechanism" id="running-mechanism"></a>

* The block only runs when the `Enable` socket receives a true value.
* It requires a valid `DB Client` socket connected (typically provided by a database connection block).
* When triggered, the block runs the selected operation in the background and returns `Output Data` and `Success?` when finished.
* Any problems (invalid inputs, missing client, malformed JSON, or SQL errors) are reported in the block’s message/log area.

## ✨ Key features <a href="#features" id="features"></a>

* Dynamic sockets that adapt to the chosen SQL operation for a clean UI.
* Background execution to keep the interface responsive during long-running database calls.
* Simple JSON-based inputs for INSERT and UPDATE to make feeding tabular data easy.
* Clear success indicator and returned result data for further processing.

## 📝 Usage instructions <a href="#usage" id="usage"></a>

1. Provide a database client to the `DB Client` socket (see Tips and Tricks).
2. Choose the desired operation with `Select SQL Operation`.
3. If applicable, enter the target table into `Table Name`.
4. Connect the required data sockets for the chosen operation (e.g., `JSON Data` for INSERT).
5. Send a true signal to `Enable` to run the operation.
6. Inspect `Output Data` and `Success?` to continue processing in your scenario.

## 💡 Tips and Tricks <a href="#tips-and-tricks" id="tips-and-tricks"></a>

* For establishing connections, use `SQL-DB Client Connect` to create and supply the `DB Client` socket.
* Prepare insert/update payloads using `Data to JSON` so the data format matches expected JSON/dictionary inputs.
* If you build SQL strings dynamically, use `String Input` or `String Merge` to compose the query or statement before feeding it into `Query String` or `Statement String`.
* Store or share frequently used DB clients or results using `Data Write Local` / `Data Read Local` or the global variants for cross-scenario access.
* Use `Parse Data Dictionary` to extract fields from returned query rows and feed them into other blocks.
* Use `Debug Input` to quickly log and inspect intermediate data going into the block when troubleshooting.
* If you need to save query results for later, combine with `CSV Export` to write output data to a file.

## 🛠️ Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

* `DB Client` is not valid Ensure you connected a proper database client (use `SQL-DB Client Connect`). The block will display an error if the client is missing or invalid.
* Operation returns error Check the provided JSON payload or SQL string for correctness. Use `Debug Input` or `Parse Data Dictionary` to inspect inputs and outputs.
* No response or long wait The block runs operations in the background, but long queries can still take time. Keep queries small or verify that the database is reachable and responsive.
* Malformed JSON When using JSON inputs, validate the JSON with `Data to JSON` or check contents with logging blocks before connecting.

If problems persist, inspect the block’s message/log output for hints and adjust inputs or database settings accordingly.