Skip to main content
Pongo supports both SQLite and PostgreSQL databases. The database driver is automatically detected from your DATABASE_URL connection string.

​
Database Drivers

​
SQLite (Default)

SQLite is the default database backend, perfect for development and small to medium deployments:
  • Zero configuration required
  • WAL mode enabled for better concurrency
  • Local file-based storage
  • No separate database server needed
# .env
DATABASE_URL=file:./pongo/pongo.db
This is the default if no DATABASE_URL is specified. PostgreSQL is recommended for production deployments:
  • Better scalability and performance
  • ACID compliance with robust transaction support
  • Multi-region support
  • Better concurrent access handling
# .env
DATABE_URL=postgres://user:password@localhost:5432/pongo

​
Connection String Formats

​
SQLite

DATABASE_URL=file:./pongo/pongo.db

​
PostgreSQL

DATABASE_URL=postgres://username:password@host:5432/database

​
Auto-Detection

The DB_DRIVER variable is automatically detected from your connection string:
  • Starts with postgres:// → PostgreSQL driver
  • Starts with file: or other → SQLite driver
You can manually override this if needed: 
DB_DRIVER=pg        # Force PostgreSQL
DB_DRIVER=sqlite    # Force SQLite

​
Environment Variables

VariableTypeDefaultDescription
DATABASE_URLstringfile:./pongo/pongo.dbDatabase connection string
DB_DRIVERsqlite | pgauto-detectedDatabase driver (auto-detected from URL)

​
Running Migrations

Migrations create and update your database schema. They run automatically during the build process, but you can also run them manually.

​
PostgreSQL Migrations

bun run db:pg:migrate
Run this command after setting your PostgreSQL DATABASE_URL for the first time, or when upgrading Pongo versions.

​
SQLite Migrations

bun run db:sqlite:migrate
Run this for SQLite databases. This is included in the quick start setup.

​
Automatic Migrations

Migrations run automatically when you build for production: 
bun run build
This ensures your database schema is always up to date with your deployed application version.

​
Database Studio

Pongo uses Drizzle ORM, which includes Drizzle Studio for visual database management.

​
PostgreSQL Studio

bun run db:pg:studio
Opens Drizzle Studio connected to your PostgreSQL database.

​
SQLite Studio

bun run db:sqlite:studio
Opens Drizzle Studio connected to your SQLite database.

​
Multi-Region Setup

When deploying multiple scheduler instances across regions, all schedulers should point to the same database: 
# Region 1 (US East)
DATABASE_URL=postgres://user:[email protected]:5432/pongo
PONGO_REGION=us-east

# Region 2 (EU West) - Same database
DATABASE_URL=postgres://user:[email protected]:5432/pongo
PONGO_REGION=eu-west
PostgreSQL is strongly recommended for multi-region deployments due to better concurrent access handling.

​
Docker Compose Example

Here’s a complete example with PostgreSQL:
docker-compose.yml
services:
  pongo:
    build: .
    ports: ["3000:3000"]
    environment:
      DATABASE_URL: postgres://postgres:password@db:5432/pongo
      ACCESS_CODE: your-password
    depends_on: [db]

  scheduler:
    build: .
    command: ["bun", "scheduler"]
    environment:
      DATABASE_URL: postgres://postgres:password@db:5432/pongo
    depends_on: [db]

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_DB: pongo
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

​
Troubleshooting

​
Connection Issues

If you’re having trouble connecting to your database:
  1. Verify your DATABASE_URL is correct
  2. Check that the database server is running
  3. Ensure network access (firewall rules, security groups)
  4. For PostgreSQL, verify SSL requirements match your connection string

​
Migration Failures

If migrations fail:
  1. Check database permissions (CREATE TABLE, ALTER TABLE)
  2. Ensure the database exists (Pongo doesn’t auto-create databases)
  3. Review migration logs for specific errors
  4. For PostgreSQL, ensure your user has schema creation rights

Build docs developers (and LLMs) love

Get started for freeTalk to us