Run the database service

The database service runs your queries and mutations and sends live results to the browser. Start it alongside your app and PostgreSQL when you use browser functions.

This page configures the service created in Build a live task list.

Generation and development use Bun:

bun --bun hulla-db generate
bun --bun hulla-db init
bun --bun hulla-db dev

Commands default to db.config.ts in the current directory. An optional final path selects another config. Initialization never silently resets data; schema changes in a disposable development database may need explicit recreation.

import { defineConfig } from '@hulla/db/config'

export default defineConfig({
  database: {
    server: { url: process.env.DATABASE_URL! },
    client: { url: 'http://localhost:3001', credentials: 'include' },
  },
  service: {
    host: '127.0.0.1',
    port: 3001,
    origins: ['http://localhost:5173'],
  },
})

Host and port default to the values shown. Origins are exact HTTP(S) origins, not wildcard patterns. The default empty list accepts requests without an Origin header. Configure your browser application’s origin for remote browser calls. Production ingress needs HTTPS and unbuffered streaming responses.

Put the public URL, credentials mode and optional timeouts in database.client. Generation copies these settings into browser bindings; it never imports the server config or credentials into the browser. A root-relative URL such as /db resolves against the browser origin when calls start. Regenerate when changing environments.

Import generated callables directly. No startup call is required, and importing modules opens no connection. On application teardown, call generated dispose(); components release their subscriptions without disposing the shared runtime.

For authenticated calls, use the authentication guide. For framework startup and SSR, choose a recipe.

Import db from ./db/_generated/server in trusted application code. Authenticate and authorize the request there; it does not need browser runtime setup. See read and write data for builders and transactions.

Defaults keep an individual invocation bounded. Raise the budget around a real workload, rather than making every operation unbounded:

export default defineConfig({
  database: {
    server: { url: process.env.DATABASE_URL! },
    client: { url: 'http://localhost:3001', credentials: 'include' },
  },
  limits: { executionMs: 10_000, outputBytes: 24 * 1024 * 1024 },
})

Keep the defineConfig import from the earlier setup. A final query/mutation declaration can override individual limits too; extensions cannot. Omitted settings inherit the config, then the defaults in the reference.

The execution deadline covers server work, including lock waits and retries—not the browser’s upload/download time. Near-limit development diagnostics report usage without logging submitted values. Exceeding a budget fails the operation and prevents a mutation commit.

For a deliberately longer server operation, raise database.client deadlines in db.config.ts before regenerating:

// Inside database.client:
{
  url: 'https://database.example.com',
  operationTimeoutMs: 60_000,
  queryTimeoutMs: 90_000,
  confirmationTimeoutMs: 90_000,
}

One-shot reads can retry interrupted transport within their overall deadline. Mutation confirmation checks the submitted result and never resubmits the write. Live reconnection is separate from replaying a handler failure. Defaults and the stream-idle deadline are listed in the reference.

The app, persistent service and PostgreSQL can run together or separately. Keep the same schema and generated artifacts on the server paths. See deployment for native assets, connection lifecycle and compatible hosting environments.