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:
DomainTablesPurpose
Users & Auth7Authentication, sessions, SSH keys, tokens
Organizations4Orgs, teams, membership
Repositories5Repos, collaborators, stars, watches, branch protection
Pull Requests5PRs, reviews, comments, labels, reviewers
Issues10Issues, comments, labels, stages, relations, templates, views
Projects & Cycles5Project management, sprints
Merge Queue4Automated merge queue system
Stacks2Stacked diffs
Releases & Packages6Releases, npm registry
CI/CD3Workflow, job, step runs
AI & Agents6Agent sessions, triage config
Other5Activities, webhooks, notifications, journal

Technology Stack

// drizzle.config.ts
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: ['./src/db/schema.ts', './src/db/auth-schema.ts'],
  out: './src/db/migrations',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});
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).
ColumnTypeDescription
idtextPrimary key
nametextDisplay name
emailtextEmail address (unique)
email_verifiedbooleanWhether email is verified
imagetextProfile image URL
usernametextUsername (unique)
display_usernametextDisplay username with original casing
biotextUser biography
locationtextLocation
websitetextPersonal website URL
avatar_urltextAvatar URL
roletextRole: user, admin, superadmin
suspendedbooleanWhether account is suspended
suspended_attimestampWhen suspended
suspended_reasontextReason for suspension
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

session

User sessions for authentication.
ColumnTypeDescription
idtextPrimary key
expires_attimestampExpiration time
tokentextSession token (unique)
ip_addresstextClient IP address
user_agenttextClient user agent
user_idtextFK to user.id
created_attimestampCreation timestamp
updated_attimestampLast update timestamp
Indexes: session_userId_idx on user_id

account

OAuth provider accounts linked to users.
ColumnTypeDescription
idtextPrimary key
account_idtextProvider’s account ID
provider_idtextProvider name (github, google)
user_idtextFK to user.id
access_tokentextOAuth access token
refresh_tokentextOAuth refresh token
id_tokentextOIDC ID token
access_token_expires_attimestampToken expiration
refresh_token_expires_attimestampRefresh token expiration
scopetextGranted scopes
passwordtextPassword hash (for credentials auth)
created_attimestampCreation timestamp
updated_attimestampLast update timestamp
Indexes: account_userId_idx on user_id

ssh_keys

SSH public keys for Git operations.
ColumnTypeDescription
iduuidPrimary key
user_idtextFK to user.id
titletextUser-provided name
public_keytextSSH public key
fingerprinttextKey fingerprint (unique)
key_typetextKey algorithm (ssh-rsa, ssh-ed25519)
last_used_attimestampLast use time
created_attimestampCreation timestamp

personal_access_tokens

API tokens for programmatic access.
ColumnTypeDescription
iduuidPrimary key
user_idtextFK to user.id
nametextToken name (e.g., “CI Token”)
token_hashtextSHA256 hash of token
token_prefixtextFirst 8 chars for identification
scopestextJSON array of scopes
last_used_attimestampLast use time
expires_attimestampExpiration (null = never)
created_attimestampCreation timestamp
Available scopes: repo:read, repo:write, user:read, user:write, admin

email_preferences

User notification preferences.
ColumnTypeDescription
iduuidPrimary key
user_idtextFK to user.id (unique)
pr_assignedbooleanNotify on PR assignment
pr_review_requestedbooleanNotify on review request
pr_mentionedbooleanNotify on mention in PR
issue_assignedbooleanNotify on issue assignment
issue_mentionedbooleanNotify on mention in issue
repo_activitybooleanNotify on repo activity
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

Organizations

organizations

Organization accounts that can own repositories.
ColumnTypeDescription
iduuidPrimary key
nametextURL slug (unique)
display_nametextDisplay name
descriptiontextOrganization description
avatar_urltextAvatar URL
websitetextWebsite URL
locationtextLocation
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

org_members

Organization membership with roles.
ColumnTypeDescription
org_iduuidFK to organizations.id
user_idtextFK to user.id
roleenummember, admin, owner
created_attimestampJoin timestamp
Primary Key: (org_id, user_id)

teams

Teams within organizations.
ColumnTypeDescription
iduuidPrimary key
org_iduuidFK to organizations.id
nametextTeam name
descriptiontextTeam description
created_attimestampCreation timestamp

team_members

Team membership.
ColumnTypeDescription
team_iduuidFK to teams.id
user_idtextFK to user.id
created_attimestampJoin timestamp
Primary Key: (team_id, user_id)

Repositories

repositories

Git repositories.
ColumnTypeDescription
iduuidPrimary key
owner_idtextFK to user.id or organization.id
owner_typeenumuser or organization
nametextRepository name
descriptiontextDescription
is_privatebooleanPrivate repository
is_forkbooleanWhether this is a fork
forked_from_iduuidFK to parent repository
default_branchtextDefault branch (default: main)
stars_countintegerCached star count
forks_countintegerCached fork count
watchers_countintegerCached watcher count
open_issues_countintegerCached open issues
open_prs_countintegerCached open PRs
language_statsjsonbCached language statistics
language_stats_updated_attimestampWhen stats were updated
disk_pathtextFilesystem path to bare repo
created_attimestampCreation timestamp
updated_attimestampLast update timestamp
pushed_attimestampLast push timestamp

collaborators

Repository collaborators with permission levels.
ColumnTypeDescription
repo_iduuidFK to repositories.id
user_idtextFK to user.id
permissionenumread, write, admin
created_attimestampGrant timestamp
Primary Key: (repo_id, user_id)

stars

Repository stars.
ColumnTypeDescription
repo_iduuidFK to repositories.id
user_idtextFK to user.id
created_attimestampStar timestamp
Primary Key: (repo_id, user_id)

watches

Repository watch subscriptions.
ColumnTypeDescription
repo_iduuidFK to repositories.id
user_idtextFK to user.id
created_attimestampWatch timestamp
Primary Key: (repo_id, user_id)

branch_protection_rules

Branch protection configuration.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
patterntextBranch pattern (e.g., main, release/*)
require_pull_requestbooleanRequire PR for changes
required_reviewersintegerMinimum reviewer count
require_status_checksbooleanRequire CI checks
required_status_checkstextJSON array of check names
allow_force_pushbooleanAllow force push
allow_deletionbooleanAllow branch deletion
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

Pull Requests

pull_requests

Pull requests for code review.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
numberintegerPR number within repo
titletextPR title
bodytextPR description (markdown)
stateenumopen, closed, merged
source_branchtextSource branch name
target_branchtextTarget branch name
source_repo_iduuidFK for cross-repo PRs (forks)
head_shatextCurrent HEAD commit SHA
base_shatextTarget branch commit SHA
merge_shatextMerge commit SHA (when merged)
author_idtextFK to user.id
milestone_iduuidFK to milestones.id
stack_iduuidFK to stacks.id
is_draftbooleanDraft PR
is_mergeablebooleanComputed mergeability
merged_attimestampMerge timestamp
closed_attimestampClose timestamp
merged_by_idtextFK to user.id who merged
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

pr_reviews

Code reviews on pull requests.
ColumnTypeDescription
iduuidPrimary key
pr_iduuidFK to pull_requests.id
user_idtextFK to reviewer user.id
stateenumpending, approved, changes_requested, commented
bodytextReview summary
commit_shatextSHA that was reviewed
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

pr_comments

Comments on pull requests (inline and general).
ColumnTypeDescription
iduuidPrimary key
pr_iduuidFK to pull_requests.id
review_iduuidFK to pr_reviews.id (optional)
user_idtextFK to commenter user.id
pathtextFile path (for inline comments)
lineintegerLine number
sidetextLEFT or RIGHT for diff
commit_shatextCommit SHA for inline comment
start_lineintegerMulti-line comment start
end_lineintegerMulti-line comment end
bodytextComment body (markdown)
reply_to_iduuidFK for threaded replies
is_resolvedbooleanThread resolved
resolved_attimestampResolution timestamp
resolved_by_idtextFK to resolver user.id
suggestiontextCode suggestion
suggestion_appliedbooleanWhether suggestion was applied
suggestion_commit_shatextCommit where suggestion was applied
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

pr_reviewers

Requested reviewers for pull requests.
ColumnTypeDescription
iduuidPrimary key
pr_iduuidFK to pull_requests.id
user_idtextFK to requested reviewer
requested_by_idtextFK to user who requested
stateenumpending, completed, dismissed
requested_attimestampRequest timestamp
completed_attimestampCompletion timestamp
Unique Constraint: (pr_id, user_id)

pr_labels

Many-to-many: PRs to labels.
ColumnTypeDescription
pr_iduuidFK to pull_requests.id
label_iduuidFK to labels.id
Primary Key: (pr_id, label_id)

Issues

issues

Issue tracking with Linear-style workflow.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
numberintegerIssue number within repo
titletextIssue title
bodytextIssue description (markdown)
stateenumopen, closed
statusenumtriage, backlog, todo, in_progress, in_review, done, canceled
stage_iduuidFK to issue_stages.id (custom stages)
priorityenumnone, low, medium, high, urgent
due_datetimestampDue date
estimateintegerStory points or hours
author_idtextFK to author user.id
assignee_idtextFK to assignee user.id
parent_iduuidFK for sub-issues hierarchy
milestone_iduuidFK to milestones.id
project_iduuidFK to projects.id
cycle_iduuidFK to cycles.id
closed_attimestampClose timestamp
closed_by_idtextFK to closer user.id
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

issue_stages

Custom workflow stages per repository.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
keytextStage identifier (e.g., backlog)
nametextDisplay name
descriptiontextStage description
icontextEmoji or icon
colortextHex color
positionintegerOrder in workflow
is_closed_statebooleanMoving here closes issue
is_triage_statebooleanInitial triage state
is_defaultbooleanDefault for new issues
is_systembooleanCannot be deleted
created_attimestampCreation timestamp
updated_attimestampLast update timestamp
Unique Constraint: (repo_id, key)

issue_comments

Comments on issues.
ColumnTypeDescription
iduuidPrimary key
issue_iduuidFK to issues.id
user_idtextFK to commenter user.id
bodytextComment body (markdown)
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

labels

Labels for issues and PRs.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
nametextLabel name
colortextHex color
descriptiontextLabel description
created_attimestampCreation timestamp

issue_labels

Many-to-many: issues to labels.
ColumnTypeDescription
issue_iduuidFK to issues.id
label_iduuidFK to labels.id
Primary Key: (issue_id, label_id)

issue_relations

Dependencies between issues.
ColumnTypeDescription
iduuidPrimary key
issue_iduuidFK to source issue
related_issue_iduuidFK to related issue
typeenumblocks, blocked_by, relates_to, duplicates, duplicated_by
created_attimestampCreation timestamp
created_by_idtextFK to creator user.id
Unique Constraint: (issue_id, related_issue_id, type)

issue_activities

Audit log for issue changes.
ColumnTypeDescription
iduuidPrimary key
issue_iduuidFK to issues.id
actor_idtextFK to actor user.id
actiontextcreated, updated, status_changed, assigned, etc.
fieldtextChanged field name
old_valuetextPrevious value
new_valuetextNew value
metadatatextAdditional context (JSON)
created_attimestampActivity timestamp

issue_templates

Reusable issue templates.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
nametextTemplate name
descriptiontextTemplate description
title_templatetextDefault title
body_templatetextDefault body (markdown)
default_labelstextJSON array of label IDs
default_assignee_idtextDefault assignee
default_prioritytextDefault priority
default_statustextDefault status
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

issue_views

Saved filter configurations.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
creator_idtextFK to creator user.id
nametextView name
descriptiontextView description
filterstextJSON filter configuration
display_optionstextJSON: groupBy, sortBy, viewType
is_sharedbooleanShared with team
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

Projects & Cycles

projects

Linear-style projects containing multiple issues.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
nametextProject name
descriptiontextProject description
icontextEmoji or icon
colortextHex color
statusenumbacklog, planned, in_progress, paused, completed, canceled
lead_idtextFK to project lead user.id
start_datetimestampStart date
target_datetimestampTarget completion date
completed_attimestampActual completion date
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

project_members

Project team members.
ColumnTypeDescription
project_iduuidFK to projects.id
user_idtextFK to user.id
roletextlead or member
created_attimestampJoin timestamp
Primary Key: (project_id, user_id)

project_updates

Project status updates/check-ins.
ColumnTypeDescription
iduuidPrimary key
project_iduuidFK to projects.id
author_idtextFK to author user.id
bodytextUpdate content (markdown)
healthenumon_track, at_risk, off_track
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

cycles

Time-boxed iterations (sprints).
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
nametextCycle name (e.g., “Sprint 1”)
numberintegerAuto-incrementing number
descriptiontextCycle description
start_datetimestampStart date
end_datetimestampEnd date
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

milestones

Milestones for tracking progress.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
titletextMilestone title
descriptiontextMilestone description
due_datetimestampDue date
stateenumopen, closed
closed_attimestampClose timestamp
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

Merge Queue

merge_queue_config

Per-branch merge queue configuration.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
target_branchtextTarget branch (e.g., main)
enabledbooleanQueue enabled
strategyenumsequential, optimistic, adaptive
max_batch_sizeintegerMax PRs per batch
min_wait_secondsintegerWait time before processing
required_checkstextJSON array of check names
require_all_checksbooleanRequire all checks
auto_rebasebooleanAuto-rebase before merge
delete_branch_after_mergebooleanDelete source branch
auto_merge_modetextauto, manual, scheduled
merge_window_startintegerWindow start hour (UTC)
merge_window_endintegerWindow end hour (UTC)
merge_window_daystextJSON array of weekdays
created_attimestampCreation timestamp
updated_attimestampLast update timestamp
Unique Constraint: (repo_id, target_branch)

merge_queue_entries

PRs waiting in the merge queue.
ColumnTypeDescription
iduuidPrimary key
pr_iduuidFK to pull_requests.id
repo_iduuidFK to repositories.id
target_branchtextTarget branch
positionintegerQueue position
stateenumpending, preparing, testing, ready, merging, completed, failed, cancelled
priorityintegerHigher = more important
added_by_idtextFK to user who queued
head_shatextHEAD SHA when added
base_shatextBase SHA when added
speculative_merge_shatextTest merge commit
batch_iduuidFK to batch
touched_filestextJSON array of changed files
conflict_scoreintegerConflict likelihood (0-100)
error_messagetextError if failed
retry_countintegerRetry attempts
started_attimestampProcessing start
completed_attimestampCompletion time
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

merge_queue_batches

Batched merge operations.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
target_branchtextTarget branch
stateenumSame as entries
strategyenumBatch strategy used
merge_shatextFinal merge commit
commit_graphtextJSON commit graph
error_messagetextError if failed
completed_attimestampCompletion time
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

merge_queue_history

Audit log for queue actions.
ColumnTypeDescription
iduuidPrimary key
pr_iduuidFK to pull_requests.id
repo_iduuidFK to repositories.id
actiontextadded, removed, merged, failed, state_changed
actor_idtextFK to actor user.id
previous_stateenumState before action
new_stateenumState after action
metadatatextAdditional context (JSON)
created_attimestampAction timestamp

Stacks

stacks

Groups of dependent branches for stacked diffs.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
nametextStack name
descriptiontextStack description
base_branchtextBase branch (e.g., main)
author_idtextFK to author user.id
created_attimestampCreation timestamp
updated_attimestampLast update timestamp
Unique Constraint: (repo_id, name)

stack_branches

Ordered branches within a stack.
ColumnTypeDescription
iduuidPrimary key
stack_iduuidFK to stacks.id
branch_nametextBranch name
positionintegerOrder in stack (0 = closest to base)
pr_iduuidFK to pull_requests.id
created_attimestampCreation timestamp
Unique Constraint: (stack_id, branch_name)

Releases & Packages

releases

Git tag-based releases.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
tag_nametextGit tag name
nametextRelease name
bodytextRelease notes (markdown)
is_draftbooleanDraft release
is_prereleasebooleanPre-release
author_idtextFK to author user.id
published_attimestampPublish timestamp
created_attimestampCreation timestamp

release_assets

Files attached to releases.
ColumnTypeDescription
iduuidPrimary key
release_iduuidFK to releases.id
nametextFilename
content_typetextMIME type
sizeintegerSize in bytes
download_urltextDownload URL
download_countintegerDownload count
created_attimestampUpload timestamp

packages

npm package registry metadata.
ColumnTypeDescription
iduuidPrimary key
nametextPackage name
scopetextnpm scope (without @)
repo_iduuidFK to repositories.id
descriptiontextPackage description
visibilityenumpublic, private
keywordstextJSON array
licensetextLicense
homepagetextHomepage URL
readmetextREADME content
download_countintegerTotal downloads
deprecatedtextDeprecation message
publish_on_releasebooleanAuto-publish on release
created_attimestampCreation timestamp
updated_attimestampLast update timestamp
Unique Constraints: (scope, name), (repo_id)

package_versions

Published package versions.
ColumnTypeDescription
iduuidPrimary key
package_iduuidFK to packages.id
versiontextSemver version
tag_nametextGit tag
tarball_urltextDownload URL
tarball_sha512textIntegrity hash
tarball_sizeintegerSize in bytes
manifesttextpackage.json as JSON
dependenciestextJSON object
dev_dependenciestextJSON object
peer_dependenciestextJSON object
optional_dependenciestextJSON object
enginestextJSON object
bintextJSON object
published_bytextFK to user.id
deprecatedtextDeprecation message
download_countintegerVersion downloads
published_attimestampPublish timestamp
Unique Constraint: (package_id, version)

package_dist_tags

npm dist-tags (latest, beta, next).
ColumnTypeDescription
iduuidPrimary key
package_iduuidFK to packages.id
tagtextTag name
version_iduuidFK to package_versions.id
updated_attimestampLast update timestamp
Unique Constraint: (package_id, tag)

package_maintainers

Users who can publish to a package.
ColumnTypeDescription
package_iduuidFK to packages.id
user_idtextFK to user.id
added_attimestampGrant timestamp
added_bytextFK to granter user.id
Primary Key: (package_id, user_id)

CI/CD

workflow_runs

CI workflow executions.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
workflow_filetextWorkflow filename
workflow_nametextWorkflow name
stateenumqueued, in_progress, completed, failed, cancelled
conclusiontextsuccess, failure, cancelled
commit_shatextTrigger commit
branchtextBranch name
pr_iduuidFK to pull_requests.id
eventtextTrigger event (push, pull_request)
started_attimestampStart time
completed_attimestampCompletion time
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

job_runs

Jobs within a workflow run.
ColumnTypeDescription
iduuidPrimary key
workflow_run_iduuidFK to workflow_runs.id
nametextJob name
stateenumSame as workflow_runs
conclusiontextSame as workflow_runs
runner_nametextRunner that executed
logstextJob output logs
started_attimestampStart time
completed_attimestampCompletion time
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

step_runs

Steps within a job run.
ColumnTypeDescription
iduuidPrimary key
job_run_iduuidFK to job_runs.id
numberintegerStep number
nametextStep name
stateenumSame as workflow_runs
conclusiontextSame as workflow_runs
logstextStep output
started_attimestampStart time
completed_attimestampCompletion time
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

AI & Agents

agent_sessions

Coding agent sessions.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
user_idtextFK to user.id
titletextSession title
statustextactive, completed, cancelled
branchtextWorking branch
modetextpm or code
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

agent_file_changes

Proposed file changes from agent.
ColumnTypeDescription
iduuidPrimary key
session_iduuidFK to agent_sessions.id
pathtextFile path
operationtextcreate, update, delete
old_contenttextPrevious content
new_contenttextNew content
approvedbooleanUser approved
applied_attimestampApply timestamp
created_attimestampCreation timestamp

triage_agent_config

Auto-triage configuration per repo.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id (unique)
enabledbooleanTriage enabled
auto_labelbooleanAuto-apply labels
auto_assignbooleanAuto-assign issues
auto_prioritybooleanAuto-set priority
label_rulestextJSON labeling rules
assignment_rulestextJSON assignment rules
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

triage_agent_runs

Triage agent execution logs.
ColumnTypeDescription
iduuidPrimary key
config_iduuidFK to triage_agent_config.id
issue_iduuidFK to issues.id
labels_addedtextJSON array of label names
assignee_settextAssigned user ID
priority_settextSet priority
confidenceintegerConfidence score (0-100)
reasoningtextAI reasoning
created_attimestampRun timestamp

repo_ai_keys

Per-repository AI API keys.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
providertextAI provider (openai, anthropic)
encrypted_keytextEncrypted API key
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

user_ai_keys

Per-user AI API keys.
ColumnTypeDescription
iduuidPrimary key
user_idtextFK to user.id (unique)
providertextAI provider
encrypted_keytextEncrypted API key
created_attimestampCreation timestamp
updated_attimestampLast update timestamp

Other

activities

Activity feed events.
ColumnTypeDescription
iduuidPrimary key
actor_idtextFK to user.id
repo_iduuidFK to repositories.id
typetextEvent type (push, pr_opened, etc.)
payloadtextJSON event data
created_attimestampEvent timestamp

webhooks

Repository webhooks.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
urltextWebhook URL
secrettextHMAC secret
eventstextJSON array of event types
is_activebooleanWebhook enabled
created_attimestampCreation timestamp
updated_attimestampLast update timestamp
Webhook events: push, pull_request, pull_request_review, issue, issue_comment, create, delete, fork, star

notifications

User notifications.
ColumnTypeDescription
iduuidPrimary key
user_idtextFK to recipient user.id
actor_idtextFK to actor user.id
typetextNotification type
repo_iduuidFK to repositories.id
issue_iduuidFK to issues.id
pr_iduuidFK to pull_requests.id
titletextNotification title
bodytextNotification body
readbooleanRead status
read_attimestampRead timestamp
created_attimestampCreation timestamp

journal_pages

Notion-like documentation pages.
ColumnTypeDescription
iduuidPrimary key
repo_iduuidFK to repositories.id
titletextPage title
slugtextURL slug
contenttextPage content (markdown)
statustextdraft, published, archived
author_idtextFK to author user.id
parent_iduuidFK for hierarchy
positionintegerSort order
created_attimestampCreation timestamp
updated_attimestampLast update timestamp
published_attimestampPublish timestamp

wrapped

Monthly activity insights (Spotify Wrapped-style).
ColumnTypeDescription
iduuidPrimary key
user_idtextFK to user.id
yearintegerYear
monthintegerMonth (1-12)
datatextJSON insights data
created_attimestampGeneration timestamp
Unique Constraint: (user_id, year, month)

Enums Reference

-- Owner type
CREATE TYPE owner_type AS ENUM ('user', 'organization');

-- PR state
CREATE TYPE pr_state AS ENUM ('open', 'closed', 'merged');

-- Issue state
CREATE TYPE issue_state AS ENUM ('open', 'closed');

-- Issue status (Kanban)
CREATE TYPE issue_status AS ENUM (
  'triage', 'backlog', 'todo', 'in_progress',
  'in_review', 'done', 'canceled'
);

-- Issue priority
CREATE TYPE issue_priority AS ENUM (
  'none', 'low', 'medium', 'high', 'urgent'
);

-- Issue relation type
CREATE TYPE issue_relation_type AS ENUM (
  'blocks', 'blocked_by', 'relates_to',
  'duplicates', 'duplicated_by'
);

-- Project status
CREATE TYPE project_status AS ENUM (
  'backlog', 'planned', 'in_progress',
  'paused', 'completed', 'canceled'
);

-- Project health
CREATE TYPE project_health AS ENUM (
  'on_track', 'at_risk', 'off_track'
);

-- Milestone state
CREATE TYPE milestone_state AS ENUM ('open', 'closed');

-- Review state
CREATE TYPE review_state AS ENUM (
  'pending', 'approved', 'changes_requested', 'commented'
);

-- Permission level
CREATE TYPE permission AS ENUM ('read', 'write', 'admin');

-- Organization role
CREATE TYPE org_role AS ENUM ('member', 'admin', 'owner');

-- Workflow run state
CREATE TYPE workflow_run_state AS ENUM (
  'queued', 'in_progress', 'completed', 'failed', 'cancelled'
);

-- Merge queue state
CREATE TYPE merge_queue_state AS ENUM (
  'pending', 'preparing', 'testing', 'ready',
  'merging', 'completed', 'failed', 'cancelled'
);

-- Merge queue strategy
CREATE TYPE merge_queue_strategy AS ENUM (
  'sequential', 'optimistic', 'adaptive'
);

-- Review request state
CREATE TYPE review_request_state AS ENUM (
  'pending', 'completed', 'dismissed'
);

-- Package visibility
CREATE TYPE package_visibility AS ENUM ('public', 'private');

Migration Guide

wit uses Drizzle Kit for database migrations.

Creating Migrations

# Generate migration from schema changes
npx drizzle-kit generate

# This creates a new file in src/db/migrations/
# e.g., 0018_new_feature.sql

Running Migrations

# Apply all pending migrations
npx drizzle-kit migrate

# Or push schema directly (development only)
npx drizzle-kit push

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:
-- Create a down migration manually
-- 0018_rollback_new_feature.sql

ALTER TABLE my_table DROP COLUMN new_column;

Query Patterns

Common Patterns

Find with relationships:
// Get PR with author
const result = await db
  .select()
  .from(pullRequests)
  .innerJoin(user, eq(pullRequests.authorId, user.id))
  .where(eq(pullRequests.id, prId));
Conditional filtering:
const conditions = [eq(issues.repoId, repoId)];

if (state) {
  conditions.push(eq(issues.state, state));
}

if (assigneeId) {
  conditions.push(eq(issues.assigneeId, assigneeId));
}

const result = await db
  .select()
  .from(issues)
  .where(and(...conditions));
Counter updates (preventing negative values):
await db
  .update(repositories)
  .set({
    starsCount: sql`GREATEST(0, ${repositories.starsCount} + ${delta})`,
  })
  .where(eq(repositories.id, repoId));
Pagination:
const result = await db
  .select()
  .from(issues)
  .where(eq(issues.repoId, repoId))
  .orderBy(desc(issues.createdAt))
  .limit(limit)
  .offset(offset);

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