gristlabs_grist-core/documentation/database.md

Database

First of all, let's explicit two databases that Grist manages:

1. The Home Database;
2. The Document Database (aka the grist document);

The Home database is responsible for things related to the instance, like:

• the users and the groups registered on the instance;
• the billing;
• the organisations (aka sites), the workspaces;
• the documents metadata (id, name, workspace under which it is located...);
• the rights (ACL) to access to organisations, workspaces and documents (the access to the content of the document is controlled by the document itself);

A Grist Document is a Sqlite database which contains data like:

• The tables, pages, views data;
• The ACL inside to access to all or part of tables (rows or columns);

The Document Database

Inspecting the Document

A Grist Document (with the .grist extension) is actually a sqlite database. You may download a document like this one and inspect its content using the sqlite3 command:

$ 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                 
_grist_Shares                     _gristsys_PluginData

⚠️ Be sure to work on a copy of a document if you inspect its content, otherwise you may loose data.

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

For more information, please consult the documentation for migrations.

The Home Database

The home database may either be a sqlite or a postgresql database depending on how the Grist instance has been installed. You may check the TYPEORM_* env variables in the README.

Unless otherwise configured, the home database is a sqlite file. In docker, it is stored in /persist/home.sqlite3.

The schema below is the same (except minor differences in the column types) whatever the database type is.

The Schema

As of 2024-04-15, the database schema is the following (it may have changed in the meantime):

[!NOTE] For simplicity's sake, we have removed tables related to the billing, nor to the migrations.

If you want to generate the above schema by yourself, you may run the following command using SchemaCrawler (a docker image is available for a quick run):

# You may adapt the --database argument to fit with the actual file name
# You may also remove the `--grep-tables` option and all that follows to get the full schema.
$ 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

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

Column name	Description
id	The primary key
name	The name as displayed in the UI
domain	The part that should be added in the URL
owner	The id of the user who owns the org
host	???

workspaces table

Tables whose rows represent workspaces

Column name	Description
id	The primary key
name	The name as displayed in the UI
org_id	The organisation to which the workspace belongs
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

Tables whose rows represent documents

Column name	Description
id	The primary key
name	The name as displayed in the UI
workspace_id	The workspace to which the document belongs
is_pinned	Whether the document has been pinned or not
url_id	Short version of the id, as displayed in the URL
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)
options	Serialized options as described in DocumentOptions
grace_period_start	Specific to getgrist.com (TODO describe it)
usage	stats about the document (see DocumentUsage)
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)

The migrations

The database migrations are handled by TypeORM (documentation). 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).