From d4cb4bd63783ffb37231f1da30125e7cb995096f Mon Sep 17 00:00:00 2001 From: fflorent Date: Mon, 15 Apr 2024 18:43:01 +0200 Subject: [PATCH] document ACL and other tables --- documentation/database.md | 84 +++++++++++++++++++++++++++++---------- 1 file changed, 63 insertions(+), 21 deletions(-) diff --git a/documentation/database.md b/documentation/database.md index 1f9d0472..2a2bbbe3 100644 --- a/documentation/database.md +++ b/documentation/database.md @@ -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 ```` @@ -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). @@ -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"). @@ -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 @@ -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 @@ -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).