Skip to main content
Databases provide persistent SQL storage for your application’s structured data.

​
What is a Database?

A database in Suga is a PostgreSQL database that:
  • Stores structured data - Tables, relations, indexes
  • Provides SQL access - Full PostgreSQL compatibility
  • Scales automatically - Managed database service
  • Integrates with services - Automatic connection configuration
Basic database
databases:
  main:
    subtype: # your choice, from target platform
    access:
      api: [query]
      worker: [query]

​
Database Configuration

​
Access Control and Connection Strings

When you grant a service access to a database, Suga automatically injects the database connection string into that service’s environment variables:
Database with environment variable injection
databases:
  main:
    subtype: # your choice, from target platform
    access:
      api: [query]
      worker: [query]
    env_var_key: DATABASE_URL  # Connection string injected as DATABASE_URL
Services with access automatically receive:
  • Full connection string - Including host, port, database name, and credentials
  • Environment variable - Specified by env_var_key
  • Ready to use - Works immediately with standard PostgreSQL libraries
Permission:
  • query - Full read/write SQL access

​
Multiple Databases

When using multiple databases, each must have a unique env_var_key to avoid conflicts:
Multiple databases with unique env vars
databases:
  users:
    subtype: # your choice, from target platform
    access:
      api: [query]
    env_var_key: USERS_DATABASE_URL

  products:
    subtype: # your choice, from target platform
    access:
      api: [query]
    env_var_key: PRODUCTS_DATABASE_URL

  orders:
    subtype: # your choice, from target platform
    access:
      api: [query]
    env_var_key: ORDERS_DATABASE_URL
Now the api service receives three separate connection strings:
  • USERS_DATABASE_URL
  • PRODUCTS_DATABASE_URL
  • ORDERS_DATABASE_URL
Each database must have a unique env_var_key if the same service accesses multiple databases. Using the same key for different databases will cause conflicts.

​
Using Databases in Code

Access databases using standard PostgreSQL libraries with the automatically injected connection string:
  • Node.js
  • Python
  • Go
Install the PostgreSQL client:
npm install pg
Then develop like you normally would, using the env_var_key you defined in your suga.yaml.
import { Pool } from 'pg';

// Connection string automatically injected by Suga
const pool = new Pool({
  connectionString: process.env.DATABASE_URL
});

// Query database
const result = await pool.query(
  'SELECT * FROM users WHERE active = $1',
  [true]
);
const users = result.rows;

// Insert data
await pool.query(
  'INSERT INTO users (name, email) VALUES ($1, $2)',
  ['Alice', 'alice@example.com']
);

// Update data
await pool.query(
  'UPDATE users SET name = $1 WHERE id = $2',
  ['Bob', 1]
);

​
Connection String Format

The injected DATABASE_URL contains everything needed to connect: 
postgresql://username:password@host:port/database?sslmode=require
This works with any PostgreSQL-compatible library or ORM (Prisma, TypeORM, SQLAlchemy, etc.):
  • Prisma
  • TypeORM
  • SQLAlchemy
prisma/schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

​
Database Migrations

Run migrations as part of your deployment:

Database Migrations Guide

Learn how to manage database schema changes

​
Local Development

During suga dev, PostgreSQL databases run automatically with no manual setup required:
  • Suga starts a local PostgreSQL instance for each database
  • Connection strings are injected into services via env_var_key
  • Data persists in .suga/databases/ between sessions
  • Use the same PostgreSQL libraries and ORMs as production
suga dev
Your services receive DATABASE_URL (or your custom env_var_key) automatically, making the same code work in both local development and production.

Local Development Guide

Learn more about local development with databases

​
Learn More

Database SDK

Complete API reference

Migrations

Schema management

Local Development

Local PostgreSQL during suga dev

Access Control

Permission management