Database

The database service, managed within the packages/db directory (as @workspace/db), stores data essential for both core application functions and AI features. It ensures that information like user profiles, conversation history, and AI-generated content is reliably preserved and efficiently accessed.

Technology

We've chosen PostgreSQL as our primary relational database for its exceptional reliability, extensibility (including powerful tools like pgvector for similarity searches), and proven track record in production environments.

Database interactions are handled through Drizzle ORM, a cutting-edge TypeScript ORM that offers outstanding type safety (generating types directly from your schema), high performance, and a developer-friendly API.

For detailed guidance on setup, configuration, schema management (including migrations), and general usage patterns of Drizzle and PostgreSQL in the TurboStarter ecosystem, check out our core documentation:

What is stored in the database?

Beyond standard application data (like users and accounts), the database plays a crucial role in storing AI-specific information:

• Chat history: stores conversations between users and AI models, including rich message parts (for example attachments, tool output parts) and token usage for billing/analytics
• Vector embeddings: stores numerical representations (vectors) of text data (like document chunks) that power Retrieval-Augmented Generation (RAG) techniques, allowing features like Knowledge RAG to quickly find relevant context from large document collections
• Document references: tracks metadata and storage identifiers (paths in Blob Storage) for user-uploaded files used in RAG
• Image generations: stores prompts, settings, and generated image URLs for the Image playground
• Credits: keeps track of each user's remaining credits (used by the middleware to gate AI operations)

Schema

The core database schema, defined in packages/db/src/schema, contains essential tables for the overall application (users, accounts, sessions, etc.).

To maintain clarity as AI features grow, AI module tables are grouped into dedicated PostgreSQL schemas using Drizzle's pgSchema, for example:

• chat.* for the Chat demo (chats, messages, message parts, usage)
• rag.* for the Knowledge RAG demo (chats, messages, documents, embeddings)
• image.* for the Image playground demo (generations, images)

This logical separation helps manage complexity and isolates feature-specific data structures. You'll typically find AI-specific schema definitions either alongside the relevant demo app code or within the main packages/db/src/schema directory, clearly labeled and organized.