embedded

Documentation

Overview

Package embedded provides the wasmtime + pglite embedded-PostgreSQL path for nSelf stacks that run without an external Postgres container.

The pglite WASM artifact is fetched from ping.nself.org/assets/pglite/<ver>/pglite.wasm with an automatic fallback to the upstream npm CDN. It is verified against a pinned SHA-256 and cached in ~/.nself/cache/pglite/<ver>/.

Index

• Constants
• func FetchOrCached(ctx context.Context, version string) (string, error)
• type EmbeddedPGRuntime
  • func NewEmbeddedPGRuntime(runtimeDir, wasmPath string) (*EmbeddedPGRuntime, error)
  • func (r *EmbeddedPGRuntime) Healthy() bool
  • func (r *EmbeddedPGRuntime) SockPath() string
  • func (r *EmbeddedPGRuntime) Start(ctx context.Context) error
  • func (r *EmbeddedPGRuntime) Stop() error
• type PGSocketBridge
  • func (b *PGSocketBridge) Close() error
  • func (b *PGSocketBridge) Listen(ctx context.Context, sockPath string, runtime *EmbeddedPGRuntime) error

Constants

const DefaultPGliteVersion = "0.2.17"

DefaultPGliteVersion is the version used by nself start --embedded-pg when no explicit NSELF_PGLITE_VERSION env var is set.

Functions

func FetchOrCached

func FetchOrCached(ctx context.Context, version string) (string, error)

FetchOrCached returns the absolute path to the pglite.wasm artifact for the given version. It checks the local cache first; if the artifact is absent or its digest does not match the pinned value it downloads and re-caches it.

Download order:

1. ping.nself.org/assets/pglite/<ver>/pglite.wasm (primary CDN)
2. unpkg.com/@electric-sql/pglite@<ver>/dist/postgres.wasm (upstream fallback)

Both sources are verified against the same pinned SHA-256 before caching. The cache directory is ~/.nself/cache/pglite/<version>/. The artifact is written atomically (tmp -> rename) so partial downloads never leave a corrupt cached copy.

FetchOrCached returns an error if:

• version is not in sha256Pins
• neither source yields an artifact whose SHA-256 matches the pin
• any non-network I/O operation fails

Types

type EmbeddedPGRuntime

type EmbeddedPGRuntime struct {
	// contains filtered or unexported fields
}

EmbeddedPGRuntime manages the lifecycle of a pglite WASM instance running inside wasmtime. It exposes the embedded Postgres via an AF_UNIX socket so that Hasura, Auth, and migrations can connect without modification.

The runtime is single-instance: one EmbeddedPGRuntime per nSelf stack. Concurrent Start calls are safe; only the first call launches the instance.

func NewEmbeddedPGRuntime

func NewEmbeddedPGRuntime(runtimeDir, wasmPath string) (*EmbeddedPGRuntime, error)

NewEmbeddedPGRuntime constructs an EmbeddedPGRuntime. runtimeDir is the directory where the Unix socket and Postgres data dir will be created (typically $NSELF_RUNTIME_DIR). wasmPath is the absolute path to pglite.wasm as returned by FetchOrCached.

func (*EmbeddedPGRuntime) Healthy

func (r *EmbeddedPGRuntime) Healthy() bool

Healthy reports whether the embedded PG is currently accepting connections on its Unix socket. It returns false if the runtime has not been started or has been stopped.

func (*EmbeddedPGRuntime) SockPath

func (r *EmbeddedPGRuntime) SockPath() string

SockPath returns the AF_UNIX socket path where the embedded PG is reachable. Use this as the host component of the UDS DSN:

host=<SockPath()> dbname=nself sslmode=disable

func (*EmbeddedPGRuntime) Start

func (r *EmbeddedPGRuntime) Start(ctx context.Context) error

Start boots the pglite WASM module and waits until the embedded PG is ready to accept connections. It is idempotent: calling Start on an already-running runtime is a no-op.

ctx is used only for the startup timeout; the runtime continues after ctx is cancelled. To stop the runtime call Stop.

func (*EmbeddedPGRuntime) Stop

func (r *EmbeddedPGRuntime) Stop() error

Stop shuts down the embedded PG runtime and removes the Unix socket file. It is safe to call Stop multiple times; only the first call takes effect.

type PGSocketBridge

type PGSocketBridge struct {
	// contains filtered or unexported fields
}

PGSocketBridge accepts Postgres wire-protocol connections on a Unix domain socket and pipes them through to the embedded pglite runtime. It intercepts COPY, LISTEN, and NOTIFY commands, which are not supported by pglite, and returns a Postgres ErrorResponse (SQLSTATE 0A000) instead of forwarding them.

One PGSocketBridge instance handles all client connections for a single EmbeddedPGRuntime.

func (*PGSocketBridge) Close

func (b *PGSocketBridge) Close() error

Close stops accepting new connections. In-flight connections continue until their clients disconnect.

func (*PGSocketBridge) Listen

func (b *PGSocketBridge) Listen(ctx context.Context, sockPath string, runtime *EmbeddedPGRuntime) error

Listen starts the bridge listener on sockPath and begins accepting connections. It returns immediately; connections are handled in background goroutines. Call Close to stop accepting new connections.

sockPath is the host-side Unix socket that Hasura and Auth containers connect to (bind-mounted into each container at the same path).