KosmoKrator

other

Mysql Lua API for KosmoKrator Agents

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

8 functions 5 read 3 write API key auth
Submit Mysql feedback View package source

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.

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 = "[email protected]",
    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 = "[email protected]",
    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.mysql_query({
  sql = "example_sql"
})
print(result)

Functions

mysql_query

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.

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

mysql_list_databases

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

Operation
Read read
Full name
mysql.mysql_list_databases
ParameterTypeRequiredDescription
No parameters.

mysql_list_tables

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

Operation
Read read
Full name
mysql.mysql_list_tables
ParameterTypeRequiredDescription
database string yes The database name (e.g., "my_app").

mysql_describe_table

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.

Operation
Read read
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").

mysql_insert

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.

Operation
Write write
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": "[email protected]"}).

mysql_update

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.

Operation
Write write
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"}).

mysql_delete

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.

Operation
Write write
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}).

mysql_get_current_user

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

Operation
Read read
Full name
mysql.mysql_get_current_user
ParameterTypeRequiredDescription
No parameters.