Skip to main content
Suga doesn’t currently auto-provision databases for local development. This guide shows you how to manually set up PostgreSQL locally until auto-provisioning is added in a future release. For production, you can use any PostgreSQL provider like Neon, Supabase, or RDS with the same Suga database configuration.
Prerequisites: This guide assumes you have an existing Suga project with a service that needs database access. If you need to create a project, see the Getting Started Guide.

​
Setup PostgreSQL with Docker

Create these files in your project root:
docker-compose.yml
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-admin}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-secure_password}
      POSTGRES_DB: ${POSTGRES_DB:-myapp}
    ports:
      - '5433:5432'
    volumes:
      - postgres_data:/var/lib/postgresql/data
    command: postgres -c ssl=off

volumes:
  postgres_data:
.env
POSTGRES_USER=admin
POSTGRES_PASSWORD=secure_password
POSTGRES_DB=myapp
DATABASE_URL=postgresql://admin:secure_password@localhost:5433/myapp?sslmode=disable
Change the default password before using in any shared environment.
Start your database:
Start Database
docker compose up -d
Verify it’s running:
Verify Database
docker compose ps
You should see the postgres service in “Up” status.

​
Configure Database in Suga

Open the Suga dashboard:
Open Suga Editor
suga edit
Drag a database resource onto your project canvas and connect it to your service. Set the environment key to DATABASE_URL. Database Configuration This automatically updates your suga.yaml:
suga.yaml
name: my-app
services:
  api:
    # Your service configuration here
databases:
  mydb:
    access:
      api:
        - query
    env_var_key: DATABASE_URL
For local development, you manually set DATABASE_URL to point to your Docker database. When deployed, Suga automatically configures this same environment variable with your production database URL.

​
Initialize Database Schema

You can set up your database schema however you prefer - using SQL files, ORM migrations, or database management tools. Below is one simple approach using a SQL file. Create an init.sql file in your project root:
init.sql
DROP TABLE IF EXISTS users;

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

INSERT INTO users (email) VALUES
  ('admin@example.com'),
  ('user@example.com');
Apply your schema:
Reset Database with Schema
docker compose down -v
docker compose up -d
sleep 2
docker compose exec -T postgres psql -U admin -d myapp < init.sql
For production, use a proper migration tool like golang-migrate, Flyway, or your ORM’s migration system.

​
Test Your Database Connection

Your application can now access the database using the DATABASE_URL environment variable that Suga provides. The connection string will be automatically injected when you run suga dev. First, verify you can connect to the database directly:
Test Direct Connection
docker compose exec postgres psql -U admin -d myapp -c "SELECT * FROM users;"
You should see your test data. Now start your application:
Start Your Application
suga dev
Your application now has access to the DATABASE_URL environment variable and can connect to PostgreSQL. Create a simple endpoint or function in your application to test the database connection and verify everything works end-to-end.
Stop the database when finished: docker compose down

​
Next Steps

  • For production, deploy your app and Suga will automatically configure the DATABASE_URL with your chosen PostgreSQL provider
  • Consider using proper migration tools or ORM migrations for schema management
  • Review your database configuration and connection handling for production requirements