Database

Neon PostgreSQL setup, Drizzle ORM migrations, and backup/restore procedures.

Database

Igris uses Neon PostgreSQL as its primary database, managed with Drizzle ORM for schema definitions and migrations.

Neon Setup

1. Create a Neon Project

Sign up at neon.tech and create a new project. Choose the region closest to your deployment.

2. Get the Connection String

From the Neon dashboard, copy the connection string:

postgresql://igris_user:[e-mail]/igris?sslmode=require

3. Set the Environment Variable

DATABASE_URL="postgresql://igris_user:[e-mail]/igris?sslmode=require"

Drizzle ORM

Igris uses Drizzle ORM for type-safe database access. Schema files define all tables in TypeScript.

Schema Overview

Key tables in the schema:

Table	Purpose
user	User accounts (Better Auth)
account	OAuth provider links
session	Active auth sessions
organization	Multi-tenant organizations
member	Organization membership with roles
mcp_servers	Registered MCP server configurations
policies	Governance policy rules
agent_sessions	Active proxy sessions
audit_events	Unified audit trail
baa	HIPAA BAA records
ai_systems	EU AI Act system registry
api_keys	Generated API keys

ID Strategy

All tables use TEXT-based IDs with prefixed nanoid generation (e.g., usr_abc123, org_def456, pol_ghi789). This provides:

• Human-readable IDs in logs and URLs
• No integer enumeration attacks
• Consistent format across all tables

Migrations

Automatic Migrations

Migrations run automatically on application startup using Drizzle’s migrate() function. When the API server boots:

1. Connects to the database
2. Checks for pending migrations
3. Applies any new migrations
4. Starts accepting requests

This means deploying a new version with schema changes automatically updates the database.

Manual Migration Commands

To generate or run migrations manually:

# Generate a new migration from schema changes
bun run db:generate

# Push schema directly (development only)
bun run db:push

# Open Drizzle Studio (database GUI)
bun run db:studio

Backup and Restore

Neon Point-in-Time Recovery (PITR)

Neon provides built-in Point-in-Time Recovery:

1. Go to your Neon project dashboard
2. Navigate to Branches
3. Click Create Branch and select a point in time
4. The new branch contains a complete copy of your database at that timestamp

This is useful for:

• Recovering from accidental data deletion
• Creating staging environments from production data
• Auditing historical state

Manual Backup

For portable backups, use pg_dump:

pg_dump "$DATABASE_URL" --format=custom --file=igris-backup.dump

Restore

pg_restore --dbname="$DATABASE_URL" --clean igris-backup.dump

Scaling

Neon PostgreSQL is serverless and auto-scales:

• Compute scales automatically based on query load
• Storage scales automatically as data grows
• Connections are pooled through Neon’s connection pooler

For high-throughput deployments, ensure your connection string uses Neon’s pooled endpoint (port 5432 with pooling enabled).

Alternative Databases

While Igris is optimized for Neon, any PostgreSQL-compatible database works. Set DATABASE_URL to your PostgreSQL instance. Minimum version: PostgreSQL 14.

If using a non-Neon PostgreSQL, you won’t have automatic PITR branching. Set up your own backup strategy.