KosmoKrator

data

PlanetScale Lua API for KosmoKrator Agents

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

7 functions 6 read 1 write Bearer token auth
Submit PlanetScale feedback View package source

Lua Namespace

Agents call this integration through app.integrations.planetscale.*. Use lua_read_doc("integrations.planetscale") 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.

PlanetScale — Lua API Reference

list_databases

List databases in a PlanetScale organization.

Parameters

NameTypeRequiredDescription
organizationstringyesThe organization name
pageintegernoPage number (1-based, default: 1)
limitintegernoResults per page (default: 20, max: 100)

Example

local result = app.integrations.planetscale.list_databases({
  organization = "my-org",
  page = 1,
  limit = 10
})

for _, db in ipairs(result.data) do
  print(db.name .. ": " .. db.state)
end

get_database

Get details of a specific PlanetScale database.

Parameters

NameTypeRequiredDescription
organizationstringyesThe organization name
databasestringyesThe database name

Example

local result = app.integrations.planetscale.get_database({
  organization = "my-org",
  database = "my-database"
})

print("State: " .. result.state)
print("Region: " .. result.region.slug)
print("Branches: " .. result.branches)

create_database

Create a new database in a PlanetScale organization.

Parameters

NameTypeRequiredDescription
organizationstringyesThe organization name
namestringyesThe database name (lowercase, hyphens allowed)
regionstringnoThe region slug (e.g., “us-east-1”)
notesstringnoOptional notes about the database

Example

local result = app.integrations.planetscale.create_database({
  organization = "my-org",
  name = "my-new-database",
  region = "us-east-1",
  notes = "Production database for project X"
})

print("Created: " .. result.name)
print("State: " .. result.state)

list_branches

List branches of a PlanetScale database.

Parameters

NameTypeRequiredDescription
organizationstringyesThe organization name
databasestringyesThe database name
pageintegernoPage number (1-based, default: 1)
limitintegernoResults per page (default: 20, max: 100)

Example

local result = app.integrations.planetscale.list_branches({
  organization = "my-org",
  database = "my-database"
})

for _, branch in ipairs(result.data) do
  print(branch.name .. " (" .. branch.role .. ")")
end

get_branch

Get details of a specific branch of a PlanetScale database.

Parameters

NameTypeRequiredDescription
organizationstringyesThe organization name
databasestringyesThe database name
branchstringyesThe branch name

Example

local result = app.integrations.planetscale.get_branch({
  organization = "my-org",
  database = "my-database",
  branch = "main"
})

print("Role: " .. result.role)
print("Ready: " .. tostring(result.ready))
print("Region: " .. result.region.slug)

list_organizations

List organizations the authenticated user belongs to.

Parameters

None.

Example

local result = app.integrations.planetscale.list_organizations({})

for _, org in ipairs(result.data) do
  print(org.name .. " (" .. org.slug .. ")")
end

get_current_user

Get the profile of the currently authenticated user.

Parameters

None.

Example

local result = app.integrations.planetscale.get_current_user({})
print("User: " .. (result.first_name or "") .. " " .. (result.last_name or ""))
print("Email: " .. result.email)

Multi-Account Usage

If you have multiple PlanetScale accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.planetscale.function_name({...})

-- Explicit default (portable across setups)
app.integrations.planetscale.default.function_name({...})

-- Named accounts
app.integrations.planetscale.production.function_name({...})
app.integrations.planetscale.staging.function_name({...})

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

Raw agent markdown 
# PlanetScale — Lua API Reference

## list_databases

List databases in a PlanetScale organization.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `organization` | string | yes | The organization name |
| `page` | integer | no | Page number (1-based, default: 1) |
| `limit` | integer | no | Results per page (default: 20, max: 100) |

### Example

```lua
local result = app.integrations.planetscale.list_databases({
  organization = "my-org",
  page = 1,
  limit = 10
})

for _, db in ipairs(result.data) do
  print(db.name .. ": " .. db.state)
end
```

---

## get_database

Get details of a specific PlanetScale database.

### Parameters

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

### Example

```lua
local result = app.integrations.planetscale.get_database({
  organization = "my-org",
  database = "my-database"
})

print("State: " .. result.state)
print("Region: " .. result.region.slug)
print("Branches: " .. result.branches)
```

---

## create_database

Create a new database in a PlanetScale organization.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `organization` | string | yes | The organization name |
| `name` | string | yes | The database name (lowercase, hyphens allowed) |
| `region` | string | no | The region slug (e.g., "us-east-1") |
| `notes` | string | no | Optional notes about the database |

### Example

```lua
local result = app.integrations.planetscale.create_database({
  organization = "my-org",
  name = "my-new-database",
  region = "us-east-1",
  notes = "Production database for project X"
})

print("Created: " .. result.name)
print("State: " .. result.state)
```

---

## list_branches

List branches of a PlanetScale database.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `organization` | string | yes | The organization name |
| `database` | string | yes | The database name |
| `page` | integer | no | Page number (1-based, default: 1) |
| `limit` | integer | no | Results per page (default: 20, max: 100) |

### Example

```lua
local result = app.integrations.planetscale.list_branches({
  organization = "my-org",
  database = "my-database"
})

for _, branch in ipairs(result.data) do
  print(branch.name .. " (" .. branch.role .. ")")
end
```

---

## get_branch

Get details of a specific branch of a PlanetScale database.

### Parameters

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

### Example

```lua
local result = app.integrations.planetscale.get_branch({
  organization = "my-org",
  database = "my-database",
  branch = "main"
})

print("Role: " .. result.role)
print("Ready: " .. tostring(result.ready))
print("Region: " .. result.region.slug)
```

---

## list_organizations

List organizations the authenticated user belongs to.

### Parameters

None.

### Example

```lua
local result = app.integrations.planetscale.list_organizations({})

for _, org in ipairs(result.data) do
  print(org.name .. " (" .. org.slug .. ")")
end
```

---

## get_current_user

Get the profile of the currently authenticated user.

### Parameters

None.

### Example

```lua
local result = app.integrations.planetscale.get_current_user({})
print("User: " .. (result.first_name or "") .. " " .. (result.last_name or ""))
print("Email: " .. result.email)
```

---

## Multi-Account Usage

If you have multiple PlanetScale accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.planetscale.function_name({...})

-- Explicit default (portable across setups)
app.integrations.planetscale.default.function_name({...})

-- Named accounts
app.integrations.planetscale.production.function_name({...})
app.integrations.planetscale.staging.function_name({...})
```

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

Metadata-Derived Lua Example

local result = app.integrations.planetscale.planetscale_list_databases({
  organization = "example_organization",
  page = 1,
  limit = 1
})
print(result)

Functions

planetscale_list_databases

List databases in a PlanetScale organization. Returns a paginated list of databases with their names, regions, and states.

Operation
Read read
Full name
planetscale.planetscale_list_databases
ParameterTypeRequiredDescription
organization string yes The organization name.
page integer no Page number (1-based, default: 1).
limit integer no Results per page (default: 20, max: 100).

planetscale_get_database

Get details of a specific PlanetScale database, including its state, region, and branch count.

Operation
Read read
Full name
planetscale.planetscale_get_database
ParameterTypeRequiredDescription
organization string yes The organization name.
database string yes The database name.

planetscale_create_database

Create a new database in a PlanetScale organization. Specify the database name and optionally a region and notes.

Operation
Write write
Full name
planetscale.planetscale_create_database
ParameterTypeRequiredDescription
organization string yes The organization name.
name string yes The database name (lowercase, hyphens allowed).
region string no The region slug (e.g., "us-east-1"). Defaults to the organization region.
notes string no Optional notes about the database.

planetscale_list_branches

List branches of a PlanetScale database. Returns a paginated list of branches with their names, roles, and states.

Operation
Read read
Full name
planetscale.planetscale_list_branches
ParameterTypeRequiredDescription
organization string yes The organization name.
database string yes The database name.
page integer no Page number (1-based, default: 1).
limit integer no Results per page (default: 20, max: 100).

planetscale_get_branch

Get details of a specific branch of a PlanetScale database, including its role, region, and readiness.

Operation
Read read
Full name
planetscale.planetscale_get_branch
ParameterTypeRequiredDescription
organization string yes The organization name.
database string yes The database name.
branch string yes The branch name.

planetscale_list_organizations

List organizations the authenticated user belongs to. Useful for discovering organization names needed by other PlanetScale tools.

Operation
Read read
Full name
planetscale.planetscale_list_organizations
ParameterTypeRequiredDescription
No parameters.

planetscale_get_current_user

Get the profile of the currently authenticated PlanetScale user. Useful for verifying API credentials and retrieving account information.

Operation
Read read
Full name
planetscale.planetscale_get_current_user
ParameterTypeRequiredDescription
No parameters.