A BWEZE backend is a Postgres database with the services an app usually builds around it, running in its own isolated space and reached at one URL:
| Part | What you get |
|---|---|
| Database | Postgres 15 with pgvector, pg_cron, pgcrypto and http; a REST API over your tables with PostgREST filters, and Postgres functions as RPC |
| Auth | Email and password sign-up and sign-in, Google and GitHub sign-in, sessions with refresh tokens |
| Storage | Buckets, public or private, for files your app stores |
| Edge functions | TypeScript functions on Deno, each at its own path, 60 seconds per call |
| Realtime | Channels over Socket.IO, and webhooks when a message is published |
| Schedules | Calls to a URL on a cron schedule, run by pg_cron |
This guide covers the database: creating a backend, its keys, and reading and writing it from your app and from the CLI.
Create a backend
In BWEZE Platform, open Backends and click Create backend, or create one from a project’s page. With the API:
curl -X POST https://api.bweze.com/v1/backends \
-H "authorization: Bearer bw_sk_..." -H "content-type: application/json" \
-d '{ "name": "acme-db" }'
The name is 2 to 31 lowercase letters, digits and hyphens, unique in the workspace. The backend starts at once and answers at https://<name>-<id>.bweze.app. GET /v1/backends/{id} reports its status: starting, running:healthy, degraded, exited:unhealthy or exited. POST /v1/backends/{id}/deploy starts or restarts it.
A workspace on Free can have one backend, on Hobby two, on Pro ten. One more than the plan allows is refused with 403 plan_limit.
Get its keys
curl https://api.bweze.com/v1/backends/BACKEND_ID/keys \
-H "authorization: Bearer bw_sk_..."
{
"url": "https://acme-db-1a2b3c4d.bweze.app",
"anonKey": "anon_…",
"serviceRoleKey": "ik_…",
"postgresPassword": "…"
}
anonKey(anon_…) is safe in browser and mobile code. Requests made with it act as an anonymous user, limited by your row-level security policies.serviceRoleKey(ik_…) bypasses those policies. Keep it on your servers, never in client code.
Every key and password is generated for this backend alone. Reading them needs an API token with backend:create. bweze secrets rotate api-key or bweze secrets rotate anon-key replaces a key, with a grace period for the old one.
No direct database connections
Postgres is not reachable from outside the backend. Apps and tools talk to it through the backend’s URL, not over the Postgres protocol, so a Postgres driver or an ORM that opens a database connection cannot reach it. Use the REST API, bweze db query, or bweze db export and import.
Use it from your app
Put the backend’s URL and anon key on your app’s service as environment variables, such as BWEZE_URL and BWEZE_ANON_KEY; Deploy an app from GitHub shows where. The app reaches the backend through its public URL, like any other client.
There is no client SDK to install. It is plain HTTP with a bearer token: the anon key until a user signs in, and their access token after.
const BWEZE_URL = process.env.BWEZE_URL!; // https://acme-db-1a2b3c4d.bweze.app
let token = process.env.BWEZE_ANON_KEY!;
const api = (path: string, init: RequestInit = {}) =>
fetch(`${BWEZE_URL}${path}`, {
...init,
headers: {
authorization: `Bearer ${token}`,
'content-type': 'application/json',
...init.headers,
},
}).then((r) => r.json());
// Sign up, then sign in
await api('/api/auth/users', { method: 'POST', body: JSON.stringify({ email, password }) });
const session = await api('/api/auth/sessions', {
method: 'POST',
body: JSON.stringify({ email, password }),
});
token = session.accessToken;
// Query a table with PostgREST filters
const posts = await api(
'/api/database/records/posts?status=eq.published&order=createdAt.desc&limit=10'
);
// Insert rows (the body is always an array)
await api('/api/database/records/posts', {
method: 'POST',
headers: { Prefer: 'return=representation' },
body: JSON.stringify([{ title: 'Hello', content: 'World' }]),
});
// Call a Postgres function
await api('/api/database/rpc/get_user_stats', {
method: 'POST',
body: JSON.stringify({ user_id: '…' }),
});
Errors come back as { error, message, statusCode, nextActions }. The backend also documents itself: GET <url>/api/docs/instructions is the starting point, and /api/docs/db/rest-api covers the database API.
From the CLI
Link the directory to the backend’s project, then:
bweze link --project-id <id>
bweze db tables
bweze db query "select id, email from users limit 10"
bweze db migrations new add_orders && bweze db migrations up
bweze logs postgres.logs
The db group also has functions, indexes, policies, triggers, rpc <fn>, export, import <file> and migrations list.
If an agent or a script runs these commands, set BWEZE_GUARD=1, or run bweze link --guard for one project. Destructive operations then stop until a person approves them: dropping or truncating tables, DELETE or UPDATE without a WHERE, changing row-level security, rotating a key.
Limits and billing
| Database disk | 10 GiB |
| Storage disk | 10 GiB |
| Logs | 2 GiB |
| Memory | 1,664 MiB reserved across the four services (Postgres 768 MiB at most) |
| Replicas | One of each service: no failover |
| Edge function call | 60 seconds |
Disk sizes cannot be changed from the dashboard yet.
A backend is billed for memory at 20 RWF per GiB-hour, for the CPU time it uses at 30 RWF per CPU-hour, and for storage at 150 RWF per GiB-month. Storage is charged as provisioned, whether the backend is busy, idle or stopped. The free monthly allowance covers app usage only, not backends. What it costs to run a production app prices a stack with a backend in it.
Backups and deletion
BWEZE runs in one data center during the beta, and the nightly backup job is not running yet. bweze backups prints “not available on BWEZE”. Export anything you cannot lose:
bweze db export --format sql -o backup.sql
Deleting a backend takes it off the internet at once. Its data is purged only after a backup newer than the deletion exists.
curl -X DELETE https://api.bweze.com/v1/backends/BACKEND_ID \
-H "authorization: Bearer bw_sk_..." -H "content-type: application/json" \
-d '{ "confirm": "acme-db" }'
confirm must be the backend’s name (400 confirmation_required otherwise), and the token needs backend:delete.
What is not available yet
- Nightly backups. Export your own with
bweze db export. - Connections over the Postgres protocol. Everything goes through the backend’s URL.
- Failover. Each service in a backend runs as one replica.
- Changing disk sizes from the dashboard.
The full reference
Backends in the docs covers every part of a backend, including auth, storage, edge functions and realtime, and the CLI docs list every backend command.