Embedded PostgreSQL

Embedded PostgreSQL — ɳSelf documentation.

Embedded PostgreSQL (pglite/wasmtime)

nself start --embedded-pg replaces the Docker postgres container with a pglite WebAssembly module executing inside wasmtime. The full ɳSelf stack — Hasura, Auth, Nginx — connects to it over a Unix-domain socket, same as a standard postgres deployment.

pgvector is included in pglite v0.2.17 with no extra configuration.

Stack layout

Hasura / Auth
     │  Postgres wire protocol (Unix socket)
     ▼
PGSocketBridge  ← intercepts unsupported ops (COPY, LISTEN, NOTIFY)
     │
     ▼
pglite WASM (wasmtime)
     │  WASI filesystem
     ▼
.nself/embedded-pg/pgdata/   ← durable data directory

Requirements

macOS or Linux (amd64 or arm64)
Internet access for the first run (pglite WASM download, ~5 MB, cached at ~/.nself/cache/pglite/)
Docker still needed for Hasura, Auth, and Nginx (not postgres)

Usage

# One-time flag
nself start --embedded-pg

# Persistent via env var — no flag needed on every start
NSELF_EMBEDDED_PG=true nself start

Add NSELF_EMBEDDED_PG=true to your .env.local to make it the default for a project.

First run

On first use, the CLI downloads the pglite WASM binary, compiles it to native machine code (5-15 seconds), and caches the compiled artifact. Warm starts reuse the cache and typically take under 5 seconds.

Backup

nself backup works with embedded PG. The command targets the Unix-domain socket and attempts pg_dump --format=custom first, then falls back to a SQL dump if pg_dump is not on PATH. Backup files go to ~/.nself/backups/ by default.

Limitations

COPY TO, COPY FROM, LISTEN, and NOTIFY are not supported (return SQLSTATE 0A000).
Windows is not supported.
Single-process WASM instance: not suitable for high-concurrency production workloads.

Environment variables

Variable	Default	Purpose
`NSELF_EMBEDDED_PG`	`false`	Enable embedded PG without the `--embedded-pg` flag
`NSELF_RUNTIME_DIR`	`.nself/embedded-pg`	Override the runtime directory

For the full reference, see the CLI wiki.