npm package: @heliont/n8n-nodes-mysql
Description: Custom MySQL node for n8n that merges query results into input data.
Author: Mario Bitter
Latest version: 2.0.0

# Heliont MySQL — n8n Custom Node

**A smart wrapper around the native n8n MySQL node for structured SELECT-based query processing and context merging.**

![n8n](https://img.shields.io/badge/built%20for-n8n-orange?logo=n8n) ![mysql](https://img.shields.io/badge/database-MySQL-blue) ![License](https://img.shields.io/npm/l/@heliont/n8n-nodes-messaging-hub)

---

## ✨ Overview

`Heliont MySQL` extends the base n8n MySQL node with additional functionality designed for flow-based merging of query results into existing input data structures.

Key features:

- Dual output routing: separates flows with and without results
- Smart dot-notation merge of SQL results into input JSON
- Optional debug output with full query and result metadata
- Fully compatible with existing MySQL credentials and configuration

---

## 🔌 Node Behavior

This node:

1. Executes the provided SQL query using standard n8n MySQL node infrastructure
2. Routes results to:
   - `Results`: if at least one row was returned
   - `No Result`: if the query was a `SELECT` and no rows were returned
3. For single-row `SELECT` queries, attempts to **merge result columns** directly into the input JSON via dot notation (e.g., `user.name`)
4. For multiple-row results or unmatched columns, attaches them to a `result` key

---

## 📤 Outputs

| Output Port     | Description                                                  |
|------------------|--------------------------------------------------------------|
| **No Result**   | Used when a `SELECT` query returns 0 rows                     |
| **Results**     | Used when a result exists or non-SELECT query was executed    |

Each item passed through includes:

```json
{
  "fieldA": "valueA",
  "nested": { "fieldB": "valueB" },
  "result": {
    "numberOfRows": 2,
    "results": [ ... ]
  },
  "debug": {
    "query": "SELECT * FROM users",
    "queryType": "SELECT",
    "numberOfRows": 2,
    "rawResult": [ ... ]
  }
}
```

> 🔍 `debug` info is only present when the `Detailed Output` option is enabled.

---

## 🧠 Merge Logic

- If the query returns **exactly one row**, and all its keys **match existing dot notation paths** in the input, the values are merged directly.
- If any key does **not** match an existing dot path in the input, the full result is attached under `result`.

Example:

```sql
SELECT user.name, user.age FROM users WHERE id = 1;
```

Will inject `user.name` and `user.age` directly into:

```json
{
  "user": {
    "name": "Alice",
    "age": 30
  }
}
```

---

## 🛠️ Usage Tips

- Ideal for context-aware query augmentation (e.g., enrich a contract or session with user profile info)
- Works seamlessly with workflows expecting conditional logic based on SQL results
- Combine with the Heliont contract pattern for advanced flow merging

---

## 🧪 Development

This node wraps the internal `mysqlVersionDescription` and uses the internal `router` and shared methods (`listSearch`, `loadOptions`, etc.).

Output structure is built by `extractDataRows()` and dot-merging via `dotNotationMerge()`.

---

## 📄 License

MIT License — see [`LICENSE`](./LICENSE)

---

## 💡 Author

Made with 💚 by [Heliont](https://www.heliont.com)