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

docs: update schema documentation #7

Merged
kubrickcode merged 1 commit into from
Jan 24, 2026
Merged

docs: update schema documentation #7

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
7 changes: 7 additions & 0 deletions docs/schema/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
| [public.usage_events](public.usage_events.md) | 7 | | BASE TABLE |
| [public.subscription_plans](public.subscription_plans.md) | 7 | | BASE TABLE |
| [public.user_subscriptions](public.user_subscriptions.md) | 9 | | BASE TABLE |
| [public.behavior_caches](public.behavior_caches.md) | 4 | | BASE TABLE |

## Enums

Expand Down Expand Up @@ -321,6 +322,12 @@ erDiagram
timestamp_with_time_zone created_at
timestamp_with_time_zone updated_at
}
"public.behavior_caches" {
uuid id
bytea cache_key_hash
text converted_description
timestamp_with_time_zone created_at
}
```

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

## Description

Comment on lines +3 to +4
Copy link

@gemini-code-assist gemini-code-assist bot Jan 24, 2026

Choose a reason for hiding this comment

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

medium

The description for the behavior_caches table is missing. It's important to document the purpose of the table for future reference. Based on the pull request description, a good description would be to explain what this table caches and why.

Suggested change
## Description
## Description
Caches `test_name` → `behavior` conversion results in Phase 2 to reduce AI API call costs.

## Columns

| Name | Type | Default | Nullable | Children | Parents | Comment |
| --------------------- | ------------------------ | ----------------- | -------- | -------- | ------- | ------- |
| id | uuid | gen_random_uuid() | false | | | |
| cache_key_hash | bytea | | false | | | |
| converted_description | text | | false | | | |
| created_at | timestamp with time zone | now() | false | | | |
Comment on lines +7 to +12
Copy link

@gemini-code-assist gemini-code-assist bot Jan 24, 2026

Choose a reason for hiding this comment

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

medium

The column comments are missing. It would be very helpful to add comments explaining the purpose of each column, especially for cache_key_hash and converted_description.

For example, for cache_key_hash, you could add:

SHA-256 hash of (test_name + suite_path + file_path + language + model_id). Used as the cache key.

And for converted_description:

The cached behavior conversion result from the AI model.

Since this file is auto-generated, you might need to add these comments to the table definition in the database schema and regenerate the documentation.


## Constraints

| Name | Type | Definition |
| ---------------------- | ----------- | ----------------------- |
| behavior_caches_pkey | PRIMARY KEY | PRIMARY KEY (id) |
| uq_behavior_caches_key | UNIQUE | UNIQUE (cache_key_hash) |

## Indexes

| Name | Definition |
| ------------------------------ | ------------------------------------------------------------------------------------------------- |
| behavior_caches_pkey | CREATE UNIQUE INDEX behavior_caches_pkey ON public.behavior_caches USING btree (id) |
| uq_behavior_caches_key | CREATE UNIQUE INDEX uq_behavior_caches_key ON public.behavior_caches USING btree (cache_key_hash) |
| idx_behavior_caches_created_at | CREATE INDEX idx_behavior_caches_created_at ON public.behavior_caches USING btree (created_at) |

## Relations

```mermaid
erDiagram


"public.behavior_caches" {
uuid id
bytea cache_key_hash
text converted_description
timestamp_with_time_zone created_at
}
```

---

> Generated by [tbls](https://github.com/k1LoW/tbls)
66 changes: 66 additions & 0 deletions docs/schema/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2399,6 +2399,72 @@
"columns": ["id"]
}
]
},
{
"name": "public.behavior_caches",
"type": "BASE TABLE",
"columns": [
{
"name": "id",
"type": "uuid",
"nullable": false,
"default": "gen_random_uuid()"
},
{
"name": "cache_key_hash",
"type": "bytea",
"nullable": false
},
{
"name": "converted_description",
"type": "text",
"nullable": false
},
{
"name": "created_at",
"type": "timestamp with time zone",
"nullable": false,
"default": "now()"
}
],
"indexes": [
{
"name": "behavior_caches_pkey",
"def": "CREATE UNIQUE INDEX behavior_caches_pkey ON public.behavior_caches USING btree (id)",
"table": "public.behavior_caches",
"columns": ["id"]
},
{
"name": "uq_behavior_caches_key",
"def": "CREATE UNIQUE INDEX uq_behavior_caches_key ON public.behavior_caches USING btree (cache_key_hash)",
"table": "public.behavior_caches",
"columns": ["cache_key_hash"]
},
{
"name": "idx_behavior_caches_created_at",
"def": "CREATE INDEX idx_behavior_caches_created_at ON public.behavior_caches USING btree (created_at)",
"table": "public.behavior_caches",
"columns": ["created_at"]
}
],
"constraints": [
{
"name": "behavior_caches_pkey",
"type": "PRIMARY KEY",
"def": "PRIMARY KEY (id)",
"table": "public.behavior_caches",
"referenced_table": "",
"columns": ["id"]
},
{
"name": "uq_behavior_caches_key",
"type": "UNIQUE",
"def": "UNIQUE (cache_key_hash)",
"table": "public.behavior_caches",
"referenced_table": "",
"columns": ["cache_key_hash"]
}
]
}
Comment on lines +2403 to 2468
Copy link

@gemini-code-assist gemini-code-assist bot Jan 24, 2026

Choose a reason for hiding this comment

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

medium

The JSON schema definition for behavior_caches is missing comments for the table and its columns. Adding these comments in the database schema and regenerating this file would greatly improve maintainability.

  • A table comment should be added to clarify its purpose, e.g., "comment": "Caches test_name → behavior conversion results in Phase 2 to reduce AI API call costs."
  • Column comments are also important, especially for cache_key_hash to explain its composition: "comment": "SHA-256 hash of (test_name + suite_path + file_path + language + model_id). Used as the cache key."

],
"relations": [
Expand Down