Managed Database API

This API allows managing your tenant's dedicated SQLite database. Each tenant has exactly one managed database that can be provisioned, accessed via tokens, suspended, and activated.

The TenantDatabase Object

The TenantDatabase object represents your managed database.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "hostname": "your-tenant-abc123.turso.io",
  "status": "active",
  "statusMessage": null,
  "connectionUrl": "libsql://your-tenant-abc123.turso.io",
  "tokenExpiresAt": "2024-01-15T12:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}

Attributes

Attribute	Description	Type
id	Unique identifier of the database	String
hostname	Database hostname for connections	String
status	Current status of the database	String
statusMessage	Additional status information	String (nullable)
connectionUrl	Full libsql:// connection URL	String
tokenExpiresAt	When the last generated token expires	String (ISO 8601)
createdAt	Database creation timestamp	String (ISO 8601)
updatedAt	Last update timestamp	String (ISO 8601)

Status Values

Status	Description
active	Database is operational and accepting connections
pending	Database is being provisioned
suspended	Database is temporarily disabled
error	Database encountered an error during provisioning

Available Operations

Create Database

Creates and provisions a new managed database for your tenant. Each tenant can only have one database.

POST /v1/tenant-databases

Request Headers

Header	Description	Required
Authorization	Bearer token for authentication	Yes

Successful Response (201 Created)

Returns the database details with an initial access token.

{
  "database": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "hostname": "your-tenant-abc123.turso.io",
    "status": "active",
    "statusMessage": null,
    "connectionUrl": "libsql://your-tenant-abc123.turso.io",
    "tokenExpiresAt": "2024-01-15T12:00:00Z",
    "createdAt": "2024-01-15T11:00:00Z",
    "updatedAt": "2024-01-15T11:00:00Z"
  },
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
}

Response (200 OK)

If a database already exists for the tenant, returns the existing database without a token.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "hostname": "your-tenant-abc123.turso.io",
  "status": "active",
  ...
}

Get Database

Retrieves information about your tenant's managed database.

GET /v1/tenant-databases

Request Headers

Header	Description	Required
Authorization	Bearer token for authentication	Yes

Successful Response (200 OK)

Returns the TenantDatabase object.

Error Response (404 Not Found)

{
  "code": "NotFoundError",
  "message": "No database found for this tenant. Create one first."
}

Generate Access Token

Generates a new short-lived access token for connecting to your database.

POST /v1/tenant-databases/tokens

Request Headers

Header	Description	Required
Authorization	Bearer token for authentication	Yes

Input Parameters

Parameter	Description	Type	Required	Default
expiration	Token lifetime (e.g., `30m`, `1h`, `12h`, `24h`)	String	No	`1h`
authorization	Access level: `full-access` or `read-only`	String	No	`full-access`

Request Example

{
  "expiration": "1h",
  "authorization": "full-access"
}

Successful Response (201 Created)

{
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2024-01-15T12:00:00Z"
}

Validation Rules

expiration: Must be in format like 30m, 1h, 24h. Maximum is 24 hours. Non-expiring tokens are not allowed.
authorization: Must be either full-access or read-only.

Suspend Database

Temporarily suspends the database, preventing all access.

POST /v1/tenant-databases/suspend

Request Headers

Header	Description	Required
Authorization	Bearer token for authentication	Yes

Input Parameters

Parameter	Description	Type	Required
reason	Reason for suspension	String	No

Request Example

{
  "reason": "Scheduled maintenance"
}

Successful Response (200 OK)

Returns the updated TenantDatabase object with status: "suspended".

Error Response (400 Bad Request)

Returned if the database is not in active state.

{
  "code": "BadRequestError",
  "message": "Cannot suspend database in 'pending' state. Only active databases can be suspended."
}

Activate Database

Reactivates a suspended or error-state database.

POST /v1/tenant-databases/activate

Request Headers

Header	Description	Required
Authorization	Bearer token for authentication	Yes

Successful Response (200 OK)

Returns the updated TenantDatabase object with status: "active".

Error Response (400 Bad Request)

Returned if the database is not in suspended or error state.

{
  "code": "BadRequestError",
  "message": "Cannot activate database in 'active' state. Only suspended or error databases can be activated."
}

Connecting to Your Database

Once you have a token, use the connectionUrl to connect:

HTTP API (Turso Pipeline API)

curl -X POST "https://YOUR_HOSTNAME/v2/pipeline" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {"type": "execute", "stmt": {"sql": "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"}},
      {"type": "execute", "stmt": {"sql": "INSERT INTO users (name) VALUES (?)", "args": [{"type": "text", "value": "John"}]}},
      {"type": "execute", "stmt": {"sql": "SELECT * FROM users"}},
      {"type": "close"}
    ]
  }'

libSQL Client (TypeScript)

import { createClient } from '@libsql/client'
 
const client = createClient({
  url: connectionUrl, // e.g., "libsql://your-tenant.turso.io"
  authToken: token
})
 
await client.execute('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)')
await client.execute({ sql: 'INSERT INTO users (name) VALUES (?)', args: ['John'] })
const result = await client.execute('SELECT * FROM users')

Error Handling

The API may return the following error codes:

Code	Description
400	Bad Request - Invalid parameters or invalid state transition
401	Unauthorized - Missing or invalid authentication
403	Forbidden - Insufficient permissions
404	Not Found - No database exists for tenant
409	Conflict - Database already exists or limit exceeded
503	Service Unavailable - Turso API temporarily unavailable

Error SubCodes

Some errors include an errorSubCode in the details for more specific handling:

SubCode	Description
TENANT_DATABASE_LIMIT_EXCEEDED	Tenant already has a database (one per tenant)
DATABASE_ALREADY_EXISTS_IN_TURSO	Database already exists in Turso

On this page