LIGHTCLOUD
DOCS
Documentation menu

Database endpoints - provision, retrieve, resize, get a connection string, rotate the password, dump, and inspect data.

Databases

Managed PostgreSQL and MySQL. A database is created, then provisioned; shared tiers are ready in seconds, dedicated ones take 10-20 minutes.

With an API key the organisation is inferred. Session tokens must add targetOrganisationId to every body.

List databases#

POST/api/databases

Databases in the organisation, newest first, paginated.

permission
read:projects

Parameters

pagenumberdefault 1
1-based page number
limitnumberdefault 10
Between 1 and 100
filterstringoptional
Free text, matched against the name
sortColumnstringdefault created_at
Field to order by
sortOrderstringdefault desc
asc or desc
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/databases \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'
200ResponsePaginated envelope
{
  "items": [
    {
      "id": "db_2Vx",
      "name": "shop-orders",
      "database_type": "postgresql",
      "tier": "db-f1-micro",
      "region": "europe-west1",
      "storage_gb": 5,
      "ha_enabled": false,
      "status": "healthy",
      "created_at": "2026-08-20T10:00:00.000Z"
    }
  ],
  "totalItems": 1,
  "totalPages": 1,
  "currentPage": 1
}

Retrieve a database#

POST/api/databases/get

One database and its configuration. Never includes credentials — use the connection string endpoint for those.

permission
read:projects

Parameters

databaseIdstringrequired
The database to read
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/databases/get \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"databaseId": "db_2Vx"}'
200ResponseA database
{
  "id": "db_2Vx",
  "name": "shop-orders",
  "database_type": "postgresql",
  "tier": "db-f1-micro",
  "region": "europe-west1",
  "storage_gb": 5,
  "ha_enabled": false,
  "public_ip_enabled": true,
  "status": "healthy",
  "created_at": "2026-08-20T10:00:00.000Z"
}

Retrieve status#

POST/api/databases/status

Poll this while a dedicated instance provisions — it can take 10-20 minutes.

permission
read:projects

Parameters

databaseIdstringrequired
The database to poll
targetOrganisationIdstringsession only
Required when using a session token
until [ "$(curl -sS -X POST https://api.light-cloud.com/api/databases/status \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"databaseId\":\"$DB_ID\"}" | jq -r .status)" = "healthy" ]; do
  sleep 15
done
200ResponseCurrent status
{ "id": "db_2Vx", "status": "provisioning" }

Create a database#

POST/api/databases/create

Records the database and begins provisioning. Shared tiers are ready in seconds, dedicated ones take 10-20 minutes.

permission
create:projects

Parameters

namestringrequired
Display name
databaseTypestringdefault platform default
postgresql or mysql
tierstringdefault platform default
Cloud SQL machine type: db-f1-micro or db-g1-small (shared-core, dev/test, no SLA), or db-custom-<vCPU>-<memoryMB> (dedicated)
regionstringdefault platform default
See Limits
storageGbnumberdefault platform default
Grows without downtime, never shrinks
haEnabledbooleandefault false
High availability. Doubles the compute price
publicIpEnabledbooleandefault true
Whether the instance gets a public address
authorizedNetworksstring[]optional
CIDR list. An empty list means world-reachable
databaseNamestringdefault generated
Initial database name
adminUserstringdefault generated
Admin username
adminPasswordstringdefault generated
12+ characters, no spaces, quotes or backslashes
projectIdstringoptional
Folder to file it under
curl -X POST https://api.light-cloud.com/api/databases/create \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "shop-orders",
    "databaseType": "postgresql",
    "tier": "db-f1-micro",
    "storageGb": 5,
    "authorizedNetworks": ["203.0.113.10/32"]
  }'
201ResponseThe created database
{
  "id": "db_2Vx",
  "name": "shop-orders",
  "database_type": "postgresql",
  "tier": "db-f1-micro",
  "status": "provisioning"
}

Warning

publicIpEnabled defaults to true because that is what actually gets provisioned today. Restrict reachability with authorizedNetworks, and treat an unset list as world-reachable.

Get a connection string#

POST/api/databases/connection-string

Returns the full connection URL, credentials included.

permission
read:projects

Parameters

databaseIdstringrequired
The database to connect to
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/databases/connection-string \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"databaseId": "db_2Vx"}'
200ResponseConnection URL
{
  "connectionString": "postgresql://app:s3cr3t@34.0.0.1:5432/shop?sslmode=require"
}

Important

This response contains the password in clear text. Do not log it, and do not write it to a file your CI archives. See Connecting.

Update a database#

POST/api/databases/update

Changes size or configuration. Storage grows without downtime and never shrinks; changing tier restarts the instance.

permission
update:projects

Parameters

databaseIdstringrequired
The database to update
namestringoptional
Display name
tierstringoptional
Restarts the instance
regionstringoptional
See Limits
storageGbnumberoptional
Can only increase
haEnabledbooleanoptional
Doubles the compute price
curl -X POST https://api.light-cloud.com/api/databases/update \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"databaseId": "db_2Vx", "tier": "db-custom-1-3840", "storageGb": 20}'
200ResponseThe updated database
{ "id": "db_2Vx", "tier": "db-custom-1-3840", "storage_gb": 20 }

Rotate the password#

POST/api/databases/rotate-password

Issues new credentials. Applications holding the old ones break immediately.

permission
update:projects

Parameters

databaseIdstringrequired
The database to rotate
newPasswordstringdefault generated
12+ characters, no spaces, quotes or backslashes
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/databases/rotate-password \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"databaseId": "db_2Vx"}'
200ResponseThe new connection details
{
  "connectionString": "postgresql://app:n3wp4ss@34.0.0.1:5432/shop?sslmode=require"
}

Warning

Update the variables of anything using this database and redeploy, or it stays broken.

Read metrics#

POST/api/databases/metrics

CPU, memory, storage and connection counts over a window.

permission
read:projects

Parameters

databaseIdstringrequired
The database to measure
timeRangestringdefault 1h
1h, 6h, 24h or 7d
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/databases/metrics \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"databaseId": "db_2Vx", "timeRange": "24h"}'
200ResponseSeries per metric
{
  "databaseId": "db_2Vx",
  "metrics": {
    "cpu": [{ "t": "2026-08-28T08:00:00.000Z", "v": 0.12 }],
    "connections": [{ "t": "2026-08-28T08:00:00.000Z", "v": 7 }]
  }
}

Delete a database#

POST/api/databases/delete

Removes the instance and its data. Not reversible.

permission
delete:projects

Parameters

databaseIdstringrequired
The database to delete
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/databases/delete \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"databaseId": "db_2Vx"}'
200ResponseDeletion accepted
{ "message": "Database deleted" }

Other endpoints#

EndpointBodyDescription
POST /api/databases/provisiondatabaseIdStarts provisioning for a database created but not yet built
POST /api/databases/dumpdatabaseIdProduces a pg_dump or mysqldump file to download
POST /api/databases/importdatabaseIdThe other direction
POST /api/databases/movedatabaseId, targetFolderIdFiles it under a different folder
GET /api/databases/:targetOrganisationId/:databaseId/streamServer-sent events for provisioning progress

Data explorer#

Reading and editing rows directly, the same surface the console's Data tab uses. Each takes databaseId.

EndpointDescription
POST /api/databases/explorer/schemaTables and columns
POST /api/databases/explorer/rowsPaged rows of one table
POST /api/databases/explorer/queryRun a statement
POST /api/databases/explorer/rowInsert, update, or delete one row
POST /api/databases/explorer/tableTable-level operations

Note

The explorer and dump endpoints sit behind feature flags. If they answer with a "not enabled" message on your account, check GET /api/config/feature-flags.

Related#

DatabasesEngines, tiers, and how provisioning works.ConnectingConnection strings and clients.LimitsTiers, storage, and password rules.