Skip to main content
wit uses PostgreSQL with Drizzle ORM for type-safe database access. This document provides a complete reference to the data model.

Overview

The database contains 50+ tables organized into these domains:

Technology Stack

Key files:
  • src/db/schema.ts - Main schema definitions (50+ tables)
  • src/db/auth-schema.ts - better-auth tables (user, session, account, verification)
  • src/db/models/*.ts - Data access layer with CRUD operations
  • src/db/migrations/ - SQL migration files

Entity Relationship Diagram


Users & Auth

wit uses better-auth for authentication, which creates the core user tables.

user

The primary user table (managed by better-auth).

session

User sessions for authentication. Indexes: session_userId_idx on user_id

account

OAuth provider accounts linked to users. Indexes: account_userId_idx on user_id

ssh_keys

SSH public keys for Git operations.

personal_access_tokens

API tokens for programmatic access. Available scopes: repo:read, repo:write, user:read, user:write, admin

email_preferences

User notification preferences.

Organizations

organizations

Organization accounts that can own repositories.

org_members

Organization membership with roles. Primary Key: (org_id, user_id)

teams

Teams within organizations.

team_members

Team membership. Primary Key: (team_id, user_id)

Repositories

repositories

Git repositories.

collaborators

Repository collaborators with permission levels. Primary Key: (repo_id, user_id)

stars

Repository stars. Primary Key: (repo_id, user_id)

watches

Repository watch subscriptions. Primary Key: (repo_id, user_id)

branch_protection_rules

Branch protection configuration.

Pull Requests

pull_requests

Pull requests for code review.

pr_reviews

Code reviews on pull requests.

pr_comments

Comments on pull requests (inline and general).

pr_reviewers

Requested reviewers for pull requests. Unique Constraint: (pr_id, user_id)

pr_labels

Many-to-many: PRs to labels. Primary Key: (pr_id, label_id)

Issues

issues

Issue tracking with Linear-style workflow.

issue_stages

Custom workflow stages per repository. Unique Constraint: (repo_id, key)

issue_comments

Comments on issues.

labels

Labels for issues and PRs.

issue_labels

Many-to-many: issues to labels. Primary Key: (issue_id, label_id)

issue_relations

Dependencies between issues. Unique Constraint: (issue_id, related_issue_id, type)

issue_activities

Audit log for issue changes.

issue_templates

Reusable issue templates.

issue_views

Saved filter configurations.

Projects & Cycles

projects

Linear-style projects containing multiple issues.

project_members

Project team members. Primary Key: (project_id, user_id)

project_updates

Project status updates/check-ins.

cycles

Time-boxed iterations (sprints).

milestones

Milestones for tracking progress.

Merge Queue

merge_queue_config

Per-branch merge queue configuration. Unique Constraint: (repo_id, target_branch)

merge_queue_entries

PRs waiting in the merge queue.

merge_queue_batches

Batched merge operations.

merge_queue_history

Audit log for queue actions.

Stacks

stacks

Groups of dependent branches for stacked diffs. Unique Constraint: (repo_id, name)

stack_branches

Ordered branches within a stack. Unique Constraint: (stack_id, branch_name)

Releases & Packages

releases

Git tag-based releases.

release_assets

Files attached to releases.

packages

npm package registry metadata. Unique Constraints: (scope, name), (repo_id)

package_versions

Published package versions. Unique Constraint: (package_id, version)

package_dist_tags

npm dist-tags (latest, beta, next). Unique Constraint: (package_id, tag)

package_maintainers

Users who can publish to a package. Primary Key: (package_id, user_id)

CI/CD

workflow_runs

CI workflow executions.

job_runs

Jobs within a workflow run.

step_runs

Steps within a job run.

AI & Agents

agent_sessions

Coding agent sessions.

agent_file_changes

Proposed file changes from agent.

triage_agent_config

Auto-triage configuration per repo.

triage_agent_runs

Triage agent execution logs.

repo_ai_keys

Per-repository AI API keys.

user_ai_keys

Per-user AI API keys.

Other

activities

Activity feed events.

webhooks

Repository webhooks. Webhook events: push, pull_request, pull_request_review, issue, issue_comment, create, delete, fork, star

notifications

User notifications.

journal_pages

Notion-like documentation pages.

wrapped

Monthly activity insights (Spotify Wrapped-style). Unique Constraint: (user_id, year, month)

Enums Reference


Migration Guide

wit uses Drizzle Kit for database migrations.

Creating Migrations

Running Migrations

Migration Best Practices

  1. Never modify existing migrations - Create new ones instead
  2. Test migrations locally before deploying
  3. Use transactions for complex changes
  4. Add indexes for foreign keys and frequently queried columns
  5. Consider backwards compatibility - Add columns as nullable first

Rollback Strategy

Drizzle doesn’t support automatic rollbacks. For manual rollbacks:

Query Patterns

Common Patterns

Find with relationships:
Conditional filtering:
Counter updates (preventing negative values):
Pagination:

Performance Tips

  1. Use indexes for frequently filtered columns
  2. Avoid N+1 queries - Use joins or batch queries
  3. Cache counts - Use denormalized counters (stars_count, etc.)
  4. Limit result sets - Always use pagination
  5. Use connection pooling - Configure pool size appropriately

Architecture Overview

How wit’s components fit together

API Reference

tRPC API documentation

Events System

Event-driven notifications

Self-Hosting

Deploy your own wit instance