buster/packages/database/CLAUDE.md

CLAUDE.md - Database Package

This file provides guidance to Claude Code when working with the database package.

Overview

The @buster/database package provides the database schema, types, and helper functions for the Buster application. It uses Drizzle ORM for type-safe database operations and PostgreSQL as the database.

Package Structure

packages/database/
├── src/
│   ├── connection.ts      # Database connection setup
│   ├── schema.ts          # Database table definitions
│   ├── relations.ts       # Table relationships
│   ├── enums.ts          # Enum type definitions
│   ├── helpers/          # Database helper functions
│   │   ├── index.ts      # Helper exports
│   │   └── messages.ts   # Message-related helpers
│   └── index.ts          # Package exports
├── migrations/           # Database migration files
└── tests/               # Database tests

Database Helpers

Message Helpers (src/helpers/messages.ts)

The message helpers provide clean abstractions for working with the messages table:

// Get raw LLM messages for a specific message ID
getRawLlmMessages(messageId: string): Promise<any>

// Get all messages for a chat
getMessagesForChat(chatId: string): Promise<Message[]>

// Get the latest message in a chat
getLatestMessageForChat(chatId: string): Promise<Message | null>

// Get completed messages for a chat
getCompletedMessagesForChat(chatId: string): Promise<Message[]>

// Get all raw LLM messages for an entire chat
getAllRawLlmMessagesForChat(chatId: string): Promise<{
  messageId: string;
  rawLlmMessages: any;
  createdAt: Date;
}[]>

Usage Examples

import { getRawLlmMessages, getAllRawLlmMessagesForChat } from '@buster/database';

// Fetch conversation history for a specific message
const conversationHistory = await getRawLlmMessages(messageId);

// Fetch all conversation histories for a chat
const allHistories = await getAllRawLlmMessagesForChat(chatId);

Key Tables

Messages Table

• id: UUID primary key
• chatId: Foreign key to chats table
• userId: Foreign key to users table
• rawLlmMessages: JSONB field storing conversation history (array of CoreMessage objects)
• requestMessage: User's request text
• responseMessages: Assistant's response (JSONB)
• reasoning: Reasoning steps (JSONB)
• isCompleted: Boolean flag
• createdAt, updatedAt, deletedAt: Timestamps

Best Practices

1. Use Helpers Over Direct Queries: Always prefer the helper functions over direct database queries for better maintainability
2. Handle Soft Deletes: The helpers automatically filter out soft-deleted records (where deletedAt is not null)
3. Type Safety: Use the exported types (Message, etc.) for type-safe operations
4. Error Handling: Helpers return null or empty arrays when no data is found

Development Commands

# Run database migrations
npm run db:migrate

# Generate TypeScript types from schema
npm run db:generate

# Run database tests
npm run test packages/database

Integration with AI Package

The database helpers are used by the AI package for managing conversation history:

1. During workflow execution, rawLlmMessages are saved to the database when a messageId is provided
2. The AI package's get-chat-history.ts uses these database helpers to fetch conversation history
3. This enables multi-turn conversations by retrieving previous message history

Example flow:

// In AI workflow
if (messageId) {
  // Save conversation history to database
  await saveConversationHistory(messageId, messages);
}

// Later, retrieve history
const history = await getRawLlmMessages(messageId);