document ACL and other tables

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).