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:password@ep-cool-name.us-east-2.aws.neon.tech/igris?sslmode=require
3. Set the Environment Variable
DATABASE_URL="postgresql://igris_user:password@ep-cool-name.us-east-2.aws.neon.tech/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:
- Connects to the database
- Checks for pending migrations
- Applies any new migrations
- 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:
- Go to your Neon project dashboard
- Navigate to Branches
- Click Create Branch and select a point in time
- 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.
