diff --git a/content/reference/sql/version-control/dolt-sysvars.md b/content/reference/sql/version-control/dolt-sysvars.md index 0d18c619d..c4aafa922 100644 --- a/content/reference/sql/version-control/dolt-sysvars.md +++ b/content/reference/sql/version-control/dolt-sysvars.md @@ -10,6 +10,7 @@ title: Dolt System Variables - [dolt_allow_commit_conflicts](#dolt_allow_commit_conflicts) - [dolt_force_transaction_commit](#dolt_force_transaction_commit) - [dolt_log_level](#dolt_log_level) + - [dolt_override_schema](#dolt_override_schema) - [dolt_show_branch_databases](#dolt_show_branch_databases) - [dolt_show_system_tables](#dolt_show_system_tables) - [dolt_transaction_commit](#dolt_transaction_commit) @@ -90,6 +91,40 @@ fresh> show databases; When set to `1`, this system variable causes all system tables to be show in `show tables` and in `information_schema.tables`. Defaults to `0`. + +## `dolt_override_schema` + +When set to a commit hash, branch name, or tag name, Dolt will map all table data to the schema at the specified commit, +branch, or tag. This is useful when you have a query that runs with a specific schema, and you want to run it with +data that has a different schema. For example, if you add a `Birthdate` column to the `People` table in the most recent commits +in your database, you cannot reference that column in queries run against older commits. If you enable schema overriding, and +set `@@dolt_override_schema` to a commit that contains the `Birthdate` column, you can run the same query with recent +commits and with older commits, without having to modify the query for the schema changes in the older commits. Dolt will +map the table data to the schema at the specified commit, branch, or tag, and fill in the missing columns with `NULL` values. + +```sql +-- check out an older branch that has a different schema +CALL dolt_checkout('olderBranch'); + +-- running a query that references the Birthdate column will fail +SELECT Name, Birthdate FROM People; +column "Birthdate" could not be found in any table in scope + +-- turning on schema overriding allows us to automatically map our data to the schema at the specified commit +SET @@dolt_override_schema = 'main'; +SELECT Name, Birthdate FROM People; ++-----------+-----------+ +| Name | Birthdate | ++-----------+-----------+ +| Billy | NULL | +| Jimbo | NULL | ++-----------+-----------+ +``` + +Note that when this session variable is set, the active Dolt session becomes read-only. To disable schema overriding, +simply set this variable to `NULL`. + + ## `dolt_transaction_commit` When set to `1`, this system variable creates a Dolt commit for every