KosmoKrator

data

Mysql Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Mysql KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.mysql.*. Use lua_read_doc("integrations.mysql") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Mysql workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.mysql.query({sql = "example_sql"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("mysql"))' --json
kosmo integrations:lua --eval 'print(docs.read("mysql.query"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local mysql = app.integrations.mysql
local result = mysql.query({sql = "example_sql"})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.mysql, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.mysql.default.* or app.integrations.mysql.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Mysql, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

MySQL — Lua API Reference

query

Execute a raw SQL query on the MySQL database.

Parameters

NameTypeRequiredDescription
sqlstringyesThe SQL query to execute

Examples

Simple SELECT query

local result = app.integrations.mysql.query({
  sql = "SELECT * FROM users WHERE active = 1 LIMIT 10"
})

for _, row in ipairs(result.rows) do
  print(row.name .. " <" .. row.email .. ">")
end

Aggregation query

local result = app.integrations.mysql.query({
  sql = "SELECT country, COUNT(*) as total FROM users GROUP BY country ORDER BY total DESC LIMIT 5"
})

JOIN query

local result = app.integrations.mysql.query({
  sql = "SELECT o.id, u.name, o.total FROM orders o JOIN users u ON o.user_id = u.id WHERE o.status = 'pending'"
})

list_databases

List all databases accessible to the authenticated user.

Parameters

None.

Example

local result = app.integrations.mysql.list_databases({})

for _, db in ipairs(result.databases) do
  print(db)
end

list_tables

List all tables in a database.

Parameters

NameTypeRequiredDescription
databasestringyesThe database name

Example

local result = app.integrations.mysql.list_tables({
  database = "my_app"
})

for _, tbl in ipairs(result.tables) do
  print(tbl.name)
end

describe_table

Get the column structure of a table.

Parameters

NameTypeRequiredDescription
databasestringyesThe database name
tablestringyesThe table name

Example

local result = app.integrations.mysql.describe_table({
  database = "my_app",
  table = "users"
})

for _, col in ipairs(result.columns) do
  print(col.field .. " (" .. col.type .. ")" .. (col.null == "YES" and " NULL" or " NOT NULL"))
end

insert

Insert a row into a table.

Parameters

NameTypeRequiredDescription
databasestringyesThe database name
tablestringyesThe table name
dataobjectyesColumn-value pairs to insert

Example

local result = app.integrations.mysql.insert({
  database = "my_app",
  table = "users",
  data = {
    name = "Alice",
    email = "alice@example.com",
    active = true
  }
})

print("Inserted row ID: " .. result.insert_id)

update

Update rows matching a filter.

Parameters

NameTypeRequiredDescription
databasestringyesThe database name
tablestringyesThe table name
filterobjectyesColumn-value pairs to match rows
dataobjectyesColumn-value pairs to update

Example

local result = app.integrations.mysql.update({
  database = "my_app",
  table = "users",
  filter = { id = 42 },
  data = { name = "Bob", status = "active" }
})

print("Rows affected: " .. result.affected_rows)

delete

Delete rows matching a filter.

Parameters

NameTypeRequiredDescription
databasestringyesThe database name
tablestringyesThe table name
filterobjectyesColumn-value pairs to match rows

Example

local result = app.integrations.mysql.delete({
  database = "my_app",
  table = "sessions",
  filter = { expired = true }
})

print("Rows deleted: " .. result.affected_rows)

get_current_user

Get the currently authenticated database user. Useful for verifying credentials.

Parameters

None.

Example

local result = app.integrations.mysql.get_current_user({})

print("Connected as: " .. result.user)

Multi-Account Usage

If you have multiple MySQL connections configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.mysql.query({ sql = "SELECT 1" })

-- Explicit default (portable across setups)
app.integrations.mysql.default.query({ sql = "SELECT 1" })

-- Named accounts
app.integrations.mysql.production.query({ sql = "SELECT * FROM users LIMIT 5" })
app.integrations.mysql.staging.query({ sql = "SELECT * FROM users LIMIT 5" })

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# MySQL — Lua API Reference

## query

Execute a raw SQL query on the MySQL database.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `sql` | string | yes | The SQL query to execute |

### Examples

#### Simple SELECT query

```lua
local result = app.integrations.mysql.query({
  sql = "SELECT * FROM users WHERE active = 1 LIMIT 10"
})

for _, row in ipairs(result.rows) do
  print(row.name .. " <" .. row.email .. ">")
end
```

#### Aggregation query

```lua
local result = app.integrations.mysql.query({
  sql = "SELECT country, COUNT(*) as total FROM users GROUP BY country ORDER BY total DESC LIMIT 5"
})
```

#### JOIN query

```lua
local result = app.integrations.mysql.query({
  sql = "SELECT o.id, u.name, o.total FROM orders o JOIN users u ON o.user_id = u.id WHERE o.status = 'pending'"
})
```

---

## list_databases

List all databases accessible to the authenticated user.

### Parameters

None.

### Example

```lua
local result = app.integrations.mysql.list_databases({})

for _, db in ipairs(result.databases) do
  print(db)
end
```

---

## list_tables

List all tables in a database.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `database` | string | yes | The database name |

### Example

```lua
local result = app.integrations.mysql.list_tables({
  database = "my_app"
})

for _, tbl in ipairs(result.tables) do
  print(tbl.name)
end
```

---

## describe_table

Get the column structure of a table.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `database` | string | yes | The database name |
| `table` | string | yes | The table name |

### Example

```lua
local result = app.integrations.mysql.describe_table({
  database = "my_app",
  table = "users"
})

for _, col in ipairs(result.columns) do
  print(col.field .. " (" .. col.type .. ")" .. (col.null == "YES" and " NULL" or " NOT NULL"))
end
```

---

## insert

Insert a row into a table.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `database` | string | yes | The database name |
| `table` | string | yes | The table name |
| `data` | object | yes | Column-value pairs to insert |

### Example

```lua
local result = app.integrations.mysql.insert({
  database = "my_app",
  table = "users",
  data = {
    name = "Alice",
    email = "alice@example.com",
    active = true
  }
})

print("Inserted row ID: " .. result.insert_id)
```

---

## update

Update rows matching a filter.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `database` | string | yes | The database name |
| `table` | string | yes | The table name |
| `filter` | object | yes | Column-value pairs to match rows |
| `data` | object | yes | Column-value pairs to update |

### Example

```lua
local result = app.integrations.mysql.update({
  database = "my_app",
  table = "users",
  filter = { id = 42 },
  data = { name = "Bob", status = "active" }
})

print("Rows affected: " .. result.affected_rows)
```

---

## delete

Delete rows matching a filter.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `database` | string | yes | The database name |
| `table` | string | yes | The table name |
| `filter` | object | yes | Column-value pairs to match rows |

### Example

```lua
local result = app.integrations.mysql.delete({
  database = "my_app",
  table = "sessions",
  filter = { expired = true }
})

print("Rows deleted: " .. result.affected_rows)
```

---

## get_current_user

Get the currently authenticated database user. Useful for verifying credentials.

### Parameters

None.

### Example

```lua
local result = app.integrations.mysql.get_current_user({})

print("Connected as: " .. result.user)
```

---

## Multi-Account Usage

If you have multiple MySQL connections configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.mysql.query({ sql = "SELECT 1" })

-- Explicit default (portable across setups)
app.integrations.mysql.default.query({ sql = "SELECT 1" })

-- Named accounts
app.integrations.mysql.production.query({ sql = "SELECT * FROM users LIMIT 5" })
app.integrations.mysql.staging.query({ sql = "SELECT * FROM users LIMIT 5" })
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.mysql.query({sql = "example_sql"})
print(result)

Functions

query Read

Execute a raw SQL query on the MySQL database. Supports SELECT, INSERT, UPDATE, DELETE, and other SQL statements. Use for custom queries, joins, aggregations, and complex data retrieval.

Lua path
app.integrations.mysql.query
Full name
mysql.mysql_query
ParameterTypeRequiredDescription
sql string yes The SQL query to execute (e.g., "SELECT * FROM users WHERE active = 1 LIMIT 10").
list_databases Read

List all databases accessible to the authenticated MySQL user. Use this to discover which databases are available before querying or exploring tables.

Lua path
app.integrations.mysql.list_databases
Full name
mysql.mysql_list_databases
ParameterTypeRequiredDescription
No parameters.
list_tables Read

List all tables in a MySQL database. Use this to discover which tables exist before querying or describing their structure.

Lua path
app.integrations.mysql.list_tables
Full name
mysql.mysql_list_tables
ParameterTypeRequiredDescription
database string yes The database name (e.g., "my_app").
describe_table Read

Get the column structure of a MySQL table. Returns column names, types, nullable status, keys, defaults, and extra info. Use this before inserting or updating data to understand the schema.

Lua path
app.integrations.mysql.describe_table
Full name
mysql.mysql_describe_table
ParameterTypeRequiredDescription
database string yes The database name (e.g., "my_app").
table string yes The table name (e.g., "users").
insert_row Write

Insert a new row into a MySQL table. Provide column names and values as key-value pairs. Use mysql_describe_table first to understand the schema if needed.

Lua path
app.integrations.mysql.insert_row
Full name
mysql.mysql_insert
ParameterTypeRequiredDescription
database string yes The database name (e.g., "my_app").
table string yes The table name (e.g., "users").
data object yes Column-value pairs to insert (e.g., {"name": "Alice", "email": "alice@example.com"}).
update_rows Write

Update rows in a MySQL table that match a filter. Provide a filter to identify which rows to update and a data object with the new column values. Use mysql_describe_table first to understand the schema if needed.

Lua path
app.integrations.mysql.update_rows
Full name
mysql.mysql_update
ParameterTypeRequiredDescription
database string yes The database name (e.g., "my_app").
table string yes The table name (e.g., "users").
filter object yes Column-value pairs to match rows for update (e.g., {"id": 42}).
data object yes Column-value pairs to update (e.g., {"name": "Bob", "status": "active"}).
delete_rows Write

Delete rows from a MySQL table that match a filter. Provide a filter with column-value pairs to identify which rows to delete. This action is irreversible — use with caution.

Lua path
app.integrations.mysql.delete_rows
Full name
mysql.mysql_delete
ParameterTypeRequiredDescription
database string yes The database name (e.g., "my_app").
table string yes The table name (e.g., "users").
filter object yes Column-value pairs to match rows for deletion (e.g., {"id": 42}).
current_user Read

Get information about the currently authenticated MySQL user. Useful for verifying credentials and connection status.

Lua path
app.integrations.mysql.current_user
Full name
mysql.mysql_get_current_user
ParameterTypeRequiredDescription
No parameters.