Skip to main content
VulnTrack uses PostgreSQL as its primary database with Prisma ORM for schema management and migrations.

​
Prerequisites

1

Install PostgreSQL

VulnTrack requires PostgreSQL 12 or higher.macOS:
brew install postgresql@16
brew services start postgresql@16
Ubuntu/Debian:
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
Docker:
docker run -d \
  --name vulntrack-db \
  -e POSTGRES_PASSWORD=secure_password \
  -e POSTGRES_USER=vulntrack_user \
  -e POSTGRES_DB=vulntrack \
  -p 5432:5432 \
  postgres:16-alpine
2

Create database

Connect to PostgreSQL and create the VulnTrack database:
# Using psql
psql -U postgres

CREATE DATABASE vulntrack;
CREATE USER vulntrack_user WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE vulntrack TO vulntrack_user;
3

Configure connection string

Add the database connection string to your .env file:
.env
DATABASE_URL="postgresql://vulntrack_user:secure_password@localhost:5432/vulntrack"
For production, use SSL-enabled connections: postgresql://user:password@host:5432/db?sslmode=require

​
Schema Initialization

VulnTrack uses Prisma to manage the database schema.
1

Generate Prisma Client

Generate the Prisma client based on prisma/schema.prisma:
npx prisma generate
This creates the TypeScript client for database queries.
2

Push schema to database

Initialize the database with the current schema:
npx prisma db push
This creates all tables, relations, and indexes defined in the Prisma schema.
db push is recommended for development. For production, use migrations (see below).
3

Verify setup

Check that tables were created successfully:
npx prisma studio
This opens a browser-based database viewer at http://localhost:5555.

​
Database Schema

VulnTrack’s schema includes the following core models:

​
User Management

  • User - User accounts with role-based access control (ADMIN, ANALYST, VIEWER)
  • Team - Multi-tenant team workspaces
  • Invitation - Time-limited invitation tokens for secure onboarding

​
Vulnerability Tracking

  • Vulnerability - Core vulnerability records with CVE data
  • DreadScore - DREAD risk assessment scores
  • StrideScore - STRIDE threat modeling flags
  • Comment - Collaboration threads on vulnerabilities

​
Audit & Notifications

  • AuditLog - Comprehensive activity tracking
  • Notification - In-app notification system
View the full schema at prisma/schema.prisma in your installation.

​
Migrations

For production deployments, use Prisma migrations instead of db push.
1

Check migration status

View applied migrations:
npx prisma migrate status
2

Apply migrations

Run pending migrations:
npx prisma migrate deploy
This applies migrations from prisma/migrations/ in order.
3

Create new migration (development)

After modifying schema.prisma, create a new migration:
npx prisma migrate dev --name description_of_changes
This generates SQL migration files and applies them to your database.

​
Package.json Scripts

VulnTrack includes these database-related scripts:
​
build
script
npx prisma generate && npx prisma db push --accept-data-loss && next build
Generates Prisma client, pushes schema, and builds the Next.js application.
​
postinstall
script
prisma generate
Automatically generates Prisma client after npm install.

​
Seeding Data

To populate the database with initial data:
1

Check for seed script

If a prisma/seed.ts or seed.js file exists:
npx prisma db seed
This typically creates:
  • An initial admin user
  • Sample vulnerability data
  • Default team configuration
2

Manual admin creation

If no seed script exists, create the first admin user through the registration flow.The first registered user automatically receives ADMIN privileges.

​
Backup & Restore

​
Backup Database

pg_dump -U vulntrack_user -h localhost vulntrack > backup.sql

​
Restore Database

psql -U vulntrack_user -h localhost vulntrack < backup.sql

​
Troubleshooting

Symptoms: Error: connect ECONNREFUSED 127.0.0.1:5432Solutions:
  • Verify PostgreSQL is running: pg_isready
  • Check port availability: lsof -i :5432
  • Ensure DATABASE_URL matches your PostgreSQL configuration
Symptoms: Error: password authentication failed for userSolutions:
  • Verify credentials in DATABASE_URL
  • Check pg_hba.conf authentication method (should be md5 or scram-sha-256)
  • Reset user password in PostgreSQL: ALTER USER vulntrack_user WITH PASSWORD 'new_password';
Symptoms: Error: Migration failed to applySolutions:
  • Reset migration history: npx prisma migrate resolve --applied <migration_name>
  • For development, reset database: npx prisma migrate reset (WARNING: deletes all data)
  • For production, manually resolve conflicts and mark as applied
Symptoms: Warning: Database schema is out of syncSolutions:
  • Development: Run npx prisma db push or create a new migration
  • Production: Always use prisma migrate deploy to apply migrations
Production Warning: Never use prisma db push or prisma migrate reset in production. These commands can cause data loss. Always use prisma migrate deploy for production deployments.

Build docs developers (and LLMs) love

Get started for freeTalk to us