PostgreSQL

This guide walks you through deploying PostgreSQL to Magic Containers, either as a standalone container or as part of a multi-container app alongside your application. You’ll need a bunny.net account with Magic Containers enabled.

Quickstart

Create a new app

Go to the bunny.net dashboard, select Magic Containers, and click Add App. Select Single region deployment.

Databases should use single region deployment with a single instance. Each pod gets its own dedicated volume with no data replication — this applies both across regions and within the same region. Scaling to multiple pods or regions would result in separate, isolated databases each with their own data.

Add the PostgreSQL container

Click Add Container and configure the image:

Registry: Docker Hub
Image: library/postgres
Tag: 17-alpine

Magic Containers will automatically detect the required endpoint and environment variables for the image. Configure the environment variables as needed:

POSTGRES_USER = postgres
POSTGRES_PASSWORD = a strong password
POSTGRES_DB = app
PGDATA = /var/lib/postgresql/data/pgdata

Add a persistent volume

In the Volumes section of the container settings, add a volume:

Name: postgres-data
Mount path: /var/lib/postgresql/data

This ensures your database files persist across restarts and redeployments. Without a volume, all data is lost when the container stops.See persistent volumes for more details on volume behavior and pricing.

Deploy

Review your settings and click Confirm and Create.

Always set a strong POSTGRES_PASSWORD, even if the database is not exposed externally. Other containers in the same pod can access the network, and a password protects against accidental or unauthorized access.

You must set PGDATA to a subdirectory of the volume mount (e.g. /var/lib/postgresql/data/pgdata). PostgreSQL requires the data directory to be empty on first initialization, and the volume mount point itself may contain system files.

Environment variables

The official PostgreSQL image supports these environment variables:

Variable	Description	Default
`POSTGRES_USER`	Superuser name	`postgres`
`POSTGRES_PASSWORD`	Superuser password (required)	-
`POSTGRES_DB`	Default database created on first start	`postgres`
`PGDATA`	Data directory inside the container	`/var/lib/postgresql/data`

Connect from your app

In a multi-container setup, your app and PostgreSQL share the same localhost network. Connect using 127.0.0.1 and the default port 5432.

Connection string
Node.js
Go
Python
PHP

postgresql://postgres:YOUR_PASSWORD@127.0.0.1:5432/app

import pg from "pg";

const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
});

const result = await pool.query("SELECT NOW()");

import (
	"database/sql"
	"os"

	_ "github.com/lib/pq"
)

db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
if err != nil {
	log.Fatal(err)
}
defer db.Close()

import psycopg2
import os

conn = psycopg2.connect(os.environ["DATABASE_URL"])
cur = conn.cursor()
cur.execute("SELECT NOW()")

<?php

$dsn = "pgsql:host=127.0.0.1;port=5432;dbname=app";
$pdo = new PDO($dsn, 'postgres', getenv('POSTGRES_PASSWORD'));

$result = $pdo->query('SELECT NOW()')->fetch();

Multi-container example

A typical setup pairs PostgreSQL with your application. When configuring the app, add two containers:

App container

Image: your app image (e.g. ghcr.io/<your-username>/my-app:latest)
Endpoint: the port your app listens on
Environment variables:
- DATABASE_URL = postgresql://postgres:YOUR_PASSWORD@127.0.0.1:5432/app

PostgreSQL container

Image: postgres:17-alpine
Volume: mount path /var/lib/postgresql/data
Environment variables:
- POSTGRES_USER = postgres
- POSTGRES_PASSWORD = a strong password
- POSTGRES_DB = app
- PGDATA = /var/lib/postgresql/data/pgdata

Both containers share the same localhost network, so your app connects to PostgreSQL at 127.0.0.1:5432. See multi-container apps for more details.

External access

To connect to PostgreSQL from outside Magic Containers (e.g. from your local terminal), add an Anycast endpoint:

Go to your app’s Endpoints tab and click Add New Endpoint
Select Anycast as the type
Set Container Port to 5432
Set Exposed Port to 5432
Click Add Endpoint

Then connect using the Anycast IP and the exposed port:

psql -h <anycast-ip> -p <exposed-port> -U postgres -d app

The exposed port and container port may differ. When connecting externally, always use the exposed port shown in your endpoint configuration.

Exposing your database to the internet means anyone with the credentials can connect. Use a strong password and consider removing the Anycast endpoint when external access is no longer needed.

Documentation

Deployment

Managing Apps

Observability

Platform

Reference

Tutorials

Quickstart

Environment variables

Connect from your app

Multi-container example

App container

PostgreSQL container

External access

Documentation

Deployment

Managing Apps

Observability

Platform

Reference

Tutorials

​Quickstart

​Environment variables

​Connect from your app

​Multi-container example

​App container

​PostgreSQL container

​External access

Quickstart

Environment variables

Connect from your app

Multi-container example

App container

PostgreSQL container

External access