Database plugin

Declare your tables in config/database/schema.ts and register database() to get generated HTTP CRUD and a server-side database client. CRUD is enabled for every declared table by default. Use api to restrict the generated routes without disabling server-side access.

Basic usage

Configure a Lakebase postgres resource and its connection environment variables as described in Lakebase configuration. The database tables must already exist and match the declared schema. This plugin checks connectivity during setup; it does not create or migrate tables.

Apps scaffolded with the Database plugin selected include an empty config/database/schema.ts, so database() can start without requiring sample tables. Replace the empty declaration with your models when their PostgreSQL tables are ready.

For local development, the PostgreSQL username is resolved from your Databricks credentials when PGUSER and DATABRICKS_CLIENT_ID are absent. An explicitly configured username takes precedence.

// config/database/schema.ts
import { defineSchema, id, text } from "@databricks/appkit/beta";

export const schema = defineSchema((builder) => ({
  notes: builder.table("notes", {
    id: id(),
    body: text().notNull(),
  }),
}));

// server/index.ts
import { createApp, server } from "@databricks/appkit";
import { database } from "@databricks/appkit/beta";

const AppKit = await createApp({
  plugins: [server(), database()],
});

With the server plugin enabled, this registers:

A table without a public primary key supports list and create only. upsert is available to server code but has no generated HTTP route.

Schema discovery and overrides

database() and database({}) use the same defaults. During setup, the plugin loads the named schema export from config/database/schema.ts, relative to the application's working directory. The file must export a finalized defineSchema() result. Missing files, import failures, and invalid exports fail setup before the plugin creates a connection pool; they do not silently create an empty schema.

Keep config/database/schema.ts and its local imports in your deployment. The plugin loads TypeScript through Jiti, so a plain Node production process does not need a separate TypeScript loader. The schema module should only declare tables, not connect to the database or start the app.

For a different layout or a deployment that contains only a server bundle, import the schema explicitly and pass it to the plugin:

import { schema } from "../config/database/schema";

database({ schema });

An explicit schema always takes precedence and skips file discovery. An invalid explicit schema fails setup instead of falling back to another file.

Run appkit generate-types to generate the database registry. With that registry, configuration without an explicit schema still infers table names and hook payloads. An explicitly supplied schema also checks configuration keys against its own table names.

Restrict the generated API

Omitting api, or setting it to true or {}, enables full CRUD. Restrictions are optional. There is no separate write opt-in.

// No generated HTTP routes. The server-side client still works.
database({ api: false });

// Read-only routes for every table.
database({ api: { writes: false } });

// Full CRUD for selected tables only.
database({ api: { tables: ["notes"] } });

// Allow reads, create, and update, but not delete.
database({
  api: { writes: { operations: ["create", "update"] } },
});

// Read every table, but allow writes only to notes.
database({
  api: { writes: { tables: ["notes"] } },
});

api.tables: [] disables all generated routes. An empty write-table or write-operation list keeps reads and disables writes. Tables omitted from api.tables also cannot be included through relations on exposed tables. These restrictions apply to HTTP only, not to the server-side client or hooks.

An omitted restriction uses its default. A malformed restriction fails setup. For example, { api: { write: false } } is an error, not permission to generate all writes. Unknown tables, duplicate names, and unsupported operations also fail setup before the plugin creates a connection pool.

Replace the former crudRoutes option with api. The old name is rejected at runtime so an old opt-out cannot silently enable the API. To preserve read-only behavior, specify api: { writes: false }.

Table names and setup errors

Generated route names must:

• Start with an ASCII letter.
• Contain only ASCII letters, digits, underscores, or hyphens.
• Be at most 64 characters long.
• Be unique without regard to case, because Express routes are case-insensitive.

The default API validates every declared table. A table such as _events fails setup instead of being silently omitted. The error names the table and suggests renaming it, excluding it with api.tables, or disabling routes with api: false. An excluded table remains available to server code.

Configuration errors include actionable details in the server-side error message. Client-facing messages do not expose those details.

Validation and private columns

The generated API validates request bodies and rejects unknown or read-only fields. Columns marked .private() are not available through generated routes. Database-generated primary keys, including uuid().primaryKey().defaultRandom(), cannot be supplied by HTTP callers. A natural primary key may be supplied on create, but primary keys cannot be updated through HTTP.

Validation is not authorization. A valid request can still read or change any exposed row. Use custom authorized routes when that is not the desired access model.

Mutation hooks

A table can declare beforeCreate, afterCreate, beforeUpdate, afterUpdate, beforeUpsert, afterUpsert, beforeDelete, and afterDelete. Hooks and the mutation run in one database transaction. Related writes through ctx.app.database join that same transaction. This does not make writes through other plugins or external services transactional.

import { DatabaseValidationError } from "@databricks/appkit";

database({
  hooks: {
    notes: {
      beforeCreate(values) {
        if (typeof values.body === "string" && values.body.length > 5_000) {
          throw new DatabaseValidationError("Note too long", [
            { path: ["body"], message: "Must be at most 5000 characters" },
          ]);
        }
      },
    },
  },
});

A before* hook can return replacement values, which are validated again before persistence. DatabaseValidationError produces HTTP 422 with issues limited to public columns. Other hook failures return an opaque server error.

Keep hooks short and await all database work. A transaction has a 30-second callback deadline, a shared budget of 100 database operations, and a maximum mutation nesting depth of 8. Repeating the same entity and mutation operation in a nested hook chain is rejected. PostgreSQL also enforces a 30-second statement_timeout and a 30-second idle_in_transaction_session_timeout.

The callback deadline does not cancel arbitrary JavaScript, HTTP requests, or other external side effects. Avoid putting external side effects in hooks that need database rollback semantics.

API reference

• database
• IDatabaseConfig
• DatabaseApiConfig
• EntityHooks