Database Operations

Eve Horizon provides managed Postgres databases provisioned through your manifest, plus a full suite of CLI tools for migrations, schema inspection, SQL access, and credential management. Databases are scoped to environments -- each environment gets its own isolated tenant.

Managed database overview

Managed databases are platform-provisioned Postgres instances declared in your manifest. Unlike regular services, managed DB services are not rendered into Kubernetes manifests -- the orchestrator provisions a tenant when you deploy an environment.

The provisioning lifecycle follows this flow:

Key characteristics:

• Provisioning occurs on first deploy for each environment
• Each environment gets an isolated database tenant
• Credentials are managed by the platform and available via interpolation
• Managed DB availability depends on platform configuration -- ask an admin if provisioning is disabled

Provisioning via manifest

Declare a managed database as a service with x-eve.role: managed_db:

services:
  db:
    x-eve:
      role: managed_db
      managed:
        class: db.p1
        engine: postgres
        engine_version: "16"

Configuration fields

Field	Required	Description
role	Yes	Must be managed_db
class	Yes	Database tier -- db.p1, db.p2, or db.p3
engine	Yes	Database engine (currently postgres)
engine_version	No	Engine version (e.g., "16")

Database tiers

Tier	Use case
db.p1	Development and testing
db.p2	Staging and light production
db.p3	Production workloads

Referencing managed values

Other services reference managed database values using interpolation placeholders that are resolved at deploy time:

services:
  db:
    x-eve:
      role: managed_db
      managed:
        class: db.p1
        engine: postgres
        engine_version: "16"

  api:
    build:
      context: ./apps/api
    ports: [3000]
    environment:
      DATABASE_URL: ${managed.db.url}
    depends_on:
      db:
        condition: service_healthy

The ${managed.<service>.<field>} syntax resolves to the provisioned values when the environment is deployed. Use eve db status to confirm tenant readiness before relying on managed values.

Database status and credentials

Checking status

Verify that your managed database is provisioned and ready:

eve db status --env staging

This shows the provisioning state, connection details, and health of the managed database for the specified environment.

Credential rotation

Rotate database credentials when needed for security compliance:

eve db rotate-credentials --env staging

After rotation, redeploy services that reference managed database values so they pick up the new credentials.

Migrations

Eve provides a migration workflow built around SQL files with timestamp-based ordering.

Creating a new migration

eve db new create_users_table

This creates a new migration file under db/migrations/ with the naming convention YYYYMMDDHHmmss_create_users_table.sql. The timestamp prefix ensures migrations execute in the correct order.

You can specify a custom migrations directory:

eve db new create_users_table --path db/custom-migrations

Running migrations

Apply pending migrations to an environment:

eve db migrate --env staging

To use a custom migrations path:

eve db migrate --env staging --path db/migrations

Listing applied migrations

View which migrations have been applied:

eve db migrations --env staging

Migration as a pipeline step

For automated workflows, you can run migrations as a pipeline step using a service with x-eve.role: job:

services:
  migrate:
    image: flyway/flyway:10
    command: >-
      -url=jdbc:postgresql://db:5432/app
      -user=app
      -password=${secret.DB_PASSWORD}
      -locations=filesystem:/migrations
      migrate
    volumes:
      - ./db/migrations:/migrations:ro
    depends_on:
      db:
        condition: service_healthy
    x-eve:
      role: job

pipelines:
  deploy:
    steps:
      - name: migrate
        action: { type: job, service: migrate }
      - name: deploy
        depends_on: [migrate]
        action: { type: deploy }

This ensures migrations run before the application deploy step, and the pipeline fails if the migration fails.

Schema management

Inspecting the schema

View the current database schema for an environment:

eve db schema --env staging

To scope to a specific project:

eve db schema --env staging --project proj_xxx

Row-level security

Inspect the RLS policies configured on your database:

eve db rls --env staging

This shows all active row-level security policies, which tables they apply to, and the policy expressions.

SQL access

The eve db sql command provides direct SQL access to environment databases. This is useful for ad hoc queries, debugging, and data inspection.

Read queries

# Inline query
eve db sql --env staging --sql "SELECT count(*) FROM users"

# Query from a file
eve db sql --env staging --file ./queries/user-report.sql

Write queries

Write operations require the --write flag as a safety measure:

eve db sql --env staging --sql "UPDATE users SET active = true WHERE id = 42" --write

warning

The --write flag is a safety gate, not a permission check. Always verify your SQL before running write operations against production environments.

SQL access patterns

Pattern	Command
Quick count	eve db sql --env staging --sql "SELECT count(*) FROM orders"
Table inspection	eve db sql --env staging --sql "SELECT * FROM users LIMIT 10"
Report from file	eve db sql --env staging --file ./reports/monthly.sql
Data fix	eve db sql --env staging --sql "UPDATE ..." --write

Scaling

Scale a managed database to a different tier:

eve db scale --env staging --class db.p2

This changes the database tier for the specified environment. The operation may involve a brief maintenance window depending on the platform configuration.

Backup and restore

Managed databases are backed up by the platform according to the tier's backup policy. For manual backup operations, use the SQL access commands to export data:

# Export a table to check data before a migration
eve db sql --env staging --sql "SELECT * FROM users" > users-backup.json

For full backup and restore procedures, coordinate with your platform administrator -- the managed database infrastructure handles automated backups at the platform level.

Destroying a managed database

Remove a managed database tenant from an environment:

eve db destroy --env staging --force

The --force flag is required to confirm destruction. This permanently removes the database tenant and all its data for the specified environment.

danger

Database destruction is irreversible. Ensure you have backups before running eve db destroy.

Admin APIs

Platform administrators can manage managed database instances directly:

Endpoint	Method	Purpose
/admin/managed-db/instances	GET	List all managed DB instances
/admin/managed-db/instances	POST	Register a new instance
/admin/managed-db/instances/:id	GET	Get instance details

Per-environment tenant endpoints:

Endpoint	Method	Purpose
/projects/:id/envs/:env/db/managed	GET	Get tenant status
/projects/:id/envs/:env/db/managed/rotate	POST	Rotate credentials
/projects/:id/envs/:env/db/managed/scale	POST	Change tier
/projects/:id/envs/:env/db/managed	DELETE	Destroy tenant

CLI reference

Command	Purpose
eve db status --env <name>	Check managed DB provisioning state
eve db schema --env <name>	Inspect database schema
eve db rls --env <name>	View row-level security policies
eve db sql --env <name> --sql "..."	Execute read query
eve db sql --env <name> --sql "..." --write	Execute write query
eve db sql --env <name> --file ./query.sql	Execute query from file
eve db migrate --env <name>	Run pending migrations
eve db migrations --env <name>	List applied migrations
eve db new <description>	Create new migration file
eve db rotate-credentials --env <name>	Rotate database credentials
eve db scale --env <name> --class <tier>	Change database tier
eve db destroy --env <name> --force	Remove database tenant

See CLI Commands for the full command reference.