Overview
The database contains 50+ tables organized into these domains:Technology Stack
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 operationssrc/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
- Never modify existing migrations - Create new ones instead
- Test migrations locally before deploying
- Use transactions for complex changes
- Add indexes for foreign keys and frequently queried columns
- 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:Performance Tips
- Use indexes for frequently filtered columns
- Avoid N+1 queries - Use joins or batch queries
- Cache counts - Use denormalized counters (stars_count, etc.)
- Limit result sets - Always use pagination
- Use connection pooling - Configure pool size appropriately
Related Documentation
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