Guides
Architecture
Pull Requests
What is a pull request?
Pull requests are a way to propose changes to a database. A pull request is created from a branch with new changes that a user would like to make to another branch (commonly the
main or master branch). Once the pull request is opened, the reviewer can easily review the diff of the proposed changes and discuss potential improvements or implications of the change. If approved, the pull request can be merged, which will update the base branch with the changes from the feature branch.How to use pull requests
You can use pull requests to propose changes for another branch. To create a pull request, you should make changes to a branch on your database or a fork of another database. Then you can use the new pull request form to choose your base branch. You can also add a title (required) and description (optional).
Difference between GitHub pull requests and DoltHub pull requests
GitHub pull requests are similar to DoltHub pull requests in purpose. GitHub pull requests include some extra features that are on our longer-term DoltHub roadmap (like actions, tagging other users as reviewers, etc). Both include a list of commits, comments, and a diff of proposed changes.
Due to the difference in nature of reviewing data vs reviewing code, diffs on DoltHub look a little from diffs on GitHub. On GitHub you compare files, while DoltHub compares changes to data tables (outside of README and LICENSE changes). It's rare to have a pull request on GitHub with a file containing thousands of line changes, while this is much more common for data tables. DoltHub diffs attempt to make reviewing data easier by letting the user focus on one table at a time and filter by added, deleted, or modified rows.
Example
We will use our
dolthub/us-schools database as an example. This database was created through one of our bounties.1
% dolt clone taylor/us-schools
2
cloning https://doltremoteapi.dolthub.com/taylor/us-schools
3
141,350 of 141,350 chunks complete. 0 chunks being downloaded currently
4
​
5
% cd us-schools
Copied!
We check out a new branch for our change, and then use the SQL shell to make some changes to the data. In this case, we'll fill in some missing school websites.
1
% dolt checkout -b taylor/add-missing-websites
2
Switched to branch 'taylor/add-missing-websites'
3
​
4
% dolt sql
5
# Welcome to the DoltSQL shell.
6
# Statements must be terminated with ';'.
7
# "exit" or "quit" (or Ctrl-D) to exit.
8
​
9
us_schools> update schools set website='https://www.cde.ca.gov/schooldirectory/details?cdscode=19111976102321' where name='HILLCREST' and city='REDONDO BEACH' and state='CA';
10
Query OK, 1 row affected
11
Rows matched: 1 Changed: 1 Warnings: 0
12
​
13
us_schools> update schools set website='https://www.cde.ca.gov/schooldirectory/details?cdscode=39322763932951' where name='HOLTON (KARL) HIGH' and city='STOCKTON' and state='CA';
14
Query OK, 1 row affected
15
Rows matched: 1 Changed: 1 Warnings: 0]
16
​
17
us_schools> exit;
18
Bye
Copied!
1
% dolt diff
2
diff --dolt a/schools b/schools
3
--- a/schools @ ml65mjlsqpd45htsq1oc741nj4ns64fe
4
+++ b/schools @ jlrm3n5scc9cdj7sh368i4scik81km32
5
+-----+--------------------+---------------+-------+---------------------+-------+-----------------------------------------------------------------------+----------+----------------+--------------------------------------+-------------------+---------------------+
6
| | name | city | state | address | zip | website | category | public_private | district | lat | lon |
7
+-----+--------------------+---------------+-------+---------------------+-------+-----------------------------------------------------------------------+----------+----------------+--------------------------------------+-------------------+---------------------+
8
| < | HILLCREST | REDONDO BEACH | CA | 200 N LUCIA AVE | 90277 | NULL | NULL | PUBLIC | LOS ANGELES COUNTY SPECIAL EDUCATION | 33.84496307373047 | -118.3777847290039 |
9
| > | HILLCREST | REDONDO BEACH | CA | 200 N LUCIA AVE | 90277 | https://www.cde.ca.gov/schooldirectory/details?cdscode=19111976102321 | NULL | PUBLIC | LOS ANGELES COUNTY SPECIAL EDUCATION | 33.84496307373047 | -118.3777847290039 |
10
| < | HOLTON (KARL) HIGH | STOCKTON | CA | 7650 S NEWCASTLE RD | 95213 | NULL | HIGH | PUBLIC | CEA SAN JOAQUIN COUNTY | 37.89115524291992 | -121.19744110107422 |
11
| > | HOLTON (KARL) HIGH | STOCKTON | CA | 7650 S NEWCASTLE RD | 95213 | https://www.cde.ca.gov/schooldirectory/details?cdscode=39322763932951 | HIGH | PUBLIC | CEA SAN JOAQUIN COUNTY | 37.89115524291992 | -121.19744110107422 |
12
+-----+--------------------+---------------+-------+---------------------+-------+-----------------------------------------------------------------------+----------+----------------+--------------------------------------+-------------------+---------------------+
13
​
14
% dolt add schools && dolt commit -m "Update two schools with websites"
15
commit qvbg0laf84umi1hkdkiooiciil2gtene
16
Author: Taylor Bantle <[email protected]>
17
Date: Fri Dec 03 14:15:38 -0800 2021
18
​
19
Update two schools with websites
20
​
21
% dolt push origin taylor/add-missing-websites
22
/ Tree Level: 1, Percent Buffered: 0.00%, Files Written: 0, Files Uploaded: 1, Current Upload Speed: 59 kB/s
Copied!
We can open a pull request in
dolthub/us-schools by selecting our fork and branch. We also add a title.
New pull request form
The owner of
dolthub/us-schools can look at the diff and request changes.
New pull request diff
Once the changes have been approved, the owner can merge the pull request. The commits from the pull request will show up on the
main (or master in this case) branch.
Merged pull with feedback
And we have successful used pull requests to incorporate a change to a database!
Last modified 1mo ago
Export as PDF
Copy link
Edit on GitHub