Functions

Table of Contents
​Informational Functions​
​active_branch()​
​dolt_merge_base()​
​hashof()​
​dolt_version()​
​Table Functions​
​dolt_diff()​
​Version Control Functions (deprecated)
​These are deprecated, please use the equivalent stored procedures instead.
​dolt_add()​
​dolt_checkout()​
​dolt_commit()​
​dolt_fetch()​
​dolt_merge()​
​dolt_pull()​
​dolt_push()​
​dolt_reset()​
Informational Functions
ACTIVE_BRANCH()
The ACTIVE_BRANCH() function returns the name of the currently active branch for this session.
1
mysql> select active_branch();
2
+-----------------+
3
| active_branch() |
4
+-----------------+
5
| main            |
6
+-----------------+
Copied!
DOLT_MERGE_BASE()
DOLT_MERGE_BASE() returns the hash of the common ancestor between two branches. Given the following branch structure:
Consider the following branch structure:
1
      A---B---C feature
2
     /
3
D---E---F---G main
Copied!
The following would return the hash of commit E:
1
SELECT DOLT_MERGE_BASE('feature', 'main');
Copied!
HASHOF()
The HASHOF() function returns the commit hash of a branch or other commit spec.
1
mysql> select hashof('main');
2
+----------------------------------+
3
| hashof('main')                   |
4
+----------------------------------+
5
| v391rm7r0t4989sgomv0rpn9ue4ugo6g |
6
+----------------------------------+
Copied!
DOLT_VERSION()
The DOLT_VERSION() function returns the version string for the Dolt binary.
1
mysql> select dolt_version();
2
+----------------+
3
| dolt_version() |
4
+----------------+
5
| 0.40.4         |
6
+----------------+
Copied!
Table Functions
Table functions operate like regular SQL functions, but instead of returning a single, scalar value, a table function returns rows of data, just like a table. Dolt's table function support is currently limited to only the DOLT_DIFF() function and table functions have several restrictions in how they can be used in queries. For example, you cannot currently alias a table function or join a table function with another table or table function.
DOLT_DIFF()
The DOLT_DIFF() table function calculates the differences in a table's data at any two commits in the database. Each row in the result set describes how a row in the underlying table has changed between the two commits, including the row's values at to and from commits and the type of change (i.e. added, modified, or removed). DOLT_DIFF() is an alternative to the dolt_commit_diff_$tablename system table. You should generally prefer the system tables when possible, since they have less restrictions on use. However, some use cases, such as viewing a table data diff containing schema changes, can be easier to view with the DOLT_DIFF table function.
The main difference between the results of the DOLT_DIFF() table function and the dolt_commit_diff_$tablename system table is the schema of the returned results. dolt_commit_diff_$tablename generates the resulting schema based on the table's schema at the currently checked out branch. DOLT_DIFF() will use the schema at the from_commit for the from_ columns and the schema at the to_commit for the to_ columns. This can make it easier to view diffs where the schema of the underlying table has changed.
Note that the DOLT_DIFF() table function currently has restrictions on how it can be used in queries. It does not support aliasing or joining with other tables, and argument values must currently be literal values.
Options
1
DOLT_DIFF(<tablename>, <from_revision>, <to_revision>)
Copied!
The DOLT_DIFF() table function takes three required arguments:
tablename — the name of the table containing the data to diff
from_revision — the revision of the table data for the start of the diff. This may be a commit, tag, branch name, or other revision specifier (e.g. "main~").
to_revision — the revision of the table data for the end of the diff. This may be a commit, tag, branch name, or other revision specifier (e.g. "main~").
Schema
1
+------------------+----------+
2
| field            | type     |
3
+------------------+----------+
4
| from_commit      | TEXT     |
5
| from_commit_date | DATETIME |
6
| to_commit        | TEXT     |
7
| to_commit_date   | DATETIME |
8
| diff_type        | TEXT     |
9
| other cols       |          |
10
+------------------+----------+
Copied!
The remaining columns are dependent on the schema of the user table as it existed at the from_commit and at the to_commit. For every column X in your table at the from_commit revision, there is a column in the result set named from_X. Likewise, for every column Y in your table at the to_commit revision, there is a column in the result set named to_Y. This is the major difference between the DOLT_DIFF() table function and the dolt_commit_diff_$tablename system table – DOLT_DIFF() uses the two schemas at the to_commit and from_commit revisions to form the to and from columns of the result set, while dolt_commit_diff_$tablename uses only the table schema of the currently checked out branch to form the to and from columns of the result set.
Example
Consider a table named inventory in a database with two branches: main and feature_branch. We can use the DOLT_DIFF() function to calculate a diff of the table data from the main branch to the feature_branch branch to see how our data has changed on the feature branch.
Here is the schema of inventory at the tip of main:
1
+----------+------+
2
| field    | type |
3
+----------+------+
4
| pk       | int  |
5
| name     | text |
6
| quantity | int  |
7
+----------+------+
Copied!
Here is the schema of inventory at the tip of feature_branch:
1
+----------+------+
2
| field    | type |
3
+----------+------+
4
| pk       | int  |
5
| name     | text |
6
| color    | text |
7
| size     | int  |
8
+----------+------+
Copied!
Based on the schemas at the two revision above, the resulting schema from DOLT_DIFF() will be:
1
+------------------+----------+
2
| field            | type     |
3
+------------------+----------+
4
| from_pk          | int      |
5
| from_name        | text     |
6
| from_quantity    | int      |
7
| from_commit      | TEXT     |
8
| from_commit_date | DATETIME |
9
| to_pk            | int      |
10
| to_name          | text     |
11
| to_color         | text     |
12
| to_size          | int      |
13
| to_commit        | TEXT     |
14
| to_commit_date   | DATETIME |
15
| diff_type        | text     |
16
+------------------+----------+
Copied!
To calculate the diff and view the results, we run the following query:
1
SELECT * FROM DOLT_DIFF("inventory", "main", "feature_branch")
Copied!
The results from DOLT_DIFF() show how the data has changed going from main to feature_branch:
1
+---------+-------+---------+----------+----------------+-----------------------------------+-----------+---------+---------------+-------------+-----------------------------------+-----------+
2
| to_name | to_pk | to_size | to_color | to_commit      | to_commit_date                    | from_name | from_pk | from_quantity | from_commit | from_commit_date                  | diff_type |
3
+---------+-------+---------+----------+----------------+-----------------------------------+-----------+---------+---------------+-------------+-----------------------------------+-----------+
4
| shirt   | 1     | 15      | false    | feature_branch | 2022-03-23 18:57:38.476 +0000 UTC | shirt     | 1       | 70            | main        | 2022-03-23 18:51:48.333 +0000 UTC | modified  |
5
| shoes   | 2     | 9       | brown    | feature_branch | 2022-03-23 18:57:38.476 +0000 UTC | shoes     | 2       | 200           | main        | 2022-03-23 18:51:48.333 +0000 UTC | modified  |
6
| pants   | 3     | 30      | blue     | feature_branch | 2022-03-23 18:57:38.476 +0000 UTC | pants     | 3       | 150           | main        | 2022-03-23 18:51:48.333 +0000 UTC | modified  |
7
| hat     | 4     | 6       | grey     | feature_branch | 2022-03-23 18:57:38.476 +0000 UTC | NULL      | NULL    | NULL          | main        | 2022-03-23 18:51:48.333 +0000 UTC | added     |
8
+---------+-------+---------+----------+----------------+-----------------------------------+-----------+---------+---------------+-------------+-----------------------------------+-----------+
Copied!
Version Control Functions
Deprecation Warning
All of the functions in this section have been deprecated and replaced with their stored procedure equivalents. They will be removed in a future release.
DOLT_ADD()
Deprecated. Use the DOLT_ADD stored procedure.
1
SELECT DOLT_ADD('-A');
2
SELECT DOLT_ADD('.');
3
SELECT DOLT_ADD('table1', 'table2');
Copied!
DOLT_CHECKOUT()
Deprecated. Use the DOLT_CHECKOUT stored procedure instead.
1
SELECT DOLT_CHECKOUT('-b', 'my-new-branch');
2
SELECT DOLT_CHECKOUT('my-existing-branch');
3
SELECT DOLT_CHECKOUT('my-table');
Copied!
DOLT_COMMIT()
Deprecated. Use the DOLT_COMMIT stored procedure instead.
1
SELECT DOLT_COMMIT('-a', '-m', 'This is a commit');
2
SELECT DOLT_COMMIT('-m', 'This is a commit');
3
SELECT DOLT_COMMIT('-m', 'This is a commit', '--author', 'John Doe <[email protected]>');
Copied!
DOLT_FETCH()
Deprecated. Use the DOLT_FETCH stored procedure instead.
1
SELECT DOLT_FETCH('origin', 'main');
2
SELECT DOLT_FETCH('origin', 'feature-branch');
3
SELECT DOLT_FETCH('origin', 'refs/heads/main:refs/remotes/origin/main');
Copied!
DOLT_MERGE()
Deprecated. Use the DOLT_MERGE stored procedure instead.
1
SELECT DOLT_MERGE('feature-branch'); -- Optional --squash parameter
2
SELECT DOLT_MERGE('feature-branch', '-no-ff', '-m', 'This is a msg for a non fast forward merge');
3
SELECT DOLT_MERGE('--abort');
Copied!
DOLT_RESET()
Deprecated. Use the DOLT_RESET stored procedure instead.
1
SELECT DOLT_RESET('--hard');
2
SELECT DOLT_RESET('my-table'); -- soft reset
Copied!
DOLT_PUSH()
Deprecated. Use the DOLT_PUSH stored procedure instead.
1
SELECT DOLT_PUSH('origin', 'main');
2
SELECT DOLT_PUSH('--force', 'origin', 'main');
Copied!
DOLT_PULL()
Deprecated. Use the DOLT_PULL stored procedure instead.
1
SELECT DOLT_PULL('origin');
2
SELECT DOLT_PULL('feature-branch', '--force');
Copied!