Databases#

API version: v1alpha1

DoltHub provides API endpoints for creating, forking, and listing forks of a database.

Note: please send requests to https://www.dolthub.com, not https://dolthub.com.

Create database#

Here’s an example of how to create a new database called museum-collections under the organization dolthub using an authorization token.

Creating a database requires authentication, so you must include this authorization header in your request. See the Authentication section for more details.

headers = {
    'authorization': 'token [api token you created]'
}

POST /database

Create a new Dolt database

This API allows you to create a new Dolt database.

URL https://www.dolthub.com/api/v1alpha1/database

Request Body

Content-Type: application/json

Field	Type	Required	Description
`description`	string	No	A description of the database.
`ownerName`	string	Yes	The name of the owner of the database.
`repoName`	string	Yes	The name of the repository for the database.
`visibility`	string	Yes	The visibility of the database (public or private).

Responses

200 Database created successfully.

Body — application/json

{
  "status": "Success",
  "description": "Records from museums around the world.",
  "repository_owner": "dolthub",
  "repository_name": "museum-collections",
  "visibility": "public"
}

Field	Type	Description
`status`	string
`description`	string
`repository_owner`	string
`repository_name`	string
`visibility`	string

400 Bad request. The request was invalid or could not be processed.

Body — application/json

{
  "status": "Error",
  "message": "Error creating a database.",
  "description": "Records from museums around the world.",
  "repository_owner": "dolthub",
  "repository_name": "museum-collections",
  "visibility": "public"
}

Field	Type	Description
`status`	string
`message`	string
`description`	string
`repository_owner`	string
`repository_name`	string
`visibility`	string

Fork database#

Here’s an example of how to fork a database called dolthub/museum-collections to the username taylor using an authorization token. Note that the fork operation is asynchronous and creates an operation that can be polled to get the result.

To poll the operation and check its status, you can use the operationName in the returned response of the fork request to query the API. Once the operation is complete, the response will contain the new database owner and name.

Keep in mind that the time it takes for the fork operation to complete can vary depending on the size of the database.

Forking a database requires authentication, so you must include this authorization header in your request. See the Authentication section for more details.

headers = {
    'authorization': 'token [api token you created]'
}

POST /fork

Fork an existing Dolt database

This API allows you to fork an existing Dolt database.

URL https://www.dolthub.com/api/v1alpha1/fork

Request Body

Content-Type: application/json

Field	Type	Required	Description
`parentOwnerName`	string	No	The name of the owner of the parent database.
`parentDatabaseName`	string	No	The name of the parent database.
`ownerName`	string	No	The name of the owner to fork to.

Responses

200 Success.

Body — application/json

{
  "status": "Success",
  "parent_owner": "dolthub",
  "parent_database": "museum-collections",
  "forked_owner": "myusername",
  "operation_name": "operations/b09a9221-9dcb-4a15-9ca8-a64656946f12"
}

Field	Type	Description
`status`	string
`parent_owner`	string
`parent_database`	string
`forked_owner`	string
`operation_name`	string

400 Bad request. The request was invalid or could not be processed.

Body — application/json

{
  "status": "Error",
  "message": "Error creating a database.",
  "parent_owner": "dolthub",
  "parent_database": "museum-collections",
  "forked_owner": "myusername"
}

Field	Type	Description
`status`	string
`message`	string
`parent_owner`	string
`parent_database`	string
`forked_owner`	string

Then use GET to poll the operation to check if the fork operation is done.

GET /fork

Check fork operation status

Poll the operation to check if the fork operation is done

URL https://www.dolthub.com/api/v1alpha1/fork

Parameters

Name	In	Type	Required	Description
`operationName`	query	string	Yes	The operation name to check Example: `operations/b09a9221-9dcb-4a15-9ca8-a64656946f12`

Responses

200 The status of the fork operation

Body — application/json

{
  "status": "Success",
  "done": true,
  "operation_name": "operations/jobs/b09a9221-9dcb-4a15-9ca8-a64656946f12",
  "database_owner": "myusername",
  "database_name": "museum-collections"
}

Field	Type	Description
`status`	string	The status of the operation, Success if the fork creation was successful
`done`	boolean	True if the fork operation is done, false otherwise
`operation_name`	string	The operation name
`database_owner`	string	The owner of the newly forked database
`database_name`	string	The name of the newly forked database

400 Bad request. The request was invalid or could not be processed.

Body — application/json

{
  "status": "Error",
  "message": "Error polling an operation status.",
  "operation_name": "operations/jobs/b09a9221-9dcb-4a15-9ca8-a64656946f12"
}

Field	Type	Description
`status`	string
`message`	string
`operation_name`	string

List forks#

Here’s an example of how to list the databases within the fork network of a database called dolthub/museum-collections using an authorization token.

headers = {
    'authorization': 'token [api token you created]'
}

GET /{owner}/{database}/forks

List Forks

This API endpoint allows you to list all forks within the fork network of a database.

URL https://www.dolthub.com/api/v1alpha1/{owner}/{database}/forks

Parameters

Name	In	Type	Required	Description
`owner`	path	string	Yes	The name of the owner of the database. Example: `dolthub`
`database`	path	string	Yes	The name of the database. Example: `museum-collections`

Responses

200 Success

Body — application/json

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "forks": [
    {
      "database_owner": "anotherOrg",
      "database_name": "museum-collections"
    }
  ],
  "parent_owner": "",
  "parent_database_name": "",
  "network_root_owner": "dolthub",
  "network_root_database_name": "museum-collections",
  "fork_network_count": 3
}

Field	Type	Description
`status`	string	Status of the request.
`database_owner`	string	Owner of the database.
`database_name`	string	Name of the database.
`forks`	array<object>	List of forks within the fork network of this database.
`parent_owner`	string	Owner of the parent database, empty if this is the root.
`parent_database_name`	string	Name of the parent database, empty if this is the root.
`network_root_owner`	string	Owner of the root database in the fork network.
`network_root_database_name`	string	Name of the root database in the fork network.
`fork_network_count`	integer	Number of forks in the fork network (excluding the root).

400 Bad request. The request was invalid or could not be processed.

Body — application/json

{
  "status": "Error",
  "message": "Error getting the forks list.",
  "database_owner": "dolthub",
  "database_name": "with-archives"
}

Field	Type	Description
`status`	string
`message`	string
`database_owner`	string	Owner of the database.
`database_name`	string	Name of the database.