Guides

Database

Declare a named Postgres database and tables in robodev/database.ts.

Every project has one robodev/database.ts (legacy projects may still use root database.ts). Default-export defineDatabase with a name and Drizzle pgTable definitions. @robodev-ai/sdk re-exports the Drizzle helpers you need (pgTable, text, uuid, eq, and so on).

robodev/database.ts

import { defineDatabase, integer, pgTable, text, uuid } from "@robodev-ai/sdk";

export const planets = pgTable("planets", {
  id: uuid("id").primaryKey().defaultRandom(),
  name: text("name").notNull(),
  moons: integer("moons").default(0),
});

export default defineDatabase({
  name: "space",
  tables: { planets },
});

Database name

The name must be lowercase, start with a letter, and use only a-z, 0-9, and _. Starbase creates that tenant database on first deploy if it does not exist yet. Existing unused databases are left alone.

Schema sync

There are no migration files. Deploy compares robodev/database.ts to the live schema and applies the difference. Adding tables or columns is applied automatically. Dropping columns or tables is treated as destructive and requires confirmation or --force.

Import table objects from robodev/database.ts into your API files so handlers and schema stay in one place.

Relational queries

To load rows with their related rows through ctx.db.query, describe the relations with defineRelations and pass them to defineDatabase. Relations add no columns or constraints; they only tell ctx.db.query how tables join.

robodev/database.ts

import { defineDatabase, defineRelations, pgTable, text, uuid } from "@robodev-ai/sdk";

export const authors = pgTable("authors", {
  id: uuid("id").primaryKey().defaultRandom(),
  name: text("name").notNull(),
});

export const posts = pgTable("posts", {
  id: uuid("id").primaryKey().defaultRandom(),
  authorId: uuid("author_id").notNull(),
  title: text("title").notNull(),
});

const tables = { authors, posts };

export default defineDatabase({
  name: "blog",
  tables,
  relations: defineRelations(tables, (r) => ({
    authors: { posts: r.many.posts() },
    posts: { author: r.one.authors({ from: r.posts.authorId, to: r.authors.id }) },
  })),
});

// In a handler:
// await ctx.db.query.authors.findFirst({ where: { id }, with: { posts: true } });

The older relations(table, ...) helper is still exported but does nothing for ctx.db.query. A raw sql field selected inside a union or subquery needs an alias: sql`1`.as("one").