Deployment

An application with live browser queries has three parts: your app, the persistent @hulla/db service and PostgreSQL. Your framework deploys as usual; the service maintains subscriptions and runs declared database functions.

A container or VM can host the app and service together. Suitable function hosts can run direct server operations; keep the subscription service persistent. An edge isolate cannot run direct db if it forbids native processes, but it can serve the frontend or call an application API. Next.js does not require Vercel.

Supply the PostgreSQL connection URL in server config. A self-hosted instance and a compatible managed endpoint use the same application API. SQLite services are not PostgreSQL backends.

Check TLS, schema privileges, connection limits and session behavior against the endpoint you will actually use. A transaction-pooler URL can behave differently from a direct database URL; a PostgreSQL-compatible label alone does not establish support for the package’s session settings.

Install @hulla/db@0.1.0 from npm using the installation commands. The package includes macOS arm64 and Linux x64/glibc executables. Generate in a Bun build environment:

bun --bun hulla-db generate db.config.ts

Include the config, schema, generated artifacts and their runtime dependencies. Deploy the same schema and function artifacts to the app and service. Native files live under node_modules/@hulla/db/native/<os>-<arch>/; retaining only the JavaScript files is insufficient.

Framework bundlers must externalize/copy the package and retain its executables. The Next recipe includes asset tracing; other hosts use their normal packaging mechanisms. Use the bundled executables for a supported target. Linux musl/Alpine, Linux arm64 and macOS x64 are not included in this release.

Use a provisioning credential to initialize or verify storage. Node can run the prepared runtime; Bun is not required for serving:

node node_modules/@hulla/db/dist/cli.js init db.config.ts
node node_modules/@hulla/db/dist/cli.js serve db.config.ts

These commands assume server environment variables are already supplied. serve does not regenerate, watch source or reset storage. Terminate HTTPS at an ingress that preserves streaming responses, allow the browser app’s exact origin, and verify credentials through the existing auth provider.

For same-origin browser calls, route /functions/* to the persistent service and keep application/auth routes on the app server. Then browser configuration can use the app’s public origin. When the service has a separate origin, use that service URL and configure CORS and credential transport for it explicitly. The PostgreSQL URL remains private in both layouts.

The generated server db lazily leases native database sessions and drains idle ones. Reuse it across requests. Call db.close() at application shutdown, not after each request, because another request can share that handle.

Transactions have an execution deadline, including waits between statements. Keep slow external requests outside them. PostgreSQL also enforces statement and idle-transaction bounds so a suspended application cannot hold a transaction indefinitely.

A terminated application can lose a commit acknowledgement. Direct operations do not replay that uncertain commit. Browser mutations use their existing confirmation flow.

Before routing production traffic, exercise native startup, concurrent requests, reused instances, rollback, reconnects and live updates against that host and database endpoint. Keep test namespaces and credentials separate from production. Local package/build tests do not substitute for this endpoint-specific check.

Use the framework recipes for app entrypoints and the service guide for listeners and budgets.