mirror of
https://github.com/dolthub/dolt.git
synced 2026-04-26 03:30:09 -05:00
Change initial commit message to imperative tense (#140)
* go/libraries/doltcore/doltdb/doltdb.go: Change initial commit message to imperative tense * bats: Don't forget the bats tests! * README.md: Make example commit messages consistent * README.md: Apply automatic formatting fixes
This commit is contained in:
Matt Jesuele
@@ -1,4 +1,5 @@
|
||||
## Dolt
|
||||
|
||||
Dolt is a relational database, i.e. it has tables, and you can execute SQL queries against those tables. It also has version control primitives that operate at the level of table cell. Thus Dolt is a database that supports fine grained value-wise version control, where all changes to data and schema are stored in commit log.
|
||||
|
||||
It is inspired by RDBMS and Git, and attempts to blend concepts about both in a manner that allows users to better manage, distribute, and collaborate on, data.
|
||||
@@ -38,30 +39,35 @@ Valid commands for dolt are
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
These installation instructions assume that you have Go installed, and that `go` is in your path.
|
||||
|
||||
### From Latest Release
|
||||
|
||||
Obtain the appropriate archive for your operating system under [releases](https://github.com/liquidata-inc/dolt/releases):
|
||||
|
||||
System|Archive
|
||||
---|---
|
||||
64-bit Mac|dolt-darwin-amd64.tar.gz
|
||||
32-bit Mac|dolt-darwin-386.tar.gz
|
||||
64-bit Linux|dolt-linux-amd64.tar.gz
|
||||
32-bit Linux|dolt-linux-386.tar.gz
|
||||
64-bit Windows|dolt-windows-amd64.tar.gz
|
||||
32-bit Windows|dolt-windows-386.tar.gz
|
||||
| System | Archive |
|
||||
| -------------- | ------------------------- |
|
||||
| 64-bit Mac | dolt-darwin-amd64.tar.gz |
|
||||
| 32-bit Mac | dolt-darwin-386.tar.gz |
|
||||
| 64-bit Linux | dolt-linux-amd64.tar.gz |
|
||||
| 32-bit Linux | dolt-linux-386.tar.gz |
|
||||
| 64-bit Windows | dolt-windows-amd64.tar.gz |
|
||||
| 32-bit Windows | dolt-windows-386.tar.gz |
|
||||
|
||||
For Unix systems extract the archive to a directory on in your path, for example (you might have to use `sudo` here):
|
||||
|
||||
```
|
||||
$ tar -xf /your/download/location/dolt-darwin-amd64.tar.gz -C /usr/local/lib
|
||||
$ ln -s /usr/local/lib/dolt-darwin-amd64/bin/dolt /usr/local/bin/dolt
|
||||
$ ln -s /usr/local/lib/dolt-darwin-amd64/bin/git-dolt /usr/local/bin/git-dolt
|
||||
$ ln -s /usr/local/lib/dolt-darwin-amd64/bin/git-dolt /usr/local/bin/git-dolt
|
||||
$ ln -s /usr/local/lib/dolt-darwin-amd64/bin/git-dolt-smudge /usr/local/bin/git-dolt-smudge
|
||||
```
|
||||
|
||||
### From Source
|
||||
|
||||
Alternatively clone this repository and then, assuming you cloned the repository into your home directory:
|
||||
|
||||
```
|
||||
$ cd ~/dolt/go
|
||||
$ go install ./cmd/dolt
|
||||
@@ -71,35 +77,46 @@ $ go install ./cmd/git-dolt
|
||||
$ go install ./cmd/git-dolt-smudge
|
||||
[...]
|
||||
```
|
||||
|
||||
This will install the requisite binaries at `$GOROOT/bin`, which defaults to `$HOME/go`, thus you should see something like (unless you set `$GOROOT` to something else):
|
||||
|
||||
```
|
||||
$ ls -ltr $HOME/go/bin/
|
||||
dolt git-dolt git-dolt-smudge
|
||||
```
|
||||
|
||||
Ensure that `$GOROOT/bin` is on your path, and then proceed.
|
||||
|
||||
### Verify
|
||||
|
||||
Whichever method you used, verify that your installation has succeeded as follows:
|
||||
|
||||
```
|
||||
$ dolt
|
||||
Valid commands for dolt are
|
||||
[...]
|
||||
```
|
||||
|
||||
Finally, setup your name and email in the global config (this should be very familiar to Git users):
|
||||
|
||||
```
|
||||
$ dolt config --global --add user.email YOU@DOMAIN.COM
|
||||
$ dolt config --global --add user.name "YOUR NAME"
|
||||
```
|
||||
|
||||
You're all set to start getting value from Dolt!
|
||||
|
||||
## First Repository
|
||||
|
||||
Suppose we want to create a table of state populations from 1790 in Dolt, then:
|
||||
|
||||
```
|
||||
$ mkdir state-populations
|
||||
$ cd state-populations
|
||||
```
|
||||
|
||||
Initialize the directory, and load some data:
|
||||
|
||||
```
|
||||
$ dolt init
|
||||
Successfully initialized dolt data repository.
|
||||
@@ -130,7 +147,9 @@ $ dolt sql -q 'insert into state_populations (state, population) values
|
||||
("Rhode Island", 68825)'
|
||||
Rows inserted: 17
|
||||
```
|
||||
|
||||
Now let's run some SQL against it:
|
||||
|
||||
```
|
||||
$ dolt sql -q "select * from state_populations where state = 'New York'"
|
||||
+----------+------------+
|
||||
@@ -139,10 +158,12 @@ $ dolt sql -q "select * from state_populations where state = 'New York'"
|
||||
| New York | 340120 |
|
||||
+----------+------------+
|
||||
```
|
||||
|
||||
Assuming you're satisfied, create a commit as follows:
|
||||
|
||||
```
|
||||
$ dolt add .
|
||||
$ dolt commit -m 'adding state populations from 1790.'
|
||||
$ dolt commit -m "Add state populations from 1790"
|
||||
$ dolt status
|
||||
On branch master
|
||||
nothing to commit, working tree clean
|
||||
@@ -151,6 +172,7 @@ nothing to commit, working tree clean
|
||||
You've just generated your first commit to a relational database with version control!
|
||||
|
||||
Alternatively, you can import CSV and PSV files, where the file type is inferred from the extension. Suppose your state populations are in a file:
|
||||
|
||||
```
|
||||
$ head -n3 data.csv
|
||||
state,population
|
||||
@@ -158,22 +180,28 @@ Delaware,59096
|
||||
Maryland,319728
|
||||
$ dolt import table -pk=state state_populations data.csv
|
||||
```
|
||||
|
||||
Note if you do not have a file extension, i.e. your file is called `data`, Dolt will think you are trying to import from another table and thus not behave in the way you expect.
|
||||
|
||||
## Modifying Data
|
||||
|
||||
Override the table with the contents of another file:
|
||||
|
||||
```
|
||||
$ dolt table import --update-table <table> <csv_file>
|
||||
```
|
||||
|
||||
To add or update rows, use the SQL interface:
|
||||
|
||||
```
|
||||
$ dolt sql --query 'INSERT INTO state_populations VALUES ("My State", 0)'
|
||||
Rows inserted: 1
|
||||
$ dolt sql --query 'UPDATE state_populations SET population=1 where state="My State"'
|
||||
Rows updated: 1
|
||||
```
|
||||
|
||||
Now you can see that you have changes to a table that are not staged for commit, in the same way that Git does not automatically stage modified files for commit:
|
||||
|
||||
```
|
||||
$ dolt status
|
||||
On branch master
|
||||
@@ -191,11 +219,14 @@ diff --dolt a/state_populations b/state_populations
|
||||
| + | My State | 1 |
|
||||
+-----+----------+------------+
|
||||
```
|
||||
|
||||
If you're happy with the changes, you can go ahead and commit them:
|
||||
|
||||
```
|
||||
$ dolt add state_populations
|
||||
$ dolt commit -m "Added 'My State'"
|
||||
```
|
||||
|
||||
Well done, you updated a table, and committed your changes!
|
||||
|
||||
## Simple Branching Workflow
|
||||
@@ -204,7 +235,7 @@ When making changes it is advisable to create a new branch which will serve as t
|
||||
|
||||
dolt checkout -b <branch>
|
||||
|
||||
Once you've made your changes, add and commit the modified tables like you did previously. Once your work is done and you are ready to get all your changes back into the master branch run:
|
||||
Once you've made your changes, add and commit the modified tables like you did previously. Once your work is done and you are ready to get all your changes back into the master branch run:
|
||||
|
||||
dolt checkout master
|
||||
dolt merge <branch>
|
||||
@@ -212,23 +243,26 @@ Once you've made your changes, add and commit the modified tables like you did p
|
||||
Then you'll need to add and commit the merged data:
|
||||
|
||||
dolt add .
|
||||
dolt commit -m "Merged work from <branch> into master"
|
||||
|
||||
dolt commit -m "Merge work from <branch> into master"
|
||||
|
||||
## Adding Remotes
|
||||
|
||||
Dolt supports remotes in a similar manner to Git. Liquidata, the company behind Dolt, also created DoltHub, a hosting service for Dolt databases. In the following we use DoltHub as an example for setting up a remote.
|
||||
|
||||
If you haven't done so already, setting up your default servers will make it easier to add and clone remotes
|
||||
|
||||
```
|
||||
$ dolt login
|
||||
[...]
|
||||
```
|
||||
|
||||
Which should open a browser window where you can create a credential for HTTPS. Upon successful creation the following will appear in the shell:
|
||||
|
||||
```
|
||||
Key successfully associated with user: youusername email you@youremail.com
|
||||
```
|
||||
Next you'll want to make sure you've created the remote at https://www.dolthub.com . Once created you can add the remote. As an example, if the repository is created under an organization named "org", with the name "repo" you could add the remote like so:
|
||||
|
||||
Next you'll want to make sure you've created the remote at https://www.dolthub.com . Once created you can add the remote. As an example, if the repository is created under an organization named "org", with the name "repo" you could add the remote like so:
|
||||
|
||||
dolt remote add origin org/repo
|
||||
|
||||
@@ -259,22 +293,24 @@ IP Address to Country: https://www.dolthub.com/repositories/Liquidata/ip-to-coun
|
||||
|
||||
dolt also supports directory, aws, and gcs based remotes:
|
||||
|
||||
* file - you can use a directory as a remote that can be pushed to, cloned, and purlled from just like any other remote by providing a file uri for the directory
|
||||
- file - you can use a directory as a remote that can be pushed to, cloned, and purlled from just like any other remote by providing a file uri for the directory
|
||||
|
||||
dolt remote add <remote> file:///Users/xyz/abs/path/
|
||||
dolt remote add <remote> file:///Users/xyz/abs/path/
|
||||
|
||||
* aws - you can use your aws cloud resources directly (If you are interested in trying this contact the dolt team directly as we are still writing documentation).
|
||||
- aws - you can use your aws cloud resources directly (If you are interested in trying this contact the dolt team directly as we are still writing documentation).
|
||||
|
||||
dolt remote add <remote> aws://dynamo-table:s3-bucket/database
|
||||
dolt remote add <remote> aws://dynamo-table:s3-bucket/database
|
||||
|
||||
* gs - you can use a GCS bucket as well. Setup here should be straight forward. You'll need to create a gcs bucket, and you'll need to use the gcloud auth login command in order to setup your credentials.
|
||||
- gs - you can use a GCS bucket as well. Setup here should be straight forward. You'll need to create a gcs bucket, and you'll need to use the gcloud auth login command in order to setup your credentials.
|
||||
|
||||
dolt remote add <remote> gs://gcs-bucket/database
|
||||
dolt remote add <remote> gs://gcs-bucket/database
|
||||
|
||||
## Issues
|
||||
|
||||
If you have any issues with Dolt, find any bugs, or simply have a question, feel free to file an issue!
|
||||
|
||||
# Credits and License
|
||||
|
||||
Dolt relies heavily on open source code and ideas from the [Noms](https://github.com/attic-labs/noms) project. We are very thankful to the Noms team for making this code freely available, without which we would not have been able to build Dolt so rapidly.
|
||||
|
||||
Dolt is licensed under the Apache License, Version 2.0. See
|
||||
|
||||
@@ -65,11 +65,11 @@ teardown() {
|
||||
run dolt log
|
||||
[ "$status" -eq "0" ]
|
||||
[[ "$output" =~ "first commit" ]] || false
|
||||
[[ "$output" =~ "Data repository created." ]] || false
|
||||
[[ "$output" =~ "Initialize data repository" ]] || false
|
||||
run dolt log -n 1
|
||||
[ "$status" -eq "0" ]
|
||||
[[ "$output" =~ "first commit" ]] || false
|
||||
[[ ! "$output" =~ "Data repository created." ]] || false
|
||||
[[ ! "$output" =~ "Initialize data repository" ]] || false
|
||||
}
|
||||
|
||||
@test "add a row to a created table using dolt table put-row" {
|
||||
|
||||
@@ -41,7 +41,7 @@ teardown() {
|
||||
run dolt log
|
||||
[ "$status" -eq 0 ]
|
||||
[[ "$output" =~ "commit " ]] || false
|
||||
[[ "$output" =~ "Data repository created." ]] || false
|
||||
[[ "$output" =~ "Initialize data repository" ]] || false
|
||||
}
|
||||
|
||||
@test "dolt add . in new repository" {
|
||||
|
||||
@@ -127,7 +127,7 @@ func (ddb *DoltDB) WriteEmptyRepo(ctx context.Context, name, email string) error
|
||||
return err
|
||||
}
|
||||
|
||||
cm, _ := NewCommitMeta(name, email, "Data repository created.")
|
||||
cm, _ := NewCommitMeta(name, email, "Initialize data repository")
|
||||
|
||||
parentSet, err := types.NewSet(ctx, ddb.db)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user