PostgreSQL - Microsandbox

<Tooltip tip="This example depends on a disk-kind named volume and a published client-host port, which are not available on microsandbox cloud."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

This example runs PostgreSQL 17 in a microVM, stores the database on a disk-backed named volume, and publishes the service only to host loopback.

<Note> 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 microsandbox's guest environment validation. </Note>

Run PostgreSQL

Set a demo password in the host shell:

<CodeGroup> ```sh macOS & Linux export POSTGRES_PASSWORD="$(openssl rand -hex 24)" ```

powershell

$bytes = New-Object byte[] 24
$rng = [Security.Cryptography.RandomNumberGenerator]::Create()
$rng.GetBytes($bytes)
$rng.Dispose()
$env:POSTGRES_PASSWORD = -join ($bytes | ForEach-Object { $_.ToString('x2') })

</CodeGroup>

Start the database:

<CodeGroup> ```sh macOS & Linux msb run -d --name postgres-demo --replace \ --cpus 1 --memory 1G --root-disk 2G \ -p 127.0.0.1:55432:5432 \ -e POSTGRES_PASSWORD="$POSTGRES_PASSWORD" \ -e POSTGRES_DB=examples \ -e DOCKER_PG_LLVM_DEPS= \ --mount-named postgres-data:/var/lib/postgresql/data:kind=disk,size=5G \ postgres:17-alpine ```

powershell

msb run -d --name postgres-demo --replace `
  --cpus 1 --memory 1G --root-disk 2G `
  -p 127.0.0.1:55432:5432 `
  -e "POSTGRES_PASSWORD=$env:POSTGRES_PASSWORD" `
  -e POSTGRES_DB=examples `
  -e DOCKER_PG_LLVM_DEPS= `
  --mount-named postgres-data:/var/lib/postgresql/data:kind=disk,size=5G `
  postgres:17-alpine

</CodeGroup>

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

</Step> <Step title="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
'

</Step> <Step title="Run a query"> <CodeGroup> ```sh macOS & Linux 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');" ```

powershell

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');"

</CodeGroup>

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.

<Warning> Environment variables and command arguments are appropriate for this local demo, not for production secrets. Use [secret injection](/sandboxes/secrets), retain the loopback bind, and configure PostgreSQL access controls before allowing remote clients. </Warning> </Step> <Step title="Clean up or keep the data">

Remove the VM while keeping its database:

msb rm -f postgres-demo

Remove the database volume only when you no longer need its contents:

msb volume rm postgres-data

Clear the password from the host shell:

<CodeGroup> ```sh macOS & Linux unset POSTGRES_PASSWORD ```

powershell

Remove-Item Env:POSTGRES_PASSWORD

</CodeGroup> </Step> </Steps>