@naisys/hub-database

← Back to packages | ← Back to main README

Prisma schema and generated client for the NAISYS hub database (the supervisor has its own DB — see @naisys/supervisor-database).

For the overall database strategy (Prisma rationale, the three schemas, migration flow, connection conventions), see doc 001 — Database Design.

Overview

This package provides:

• Prisma schema definitions for the hub database
• Generated Prisma Client for type-safe database access
• TypeScript types for all database models

Database Schema

Hub-owned tables:

• users / user_hosts / user_notifications - User accounts, host bindings, latest mail/log pointers
• hosts - Registered NAISYS host instances
• mail_messages / mail_recipients / mail_attachments - Flat (non-threaded) mail model (see doc 002)
• attachments - Generic attachment blobs (mail/chat, see doc 011)
• context_log - Agent conversation and activity logs
• run_session - Agent run sessions with timing, model, and cost info
• costs - API cost tracking with token usage
• models - Model metadata / pricing
• config_revisions - Agent/system config revision history
• variables - Shared variables
• schema_version - Schema version tracking for migrations

Development

Updating the Schema

If you need to update the database schema:

1. Update prisma/schema.prisma
2. Create a migration: npm run prisma:migrate (generates a SQL migration under prisma/migrations/)
3. Bump HUB_DB_VERSION in src/dbConfig.ts — on startup the hub compares this constant to the schema_version row and deploys pending migrations only when it's higher. If you skip this step, your new migration will not run in existing deployments.
4. Generate the new client: npm run prisma:generate
5. Build the package: npm run build

Reiniting the db for a breaking change

1. Delete the existing db files in NAISYS_FOLDER
2. Delete migration files
3. Run npm run prisma:migrate and enter name 'init' when prompted

Scripts

• npm run build - Generate Prisma Client and compile TypeScript
• npm run clean - Remove dist/
• npm run prisma:generate - Generate Prisma Client
• npm run prisma:migrate - Create a new migration (prisma migrate dev --create-only)

Environment Variables

• NAISYS_FOLDER - Path to NAISYS data folder (optional for client generation, required at runtime)

Type Exports

All Prisma types are exported for use in other packages:

import type {
  users,
  costs,
  context_log,
  mail_messages,
} from "@naisys/hub-database";

Notes

• The database path is configured dynamically at runtime
• Prisma DateTime fields are exposed as JavaScript Date values by the generated client; API/protocol layers serialize them as ISO strings where needed
• The Prisma Client is generated to src/generated/prisma/
• Foreign key constraints are enabled at runtime

License

MIT