Skip to content
This repository was archived by the owner on Feb 17, 2026. It is now read-only.

docs: update schema documentation #9

Merged
kubrickcode merged 1 commit into from
Feb 1, 2026
Merged

docs: update schema documentation #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/schema/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
| [public.user_subscriptions](public.user_subscriptions.md) | 9 | | BASE TABLE |
| [public.behavior_caches](public.behavior_caches.md) | 4 | | BASE TABLE |
| [public.classification_caches](public.classification_caches.md) | 7 | | BASE TABLE |
| [public.quota_reservations](public.quota_reservations.md) | 7 | | BASE TABLE |

## Enums

Expand Down Expand Up @@ -79,6 +80,7 @@ erDiagram
"public.usage_events" }o--o| "public.spec_documents" : "FOREIGN KEY (document_id) REFERENCES spec_documents(id) ON DELETE SET NULL"
"public.user_subscriptions" }o--|| "public.users" : "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"
"public.user_subscriptions" }o--|| "public.subscription_plans" : "FOREIGN KEY (plan_id) REFERENCES subscription_plans(id) ON DELETE RESTRICT"
"public.quota_reservations" }o--|| "public.users" : "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"

"atlas_schema_revisions.atlas_schema_revisions" {
varchar version
Expand Down Expand Up @@ -338,6 +340,15 @@ erDiagram
jsonb test_index_map
timestamp_with_time_zone created_at
}
"public.quota_reservations" {
uuid id
uuid user_id FK
usage_event_type event_type
integer reserved_amount
bigint job_id
timestamp_with_time_zone expires_at
timestamp_with_time_zone created_at
}
```

---
Expand Down
65 changes: 65 additions & 0 deletions docs/schema/public.quota_reservations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# public.quota_reservations

## Description

Copy link

@gemini-code-assist gemini-code-assist bot Feb 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The Description section for the new quota_reservations table is empty. Adding a brief explanation of the table's purpose would significantly improve the documentation's clarity, especially for new developers. You could use information from the pull request description to explain how this table helps prevent race conditions in quota management.

Suggested change
Stores temporary reservations for quota-consuming operations to prevent race conditions and quota overflows from concurrent requests. A reservation is created when a job is requested and is consumed or expires after the job completes or times out.

## Columns

| Name | Type | Default | Nullable | Children | Parents | Comment |
| --------------- | ------------------------ | ------------------------------ | -------- | -------- | ------------------------------- | ------- |
| id | uuid | gen_random_uuid() | false | | | |
| user_id | uuid | | false | | [public.users](public.users.md) | |
| event_type | usage_event_type | | false | | | |
| reserved_amount | integer | | false | | | |
| job_id | bigint | | false | | | |
| expires_at | timestamp with time zone | (now() + '01:00:00'::interval) | false | | | |
| created_at | timestamp with time zone | now() | false | | | |
Comment on lines +9 to +15
Copy link

@gemini-code-assist gemini-code-assist bot Feb 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The Comment column is empty for all fields in the quota_reservations table. Adding comments to explain the purpose of each field would improve the documentation's clarity. Since this is auto-generated documentation, you might need to add these comments in the database schema itself so they are picked up by tbls on the next run.

For example:

  • job_id: "The ID of the background job (e.g., from River) that this reservation is for."
  • reserved_amount: "The estimated quota amount reserved for the operation."
  • expires_at: "Timestamp when the reservation becomes invalid and can be cleaned up if the job is orphaned."


## Constraints

| Name | Type | Definition |
| ---------------------------- | ----------- | ------------------------------------------------------------ |
| chk_reserved_amount_positive | CHECK | CHECK ((reserved_amount > 0)) |
| fk_quota_reservations_user | FOREIGN KEY | FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE |
| quota_reservations_pkey | PRIMARY KEY | PRIMARY KEY (id) |
| uq_quota_reservations_job_id | UNIQUE | UNIQUE (job_id) |

## Indexes

| Name | Definition |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| quota_reservations_pkey | CREATE UNIQUE INDEX quota_reservations_pkey ON public.quota_reservations USING btree (id) |
| uq_quota_reservations_job_id | CREATE UNIQUE INDEX uq_quota_reservations_job_id ON public.quota_reservations USING btree (job_id) |
| idx_quota_reservations_expires | CREATE INDEX idx_quota_reservations_expires ON public.quota_reservations USING btree (expires_at) |
| idx_quota_reservations_user_event | CREATE INDEX idx_quota_reservations_user_event ON public.quota_reservations USING btree (user_id, event_type) |

## Relations

```mermaid
erDiagram

"public.quota_reservations" }o--|| "public.users" : "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"

"public.quota_reservations" {
uuid id
uuid user_id FK
usage_event_type event_type
integer reserved_amount
bigint job_id
timestamp_with_time_zone expires_at
timestamp_with_time_zone created_at
}
"public.users" {
uuid id
varchar_255_ email
varchar_255_ username
text avatar_url
timestamp_with_time_zone last_login_at
timestamp_with_time_zone created_at
timestamp_with_time_zone updated_at
integer token_version
}
```

---

> Generated by [tbls](https://github.com/k1LoW/tbls)
Loading