DocumentationREST APIAPI Reference

Operations

Database Backends

Configure Prisma-backed SQLite or PostgreSQL storage for a self-hosted FlagForge API

Database Backends

FlagForge stores projects, environments, flags, targeting rules, segments, API keys, webhooks, and audit logs in a Prisma-managed database. SQLite is the default for local development; PostgreSQL is the supported option for production deployments.

The API reads the connection string from DATABASE_URL when it starts. Choose the backend before initializing the database, then run the API database setup command to generate the Prisma client and apply the schema.

Note:

Keep the database and the API configuration together. Changing DATABASE_URL does not migrate data from one database to another, and changing database providers requires the Prisma schema to use the matching provider before setup.

Choose a backend

Use SQLite when you want a simple local or small single-instance deployment with no separate database service.

dotenv
DATABASE_URL="file:./dev.db"

This is the API's default, so leaving DATABASE_URL unset uses the same SQLite connection string. The database setup command creates the schema for this database.

Initialize the database

Run setup after installing dependencies and whenever a new deployment needs its database schema initialized:

1

Install the API dependencies

From your FlagForge installation, install the project dependencies.

bash
pnpm install
2

Configure the connection

Set DATABASE_URL in the environment used by the API. For SQLite, the default is sufficient. For PostgreSQL, confirm that the Prisma datasource is configured for PostgreSQL and that the database is reachable from the API host.

3

Generate the client and apply the schema

Run the API's database setup command:

bash
pnpm --filter @flagforge/api db:setup

This runs Prisma client generation and prisma db push. A successful command returns to the shell without an error; the API can then connect to the configured database.

4

Start and verify the API

Start the service and check its liveness endpoint:

bash
pnpm --filter @flagforge/api dev
curl http://localhost:4000/health

The health check also verifies database connectivity. If it fails, check the API process environment and the value and reachability of DATABASE_URL.

Operational expectations

  • Run setup with the same environment variables used to start the API. Running it with a local default and then starting the service with a PostgreSQL URL initializes two different databases.

  • Treat the database as persistent application state. Back up the SQLite file in local deployments or use the backup and recovery procedures provided by your PostgreSQL service.

  • Ensure the API process can read and write the SQLite database location and its parent directory when using SQLite.

  • Use a server key for management requests; database configuration does not change the API's Bearer authentication model. Client keys remain limited to evaluation endpoints.

  • After changing database configuration, restart the API and verify http://localhost:4000/health before using management or evaluation endpoints.

For the complete runtime variable reference, see Configuration. For production startup and deployment checks, see Self-Hosting the API.