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.

Create database

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

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

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

Create pull request

Include this header in your request.

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

Get pull request details

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]'
}

Update a pull request

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]'
}

List pull requests

Include this header in your request.

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

Create a pull request comment

Include this header in your request.

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

Merge pull request

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]'
}

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

Upload a file

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.

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

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));
    }
  }

}

Create a branch

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

List branches

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

Create a tag

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

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

Create a release

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

List releases

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

List operations

DoltHub provides support for asynchronous operations, including merging, SQL writes, and file importing. When you execute one of these operations from the API, you will get an operation name that you can poll using another endpoint to check the operation status and other information.

This API endpoint lets you monitor the status of all the operations you started in one place without needing to poll the endpoints for singular operations. These operations have error and metadata fields which contain useful information for troubleshooting and debugging.

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

List jobs

DoltHub performs certain asynchronous operations through job execution, including merging, importing, SQL reading, and migrating. When these operations are initiated via the API, you receive an operation name that includes the job ID.

This API endpoint lets you monitor the status of jobs started in a specific database.

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

PreviousCSV NextHooks

Last updated 2 months ago

Was this helpful?

POST /api/v1alpha1/{owner}/{database}/pulls HTTP/1.1 Host: www.dolthub.com authorization: YOUR_API_KEY Content-Type: application/json Accept: */* Content-Length: 275 { "title": "LACMA data", "description": "Records from the Los Angeles County of Museum.", "fromBranchOwnerName": "liuliu", "fromBranchRepoName": "museum-collections", "fromBranchName": "lacma", "toBranchOwnerName": "dolthub", "toBranchRepoName": "museum-collections", "toBranchName": "main" }

{ "status": "Success", "title": "LACMA data", "description": "Records from the Los Angeles County of Museum.", "from_owner_name": "liuliu", "from_repository_name": "museum-collections", "from_branch_name": "lacma", "to_owner_name": "dolthub", "to_repository_name": "museum-collections", "to_branch_name": "main", "pull_id": "66" }

{ "status": "Success", "operations": [ { "operation_name": "users/liuliu/userOperations/5e4834c9-375d-4bbd-bdaf-09eb0734127c", "creator": "liuliu", "description": "Run query CREATE TABLE tablename (\\n pk INT,\\n col1 VARCHAR(255),\\n PRIMARY KEY (pk)\\n);", "operation_type": "SqlWrite", "operation_status": "liuliu", "error": "table with name tablename already exists", "metadata": "{'from_branch_name':'main','from_repo_name':'api-db','from_repo_owner':'liuliu','sql_query':'CREATE TABLE tablename (\\n pk INT,\\n col1 VARCHAR(255),\\n PRIMARY KEY (pk)\\n);','to_branch_name':'main','to_repo_name':'api-db','to_repo_owner':'liuliu'}", "created_at": "2024-01-09T22:19:49.000Z", "updated_at": "2024-01-09T22:19:50.000Z" } ], "next_page_token": "AWE2Nm9uMWQ26pQQpqLNLXu7a60647lpiZoDFrf5WDGHo68XNC-rfr068rymbEdUHCXidRxx7_fwGBMSzQi6C_D50NcJFXm0BwRnGmmHEL4T4xxkWoX3sL5mKD-PuMRuxeHPsR0NB5Rzi70jGzblVlfBTIHPJ20c630pNLrI_spxH0tYTzMnQ4uPpr3ub9P50FEH9i4Au0gUkmvj8NUibbGWi-R1AJYplEPr=" }

Create database

Create pull request

Get pull request details

Update a pull request

List pull requests

Create a pull request comment

Merge pull request

Upload a file

Create a branch

List branches

Create a tag

List tags

Create a release

List releases

List operations

List jobs

Create database

Create pull request

Get pull request details

Update a pull request

List pull requests

Create a pull request comment

Merge pull request

Upload a file

Create a branch

List branches

Create a tag

List tags

Create a release

List releases

List operations

List jobs

Update Pull Request

Get pull request by ID

Merge a pull request

List pull requests of a database

Create a new pull request

Create a new Dolt database

Add comment to pull request

List Tags

Check import operation status

Check merge operation status

Create Tag

List Branches

List jobs

List Releases

List operations

Create Branch

Upload a file to a DoltHub database