Just like Git, Dolt supports syncing with a remote database. A remote is a copy of your database that is distinct from your local copy. It usually is stored on a separate host or service for fault tolerance. The primary use cases are disaster recovery and collaboration. More conceptual description of remotes can be found here.
Remotes are configured using the
remotecommand. You configure a remote with a name and a URL. When you want to use the remote, you refer to it by name. When you clone a remote, a remote named
originis automatically configured for you.
DoltHub is a remote operated by DoltHub Inc. Public repositories are free. Private repositories are free up to a Gigabyte. After a Gigabyte, private repositories are $50 a month and scale up in cost after 100GB. DoltHub adds a web GUI to your remotes along with Forks, Pull Requests, and Issues.
Filesystem based remotes allow you to push/pull data from any location that can be accessed via the filesystem. This may be a directory on your local disk, or any other storage location that can be mounted to the filesystem. To add a filesystem based remote use a URL with the
Linux / OSX Examples
- Adding a remote
dolt remote add origin file:///Users/brian/datasets/menus
dolt clone file:///Users/brian/datasets/menus
- Adding a remote
dolt remote add origin file:///c:/Users/brian/datasets/menus
dolt clone file:///c:/Users/brian/datasets/menus
It's important to note that a directory-based remote is not the same as a workspace for a dolt clone, and the directory listed above as a remote file URL is not a dolt repository created or cloned with the Dolt cli. Similarly, a Dolt repository directory's file URL cannot be used as a remote directly.
AWS remotes use a combination of DynamoDB and S3. The Dynamo table can be created with any name but must have a primary key with the name "db".
Create a Dynamo Table with a primary key of: db
This single DynamoDB table can be used for multiple unrelated remote repositories. Once you have a DynamoDB table, and an S3 bucket setup you can add an AWS remote using a URL with the protocol
aws://. To add a remote named "origin" to my "menus" repository using an S3 bucket named
dolt_remotes_s3_storageand a DynamoDB table named
dolt_dynamo_tableyou would run:
dolt remote add origin aws://[dolt_dynamo_table:dolt_remotes_s3_storage]/menus
This same URL can then be used to clone this database by another user.
dolt clone aws://[dolt_remotes:dolt_remotes_storage]/menus
In order to initialize your system to be able to connect to your AWS cloud resources see Amazon's documentation on configuring your credential file. Dolt also provides additional parameters you may need to provide when adding an AWS remote such as
aws-creds-profileallows you to select a profile from your credential file. If it is not provided then the default profile is used.
aws-regionallows you to specify the region in which your DynamoDB table and S3 bucket are located. If not provided, it will use the default region from the current profile.
dolt remote add --aws-creds-profile prod-profile --aws-region us-west-2 origin aws://[dolt_dynamo_table:dolt_remotes_s3_storage]/menus
dolt clone --aws-creds-profile prod-profile --aws-region us-west-2 origin aws://[dolt_dynamo_table:dolt_remotes_s3_storage]/menus
Google Cloud Platform remotes use Google Cloud Storage (GCS). You can create or use an existing GCS bucket to host one or more Dolt remotes. To add a GCP remote provide a URL with the
gs://protocol like so:
dolt remote add origin gs://BUCKET/path/for/remote
Dolt supports remotes which use the protocol
https://. Remote servers must implement the GRPC methods defined by the ChunkStoreService interface. This is the way by which DoltHub itself provides remote functionality. When you add a DoltHub remote via
dolt remote add origin owner/repositoryor do a
dolt clone owner/repositoryDolt is just providing shorthand notation for the URL. When you run
dolt remote -vyou can see that Dolt adds an
https://URL with the host
doltremoteapi.dolthub.comas can be seen here:
$dolt remote add origin Dolthub/menus
$dolt remote -v
remotesrv --http-port 1234 --dir ./remote_storage
This starts a server listening on port 50051 for our grpc requests, and runs a file server on port 1234 which provides upload, and download functionality similar to S3 / GCS locally. We use the url
http://localhost:50051/test-org/test-repowhen adding a remote or cloning from this remote server.