Databases and migrations

Before you deploy

A Hasura service needs an existing PostgreSQL database, a configured Hasura service, its credentials, and working service-domain DNS/TLS. Confirm these prerequisites with Atrium for your app. Registering a manifest or receiving a resolved URL does not mean the database and service have been provisioned. The current deployment workflow supports one Hasura service per build.

services:
  gql:
    type: hasura
    path: hasura
    healthCheck: /healthz

Keep migrations and metadata under the declared path, for example:

hasura/
  config.yaml
  migrations/
  metadata/

The starter uses the service key database; this example uses gql. Use your actual key in CLI commands and URLs. https://gql.my-agent.apps.atrium.st is an HTTPS Hasura endpoint, not a PostgreSQL connection string. Keep database credentials and the Hasura admin secret outside source control.

Deployment order

For an app with a Hasura service, deployment proceeds through:

1. Build and push the application images.
2. Apply database migrations from the Hasura project.
3. Apply Hasura metadata.
4. Update application services.
5. Publish service routes after successful completion.

Application updates wait for migrations and metadata. A failure does not publish a new route set, but it does not undo SQL that already ran. Use backward-compatible migrations, review destructive changes, and provide a recovery plan before deploying. See deployment diagnosis.

Builds obtain their own temporary operation access. You do not need to copy a personal migration token into the manifest or build configuration.

Request a one-off migration session

Use this workflow for an authorized schema change or data backfill outside a normal deployment. Authenticate in the app's owning workspace and explain the operation in reason:

POST /v0/platform/agents/my-agent/services/gql/migration-sessions
Authorization: Bearer <workspace-access-token>
Content-Type: application/json

{
  "reason": "Backfill display names after the profile migration",
  "ttlSeconds": 900
}

The response contains success and a session with id, token, endpoint, and expiresAt. Keep the token in a protected process environment or secret store; do not print or commit it. The default lifetime is 15 minutes. Requests can specify 60 through 3,600 seconds.

Send both credentials to the returned endpoint when performing privileged Hasura operations:

POST https://gql.my-agent.apps.atrium.st/v1/metadata
X-Atrium-Operation-Token: <session-token>
X-Hasura-Admin-Secret: <your-hasura-admin-secret>
Content-Type: application/json

{"type":"export_metadata","args":{}}

This read example verifies access before you run a migration. Configure your migration client to send the operation header on every request and use the returned canonical endpoint. Follow your Hasura project's migration and metadata commands; do not send raw PostgreSQL traffic to the HTTPS endpoint.

The operation is scoped to the service, hostname, allowed methods/paths, and expiration. Default migration scope covers Hasura migration/metadata operations and POST /v1/graphql for backfills. Explicit manifest operation rules can narrow that scope. A session authorizes requests; it does not execute or retry SQL. Make repeatable backfills idempotent yourself.

Revoke access when finished

Revoke the session on success or failure instead of waiting for expiration:

DELETE /v0/platform/agents/my-agent/migration-sessions/<session-id>
Authorization: Bearer <workspace-access-token>

A successful revoke returns {"success":true}. An expired or revoked token cannot authorize new operations. If a request is denied, check the owning workspace, service key, canonical hostname, expiration, and permitted method/path before requesting another session.

Console permissions

The shared platform console at gql.atrium.st/admin/console requires an owner or admin role in an explicitly approved platform workspace. Sign in with Atrium and select that workspace. Access is represented by a short-lived, secure cookie and rechecked against current membership on each request. Ordinary application GraphQL requests do not inherit console privileges.

Use atrium hasura status to check central console access, atrium hasura console to obtain its URL, and atrium hasura request --path /v1/metadata --body-file request.json for authorized CLI operations. These commands require a CLI build that includes the hasura command group.

Hasura's root, console routes, and configuration route require developer access. Administration endpoints also require operation access; signing in or supplying an admin secret alone does not satisfy that gate. The GraphQL endpoint retains your application's access policy and Hasura data permissions.

The console is not automatically read-only, and Atrium does not inject an admin secret into the browser. The Hasura admin secret grants privileged data access. Use the scoped migration workflow for production changes and keep that secret out of frontend bundles.

For temporary development databases and their current availability, see Local development.