Skip to content

Commit 6213077

Browse files
committed
update database documentation based on new schema
1 parent 89aafd3 commit 6213077

1 file changed

Lines changed: 75 additions & 35 deletions

File tree

DATABASE.md

Lines changed: 75 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -4,74 +4,114 @@
44

55
_CatDat_ is based on a [SQLite database](https://sqlite.org/). During runtime of the application, it is read-only.
66

7-
The local copy of the database is located at `/databases/catdat/catdat.db`. It has three main tables:
7+
The local copy of the database is located at `/databases/catdat/catdat.db`. It contains three main tables:
8+
9+
- `structures`
10+
- `properties`
11+
- `implications`
12+
13+
The `structures` table stores data that is common to all types of categorical structures. Two types are currently supported: categories and functors. They are stored in the following table:
14+
15+
- `structure_types`
16+
17+
Structure-specific data is stored in additional tables, such as:
818

919
- `categories`
10-
- `category_properties`
11-
- `category_implications`
20+
- `functors`
1221

13-
To associate properties with categories (satisfied or not), there is a table:
22+
Properties (whether satisfied or not) are associated with categorical structures via the following table:
1423

15-
- `category_property_assignments`
24+
- `property_assignments`
1625

1726
To mark properties as assumptions or conclusions of an implication, there are two tables:
1827

19-
- `category_implication_assumptions`
20-
- `category_implication_conclusions`
28+
- `assumptions`
29+
- `conclusions`
2130

22-
But they are abstracted away by using the view `category_implications_view`.
31+
These tables are abstracted through the `implications_view` view.
2332

24-
Further tables are:
33+
Functor implications may also depend on properties of the source or target category. Such dependencies are stored in the following tables:
2534

26-
- `category_tags`
27-
- `category_tag_assignments`
28-
- `related_categories`
29-
- `relations`
30-
- `special_object_types`
31-
- `special_objects`
32-
- `special_morphism_types`
33-
- `special_morphisms`
34-
- `related_category_properties`
35-
- `category_comments`
35+
- `source_assumptions`
36+
- `target_assumptions`
3637

37-
For functors there are similar tables, such as:
38-
39-
- `functors`
40-
- `functor_properties`
41-
- `functor_implications`
42-
- `functor_property_assignments`
38+
Additional tables are available. For a complete overview, see the diagram below.
4339

4440
## Schema vs. Data
4541

46-
The schema defines the structure of the database: tables, views, indexes, and triggers. It is specified in several SQL files located in the subfolder [/databases/catdat/schema](/databases/catdat/schema/). The command `pnpm db:setup` deletes the old database file (if it exists) and creates a new one using this schema. This is required when the schema changes, so it is recommended to run it periodically.
42+
The schema defines the structure of the database: tables, views, indexes, and triggers. It is specified in several SQL files located in the subfolder [/databases/catdat/schema](/databases/catdat/schema/). The command
43+
44+
```
45+
pnpm db:setup
46+
```
47+
48+
deletes the old database file (if it exists) and creates a new one using this schema. This is required when the schema changes.
49+
50+
Database entries (categories, functors, properties, implications, etc.) are defined in YAML files located in the subfolder [/databases/catdat/data](/databases/catdat/data/). The command
51+
52+
```
53+
pnpm db:seed
54+
```
4755

48-
Database entries (categories, properties, implications, etc.) are defined in YAML files located in the subfolder [/databases/catdat/data](/databases/catdat/data/). The command `pnpm db:seed` rebuilds the database by clearing all existing data and then parsing and inserting the entries defined in these YAML files.
56+
rebuilds the database by clearing all existing data and then parsing and inserting the entries defined in these YAML files.
4957

5058
## Derived Data
5159

52-
From the defined satisfied properties of a given category, new properties can be automatically deduced using the implications. (For example, when a category has equalizers and products, we can infer that it is complete.) The same applies to unsatisfied properties. Additionally, suitable implications may be dualized, and a category inherits all dualized properties of its dual category, if available. Note that the YAML files mentioned above do _not_ contain any derived data.
60+
From the defined satisfied properties of a given categorical structure, new properties can be automatically deduced using the implications. (For example, when a category has equalizers and products, we can infer that it is complete.) The same applies to unsatisfied properties.
5361

54-
The command `pnpm db:deduce` deduces implications, satisfied properties, and unsatisfied properties.
62+
Additionally, suitable implications may be dualized, and a categorical structure inherits all dualized properties of its dual structure, if available. Note that the YAML files mentioned above do _not_ contain any derived data.
63+
64+
The command
65+
66+
```
67+
pnpm db:deduce
68+
```
69+
70+
deduces implications, satisfied properties, and unsatisfied properties.
5571

5672
## Test Data
5773

58-
The command `pnpm db:test` executes some tests and verifies that the data behaves as expected.
74+
The command
75+
76+
```
77+
pnpm db:test
78+
```
79+
80+
executes some tests and verifies that the data behaves as expected.
5981

6082
## One command for everything
6183

62-
Use `pnpm db:update` to run all the commands in sequence: `pnpm db:seed`,`pnpm db:deduce`, and `pnpm db:test`.
84+
Use the command
85+
86+
```
87+
pnpm db:update
88+
```
6389

64-
Use `pnpm db:watch` to run this command automatically every time a file in the subfolder [/databases/catdat/data](/databases/catdat/data) changes. This is useful in particular during development.
90+
to run all the commands in sequence: `pnpm db:seed`,`pnpm db:deduce`, and `pnpm db:test`. This also creates a copy of the local database in the `/static` folder.
91+
92+
Use
93+
94+
```
95+
pnpm db:watch
96+
```
97+
98+
to run this command automatically every time a file in the subfolder [/databases/catdat/data](/databases/catdat/data) changes. This is useful in particular during development.
6599

66100
## Redundancies
67101

68-
There is another script that intentionally does not run with each update: `pnpm db:redundancies` checks for redundant assignments of properties to categories.
102+
There is another script that intentionally does not run with each update. Use the command
103+
104+
```
105+
pnpm db:redundancies
106+
```
107+
108+
to check for redundant assignments of properties to categorical structures.
69109

70110
## Diagram
71111

72-
This is the database schema as of 26.05.2026; changes may occur.
112+
This is the database schema as of 15.06.2026; changes may occur.
73113

74-
<img alt="database diagram" src="https://github.com/user-attachments/assets/c8ce7e30-874b-4130-9ff5-2fc368f87f15" />
114+
<img alt="database diagram" src="https://github.com/user-attachments/assets/fc2cc524-3de3-4974-8929-9f73a2df62d7" />
75115

76116
## Application Database
77117

0 commit comments

Comments
 (0)