Install

Docs / Your first project

Your first project

A project is one application’s databases: it owns a storage identity, a PostgreSQL major version and a storage mode, all fixed at creation. A project has branches: main, plus copies you create for development, previews, tests or restores. Each branch is a full PostgreSQL 18 server that suspends when idle and wakes when a client connects. Inside a branch you create ordinary databases and roles.

You can work from the console or directly against the platform API.

With the console

  1. Sign in and choose your organization.
  2. Projects → New project. Give it a name, choose the region and PostgreSQL 18. Storage defaults to Object storage; choose Dedicated disk only if you want each branch on its own disk with full copies (see install.md). Optionally pick a compute size.
  3. The project is created with branch main and a database app owned by its own role. Creation runs in the background; the project page shows progress.
  4. Connect on the project overview shows the connection string for a database. Copying it reveals its password, which is recorded in the activity log. See connect.md.
  5. Branches → New branch creates a branch from main (or any branch) as of now. In object storage mode the branch shares unchanged data with its parent and is ready in seconds; with dedicated disks the parent is copied.
  6. Restore creates a new branch from any point in a branch’s history, or from a deleted branch during its retention period. Nothing is overwritten: you connect your application to the restored branch when you are ready. See backup-and-restore.md.
  7. Database access creates additional roles, Network access limits the source addresses that may connect, Compute sets size, idle suspension and autoscaling, and Settings deletes the project.

Members need a project grant (reader or developer) from an organization administrator under Team & access. Readers can browse schemas and run read-only SQL but cannot reveal credentials or change data.

With the CLI

Create an API key under API keys (one project, read-write or read-only, expiring after 30, 90 or 365 days or never), then download the skela binary from the release (verify.md shows how to check it):

export SKELA_CLOUD_API_URL=https://api.example.com
export SKELA_ORGANIZATION_ID=org_...
export SKELA_PROJECT_ID=<project id>
read -r -s SKELA_API_KEY; export SKELA_API_KEY
skela branch list
skela branch create --name preview --parent <main branch id> --idempotency-key preview-001
skela operation get <operation id> --wait-seconds 60

CLI & agents in the console shows the same settings for your installation, and how to run the skela-mcp server for AI agents.

Without the console

The platform API is served by the skela-control Service on port 8080 over TLS. The admin token is the token key of the skela-api Secret and reaches every project; for automation, prefer a per-project token (console.md shows how to add one). Create the project’s identity first (install.md).

kubectl -n skela port-forward svc/skela-control 8080 &
TOKEN=$(kubectl -n skela get secret skela-api -o jsonpath='{.data.token}' | base64 -d)
CA=ca.crt   # your issuer's CA certificate
curl -fsS --cacert $CA --resolve skela-control.skela.svc:8080:127.0.0.1 \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"acme-main","project":"acme"}' https://skela-control.skela.svc:8080/v1/branches
curl -fsS --cacert $CA --resolve skela-control.skela.svc:8080:127.0.0.1 \
  -H "Authorization: Bearer $TOKEN" https://skela-control.skela.svc:8080/v1/branches/acme-main/connection

Branch names are lowercase DNS labels of at most 48 characters and unique in the installation. The create request accepts parent (a branch of the same project to copy), cpu, memory, storage, suspendAfterSeconds (default 300, 0 never suspends), storageMode (separated or pvc; omitted, a child follows its parent and a new root uses object storage when installed) and restore ({"from": "<branch>", "at": "2026-10-01T12:00:00Z"}). The connection answer carries the branch’s application role skela_app, which is not a superuser. The response’s phase moves from Pending to Starting to Running; kubectl -n skela get branches shows the same.

Sizes and limits

  • Compute: 1 millicore to 64 cores and 128 MiB to 256 GiB per branch; the console offers preset sizes. Autoscaling moves one step at a time between the bounds you set.
  • Disk (dedicated disk mode): 1 GiB to 16 TiB; it can grow but never shrink.
  • Per project by default: 128 branches, 64 cores, 128 GiB of memory and 1 TiB of disk reserved. Suspended branches keep their reservation. The console allows 32 branches per project and 32 databases per branch.
  • Your license key sets the total number of branches and projects.
  • Each branch may have up to three read replicas.