Skip to content

Commit 1a1e508

Browse files
authored
Merge pull request #2062 from dolthub/fulghum/minor-doc-updates
Adding docs for the schema overriding system var
2 parents 03ba319 + 916e8c1 commit 1a1e508

File tree

1 file changed

+35
-0
lines changed

1 file changed

+35
-0
lines changed

content/reference/sql/version-control/dolt-sysvars.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ title: Dolt System Variables
1010
- [dolt_allow_commit_conflicts](#dolt_allow_commit_conflicts)
1111
- [dolt_force_transaction_commit](#dolt_force_transaction_commit)
1212
- [dolt_log_level](#dolt_log_level)
13+
- [dolt_override_schema](#dolt_override_schema)
1314
- [dolt_show_branch_databases](#dolt_show_branch_databases)
1415
- [dolt_show_system_tables](#dolt_show_system_tables)
1516
- [dolt_transaction_commit](#dolt_transaction_commit)
@@ -90,6 +91,40 @@ fresh> show databases;
9091
When set to `1`, this system variable causes all system tables to be show in `show tables` and in `information_schema.tables`.
9192
Defaults to `0`.
9293

94+
95+
## `dolt_override_schema`
96+
97+
When set to a commit hash, branch name, or tag name, Dolt will map all table data to the schema at the specified commit,
98+
branch, or tag. This is useful when you have a query that runs with a specific schema, and you want to run it with
99+
data that has a different schema. For example, if you add a `Birthdate` column to the `People` table in the most recent commits
100+
in your database, you cannot reference that column in queries run against older commits. If you enable schema overriding, and
101+
set `@@dolt_override_schema` to a commit that contains the `Birthdate` column, you can run the same query with recent
102+
commits and with older commits, without having to modify the query for the schema changes in the older commits. Dolt will
103+
map the table data to the schema at the specified commit, branch, or tag, and fill in the missing columns with `NULL` values.
104+
105+
```sql
106+
-- check out an older branch that has a different schema
107+
CALL dolt_checkout('olderBranch');
108+
109+
-- running a query that references the Birthdate column will fail
110+
SELECT Name, Birthdate FROM People;
111+
column "Birthdate" could not be found in any table in scope
112+
113+
-- turning on schema overriding allows us to automatically map our data to the schema at the specified commit
114+
SET @@dolt_override_schema = 'main';
115+
SELECT Name, Birthdate FROM People;
116+
+-----------+-----------+
117+
| Name | Birthdate |
118+
+-----------+-----------+
119+
| Billy | NULL |
120+
| Jimbo | NULL |
121+
+-----------+-----------+
122+
```
123+
124+
Note that when this session variable is set, the active Dolt session becomes read-only. To disable schema overriding,
125+
simply set this variable to `NULL`.
126+
127+
93128
## `dolt_transaction_commit`
94129

95130
When set to `1`, this system variable creates a Dolt commit for every

0 commit comments

Comments
 (0)