diff --git a/TOC-tidb-cloud.md b/TOC-tidb-cloud.md index 8038a878f3265..2c5635b64ce95 100644 --- a/TOC-tidb-cloud.md +++ b/TOC-tidb-cloud.md @@ -140,6 +140,8 @@ - [Manage Data App](/tidb-cloud/data-service-manage-data-app.md) - [Manage Endpoint](/tidb-cloud/data-service-manage-endpoint.md) - [API Key](/tidb-cloud/data-service-api-key.md) + - [Deploy Automatically with GitHub](/tidb-cloud/data-service-manage-github-connection.md) + - [Data App Configuration Files](/tidb-cloud/data-service-app-config-files.md) - [Response and Status Code](/tidb-cloud/data-service-response-and-status-code.md) - Stream Data - [Changefeed Overview](/tidb-cloud/changefeed-overview.md) diff --git a/tidb-cloud/data-service-app-config-files.md b/tidb-cloud/data-service-app-config-files.md new file mode 100644 index 0000000000000..d28ff099b1c33 --- /dev/null +++ b/tidb-cloud/data-service-app-config-files.md @@ -0,0 +1,205 @@ +--- +title: Data App Configuration Files +summary: This document describes the configuration files of Data App in TiDB Cloud. +--- + +# Data App Configuration Files + +This document describes the configuration files of a [Data App](/tidb-cloud/tidb-cloud-glossary.md#data-app) in TiDB Cloud. + +If you have [connected your Data App to GitHub](/tidb-cloud/data-service-manage-github-connection.md), you can find the configuration files of your Data App in your specified directory on GitHub as follows: + +``` +├── +│ ├── data_sources +│ │ └── cluster.json +│ ├── dataapp_config.json +│ ├── http_endpoints +│ │ ├── config.json +│ │ └── sql +│ │ ├── -.sql +│ │ ├── -.sql +│ │ └── -.sql +``` + +## Data source configuration + +The data source of a Data App comes from its linked TiDB clusters. You can find the data source configuration in `data_sources/cluster.json`. + +``` +├── +│ ├── data_sources +│ │ └── cluster.json +``` + +For each Data App, you can link to one or multiple TiDB Serverless clusters. + +The following is an example configuration of `cluster.json`. In this example, there are two linked clusters for this Data App. + +```json +[ + { + "cluster_id": + }, + { + "cluster_id": + } +] +``` + +The field description is as follows: + +| Field | Type | Description | +|---------|---------|--------------| +| `cluster_id` | Integer | The ID of your TiDB Serverless cluster. You can get it from the URL of your cluster. For example, if your cluster URL is `https://tidbcloud.com/console/clusters/1234567891234567890/overview`, your cluster ID is `1234567891234567890`. | + +## Data App configuration + +The properties of a Data App contain the App ID, name, and type. You can find the properties in the `dataapp_config.json` file. + +``` +├── +│ ├── dataapp_config.json +``` + +The following is an example configuration of `dataapp_config.json`. + +```json +{ + "app_id": "", + "app_name": "", + "app_type": "dataapi" +} +``` + +The description of each field is as follows: + +| Field | Type | Description | +|------------|--------|--------------------| +| `app_id` | String | The Data App ID. Do not change this field unless your `dataapp_config.json` file is copied from another Data App and you want to update it to the ID of your current Data App. Otherwise, the deployment triggered by this modification will fail. | +| `app_name` | String | The Data App name. | +| `app_type` | String | The Data App type, which can only be `"dataapi"`. | + +## HTTP endpoint configuration + +In your Data App directory, you can find endpoint configurations in `http_endpoints/config.json` and the SQL files in `http_endpoints/sql/-.sql`. + +``` +├── +│ ├── http_endpoints +│ │ ├── config.json +│ │ └── sql +│ │ ├── -.sql +│ │ ├── -.sql +│ │ └── -.sql +``` + +### Endpoint configuration + +For each Data App, there can be one or multiple endpoints. You can find the configurations of all endpoints for a Data App in `http_endpoints/config.json`. + +The following is an example configuration of `config.json`. In this example, there are two endpoints for this Data App. + +```json +[ + { + "name": "", + "description": "", + "method": "", + "endpoint": "", + "data_source": { + "cluster_id": + }, + "params": [], + "settings": { + "timeout": , + "row_limit": + }, + "sql_file": "", + "type": "sql_endpoint", + "return_type": "json" + }, + { + "name": "", + "description": "", + "method": "", + "endpoint": "", + "data_source": { + "cluster_id": + }, + "params": [ + { + "name": "", + "type": "", + "required": <0 | 1>, + "default": "" + } + ], + "settings": { + "timeout": , + "row_limit": + }, + "sql_file": "", + "type": "sql_endpoint", + "return_type": "json" + } +] +``` + +The description of each field is as follows: + +| Field | Type | Description | +|---------------|--------|-------------| +| `name` | String | The endpoint name. | +| `description` | String | (Optional) The endpoint description. | +| `method` | String | The HTTP method of the endpoint. You can use `GET` to query data or use `POST` to insert data. | +| `endpoint` | String | The unique path of the endpoint in the Data App. Only letters, numbers, underscores (`_`), and slashes (`/`) are allowed in the path, which must start with a slash (`/`) and end with a letter, number, or underscore (`_`). For example, `/my_endpoint/get_id`. The length of the path must be less than 64 characters.| +| `cluster_id` | String | The ID of the TiDB cluster for your endpoint. You can get it from the URL of your TiDB cluster. For example, if your cluster URL is `https://tidbcloud.com/console/clusters/1234567891234567890/overview`, the cluster ID is `1234567891234567890`. | +| `params` | Array | The parameters used in the endpoint. By defining parameters, you can dynamically replace the parameter value in your queries through the endpoint. In `params`, you can define one or multiple parameters. For each parameter, you need to define its `name`, `type`, `required`, and `default` fields. If your endpoint does not need any parameters. You can leave `params` empty such as `"params": []`. | +| `params.name` | String | The name of the parameter. The name can only include letters, digits, and underscores (`_`) and must start with a letter or an underscore (`_`). | +| `params.type` | String | The data type of the parameter. Supported values are `string`, `number`, and `boolean`. When using a `string` type parameter, you do not need to add quotation marks (`'` or `"`). For example, `foo` is valid for the `string` type and is processed as `"foo"`, whereas `"foo"` is processed as `"\"foo\""`.| +| `params.required` | Integer | Specifies whether the parameter is required in the request. Supported values are `0` (not required) and `1` (required). The default value is `0`. | +| `params.default` | String | The default value of the parameter. Make sure that the value matches the type of parameter you specified. Otherwise, the endpoint returns an error. | +| `timeout` | Integer | The timeout for the endpoint in milliseconds, which is `5000` by default. You can set it to an integer from `1` to `30000`. | +| `row_limit` | Integer | The maximum number of rows that the endpoint returns, which is `50` by default. You can set it to an integer from `1` to `2000`. | +| `sql_file` | String | The SQL file directory for the endpoint. For example, `"sql/GET-v1.sql"`. | +| `type` | String | The type of the endpoint, which can only be `"sql_endpoint"`. | +| `return_type` | String | The response format of the endpoint, which can only be `"json"`. | + +### SQL file configuration + +The SQL file of an endpoint specifies the SQL statements to query data through the endpoint. You can find the endpoint SQL files of a Data App in the `http_endpoints/sql/` directory. For each endpoint, there should be a corresponding SQL file. + +The name of a SQL file is in the `-.sql` format, where `` and `` must match the `method` and `endpoint` configuration in [`http_endpoints/config.json`](#endpoint-configuration). + +In the SQL file, you can write statements such as table join queries, complex queries, and aggregate functions. The following is an example SQL file. + +```sql +/* Getting Started: +Enter "USE {database};" before entering your SQL statements. +Type "--your question" + Enter to try out AI-generated SQL queries in the TiDB Cloud console. +Declare a parameter like "Where id = ${arg}". +*/ +USE sample_data; +SELECT + rank, + company_name, +FROM + global_fortune_500_2018_2022 +WHERE + country = ${country}; +``` + +When writing a SQL file, pay attention to the following: + +- At the beginning of the SQL file, you need to specify the database in the SQL statements. For example, `USE database_name;`. + +- To define a parameter of the endpoint, you can insert it as a variable placeholder like `${variable-name}` to the SQL statement. + + In the preceding example, `${country}` is used as a parameter of the endpoint. With this parameter, you can specify a desired country to query in your endpoint curl command. + + > **Note:** + > + > - The parameter name is case-sensitive. + > - The parameter cannot be a table name or column name. + > - The parameter name in the SQL file match the parameter name configured in [`http_endpoints/config.json`](#endpoint-configuration). \ No newline at end of file diff --git a/tidb-cloud/data-service-get-started.md b/tidb-cloud/data-service-get-started.md index 36a2acf7d0a60..ead279a80456e 100644 --- a/tidb-cloud/data-service-get-started.md +++ b/tidb-cloud/data-service-get-started.md @@ -29,7 +29,22 @@ A Data App is a group of endpoints that you can use to access data for a specifi 3. On the **Get started by creating your first data application** page, enter a name and select clusters that you want the Data App to access. -4. Click **Create Data App**. The [**Data Service**](https://tidbcloud.com/console/data-service) details page is displayed. +4. (Optional) To automatically deploy endpoints of the Data App to your preferred GitHub repository and branch, enable **Connect to GitHub**, and then do the following: + + 1. Click **Install on GitHub**, and then follow the on-screen instructions to install **TiDB Cloud Data Service** as an application on your target repository. + 2. Click **Authorize** to authorize access to the application on GitHub. + 3. Specify the target repository, branch, and directory where you want to save the configuration files of your Data App. + + > **Note:** + > + > - The directory must start with a slash (`/`). For example, `/mydata`. If the directory you specified does not exist in the target repository and branch, it will be created automatically. + > - The combination of repository, branch, and directory identifies the path of the configuration files, which must be unique among Data Apps. If your specified path is already used by another Data App, you need to specify a new path instead. Otherwise, the endpoints configured in the TiDB Cloud console for the current Data App will overwrite the files in your specified path. + +5. Click **Create Data App**. The [**Data Service**](https://tidbcloud.com/console/data-service) details page is displayed. + +6. If you have configured to connect your Data App to GitHub, check your specified GitHub directory. You will find that the [Data App configuration files](/tidb-cloud/data-service-app-config-files.md) have been committed to the directory by `tidb-cloud-data-service`, which means that your Data App is connected to GitHub successfully. + + For your new Data App, **Auto Sync & Deployment** and **Review Draft** are enabled by default so you can easily synchronize Data App changes between TiDB Cloud console and GitHub and review changes before the deployment. For more information about the GitHub integration, see [Deploy your Data App changes with GitHub automatically](/tidb-cloud/data-service-manage-github-connection.md). ## Step 2. Develop an endpoint @@ -37,7 +52,7 @@ An endpoint is a web API that you can customize to execute SQL statements. After creating a Data App, a default `untitled endpoint` is created for you automatically. You can use the default endpoint to access your TiDB Cloud cluster. -If you want to create a new endpoint, locate the newly created Data App and click **+** **Create Endpoint** on the top of the left pane. +If you want to create a new endpoint, locate the newly created Data App and click **+** **Create Endpoint** to the right of the App name. ### Configure properties @@ -46,7 +61,7 @@ On the right pane, click the **Properties** tab and set properties for the endpo - **Endpoint Path**: the unique path of the endpoint that users use to access it. - The path must be unique within a Data App. - - Only letters, numbers, underscores (`_`), and slashes (`/`) are allowed in the path, which must start with a slash (`/`). For example, `/my_endpoint/get_id`. + - Only letters, numbers, underscores (`_`), and slashes (`/`) are allowed in the path, which must start with a slash (`/`) and end with a letter, number, or underscore (`_`). For example, `/my_endpoint/get_id`. - The length of the path must be less than 64 characters. - **Endpoint URL**: (read-only) the URL is automatically generated based on the region where the corresponding cluster is located, the service URL of the Data App, and the path of the endpoint. For example, if the path of the endpoint is `/my_endpoint/get_id`, the endpoint URL is `https://.data.tidbcloud.com/api/v1beta/app//endpoint/my_endpoint/get_id`. @@ -68,7 +83,7 @@ You can customize SQL statements for the endpoint in the SQL editor, which is th > **Note:** > - > Only clusters that are linked to the Data App are displayed in the drop-down list. To manage the linked clusters, see [Manage linked clusters](/tidb-cloud/data-service-manage-data-app.md#manage-linked-clusters). + > Only clusters that are linked to the Data App are displayed in the drop-down list. To manage the linked clusters, see [Manage linked clusters](/tidb-cloud/data-service-manage-data-app.md#manage-linked-data-sources). On the upper part of the SQL editor, select a cluster on which you want to execute SQL statements from the drop-down list. Then, you can view all databases of this cluster in the **Schema** tab on the right pane. diff --git a/tidb-cloud/data-service-manage-data-app.md b/tidb-cloud/data-service-manage-data-app.md index f1d95beade49a..1a611cd56fc15 100644 --- a/tidb-cloud/data-service-manage-data-app.md +++ b/tidb-cloud/data-service-manage-data-app.md @@ -13,9 +13,27 @@ This document describes how to manage your Data Apps in the TiDB Cloud console. To create a Data App for your project, perform the following steps: -1. Navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project. -2. In the left pane, click **Create DataApp** and update the default name if necessary. -3. The newly created Data App is added to the top of the list. A default `untitled endpoint` is created for the new Data App. +1. On the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project, click **Create DataApp** in the left pane. +2. Enter a name for the Data App, and select clusters that you want the Data App to access. +3. (Optional) To automatically deploy endpoints of the Data App to your preferred GitHub repository and branch, enable **Connect to GitHub**, and then do the following: + + 1. Click **Install on GitHub**, and then follow the on-screen instructions to install **TiDB Cloud Data Service** as an application on your target repository. + 2. Click **Authorize** to authorize access to the application on GitHub. + 3. Specify the target repository, branch, and directory where you want to save the configuration files of your Data App. + + > **Note:** + > + > - The directory must start with a slash (`/`). For example, `/mydata`. If the directory you specified does not exist in the target repository and branch, it will be created automatically. + > - The combination of repository, branch, and directory identifies the path of the configuration files, which must be unique among Data Apps. If your specified path is already used by another Data App, you need to specify a new path instead. Otherwise, the endpoints configured in the TiDB Cloud console for the current Data App will overwrite the files in your specified path. + > - If your specified path contains configuration files copied from another Data App and you want to import these files to the current Data App, see [Import configurations of an existing Data App](/tidb-cloud/data-service-manage-github-connection.md#import-configurations-of-an-existing-data-app). + +4. Click **Create Data App**. + + The newly created Data App is added to the top of the list. A default `untitled endpoint` is created for the new Data App. + +5. If you have configured to connect your Data App to GitHub, check your specified GitHub directory. You will find that the [Data App configuration files](/tidb-cloud/data-service-app-config-files.md) have been committed to the directory by `tidb-cloud-data-service`, which means that your Data App is connected to GitHub successfully. + + For your new Data App, **Auto Sync & Deployment** and **Review Draft** are enabled by default so you can easily synchronize Data App changes between TiDB Cloud console and GitHub and review changes before the deployment. For more information about the GitHub integration, see [Deploy your Data App changes with GitHub automatically](/tidb-cloud/data-service-manage-github-connection.md). ## Modify a Data App @@ -23,28 +41,32 @@ You can rename a Data App, and manage its API keys, linked clusters, and endpoin ### Rename a Data App -To rename a Data App, navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page, and do one of the following: +To rename a Data App, perform the following steps: -- In the left pane, locate your target Data App, click **...** > **Rename**, and enter a new name. +1. Navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project. +2. In the left pane, click the name of your target Data App to view its details. +3. In the **Data App Properties** area, click , modify the **App Name** field, and then click **Confirm**. -- In the left pane, click the name of your target Data App to view its details. In the **Basic Settings** area, modify the **Name** field and click **Save**. +### Manage GitHub connection -### Manage linked clusters +For more information, see [Deploy automatically with GitHub](/tidb-cloud/data-service-manage-github-connection.md). -You can add or remove linked clusters for a Data App. After you remove a linked cluster, the endpoints in the Data App can still access other linked clusters. +### Manage linked data sources + +You can add or remove linked clusters for a Data App. To link a cluster to a Data App, perform the following steps: 1. Navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project. 2. In the left pane, locate your target Data App and click the name of your target Data App to view its details. -3. In the **Linked Cluster** area, click **Add Cluster**. +3. In the **Linked Data Sources** area, click **Add Cluster**. 4. In the displayed dialog box, select a cluster from the list and click **Add**. To remove a linked cluster from a Data App, perform the following steps: 1. Navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project. 2. In the left pane, locate your target Data App and click the name of your target Data App to view its details. -3. In the **Linked Cluster** area, locate the target linked cluster you want to remove from the Data App, and click **Delete** in the **Action** column. +3. In the **Linked Data Sources** area, locate the target linked cluster you want to remove from the Data App, and click **Delete** in the **Action** column. 4. In the displayed dialog box, confirm the removal. After you remove a linked cluster, the cluster is not deleted, but the existing endpoints in the Data App cannot access it. @@ -57,6 +79,28 @@ For more information, see [Manage an API key](/tidb-cloud/data-service-api-key.m For more information, see [Manage an endpoint](/tidb-cloud/data-service-manage-endpoint.md). +### Manage deployments + +To manage deployments, perform the following steps: + +1. Navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project. +2. In the left pane, locate your target Data App and click the name of your target Data App to view its details. +3. Click the **Deployments** tab to view the deployment information. +4. In the upper-right corner, click **Configure**, and then choose your desired setting of **Auto Sync & Deployment** and **Review Draft**. + + - **Auto Sync & Deployment** + + - This option can be enabled only when your Data App is connected to GitHub. For more information, see [Deploy automatically with GitHub](/tidb-cloud/data-service-manage-github-connection.md). + - When it is enabled, the changes made in your specified GitHub directory can be automatically deployed in TiDB Cloud, and the changes made in the TiDB Cloud console can be pushed to GitHub as well. You can find the corresponding deployment and commit information in the Data App deployment history. + - When it is disabled, the changes made in your specified GitHub directory will **NOT** be deployed in TiDB Cloud, and the changes made in the TiDB Cloud console will **NOT** be pushed to GitHub either. + + - **Review Draft** + + - When it is enabled, you can review the Data App changes you made in the TiDB Cloud console before the deployment. Based on the review, you can either deploy or discard the changes. + - When it is disabled, the Data App changes you made in the TiDB Cloud console are deployed directly. + +5. In the **Action** column, you can edit or re-deploy your changes according to your needs. + ## Delete a Data App > **Note:** @@ -66,7 +110,8 @@ For more information, see [Manage an endpoint](/tidb-cloud/data-service-manage-e To delete a Data App, perform the following steps: 1. Navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project. -2. In the left pane, locate your target Data App, and click **...** > **Delete**. The **Confirm deletion of DataApp** dialog box is displayed. -3. Click **Delete** to confirm the deletion. +2. In the left pane, locate your target Data App and click the name of your target Data App to view its details. +3. In the **Delete Data App** area, click **Delete Data App**. A dialog box for confirmation is displayed. +4. Type the name of target Data App, and then click **I understand, delete**. - Once a Data App is deleted, the existing endpoints and API keys in the Data App are also deleted. + Once a Data App is deleted, the existing endpoints and API keys in the Data App are also deleted. If this Data App is connected to GitHub, deleting the App does not delete the files in the corresponding GitHub repository. diff --git a/tidb-cloud/data-service-manage-endpoint.md b/tidb-cloud/data-service-manage-endpoint.md index 41862197221ed..89d4dcff0637f 100644 --- a/tidb-cloud/data-service-manage-endpoint.md +++ b/tidb-cloud/data-service-manage-endpoint.md @@ -20,7 +20,7 @@ Before you call an endpoint, make sure that you have created an API key in the D To create an endpoint, perform the following steps: 1. Navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project. -2. In the left pane, click the name of your target Data App and click **...** > **Create Endpoint**. You can update the default name if necessary. +2. In the left pane, locate your target Data App and click **+** **Create Endpoint** to the right of the App name. You can update the default name if necessary. > **Tip:** > @@ -34,6 +34,10 @@ You can also create an endpoint from a SQL file in Chat2Query (beta). For more d For each endpoint, you can write SQL statements to execute on a TiDB cluster, define parameters for the SQL statements, or manage the name and version. +> **Note:** +> +> If you have connected your Data App to GitHub with **Auto Sync & Deployment** enabled, you can also update the endpoint configurations using GitHub. Any changes you made in GitHub will be deployed in TiDB Cloud automatically. For more information, see [Deploy automatically with GitHub](/tidb-cloud/data-service-manage-github-connection.md). + ### Configure properties On the right pane of the endpoint details page, you can click the **Properties** tab to view and manage the following properties of the endpoint: @@ -41,7 +45,7 @@ On the right pane of the endpoint details page, you can click the **Properties** - **Endpoint Path**: the unique path of the endpoint that users use to access it. - The path must be unique within a Data App. - - Only letters, numbers, underscores (`_`), and slashes (`/`) are allowed in the path, which must start with a slash (`/`). For example, `/my_endpoint/get_id`. + - Only letters, numbers, underscores (`_`), and slashes (`/`) are allowed in the path, which must start with a slash (`/`) and end with a letter, number, or underscore (`_`). For example, `/my_endpoint/get_id`. - The length of the path must be less than 64 characters. - **Endpoint URL**: (read-only) the URL is automatically generated based on the region where the corresponding cluster is located, the service URL of the Data App, and the path of the endpoint. For example, if the path of the endpoint is `/my_endpoint/get_id`, the endpoint URL is `https://.data.tidbcloud.com/api/v1beta/app//endpoint/my_endpoint/get_id`. @@ -74,7 +78,7 @@ On the SQL editor of the endpoint details page, you can write and run the SQL st > **Note:** > - > Only clusters that are linked to the Data App are displayed in the drop-down list. To manage the linked clusters, see [Manage linked clusters](/tidb-cloud/data-service-manage-data-app.md#manage-linked-clusters). + > Only clusters that are linked to the Data App are displayed in the drop-down list. To manage the linked clusters, see [Manage linked clusters](/tidb-cloud/data-service-manage-data-app.md#manage-linked-data-sources). On the upper part of the SQL editor, select a cluster on which you want to execute SQL statements from the drop-down list. Then, you can view all databases of this cluster in the **Schema** tab on the right pane. @@ -155,13 +159,17 @@ After testing the endpoint, you can see the response as JSON at the bottom of th ## Deploy an endpoint +> **Note:** +> +> If you have connected your Data App to GitHub with **Auto Sync & Deployment** enabled, any Data App changes you made in GitHub will be deployed in TiDB Cloud automatically. For more information, see [Deploy automatically with GitHub](/tidb-cloud/data-service-manage-github-connection.md). + To deploy an endpoint, perform the following steps: 1. Navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project. 2. In the left pane, click the name of your target Data App to view its endpoints. 3. Locate the endpoint you want to deploy, click the endpoint name to view its details, and then click **Deploy** in the upper-right corner. - -4. Click **Deploy** to confirm the deployment. You will get the **Endpoint has been deployed** prompt if the endpoint is successfully deployed. +4. If **Review Draft** is enabled for your Data App, a dialog is displayed for you to review the changes you made. You can choose whether to discard the changes based on the review. +5. Click **Deploy** to confirm the deployment. You will get the **Endpoint has been deployed** prompt if the endpoint is successfully deployed. On the right pane of the endpoint details page, you can click the **Deployments** tab to view the deployed history. @@ -238,13 +246,16 @@ After calling an endpoint, you can see the response in JSON format. For more inf ## Undeploy an endpoint +> **Note:** +> +> If you have [connected your Data App to GitHub](/tidb-cloud/data-service-manage-github-connection.md) with **Auto Sync & Deployment** enabled, undeploying an endpoint of this Data App will also delete the configuration of this endpoint on GitHub. + To undeploy an endpoint, perform the following steps: 1. Navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project. 2. In the left pane, click the name of your target Data App to view its endpoints. -3. Click the name of the endpoint you want to undeploy to view its details. -4. On the right pane of the endpoint details page, click the **Deployments** tab. The deployed version page is displayed. -5. Locate the current online version and click **Undeploy**. The version status will be changed to **Offline**. +3. Locate the endpoint you want to undeploy, click **...** > **Undeploy**. +4. Click **Undeploy** to confirm the undeployment. ## Delete an endpoint @@ -256,10 +267,5 @@ To delete an endpoint, perform the following steps: 1. Navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project. 2. In the left pane, click the name of your target Data App to view its endpoints. -3. Locate the endpoint you want to delete and click **...** > **Delete**. The **Confirm deletion of endpoint** dialog box is displayed. - - > **Tip:** - > - > Alternatively, you can also click the endpoint name to view its details and click **...** > **Delete** in the upper-right corner. - +3. Click the name of the endpoint you want to delete, and then click **...** > **Delete** in the upper-right corner. 4. Click **Delete** to confirm the deletion. diff --git a/tidb-cloud/data-service-manage-github-connection.md b/tidb-cloud/data-service-manage-github-connection.md new file mode 100644 index 0000000000000..ecf116c144621 --- /dev/null +++ b/tidb-cloud/data-service-manage-github-connection.md @@ -0,0 +1,158 @@ +--- +title: Deploy Data App Automatically with GitHub +summary: Learn how to deploy your Data App automatically with GitHub. +--- + +# Deploy Data App Automatically with GitHub + +TiDB Cloud provides a Configuration as Code (CaC) approach to represent your entire Data App configurations as code using the JSON syntax. + +By connecting your Data App to GitHub, TiDB Cloud can use the CaC approach and push your Data App configurations as [configuration files](/tidb-cloud/data-service-app-config-files.md) to your preferred GitHub repository and branch. + +If **Auto Sync & Deployment** is enabled for your GitHub connection, you can also modify your Data App by updating its configuration files on GitHub. After you push the configuration file changes to GitHub, the new configurations will be deployed in TiDB Cloud automatically. + +This document introduces how to deploy your Data App automatically with GitHub and how to manage the GitHub connection. + +## Before you begin + +Before you connect a Data App to GitHub, make sure that you have the following: + +- A GitHub account. +- A GitHub repository with your target branch. + +> **Note:** +> +> The GitHub repository is used to store [Data App configuration files](/tidb-cloud/data-service-app-config-files.md) after you connect a Data App to it. If the information (such as the cluster ID and endpoint URL) in the configuration files is sensitive, make sure to use a private repository instead of a public one. + +## Step 1. Connect your Data App to GitHub + +You can connect your Data App to GitHub when you create the App. For more information, see [Create a Data App](/tidb-cloud/data-service-manage-data-app.md). + +If you did not enable the GitHub connection during the App creation, you can still enable it as follows: + +1. Navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project. +2. In the left pane, click the name of your target Data App to view its details. +3. On the **Settings** tab, click **Connect** in the **Connect to GitHub** area. A dialog box for connection settings is displayed. +4. In the dialog box, perform the following steps: + + 1. Click **Install on GitHub**, and then follow the on-screen instructions to install **TiDB Cloud Data Service** as an application on your target repository. + 2. Click **Authorize** to authorize access to the application on GitHub. + 3. Specify the target repository, branch, and directory where you want to store the configuration files of your Data App. + + > **Note:** + > + > - The directory must start with a slash (`/`). For example, `/mydata`. If the directory you specified does not exist in the target repository and branch, it will be created automatically. + > - The combination of repository, branch, and directory identifies the path of the configuration files, which must be unique among Data Apps. If your specified path is already used by another Data App, you need to specify a new path instead. Otherwise, the endpoints configured in the TiDB Cloud console for the current Data App will overwrite the files in your specified path. + > - If your specified path contains configuration files copied from another Data App and you want to import these files to the current Data App, see [Import configurations of an existing Data App](#import-configurations-of-an-existing-data-app). + + 4. To allow Data App changes made in either TiDB Cloud console or GitHub are synchronized with each other, enable **Configure Auto Sync & Deployment**. + + - When it is enabled, the changes made in your specified GitHub directory can be automatically deployed in TiDB Cloud, and the changes made in the TiDB Cloud console can be pushed to GitHub as well. You can find the corresponding deployment and commit information in the Data App deployment history. + - When it is disabled, the changes made in your specified GitHub directory will **NOT** be deployed in TiDB Cloud, and the changes made in the TiDB Cloud console will **NOT** be pushed to GitHub either. + +5. Click **Confirm Connect**. + +## Step 2. Synchronize Data App configurations with GitHub + +If GitHub connection is enabled when you [create a Data App](/tidb-cloud/data-service-manage-data-app.md), TiDB Cloud pushes the configuration files of this Data App to GitHub immediately after the App creation. + +If GitHub connection is enabled after the App creation, you need to perform a deployment operation to synchronize the Data App configurations with GitHub. For example, you can click the **Deployments** tab, and then re-deploy a deployment for this Data App. + +After the deployment operation, check your specified GitHub directory. You will find that the Data App configuration files have been committed to the directory by `tidb-cloud-data-service`, which means that your Data App is connected to GitHub successfully. The directory structure is as follows: + +``` +├── +│ ├── data_sources +│ │ └── cluster.json # specifies the linked clusters. +│ ├── dataapp_config.json # specifies the Data APP ID, name, and type. +│ ├── http_endpoints +│ │ ├── config.json # specifies the endpoints. +│ │ └── sql # contains SQL files of the endpoints. +│ │ ├── -.sql +│ │ ├── -.sql +│ │ └── -.sql +``` + +## Step 3. Modify your Data App + +When **Auto Sync & Deployment** is enabled, you can modify your Data App using either GitHub or the TiDB Cloud console. + +- [Option 1: Modify your Data App by updating files on GitHub](#option-1-modify-your-data-app-by-updating-files-on-github) +- [Option 2: Modify your Data App in the TiDB Cloud console](#option-2-modify-your-data-app-in-the-tidb-cloud-console) + +> **Note:** +> +> If you have modified your Data App on GitHub and TiDB Cloud console at the same time, to resolve conflicts, you can choose either discard the changes made in the console or let the console changes overwrite the GitHub changes. + +### Option 1: Modify your Data App by updating files on GitHub + +When updating the configuration files, pay attention to the following: + +| File directory | Notes | +| ---------|---------| +| `data_source/cluster.json` | When updating this file, make sure that the linked clusters are TiDB Serverless clusters and that you have access to the clusters. You can get the cluster ID from the cluster URL. For example, if the cluster URL is `https://tidbcloud.com/console/clusters/1234567891234567890/overview`, the cluster ID is `1234567891234567890`. | +| `http_endpoints/config.json` | When modifying the endpoints, make sure that you follow the rules described in [HTTP endpoint configuration](/tidb-cloud/data-service-app-config-files.md#http-endpoint-configuration). | +| `http_endpoints/sql/method-.sql`| To add or remove SQL files in the `http_endpoints/sql` directory, you need to update the corresponding endpoint configurations as well. | +| `datapp_config.json` | Do not change the `app_id` field in this file unless your `dataapp_config.json` file is copied from another Data App and you want to update it to the ID of your current Data App. Otherwise, the deployment triggered by this modification will fail. | + +For more information about the field configuration in these files, see [Data App configuration files](/tidb-cloud/data-service-app-config-files.md). + +After the file changes are committed and pushed, TiDB Cloud will automatically deploy the Data App with the latest changes on GitHub. You can view the deployment status and commit information in the deployment history. + +### Option 2: Modify your Data App in the TiDB Cloud console + +After [modifying your Data App endpoints](/tidb-cloud/data-service-manage-endpoint.md) in the TiDB Cloud console (such as modifying endpoints), you can review and deploy the changes to GitHub as follows: + +1. Click **Deploy** in the upper-right corner. A dialog is displayed for you to review the changes you made. +2. Depending on your review, do one of the following: + + - If you still want to make further changes based on the current draft, close this dialog and make the changes. + - If you want to revert the current changes to the last deployment, click **Discard Draft**. + - If the current changes look fine, write a change description (optional), and then click **Deploy and Push to GitHub**. The deployment status will be displayed in the top banner. + +If the deployment is successful, the changes made in the TiDB Cloud console will be pushed to GitHub automatically. + +## Import configurations of an existing Data App + +To import configurations of an existing Data App to a new Data App, take the following steps: + +1. Copy configuration files of the existing Data App to a new branch or directory on GitHub. +2. On the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project, [create a new Data App](/tidb-cloud/data-service-manage-data-app.md#create-a-data-app) without connecting to GitHub. +3. [Connect your new Data App to GitHub](#step-1-connect-your-data-app-to-github) with **Auto Sync & Deployment** enabled. When you specify the target repository, branch, and directory for your new Data App, use your new path with the copied configuration files. +4. Get the ID and name of your new Data App. You can click the name of your new Data App in the left pane and get the App ID and name in the **Data App Properties** area of the right pane. +5. In your new path on GitHub, update the `app_id` and `app_name` in the `datapp_config.json` file to the ID and name you get, and then push the changes. + +After the file changes are pushed to GitHub, TiDB Cloud will automatically deploy your new Data App with the latest changes. You can view the deployment status and commit information in the deployment history. + +## Edit GitHub connection + +If you want to edit the GitHub connection for your Data App (such as switching the repository, branch, and directory), perform the following steps. + +1. Navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project. +2. In the left pane, click the name of your target Data App to view its details. +3. In the **Connect to GitHub** area, click . A dialog box for connection settings is displayed. +4. In the dialog box, modify the repository, branch, and directory of your Data App. + + > **Note:** + > + > - The directory must start with a slash (`/`). For example, `/mydata`. If the directory you specified does not exist in the target repository and branch, it will be created automatically. + > - The combination of repository, branch, and directory identifies the path of the configuration files, which must be unique among Data Apps. If your specified path is already used by another Data App, you need to specify a new path instead. Otherwise, the endpoints configured in the TiDB Cloud console for the current Data App will overwrite the files in your specified path. + > - If your specified path contains configuration files copied from another Data App and you want to import these files to the current Data App, see [Import configurations of an existing Data App](#import-configurations-of-an-existing-data-app). + +5. To allow Data App changes made in either TiDB Cloud console or GitHub are synchronized with each other, enable **Configure Auto Sync & Deployment**. + + - When it is enabled, the changes made in your specified GitHub directory can be automatically deployed in TiDB Cloud, and the changes made in the TiDB Cloud console can be pushed to GitHub as well. You can find the corresponding deployment and commit information in the Data App deployment history. + - When it is disabled, the changes made in your specified GitHub directory will **NOT** be deployed in TiDB Cloud, and the changes made in the TiDB Cloud console will **NOT** be pushed to GitHub either. + +6. Click **Confirm Connect**. + +## Remove GitHub connection + +If you no longer want to connect your Data App to GitHub, take the following steps: + +1. Navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project. +2. In the left pane, click the name of your target Data App to view its details. +3. On the **Settings** tab, click **Disconnect** in the **Connect to GitHub** area. +4. Click **Disconnect** to confirm the disconnection. + +After the disconnection operation, your Data App configuration files will remain in your GitHub directory but will not be synchronized by `tidb-cloud-data-service` anymore. \ No newline at end of file diff --git a/tidb-cloud/tidb-cloud-release-notes.md b/tidb-cloud/tidb-cloud-release-notes.md index 45f26e1c44622..db6af0171cf51 100644 --- a/tidb-cloud/tidb-cloud-release-notes.md +++ b/tidb-cloud/tidb-cloud-release-notes.md @@ -8,6 +8,23 @@ aliases: ['/tidbcloud/supported-tidb-versions','/tidbcloud/release-notes'] This page lists the release notes of [TiDB Cloud](https://www.pingcap.com/tidb-cloud/) in 2023. +## June 5, 2023 + +- Support connecting your [Data App](/tidb-cloud/tidb-cloud-glossary.md#data-app) to GitHub. + + By [connecting your Data App to GitHub](/tidb-cloud/data-service-manage-github-connection.md), you can manage all configurations of the Data App as [code files](/tidb-cloud/data-service-app-config-files.md) on Github, which integrates TiDB Cloud Data Service seamlessly with your system architecture and DevOps process. + + With this feature, you can easily accomplish the following tasks, which improves the CI/CD experience of developing Data Apps: + + - Automatically deploy Data App changes with GitHub. + - Configure CI/CD pipelines of your Data App changes on GitHub with version control. + - Disconnect from a connected GitHub repository. + - Review endpoint changes before the deployment. + - View deployment history and take necessary actions in the event of a failure. + - Re-deploy a commit to roll back to an earlier deployment. + + For more information, see [Deploy Data App automatically with GitHub](/tidb-cloud/data-service-manage-github-connection.md). + ## June 2, 2023 **General changes** @@ -249,7 +266,7 @@ This page lists the release notes of [TiDB Cloud](https://www.pingcap.com/tidb-c On the Data App details page, now you can link clusters to your Data App and specify the role for each API key. The role controls whether the API key can read or write data to the linked clusters and can be set to `ReadOnly` or `ReadAndWrite`. This feature provides cluster-level and permission-level access control for Data Apps, giving you more flexibility to control the access scope according to your business needs. - For more information, see [Manage linked clusters](/tidb-cloud/data-service-manage-data-app.md#manage-linked-clusters) and [Manage API keys](/tidb-cloud/data-service-api-key.md). + For more information, see [Manage linked clusters](/tidb-cloud/data-service-manage-data-app.md#manage-linked-data-sources) and [Manage API keys](/tidb-cloud/data-service-api-key.md). ## March 28, 2023