@novahelm/db

Database package for NovaHelm — the connection wrapper and core schemas. Provides the client factory, the 60+ core platform tables, pgvector support, seed functions, and the migration runner.

Note on the ORM. This package historically wrapped Drizzle. Drizzle is being removed from the platform — new schemas must be declared with defineModel() from @novahelm/engine (see packages/engine/src/PATTERNS.md). The Drizzle APIs documented below survive only to serve the remaining core schemas while they are migrated; treat them as deprecated for new code.

Quick Start

pnpm add @novahelm/db

import { createDb } from "@novahelm/db";
import { initNova } from "@novahelm/core";

// 1. Create the database client
const db = createDb({ databaseUrl: env.DATABASE_URL });

// 2. Register with the Nova registry
initNova({ db, redis, auth, logger, config });

Then retrieve it anywhere:

import { getDb } from "@novahelm/core";
import type { NovaDb } from "@novahelm/db";

const db = getDb<NovaDb>();
const user = await db.query.users.findFirst({
  where: (u, { eq }) => eq(u.id, userId),
});

createDb Options

import { createDb } from "@novahelm/db";

const db = createDb({
  // Required: full PostgreSQL connection string
  databaseUrl: "postgres://user:pass@host:5432/mydb",

  // Optional: connection pool size (default: 20)
  max: 10,

  // Optional: log all SQL queries (default: false, dev only)
  logger: true,
});

| Option | Type | Default | Description | |--------|------|---------|-------------| | databaseUrl | string | -- | PostgreSQL connection string (required) | | max | number | 20 | Max connections in pool | | logger | boolean | false | Log SQL queries to stdout |

Schema

The package exports all Drizzle pgTable definitions. Consumers re-export them alongside their own extension tables:

// In your project's schema.ts
export * from "@novahelm/db/schema";
export * from "./my-extensions";

Schema Groups

Import via @novahelm/db/schema or from the main entry point:

| Group | Tables | |-------|--------| | Auth | users, sessions, accounts, verificationTokens | | RBAC | roles, rolePermissions, userRoles | | Tenants | tenants, tenantMembers | | Billing | subscriptions, billingEvents | | Commerce | products, productVariants, collections, productCollections, inventoryLevels, orders, orderItems, cart, cartItems, discounts, shippingZones, shippingRates, reviews | | Content | posts | | Media | media, mediaUsages | | AI | embeddings, conversations, messages | | Data Sources | dataSources, dataSyncLog | | Analytics | analyticsEvents, analyticsDaily, analyticsFunnels | | Engagement | contentSubscriptions, userInteractions, userPersonas, contentRelations, contentTags, pendingDigestItems, emailCampaigns, campaignSends | | Experiments | experiments, experimentAssignments, experimentConversions | | Remote Config | remoteConfigs, remoteConfigOverrides | | System | apiKeys, notifications, pushTokens, auditLog, featureFlags, feedback, onboardingProgress, notificationPreferences, accountDeletionRequests | | System Health | systemProbes, systemAlerts | | Performance | perfEvents, perfAggregates | | Relations | All Drizzle relations() definitions |

pgvector Support

The schema includes pgvector columns for AI embedding storage:

import { EMBEDDING_DIMENSIONS } from "@novahelm/db";

// Default: 1536 dimensions (OpenAI text-embedding-3-small)
// Change this constant when switching embedding models

Vector similarity helpers:

import { cosineSimilarity, l2Distance } from "@novahelm/db";

// Use in Drizzle queries for semantic search
const results = await db
  .select()
  .from(embeddings)
  .orderBy(cosineSimilarity(embeddings.vector, queryVector))
  .limit(10);

Seeding

Seed the database with default roles, permissions, admin user, feature flags, and sample content:

import { seedCore } from "@novahelm/db";

await seedCore(db, {
  // Optional: custom password hasher (uses bcrypt by default)
  hashPassword: async (password) => {
    return await hash(password);
  },
});

The seed creates:

• 4 roles: Admin, Moderator, User, Viewer (with permissions)
• 1 admin user: [email protected] / admin123
• Default feature flags
• Sample content

Migrations

Run pending Drizzle migrations at consumer app startup:

import { runProjectMigrations } from "@novahelm/db";

// Call before accepting requests
await runProjectMigrations(env.DATABASE_URL);

Migration files are bundled in the drizzle/ folder of the published package.

For development, use the CLI:

novahelm db push     # Push schema changes to dev database
novahelm db seed     # Run seedCore()
novahelm db studio   # Open Drizzle Studio

Subpath Exports

| Import Path | Description | |-------------|-------------| | @novahelm/db | Main entry: createDb, schemas, helpers, seed, migrations | | @novahelm/db/schema | Schema-only: all table definitions and relations |

API Reference

| Export | Description | |--------|-------------| | DB_VERSION | Current package version (CalVer) | | EMBEDDING_DIMENSIONS | Vector dimensions constant (default: 1536) | | createDb(options) | Create a Drizzle ORM database client | | NovaDb | Fully-typed Drizzle database type | | CreateDbOptions | Options for createDb() | | cosineSimilarity(col, vec) | Cosine similarity SQL helper | | l2Distance(col, vec) | L2 distance SQL helper | | seedCore(db, options?) | Seed database with defaults | | SeedOptions | Seed configuration type | | runProjectMigrations(url) | Run pending Drizzle migrations | | users, sessions, posts, ... | All Drizzle table definitions |