Comment on page
Database
DoltHub provides a database API for fetching and creating data on your database. You can create a database, create a pull request, create a pull request comment, and merge a pull request through these APIs.
Please make sure to send your requests to
https://www.dolthub.com
instead of https://dolthub.com
.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': '[api token you created]'
}
post
https://www.dolthub.com
/api/v1alpha1/database
Create a new Dolt database
Here is an example of opening a pull request on the
museum-collections
database with data from the Los Angeles County Museum of Art. This data was added to the lacma
branch on a fork database, whose owner
is liuliu
, we would like to eventually merge lacma
branch into the main
branch using an authorization token.Include this
header
in your request.headers = {
'authorization': '[api token you created]'
}
post
https://www.dolthub.com/api/v1alpha1
/{owner}/{database}/pulls
Create a new pull request
This API allows you to retrieve the details of a specific pull request in the
museum-collections
database. In this example, we will retrieve the details of pull request #1.Include this
header
in your request.headers = {
'authorization': '[api token you created]'
}
get
https://www.dolthub.com/api/v1alpha1
/{owner}/{database}/pulls/{pull_id}
Get pull request by ID
This API allows you to update a pull request by providing the fields you want to update in the request body. You can update the title, description, and state (only closing a pull request is supported).
Here's an example of how to update pull request #1 on the museum-collections database. In this example, we will set a new title, description, and close the pull request.
headers = {
'authorization': '[api token you created]'
}
patch
https://www.dolthub.com/api/v1alpha1
/{owner}/{database}/pulls/{pull_id}
Update Pull Request
Here is an example of listing pull requests for the
museum-collections
database using an authorization token. The response of pull request list is paginated, so you need to use the next page token included in the response to retrieve the following pages of pull requests.Include this
header
in your request.headers = {
'authorization': '[api token you created]'
}
get
https://www.dolthub.com/api/v1alpha1
/{owner}/{database}/pulls
List pull requests of a database
Include this
header
in your request.headers = {
'authorization': '[api token you created]'
}
post
https://www.dolthub.com/api/v1alpha1
/{owner}/{database}/pulls/{pull_id}/comments
Add comment to pull request
Here is an example of merging a pull request
#66
on a database museum-collections
using an authorization token. Note that the merge 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 merge request to query the API. Once the operation is complete, the response will contain a job_id
field indicating the job that's running the merge, as well as other information such as the database_owner
, database_name
, and pull_id
.Keep in mind that the time it takes for the merge operation to complete can vary depending on the size of the pull request and the complexity of the changes being merged.
Include this
header
in your request with the API token you created.headers = {
'authorization': '[api token you created]'
}
post
https://www.dolthub.com/api/v1alpha1
/{owner}/{database}/pulls/{pull_id}/merge
Merge a pull request
Then use
GET
to poll the operation to check if the merge operation is done.get
https://www.dolthub.com/api/v1alpha1
/{owner}/{database}/pulls/{pull_id}/merge
Check merge operation status
Here is an example of uploading a file
lacma.csv
to create a table lacma
on a database museum-collections
using an authorization token. Note that the file import 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 file upload post to query the API. Once the operation is complete, the response will contain a job_id
field indicating the job that's running the file import as well as the id of the pull request that's created when the import job is completed.Keep in mind that the time it takes for the import operation to complete can vary depending on the size of the file and the complexity of the changes being applied to the database. The file size limit is 100 MB.
Include this
header
in your request with the API token you created.headers = {
'authorization': '[api token you created]'
}
To upload the file, include two fields in the request body,
file
and params
, the file
should be type of Blob
, and params
should be a JSON object.post
https://www.dolthub.com/api/v1alpha1
/{owner}/{database}/upload
Upload a file to a DoltHub database
Then use
GET
to poll the operation to check if the import operation is done.get
https://www.dolthub.com/api/v1alpha1
/{owner}/{database}/upload
Check import operation status
Here is an example of uploading a CSV file to create a table through this api endpoint in Javascript, you can reference the
dolt table import
documentation for additional information.:Please make sure to send your requests to
https://www.dolthub.com/api/v1alpha1/{owner}/{database}/upload
instead of https://www.dolthub.com/api/v1alpha1/{owner}/{database}/upload/
, do not need the last /
.const fs = require("fs");
const url =
"https://www.dolthub.com/api/v1alpha1/dolthub/museum-collections/upload";
const headers = {
"Content-Type": "application/json",
authorization: [api token you created],
};
const filePath = "lacma.csv";
fetchFileAndSend(filePath);
async function fetchFileAndSend(filePath) {
const params = {
tableName: "lacma",
fileName: "lacma.csv",
branchName:"main",
fileType: "Csv",
importOp: "Create",
primaryKeys: ["id"],
};
const formData = new FormData();
const fileData = fs.readFileSync(filePath);
const blob = new Blob([buffer], { type: "application/octet-stream" });
await formData.append("file", blob, "lacma.csv");
formData.append("params", JSON.stringify(params));
fetch(url, {
method: "POST",
headers,
body: formData,
})
.then((response) => {
// process response
})
.catch((error) => {
// process error
});
}
And an example of polling the job status in Javascript:
function pollOperation(op_name,branch_name) {
const url = `https: //www.dolthub.com/api/v1alpha1/dolthub/museum-collections/upload?branchName=${branch_name}&operationName=${op_name}`;
const headers = {
"Content-Type": "application/json",
authorization: [api token you created],
};
while (true) {
const res = await fetch(url, {
method: "GET",
headers,
});
const data = await res.json();
if (data.job_created) {
return data;
} else {
await new Promise(r => setTimeout(r, 1000));
}
}
}
Here's an example of how to create a new branch in database
museum-collections
under the organization dolthub
using an authorization token.Creating a branch requires authentication, so you must include this authorization header in your request. See the Authentication section for more details.
headers = {
'authorization': '[api token you created]'
}
post
https://www.dolthub.com/api/v1alpha1
/{owner}/{database}/branches
Create Branch
Here's an example of how to list branches in the database
museum-collections
under the organization dolthub
using an authorization token.Listing branches requires authentication, so you must include this authorization header in your request. See the Authentication section for more details.
headers = {
'authorization': '[api token you created]'
}
get
https://www.dolthub.com/api/v1alpha1
/{owner}/{database}/branches
List Branches
Here's an example of how to create a new release in the database
museum-collections
under the organization dolthub
using an authorization token.Creating a release requires authentication, so you must include this authorization header in your request. See the Authentication section for more details.
headers = {
'authorization': '[api token you created]'
}
post
https://www.dolthub.com/api/v1alpha1
/{owner}/{database}/releases
Create Release
Here's an example of how to list releases in the database
museum-collections
under the organization dolthub
using an authorization token.Listing releases requires authentication, so you must include this authorization header in your request. See the Authentication section for more details.
headers = {
'authorization': '[api token you created]'
}
get
https://www.dolthub.com/api/v1alpha1
/{owner}/{database}/releases
List Releases
Last modified 2mo ago