# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.augelab.com/function-blocks/input-output/communication/sql-db-operations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.