mirror of
https://github.com/dolthub/dolt.git
synced 2026-01-06 08:50:04 -06:00
Expanded the docs and moved all but README out of the root dir
This commit is contained in:
Zach Musgrave
13
README.md
13
README.md
@@ -1,6 +1,6 @@
|
||||
# Dolt
|
||||
|
||||
<img align="left" height="300" src="./dolt_hi.svg"/>
|
||||
<img align="left" height="300" src="./docs/dolt_hi.svg"/>
|
||||
|
||||
### Dolt is Git for Data!
|
||||
|
||||
@@ -26,8 +26,17 @@ Lots of things! Dolt is a generally useful tool with countless
|
||||
applications. But if you want some ideas, [here's how people are using
|
||||
it so far](https://www.dolthub.com/blog/2021-03-09-dolt-use-cases-in-the-wild/).
|
||||
|
||||
### How do I use it?
|
||||
|
||||
Check out our [quick-start guide](docs/quick-start.md) to skip the
|
||||
docs and get started as fast as humanly possible!
|
||||
|
||||
Having problems? Read the [FAQ](docs/faq.md) to find answers.
|
||||
|
||||
# Dolt CLI
|
||||
|
||||
The `dolt` CLI has the same commands as `git`, with some extras.
|
||||
|
||||
```
|
||||
$ dolt
|
||||
Valid commands for dolt are
|
||||
@@ -91,7 +100,7 @@ Download the latest Microsoft Installer (`.msi` file) in
|
||||
[releases](https://github.com/dolthub/dolt/releases) and run
|
||||
it. Package manager releases coming soon!
|
||||
|
||||
For information on running on Windows, see [here](windows.md).
|
||||
For information on running on Windows, see [here](./docs/windows.md).
|
||||
|
||||
## From Source
|
||||
|
||||
|
||||
1
docs/dolt_hi.svg
Executable file
1
docs/dolt_hi.svg
Executable file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 12 KiB |
105
docs/faq.md
Normal file
105
docs/faq.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# Dolt FAQ
|
||||
|
||||
## Why is it called Dolt? Are you calling me dumb?
|
||||
|
||||
It's named `dolt` to pay homage to [how Linus Torvalds named
|
||||
git](https://en.wikipedia.org/wiki/Git#Naming):
|
||||
|
||||
> Torvalds sarcastically quipped about the name git (which means
|
||||
> "unpleasant person" in British English slang): "I'm an egotistical
|
||||
> bastard, and I name all my projects after myself. First 'Linux',
|
||||
> now 'git'."
|
||||
|
||||
We wanted a word that meant "idiot" and started with D for Data. So,
|
||||
dolt.
|
||||
|
||||
## Why does my connection to the server hang / time out?
|
||||
|
||||
With no config file, the server starts up in single user mode. It
|
||||
won't allow a second connection until the first hangs up. This is to
|
||||
prevent any unpleasant surprises with multiple writers, since Dolt's
|
||||
transaction / concurrency model is a work in progress.
|
||||
|
||||
To allow multiple simultaneous connections, set the `max_connections`
|
||||
field in the config.yaml file you pass to the `dolt sql-server`
|
||||
command, [as described in the
|
||||
docs](https://docs.dolthub.com/interfaces/cli#dolt-sql-server).
|
||||
|
||||
## What does `@@autocommit` do?
|
||||
|
||||
This is a SQL variable that you can turn on for your SQL session like so:
|
||||
|
||||
`SET @@autocommit = 1`
|
||||
|
||||
If it's set to a true value, then Dolt will flush your changes to disk
|
||||
after every SQL statement, so that you can see your changes when you
|
||||
run other commands (like `dolt diff`) from the command
|
||||
line. Specifically, it updates the working set in your database state,
|
||||
the same way that running `dolt sql -q ...` on the command line does.
|
||||
|
||||
Otherwise, you won't see changes outside your session until you issue
|
||||
a `COMMIT` statement. See the next question.
|
||||
|
||||
## What's the difference between `COMMIT`, `COMMIT()`, and `DOLT_COMMIT()`?
|
||||
|
||||
`COMMIT` is a standard SQL statement that commits a transaction. In
|
||||
dolt, it just flushes any pending changes in the current SQL session
|
||||
to disk, updating the working set. HEAD stays the same, but your
|
||||
working set changes. This means your edits will persist after this
|
||||
session ends.
|
||||
|
||||
`COMMIT()` creates a new dolt commit, but doesn't references it
|
||||
anywhere. If you want to reference it, you have to take the value
|
||||
returned by the function and create a branch with it (by inserting
|
||||
into `dolt_branches`)
|
||||
|
||||
`DOLT_COMMIT()` is the same as if you run `dolt commit` from the
|
||||
command line. It updates HEAD.
|
||||
|
||||
See the [docs on
|
||||
concurrency](https://docs.dolthub.com/interfaces/sql/concurrency) for
|
||||
more detail.
|
||||
|
||||
## I want each of my connected SQL users to get their own branch to make changes on, then merge them back into `master` when they're done making edits. How do I do that?
|
||||
|
||||
We are glad you asked! This is a common use case, and we wrote a
|
||||
couple blog articles about how to do this effectively.
|
||||
|
||||
[dolt sql-server
|
||||
concurrency](https://www.dolthub.com/blog/2021-03-12-dolt-sql-server-concurrency/)
|
||||
|
||||
[Merging and resolving conflicts programmatically with
|
||||
SQL](https://www.dolthub.com/blog/2021-03-15-programmatic-merge-and-resolve/)
|
||||
|
||||
## Does Dolt support transactions?
|
||||
|
||||
Not really, in the way that normal databases do. That's a work in
|
||||
progress. Until then, you can't `ROLLBACK` or create `SAVEPOINTS`, and
|
||||
things like row-level locking with `SELECT FOR UPDATE` don't work. You
|
||||
manage concurrency explicitly by creating branches / merging them back
|
||||
in to `master` when you're done with a unit of work (which can span
|
||||
any amount of time and any number of SQL sessions). `COMMIT` does
|
||||
something, but it's not a real transaction (see questions above).
|
||||
|
||||
Named locks work, via `GET_LOCK()` and `RELEASE_LOCK()` functions.
|
||||
|
||||
Support for traditional database transactions, concurrency, and
|
||||
row-level locking is on our [roadmap](roadmap.md).
|
||||
|
||||
## What SQL features / syntax are supported?
|
||||
|
||||
Most of them! Check out [the docs for the full list of supported
|
||||
features](https://docs.dolthub.com/interfaces/sql/sql-support).
|
||||
|
||||
You can check out what we're working on next on our
|
||||
[roadmap](roadmap.md). Paying customers get their feature requests
|
||||
bumped to the front of the line.
|
||||
|
||||
## Does Dolt support my favorite SQL workbench / tool?
|
||||
|
||||
Probably! Have you tried it? If you try it and it doesn't work, [let
|
||||
us know with an issue](https://github.com/dolthub/dolt/issues) or in
|
||||
[our Discord](https://discord.com/invite/RFwfYpu) and we'll see what
|
||||
we can do. A lot of times we can fix small compatibility issues really
|
||||
quick, like the same week. And even if we can't, we want to know about
|
||||
it! Our goal is to be a 100% drop-in replacement for MySQL.
|
||||
181
docs/quickstart.md
Normal file
181
docs/quickstart.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Dolt quickstart guide
|
||||
|
||||
This is a one-page guide to getting you started with Dolt as quickly
|
||||
as possible. If you're trying to participate in a data bounty, this
|
||||
will get you up and running.
|
||||
|
||||
This guide is intended for new data bounty participants, and is geared
|
||||
to that use case. You can find more complete documentation on how to
|
||||
use Dolt in the [README](../README.md) and in the [DoltHub
|
||||
documentation](https://docs.dolthub.com/getting-started/installation).
|
||||
|
||||
## Install Dolt
|
||||
|
||||
```sh
|
||||
% sudo bash -c 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash'
|
||||
```
|
||||
|
||||
For windows installation, see [here](windows.md).
|
||||
|
||||
## Configure dolt
|
||||
|
||||
```sh
|
||||
% dolt config --global --add user.email YOU@DOMAIN.COM
|
||||
% dolt config --global --add user.name "YOUR NAME"
|
||||
```
|
||||
|
||||
## Fork the data bounty
|
||||
|
||||
Forking a database makes a private copy for you to edit. Find the
|
||||
database you want to edit, then click the "Fork" button on the top
|
||||
left.
|
||||
|
||||
|
||||
|
||||
## Clone your fork
|
||||
|
||||
Cloning your fork of the database downloads it to your local computer
|
||||
so you can make changes to it. [DoltHub](https://dolthub.com). Click
|
||||
"Clone" to find the command to copy and paste into your terminal. This
|
||||
clone command will be different for every fork, so you can't just copy
|
||||
and paste the command in the text below.
|
||||
|
||||
|
||||
|
||||
Run the command, then cd into the database directory.
|
||||
|
||||
```sh
|
||||
% dolt clone dolthub/hospital-price-transparency
|
||||
% cd hospital-price-transparency
|
||||
```
|
||||
|
||||
## Inspect the data
|
||||
|
||||
Get familiar with the tables and their columns. The easiest way to do
|
||||
this is by using SQL commands. `show tables` and `describe
|
||||
<tablename>` are good commands to use when exploring a new database.
|
||||
|
||||
```sh
|
||||
% dolt sql
|
||||
# Welcome to the DoltSQL shell.
|
||||
# Statements must be terminated with ';'.
|
||||
# "exit" or "quit" (or Ctrl-D) to exit.
|
||||
hospital_price_transparency> show tables;
|
||||
+-----------+
|
||||
| Table |
|
||||
+-----------+
|
||||
| cpt_hcpcs |
|
||||
| hospitals |
|
||||
| prices |
|
||||
+-----------+
|
||||
hospital_price_transparency> describe hospitals;
|
||||
+----------------+--------------+------+-----+---------+-------+
|
||||
| Field | Type | Null | Key | Default | Extra |
|
||||
+----------------+--------------+------+-----+---------+-------+
|
||||
| npi_number | char(16) | NO | PRI | | |
|
||||
| name | varchar(256) | YES | | | |
|
||||
| url | varchar(512) | YES | | | |
|
||||
| street_address | varchar(512) | YES | | | |
|
||||
| city | varchar(64) | YES | | | |
|
||||
| state | varchar(32) | YES | | | |
|
||||
| zip_code | varchar(16) | YES | | | |
|
||||
| publish_date | date | YES | | | |
|
||||
+----------------+--------------+------+-----+---------+-------+
|
||||
hospital_price_transparency> select npi_number, name, street_address from hospitals limit 3;
|
||||
+------------+------------------------------------+---------------------+
|
||||
| npi_number | name | street_address |
|
||||
+------------+------------------------------------+---------------------+
|
||||
| 1003873225 | The Specialty Hospital Of Meridian | 1314 19th Ave |
|
||||
| 1023061405 | Grandview Medical Center | 3690 Grandview Pkwy |
|
||||
| 1023180502 | Medical City Dallas | 7777 Forest Ln |
|
||||
+------------+------------------------------------+---------------------+
|
||||
hospital_price_transparency> exit
|
||||
Bye
|
||||
```
|
||||
|
||||
## Add some data
|
||||
|
||||
There are two main ways to add data into your copy of the
|
||||
database. You can either import from files, or you can add data by
|
||||
writing scripts and inserting rows with SQL statements.
|
||||
|
||||
### Importing files
|
||||
|
||||
Use the `dolt table import` command to import CSV or JSON files. Use
|
||||
the `-u` option to update the table (instead of replacing the
|
||||
contents).
|
||||
|
||||
```sh
|
||||
% dolt table import -u prices hospital_prices.csv
|
||||
```
|
||||
|
||||
### Starting a SQL server
|
||||
|
||||
If you want to write a script to insert data with python or another
|
||||
programming language, start a SQL server on the command line:
|
||||
|
||||
```sh
|
||||
% dolt sql-server
|
||||
Starting server with Config HP="localhost:3306"|U="root"|P=""|T="28800000"|R="false"|L="info"
|
||||
```
|
||||
|
||||
Then connect to the database with any standard MySQL connector and
|
||||
make your edits.
|
||||
|
||||
## See your changes
|
||||
|
||||
After you've inserted some data, you can inspect the changes you made
|
||||
using `dolt diff`. If you added a lot of rows, use the `--summary` to
|
||||
get a summary instead.
|
||||
|
||||
```sh
|
||||
% dolt diff
|
||||
```
|
||||
|
||||
## Commit your changes
|
||||
|
||||
These commands work like `git`, if you know `git`. If you don't know
|
||||
`git`, don't worry! Most people who know `git` don't actually know
|
||||
`git` either!
|
||||
|
||||
```sh
|
||||
% dolt add .
|
||||
% dolt commit -m "This message describes my changes"
|
||||
```
|
||||
|
||||
You can repeat these steps as many times as you have more changes to add:
|
||||
|
||||
1) Add data
|
||||
2) Commit your changes
|
||||
|
||||
Every time you commit it creates a checkpoint you can roll back to if
|
||||
you mess up later.
|
||||
|
||||
## Push your changes back to DoltHub and create a PR
|
||||
|
||||
When you're done adding data, push the database back to DoltHub and
|
||||
submit a pull request (PR) to merge them back into the original fork.
|
||||
|
||||
```sh
|
||||
% dolt push origin master
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Respond to PR review feedback
|
||||
|
||||
Your PR will be reviewed by the people running the bounty, and they
|
||||
may ask you to make changes. If they do, then go ahead and make your
|
||||
changes on your machine, then `dolt push` those new commits back to
|
||||
DoltHub and your existing PR will automatically be updated with them.
|
||||
|
||||
## Questions? Still need help?
|
||||
|
||||
Come hang out with us on [our
|
||||
Discord](https://discord.com/invite/RFwfYpu), where the team that
|
||||
builds Dolt and lots of other customers are available to chat and ask
|
||||
questions. If this guide is missing something obvious, come tell us
|
||||
there!
|
||||
|
||||
22
docs/roadmap.md
Normal file
22
docs/roadmap.md
Normal file
@@ -0,0 +1,22 @@
|
||||
# Dolt feature roadmap
|
||||
|
||||
Full details on [supported SQL
|
||||
features](https://docs.dolthub.com/interfaces/sql/sql-support) are
|
||||
available on the docs site.
|
||||
|
||||
This is a selection of unimplemented features we're working on. It's
|
||||
not an ordered list. Don't see what you need on here? [Let us
|
||||
know!](https://github.com/dolthub/dolt/issues) Paying customers get
|
||||
their feature requests implemented first.
|
||||
|
||||
* Primary key changes in `ALTER TABLE`
|
||||
* Tuples for `IN (...)` expressions
|
||||
* `push` and `pull` via SQL
|
||||
* Concurrency and transactions
|
||||
* Check constraints
|
||||
* JSON type and functions
|
||||
* More window functions
|
||||
* Cross-database joins with indexes
|
||||
* `ROWS PRECEDING` and `ROWS FOLLOWING` window definitions
|
||||
* More function coverage
|
||||
* Geometry types and functions
|
||||
24
docs/windows.md
Normal file
24
docs/windows.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# Windows support
|
||||
|
||||
Dolt is tested and supported on windows! If you find any problems
|
||||
specific to Windows, please file an
|
||||
[issue](https://github.com/dolthub/dolt/issues/) and let us know.
|
||||
|
||||
## Installation
|
||||
|
||||
Download the latest Microsoft Installer (`.msi` file) in
|
||||
[releases](https://github.com/dolthub/dolt/releases) and run it.
|
||||
|
||||
Package manager releases coming soon!
|
||||
|
||||
## Environment
|
||||
|
||||
Dolt runs best under the Windows Subsystem for Linux, or WSL. But it
|
||||
should also work fine with `cmd.exe` or `powershell`. If you find this
|
||||
isn't true, please file an
|
||||
[issue](https://github.com/dolthub/dolt/issues/) and let us know.
|
||||
|
||||
WSL 2 currently has [known
|
||||
bugs](https://github.com/dolthub/dolt/issues/992), so we recommend
|
||||
using WSL 1 for now. Or if you do use WSL 2, we recommend using the
|
||||
Linux `dolt` binary, rather than the Windows `dolt.exe` binary.
|
||||
Reference in New Issue
Block a user