Viewing: docs.microsandbox.dev

Run a persistent PostgreSQL service with a localhost-only forwarded port

This example runs PostgreSQL 17 in a microVM, stores the database on a sized root disk, and publishes the service only to host loopback.

The current postgres:17-alpine image contains tab characters in DOCKER_PG_LLVM_DEPS. Passing -e DOCKER_PG_LLVM_DEPS= is a temporary compatibility workaround for microsandboxs guest environment validation.

Run PostgreSQL

Start PostgreSQL

Set a demo password in the host shell:

macOS & Linux
Windows
export POSTGRES_PASSWORD="$(openssl rand -hex 24)"
$bytes = New-Object byte[] 24
$rng = [Security.Cryptography.RandomNumberGenerator]::Create()
$rng.GetBytes($bytes)
$rng.Dispose()
$env:POSTGRES_PASSWORD = -join ($bytes | ForEach-Object { $_.ToString('x2') })

Start the database:

macOS & Linux
Windows
msb run -d --name postgres-demo --replace \
  --cpus 1 --memory 1G --root-disk 6G \
  -p 127.0.0.1:55432:5432 \
  -e POSTGRES_PASSWORD="$POSTGRES_PASSWORD" \
  -e POSTGRES_DB=examples \
  -e DOCKER_PG_LLVM_DEPS= \
  postgres:17-alpine
msb run -d --name postgres-demo --replace `
  --cpus 1 --memory 1G --root-disk 6G `
  -p 127.0.0.1:55432:5432 `
  -e "POSTGRES_PASSWORD=$env:POSTGRES_PASSWORD" `
  -e POSTGRES_DB=examples `
  -e DOCKER_PG_LLVM_DEPS= `
  postgres:17-alpine

With no command after the image, microsandbox runs the images declared docker-entrypoint.sh postgres command in the background.

Wait for readiness

msb exec postgres-demo -- sh -lc '
  until pg_isready -h 127.0.0.1 -d examples -U postgres; do sleep 1; done
'

Run a query

macOS & Linux
Windows
msb exec -e PGPASSWORD="$POSTGRES_PASSWORD" postgres-demo -- \
  psql -h 127.0.0.1 -U postgres -d examples \
  -c "select current_database(), current_setting('server_version');"
msb exec -e "PGPASSWORD=$env:POSTGRES_PASSWORD" postgres-demo -- `
  psql -h 127.0.0.1 -U postgres -d examples `
  -c "select current_database(), current_setting('server_version');"

The tested image returned database examples and PostgreSQL 17.10.Applications on the host can connect to 127.0.0.1:55432 with the same database, user, and password.

Environment variables and command arguments are appropriate for this local demo, not for production secrets. Use secret injection, retain the loopback bind, and configure PostgreSQL access controls before allowing remote clients.

Clean up

Remove the sandbox and its database:

msb rm -f postgres-demo

Clear the password from the host shell:

macOS & Linux
Windows
unset POSTGRES_PASSWORD
Remove-Item Env:POSTGRES_PASSWORD

Overview

AI Agents

Dev Environments

CI/CD & Jobs

Browser & Web Automation

File Processing

Docker & System Tools

Data & Storage

Observability

PostgreSQL

Run PostgreSQL

On this page