Skip to content

Commit

Permalink
document ACL and other tables
Browse files Browse the repository at this point in the history
  • Loading branch information
@fflorent
fflorent committed Apr 15, 2024
1 parent e6bea9f commit 1729532
Showing 1 changed file with 63 additions and 21 deletions.
84 changes: 63 additions & 21 deletions documentation/database.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,22 +24,22 @@ A Grist Document (with the `.grist` extension) is actually a sqlite database. Yo
````
$ sqlite3 Flashcards.grist
sqlite> .tables
Flashcards_Data _grist_TabBar
Flashcards_Data_summary_Card_Set _grist_TabItems
GristDocTour _grist_TableViews
_grist_ACLMemberships _grist_Tables
_grist_ACLPrincipals _grist_Tables_column
_grist_ACLResources _grist_Triggers
_grist_ACLRules _grist_Validations
_grist_Attachments _grist_Views
_grist_Cells _grist_Views_section
_grist_DocInfo _grist_Views_section_field
_grist_External_database _gristsys_Action
_grist_External_table _gristsys_ActionHistory
_grist_Filters _gristsys_ActionHistoryBranch
_grist_Imports _gristsys_Action_step
_grist_Pages _gristsys_FileInfo
_grist_REPL_Hist _gristsys_Files
Flashcards_Data _grist_TabBar
Flashcards_Data_summary_Card_Set _grist_TabItems
GristDocTour _grist_TableViews
_grist_ACLMemberships _grist_Tables
_grist_ACLPrincipals _grist_Tables_column
_grist_ACLResources _grist_Triggers
_grist_ACLRules _grist_Validations
_grist_Attachments _grist_Views
_grist_Cells _grist_Views_section
_grist_DocInfo _grist_Views_section_field
_grist_External_database _gristsys_Action
_grist_External_table _gristsys_ActionHistory
_grist_Filters _gristsys_ActionHistoryBranch
_grist_Imports _gristsys_Action_step
_grist_Pages _gristsys_FileInfo
_grist_REPL_Hist _gristsys_Files
_grist_Shares _gristsys_PluginData
````

Expand All @@ -48,7 +48,7 @@ _grist_Shares _gristsys_PluginData
### The migrations

The migrations are handled in the python sandbox in this code:
https://github.com/gristlabs/grist-core/blob/main/sandbox/grist/migrations.py
https://github.com/gristlabs/grist-core/blob/main/sandbox/grist/migrations.py

For more information, please consult [the documentation for migrations](./migrations.md).

Expand Down Expand Up @@ -76,7 +76,7 @@ If you want to generate the above schema by yourself, you may run the following
$ schemacrawler --server=sqlite --database=landing.db --info-level=standard --portable-names --command=schema --output-format=svg --output-file=/tmp/graph.svg --grep-tables="products|billing_accounts|limits|billing_account_managers|activations|migrations" --invert-match
````

### `orgs` table
### `orgs` table

Tables whose rows represent organisations (also called "Team sites").

Expand All @@ -88,7 +88,7 @@ Tables whose rows represent organisations (also called "Team sites").
| owner | The id of the user who owns the org |
| host | ??? |

### `workspaces` table
### `workspaces` table

Tables whose rows represent workspaces

Expand All @@ -100,7 +100,7 @@ Tables whose rows represent workspaces
| removed_at | If not null, stores the date when the workspaces has been placed in the trash (it will be hard deleted after 30 days) |


### `docs` table
### `docs` table

Tables whose rows represent documents

Expand All @@ -118,8 +118,50 @@ Tables whose rows represent documents
| trunk_id | If set, the current document is a fork (as of 2024-04-15, only from a tutorial), and this column references the original document |
| type | If set, the current document is a special one (as specified in [DocumentType](https://github.com/gristlabs/grist-core/blob/4567fad94787c20f65db68e744c47d5f44b932e4/app/common/UserAPI.ts#L123)) |

### `aliases` table

### The migrations
Aliases for documents.

FIXME: What's the difference between `docs.url_id` and `alias.url_id`?

| Column name | Description |
| ------------- | -------------- |
| url_id | The URL alias for the doc_id |
| org_id | The organisation to which the document belong to |
| doc_id | The document id |

### `acl_rules` table

Permissions for to access either a document, workspace or an organisation.

| Column name | Description |
| ------------- | -------------- |
| id | The primary key |
| permissions | The permissions granted to the group. see below. |
| type | Either equals to `ACLRuleOrg`, `ACLRuleWs` or `ACLRuleDoc` |
| org_id | The org id associated to this ACL (if set, workspace_id and doc_id are null) |
| workspace_id | The workspace id associated to this ACL (if set, doc_id and org_id are null) |
| doc_id | The document id associated to this ACL (if set, workspace_id and org_id are null) |
| group_id | The group of users for which the ACL applies |

The permissions are stored as an integer which is read in its binary form which allows to make bitwise operations:

| VIEW | UPDATE | ADD | REMOVE | SCHEMA_EDIT | ACL_EDIT | (reserved) | PUBLIC |
| --------------- | --------------- | --------------- | --------------- | --------------- | ---------- | --------- | ---- |
| can view | can update | can add | can remove | can change schema of tables | can edit the ACL (docs) or manage the teams (orgs and workspaces) of the resource | (reserved bit for the future) | virtual bit meaning that the resource is shared publicly |
| +0b00000001 | +0b00000010 | +0b00000100 | +0b00001000 | +0b00010000 | +0b00100000 | +0b01000000 | +0b10000000 |

You notice that the permissions can be then composed:
- EDITOR permissions = `VIEW | UPDATE | ADD | REMOVE` = `0b00000001+0b00000010+0b00000100+0b00001000` = `0b00001111` = `15`
- ADMIN permissions = `EDITOR | SCHEMA_EDIT` = `0b00001111+0b00010000` = `0b00011111` = `31`
- ...

For more details about that part, please refer [to the code](https://github.com/gristlabs/grist-core/blob/192e2f36ba77ec67069c58035d35205978b9215e/app/gen-server/lib/Permissions.ts).


### `prefs` table

### The migrations

The database migrations are handled by TypeORM ([documentation](https://typeorm.io/migrations)). The migration files are located at `app/gen-server/migration` and are run at startup (so you don't have to worry about running them yourself).

0 comments on commit 1729532

Please sign in to comment.