# Give your app a Postgres backend

> Create a BWEZE backend, read its keys, query Postgres over HTTP from your app and from the CLI, and keep your own backups while nightly ones are not running.

Source: https://bweze.com/guides/postgres-backend/ · Updated 2026-11-19

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:

```bash
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

```bash
curl https://api.bweze.com/v1/backends/BACKEND_ID/keys \
  -H "authorization: Bearer bw_sk_..."
```

```json
{
  "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](/guides/deploy-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.

```ts
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:

```bash
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](/resources/what-a-production-app-costs/) 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:

```bash
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.

```bash
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](https://docs.bweze.com/docs/backends) in the docs covers every part of a backend, including auth, storage, edge functions and realtime, and the [CLI docs](https://docs.bweze.com/docs/cli#backends) list every backend command.

## Sources

- [BWEZE docs: Backends](https://docs.bweze.com/docs/backends)
- [BWEZE docs: CLI](https://docs.bweze.com/docs/cli)
- [BWEZE docs: Pricing](https://docs.bweze.com/docs/pricing)
- [BWEZE docs: Billing](https://docs.bweze.com/docs/billing)
- [BWEZE docs: Networking](https://docs.bweze.com/docs/networking)
