PostgreSQL

Stackpad provides managed PostgreSQL databases (versions 16–18) as project services. Each database runs in its own container on the project’s private network with automatic backups, encrypted credentials, and pgvector pre-installed for AI workloads.

Creating a PostgreSQL service

1. Open your project in the dashboard
2. Click Add Service
3. Search for or select PostgreSQL
4. Click Add

Stackpad provisions a PostgreSQL instance with:

• Auto-generated credentials — username, password, and database name
• AES-256-GCM encrypted password
• Persistent storage — data survives container restarts
• Private network access — reachable at postgres:5432 from other services
• pgvector pre-installed — vector operations work out of the box
• Version choice — PostgreSQL 16, 17, or 18 (select in service settings)

Connecting from your application

Stackpad automatically injects DATABASE_URL into all sibling web services in the same project:

postgresql://stackpad_user:auto_generated_pass@postgres:5432/stackpad_db

Use this in your application:

// Plain pg
import { Pool } from 'pg';
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

// Drizzle ORM
import { drizzle } from 'drizzle-orm/node-postgres';
const db = drizzle(process.env.DATABASE_URL!);

// Prisma — in schema.prisma:
// datasource db {
//   provider = "postgresql"
//   url      = env("DATABASE_URL")
// }

The postgres hostname resolves via the project’s private DNS — no IP addresses or external connection strings needed.

Adding a database to an existing project

If you add PostgreSQL to a project that already has a running web service:

1. DATABASE_URL is created immediately in Stackpad’s database
2. But the running container doesn’t see it yet — it was started before the variable existed

Caution

You must redeploy your web service after adding a database. Click Redeploy on the web service to pick up the new DATABASE_URL.

Running migrations

Your application needs to handle database migrations. Common approaches:

• Prisma: Add prisma migrate deploy to your build command or start script
• Drizzle: Run drizzle-kit push as part of your deployment
• Raw SQL: Run migrations on application startup

Since DATABASE_URL is available at both build time and runtime, you can run migrations during the build or when the app starts.

pgvector (AI & vector search)

Every PostgreSQL service comes with the pgvector extension pre-installed. Build AI features, semantic search, and RAG pipelines without any extra setup.

-- Enable the extension
CREATE EXTENSION IF NOT EXISTS vector;

-- Create a table with a vector column
CREATE TABLE documents (
  id SERIAL PRIMARY KEY,
  content TEXT,
  embedding vector(1536)
);

-- Create an index for fast similarity search
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);

-- Query by similarity
SELECT content, 1 - (embedding <=> '[0.1, 0.2, ...]') AS similarity
FROM documents
ORDER BY embedding <=> '[0.1, 0.2, ...]'
LIMIT 10;

Supports cosine distance, L2 distance, and inner product with HNSW and IVFFlat indexing. Works with any embedding model (OpenAI, Cohere, HuggingFace, or self-hosted via GPU services).

Connecting from outside Stackpad

By default, PostgreSQL is only accessible from within the project’s private network. To connect from your local machine (e.g. for debugging or running migrations manually):

1. Go to the PostgreSQL service detail page
2. Open the Settings tab
3. Enable Public access

Public connections are TLS-encrypted on the standard PostgreSQL port (5432). The full connection string with credentials is shown in the dashboard:

psql "postgresql://stackpad_user:pass@{serviceId}.db.stackpad.eu:5432/stackpad_db?sslmode=require"

Use this with any PostgreSQL client — TablePlus, pgAdmin, DBeaver, or your application.

Caution

Only enable public access when you need it. The database is protected by its password and TLS encryption, but reducing exposure is always better.

Performance tuning

PostgreSQL services start with optimized configuration based on their allocated RAM — no manual config files needed:

Parameter	Value	Description
shared_buffers	25% of RAM	In-memory cache for table data
effective_cache_size	75% of RAM	Planner’s estimate of available cache
work_mem	1/200 of RAM	Memory per sort/hash operation
maintenance_work_mem	1/8 of RAM	Memory for VACUUM, CREATE INDEX
max_connections	1/50 of RAM	Maximum concurrent connections

These are computed automatically when your service starts. If you need fine-grained control, override individual parameters from the service Settings tab.

Tip

If you need more concurrent connections than max_connections allows, add PgBouncer as a connection pooler instead of increasing the limit.

Version management

Change the PostgreSQL version directly from the service settings:

• Available versions: PostgreSQL 16, 17, 18
• Pick the version, save, and the service restarts with the new image
• No need to recreate the service to change versions

Backups

PostgreSQL databases are automatically backed up using pg_dump:

Plan	Frequency	Retention
Starter	Daily	7 days
Pro	Every 6 hours	30 days
Business	Hourly	90 days

Backups are stored on European S3-compatible storage. Browse, download, and restore backups directly from the Backups tab on the service page.

Point-in-time recovery

On Pro plans and above, you can enable point-in-time recovery (PITR) for PostgreSQL. This uses continuous WAL (Write-Ahead Log) archiving to let you restore your database to any second in time.

1. Go to the PostgreSQL service Settings
2. Enable Point-in-time recovery
3. Stackpad switches to a WAL-G enabled PostgreSQL image and begins continuous archiving

To restore:

1. Go to the Backups tab
2. Select Point-in-time restore
3. Pick a date and time
4. The database is restored to that exact moment

Caution

PITR requires the Pro plan or higher. Enabling PITR switches the PostgreSQL image to include WAL-G, which triggers a service restart.

See Backups for more details on backup management.

Resource limits

Plan	Storage	RAM	CPU
Starter	256 MB	256 MB	0.25 cores
Pro	1 GB	512 MB	0.5 cores
Business	5 GB	1 GB	1 core

These limits apply per service. If you have PostgreSQL in both production and staging environments, each gets its own allocation.

Security

PostgreSQL services run with a hardened container security profile:

• SYS_NICE and IPC_LOCK capabilities for database performance
• no-new-privileges flag enabled
• PID limits to prevent fork bombs
• Isolated on the project’s Docker network — not accessible from other projects
• Credentials encrypted with AES-256-GCM at rest

What’s next?

• PgBouncer — add connection pooling
• Connecting services — how private networking and public access work
• Backups — manage and restore database backups
• GPU compute — generate embeddings for pgvector with European GPU infrastructure