Database

Ponder supports two database options, PGlite and Postgres.

• PGlite: An embedded Postgres database. PGlite runs in the same Node.js process as Ponder, and stores data in the .ponder directory. Only suitable for local development.
• PostgreSQL: A traditional Postgres database server. Required for production, can be used for local development.

Choose a database

Ponder uses PGlite by default. To use Postgres, set the DATABASE_URL environment variable to a Postgres connection string, or use explicit configuration in ponder.config.ts.

import { createConfig } from "ponder";
 
export default createConfig({
  database: { 
    kind: "postgres", 
    connectionString: "postgresql://user:password@localhost:5432/dbname", 
  }, 
  // ...
});

Read more about database configuration in the ponder.config.ts API reference.

Database schema

Ponder uses database schemas to organize data. Each instance must use a different schema.

Use the DATABASE_SCHEMA environment variable or --schema CLI option to configure the database schema for an instance. This is where the app will create the tables defined in ponder.schema.ts.

DATABASE_SCHEMA=my_schema

Read more about database schema selection in the self-hosting guide.

Guidelines

Here are a few things to keep in mind when choosing a database schema.

• No two Ponder instances/deployments can use the same database schema at the same time.
• Tables created by ponder start are treated as valuable and will never be dropped automatically.
• The default schema for ponder dev is public. There is no default for ponder start, you must explicitly set the database schema.
• Use ponder dev for local development; ponder start is intended for production.