From 8813e6915798bcd3f2d288a4130e8648aa31a326 Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Tue, 14 Oct 2025 10:07:49 +0200 Subject: [PATCH 1/4] 424 docs rfcadd docs for the cli (#4453) * chore: add first files. * chore: first draft of the REST API docs * chore: update and test. * chore: update and test. * Fix spec. Better examples and documentation * Fix replica set retrieval docs * chore: few small updates. * chore: few small updates. * chore: change title to give space for the CLI * chore: commit for pull from latest. * chore: cli docs. * Apply suggestions from code review Co-authored-by: Nathan Cochran Signed-off-by: Iain Cox * chore: updates on review. * chore: updates on review. * Apply suggestion from @nathanjcochran Co-authored-by: Nathan Cochran Signed-off-by: Iain Cox * Apply suggestion from @nathanjcochran Co-authored-by: Nathan Cochran Signed-off-by: Iain Cox * chore: updates on review. * Apply suggestions from code review Co-authored-by: Anastasiia Tovpeko <114177030+atovpeko@users.noreply.github.com> Signed-off-by: Iain Cox * chore: updates on review. * chore: updates on review. * chore: updates on review. * chore: updates on review. * chore: updates on review. * chore: add fork and free. --------- Signed-off-by: Iain Cox Co-authored-by: billy-the-fish Co-authored-by: josesahad Co-authored-by: Nathan Cochran Co-authored-by: Anastasiia Tovpeko <114177030+atovpeko@users.noreply.github.com> --- _partials/_devops-cli-get-started.md | 237 +++++ _partials/_devops-rest-api-get-started.md | 157 ++++ _partials/_prereqs-cloud-account-only.md | 5 + api/api-reference.md | 849 ++++++++++++++++++ api/page-index/page-index.js | 6 + getting-started/get-started-devops-as-code.md | 41 + getting-started/page-index/page-index.js | 5 + integrations/find-connection-details.md | 30 +- 8 files changed, 1329 insertions(+), 1 deletion(-) create mode 100644 _partials/_devops-cli-get-started.md create mode 100644 _partials/_devops-rest-api-get-started.md create mode 100644 _partials/_prereqs-cloud-account-only.md create mode 100644 api/api-reference.md create mode 100644 getting-started/get-started-devops-as-code.md diff --git a/_partials/_devops-cli-get-started.md b/_partials/_devops-cli-get-started.md new file mode 100644 index 0000000000..16eb6a88e5 --- /dev/null +++ b/_partials/_devops-cli-get-started.md @@ -0,0 +1,237 @@ +import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; + +$CLI_LONG is a command-line interface that you use to manage $CLOUD_LONG resources +including VPCs, services, read replicas, and related infrastructure. $CLI_LONG calls $REST_LONG to communicate with +$CLOUD_LONG. + +This page shows you how to install and set up secure authentication for $CLI_LONG, then create your first +service. + +## Prerequisites + + + + +## Install and configure $CLI_LONG + + + +1. **Install $CLI_LONG** + + Use the terminal to install the $CLI_SHORT: + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.deb.sh | sudo os=any dist=any bash + sudo apt-get install tiger-cli + ``` + + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.deb.sh | sudo os=any dist=any bash + sudo apt-get install tiger-cli + ``` + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.rpm.sh | sudo os=rpm_any dist=rpm_any bash + sudo yum install tiger-cli + ``` + + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.rpm.sh | sudo os=rpm_any dist=rpm_any bash + sudo yum install tiger-cli + ``` + + + + + + ```shell + brew install --cask timescale/tap/tiger-cli + ``` + + + + + + ```shell + curl -fsSL https://tiger-cli-releases.s3.amazonaws.com/install/install.sh | sh + ``` + + + + + +1. **Set up API credentials** + + 1. Log $CLI_LONG into your $ACCOUNT_LONG: + + ```shell + tiger auth login + ``` + $CLI_LONG opens $CONSOLE_SHORT in your browser. Log in, then click `Authorize`. + + 1. Log $CLI_LONG into your $ACCOUNT_LONG + + ```shell + tiger auth login + ``` + $CLI_LONG opens $CONSOLE_SHORT in your browser. Login, then click `Authorize`. + + 1. Select a $PROJECT_LONG. + + ```terminaloutput + Auth URL is: https://console.cloud.timescale.com/oauth/authorize?client_id=lotsOfURLstuff + Opening browser for authentication... + Select a project: + + > 1. Tiger Project (tgrproject) + 2. YourCompany (Company wide project) (cpnproject) + 3. YourCompany Department (dptproject) + + Use ↑/↓ arrows or number keys to navigate, enter to select, q to quit + ``` + If only one $PROJECT_SHORT is associated with your $ACCOUNT_SHORT, this step is not shown. + + Where possible, $CLI_LONG stores your authentication information in the system keychain/credential manager. + If that fails, the key is stored in `~/.config/tiger/api-key` with restricted file permissions (600). + $CLI_LONG stores your configuration in `~/.config/tiger/config.yaml`. + +1. **Test your authenticated connection to $CLOUD_LONG by listing services** + + ```bash + tiger service list + ``` + + This call returns something like: + - No services: + ```terminaloutput + 🏜️ No services found! Your project is looking a bit empty. + πŸš€ Ready to get started? Create your first service with: tiger service create + ``` + - One or more services: + + ```terminaloutput + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ SERVICE ID β”‚ NAME β”‚ STATUS β”‚ TYPE β”‚ REGION β”‚ CREATED β”‚ + β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ + β”‚ tgrservice β”‚ tiger-agent-service β”‚ READY β”‚ TIMESCALEDB β”‚ eu-central-1 β”‚ 2025-09-25 16:09 β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ``` + + + + +## Create your first service + +Create a new $SERVICE_LONG using $CLI_LONG: + + + +1. **Submit a service creation request** + ```shell + tiger service create + ``` + $CLOUD_LONG creates a Development environment for you. That is, no delete protection, high-availability, spooling or + read replication. You see something like: + ```terminaloutput + πŸš€ Creating service 'db-11111' (auto-generated name)... + βœ… Service creation request accepted! + πŸ“‹ Service ID: happyservice + πŸ” Password saved to system keyring for automatic authentication + 🎯 Set service 'happyservice' as default service. + ⏳ Waiting for service to be ready (wait timeout: 30m0s)... + ⏳ Service status: QUEUED... + πŸŽ‰ Service is ready and running! + ``` + This $SERVICE_SHORT is set as default by the $CLI_SHORT. + +1. **Check the $CLI_SHORT configuration** + ```shell + tiger config show + ``` + You see something like: + ```terminaloutput + api_url: https://console.cloud.timescale.com/public/api/v1 + console_url: https://console.cloud.timescale.com + gateway_url: https://console.cloud.timescale.com/api + docs_mcp: true + docs_mcp_url: https://mcp.tigerdata.com/docs + project_id: tgrproject + service_id: tgrservice + output: table + analytics: true + password_storage: keyring + debug: false + config_dir: /Users//.config/tiger + ``` + + + +And that is it, you are ready to use $CLI_LONG to manage your $SERVICE_SHORTs in $CLOUD_LONG. + +## Commands + +You can use the following commands with $CLI_LONG. For more information on each command, use the `-h` flag. For example: +`tiger auth login -h` + +| Command | Subcommand | Description | +|---------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| auth | | Manage authentication and the credentials for your $ACCOUNT_LONG | +| | login | Create an authenticated connection to your $ACCOUNT_LONG | +| | logout | Remove the credentials used to create authenticated connections to $CLOUD_LONG | +| | whoami | Show information about the current user | +| version | | Show information about the currently installed version of $CLI_LONG | +| | set `` `` | Set a specific value in your configuration. For example, `tiger config set debug true` | +| config | | Manage your $CLI_LONG configuration | +| | show | Show the current configuration | +| | unset `` | Clear the value of a configuration parameter. For example, `tiger config unset debug` | +| | reset | Reset the configuration to the defaults. This also logs you out from the current $PROJECT_LONG | +| service | | Manage the $SERVICE_LONGs in this $PROJECT_SHORT | +| | create `--addons=` | Create a new $SERVICE_SHORT in this $PROJECT_SHORT. Possible addons are:
  • time-series: with the Timescaledb and Timescaledb Toolkit extensions
  • ai: with the Timescaledb, Timescaledb Toolkit, vector and vectorscale extensions
  • free: free services have fixed compute of 0.25 CPU, 1 GiB RAM, and up to 500mb storage.
  • none: vanilla Postgres
All services have Tiger features such as Tiger Storage, Security, Monitoring and compliance. If you do not use the `addons` flag, the default service is `time-series`. | +| | describe `` | Show detailed information about a specific $SERVICE_SHORT in this $PROJECT_SHORT | +| | delete `` | Delete a $SERVICE_SHORT from this $PROJECT_SHORT | +| | fork `` | Fork of an existing database service. Key features are:
  • Timing options: `--now`, `--last-snapshot`, `--to-timestamp`
  • Resource configuration: `--cpu`, `--memory`
  • Naming: `--name ` . Defaults to {source-service-name}-fork
  • Wait behavior: `--no-wait`, `--wait-timeout`
  • Default service: `--no-set-default`
| +| | list | List all the $SERVICE_SHORTs in this $PROJECT_SHORT | +| | update-password `` | Update the password for a $SERVICE_SHORT | +| db | | Database operations and management | +| | connect `` | Connect to a $SERVICE_SHORT | +| | connection-string `` | Retrieve the connection string for a $SERVICE_SHORT | +| | test-connection `` | Test the connectivity to a $SERVICE_SHORT | +| mcp | | Manage the $MCP_LONG | +| | start | Start the $MCP_LONG. This is the same as `tiger mcp start stdio` | +| | start `stdio` \| `http` | Start the $MCP_LONG with stdio or HTTP transport | + +## Flags + +You can use the following global flags with $CLI_LONG: + +| Flag | Default | Description | +|--|-----------------|-----------------------------------------------------------------------| +| --analytics | `true` | Set to `false` to disable usage analytics | +| --config-dir string | `.config/tiger` | Set the directory that holds `config.yaml` | +| --debug | No debugging | Enable debug logging | +| -o, --output string | table | Set the output format. Options are `json`, `yaml`, or `table` | +| --password-storage string | keyring | Set the password storage method. Options are `keyring`, `pgpass`, or `none` | +| --project-id string | - | Set the $PROJECT_LONG to manage | +| --service-id string | - | Set the $SERVICE_LONG to manage | + + + +[rest-api-reference]: /api/:currentVersion:/api-reference/ +[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings +[get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id +[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials +[curl]: https://curl.se/ \ No newline at end of file diff --git a/_partials/_devops-rest-api-get-started.md b/_partials/_devops-rest-api-get-started.md new file mode 100644 index 0000000000..fdf27c3062 --- /dev/null +++ b/_partials/_devops-rest-api-get-started.md @@ -0,0 +1,157 @@ +import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; + +[$REST_LONG][rest-api-reference] is a comprehensive RESTful API you use to manage $CLOUD_LONG resources +including VPCs, $SERVICE_SHORTs, and read replicas. + +This page shows you how to set up secure authentication for the $REST_LONG and create your first $SERVICE_SHORT. + +## Prerequisites + + + +* Install [curl][curl]. + + +## Configure secure authentication + +$REST_LONG uses HTTP Basic Authentication with access keys and secret keys. All API requests must include +proper authentication headers. + + + +1. **Set up API credentials** + + 1. In $CONSOLE, copy your [project ID][get-project-id] and store it securely using an environment variable: + + ```bash + export TIGERDATA_PROJECT_ID="your-project-id" + ``` + + 1. [Create your client credentials][create-client-credentials] and store them securely using environment variables: + + ```bash + export TIGERDATA_ACCESS_KEY="Public key" + export TIGERDATA_SECRET_KEY="Secret key" + ``` + +1. **Configure the API endpoint** + + Set the base URL in your environment: + + ```bash + export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" + ``` + +1. **Test your authenticated connection to $REST_LONG by listing the $SERVICE_SHORTs in the current $PROJECT_LONG** + + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -u "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" \ + -H "Content-Type: application/json" + ``` + + This call returns something like: + - No $SERVICE_SHORTs: + ```terminaloutput + []% + ``` + - One or more $SERVICE_SHORTs: + + ```terminaloutput + [{"service_id":"a59clooxoe","project_id":"c8nmagk8zh","name":"events", + "region_code":"eu-central-1","service_type":"TIMESCALEDB", + "created":"2025-09-09T08:37:15.816443Z","paused":false,"status":"READY", + "resources":[{"id":"101228","spec":{"cpu_millis":500,"memory_gbs":2,"volume_type":""}}], + "metadata":{"environment":"DEV"},"endpoint":{"host":"oh.yeah.tsdb.cloud.timescale.com", + "port":12345}}] + ``` + + + + +## Create your first $SERVICE_LONG + +Create a new $SERVICE_SHORT using the $REST_LONG: + + + +1. **Create a $SERVICE_SHORT using the POST endpoint** + ```bash + curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -u "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "my-first-service", + "service_type": "TIMESCALEDB", + "region_code": "us-east-1", + "replica_count": 1, + "cpu_millis": 1000, + "memory_gbs": 4 + }' + ``` + $CLOUD_LONG creates a Development environment for you. That is, no delete protection, high-availability, spooling or + read replication. You see something like: + ```terminaloutput + { + "service_id":"asdfasdfasdf","project_id":"asdasdfasf","name":"my-first-service", + "region_code":"us-east-1", "service_type":"TIMESCALEDB", + "created":"2025-09-09T09:24:31.997767396Z", "paused":false,"status":"READY", + "resources":[{"id":"101240", + "spec":{"cpu_millis":1000,"memory_gbs":4,"volume_type":""}}], + "metadata":{"environment":"PROD"}, + "endpoint":{"host":"oh.yeah.tsdb.cloud.timescale.com","port":123435}, + "initial_password":"very-secret", + "ha_replicas":{"sync_replica_count":0,"replica_count":1} + } + ``` + +1. **Save `service_id` from the response to a variable** + ```bash + # Extract service_id from the JSON response + export SERVICE_ID="service_id-from-response" + ``` + +1. **Check the configuration for the $SERVICE_SHORT** + + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ + -u "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" \ + -H "Content-Type: application/json" + ``` + You see something like: + ```terminaloutput + {"service_id":"tgrservice","project_id":"tgrproject","name":"my-first-service","region_code":"us-east-1", + "service_type":"TIMESCALEDB","created":"2025-09-30T12:08:54.438785Z","paused":false,"status":"READY", + "resources":[{"id":"102879","spec":{"cpu_millis":1000,"memory_gbs":4,"volume_type":""}}], + "metadata":{"environment":"DEV"},"endpoint":{"host":"ohhhh.yeahhhhh.tsdb.cloud.timescale.com","port":33867}, + "ha_replicas":{"sync_replica_count":0,"replica_count":1}} + ``` + + + +And that is it, you are ready to use the [$REST_LONG][rest-api-reference] to manage your +$SERVICE_SHORTs in $CLOUD_LONG. + +## Security best practices + +Follow these security guidelines when working with the $REST_LONG: + +- **Credential management** + - Store API credentials as environment variables, not in code + - Use credential rotation policies for production environments + - Never commit credentials to version control systems + +- **Network security** + - Use HTTPS endpoints exclusively for API communication + - Implement proper certificate validation in your HTTP clients + +- **Data protection** + - Use secure storage for service connection strings and passwords + - Implement proper backup and recovery procedures for created services + - Follow data residency requirements for your region + +[rest-api-reference]: /api/:currentVersion:/api-reference/ +[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings +[get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id +[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials +[curl]: https://curl.se/ \ No newline at end of file diff --git a/_partials/_prereqs-cloud-account-only.md b/_partials/_prereqs-cloud-account-only.md new file mode 100644 index 0000000000..bebd9d9f60 --- /dev/null +++ b/_partials/_prereqs-cloud-account-only.md @@ -0,0 +1,5 @@ +To follow the steps on this page: + +* Create a target [$ACCOUNT_LONG][create-account]. + +[create-account]: /getting-started/:currentVersion:/services/#create-a-tiger-cloud-account \ No newline at end of file diff --git a/api/api-reference.md b/api/api-reference.md new file mode 100644 index 0000000000..d682b84a4d --- /dev/null +++ b/api/api-reference.md @@ -0,0 +1,849 @@ +--- +title: Tiger Cloud REST API reference +excerpt: A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, services, and read replicas. +tags: [REST] +products: [cloud] +--- + +# $REST_LONG reference + +A comprehensive RESTful API for managing $CLOUD_LONG resources including VPCs, services, and read replicas. + +## Overview + +**API Version:** 1.0.0 +**Base URL:** `https://console.cloud.timescale.com/public/api/v1` + +## Authentication + +The $REST_LONG uses HTTP Basic Authentication. Include your access key and secret key in the Authorization header. + +### Basic Authentication +```http +Authorization: Basic +``` + +### Example +```bash +# Using cURL +curl -X GET "https://console.cloud.timescale.com/public/api/v1/projects/{project_id}/services" \ + -H "Authorization: Basic $(echo -n 'your_access_key:your_secret_key' | base64)" +``` + +## Service Management + +You use this endpoint to create and manage the following Tiger Postgres services: + +- `TIMESCALEDB`: a Tiger Postgres instance optimized for real-time analytics service For time-stamped data like events, + prices, metrics, sensor readings, or any information that changes over time +- `POSTGRES`: a vanilla Postgres instance +- `VECTOR`: a Tiger Postgres instance with vector extensions + +### List All Services + +```http +GET /projects/{project_id}/services +``` + +Retrieve all services within a project. + +**Response:** `200 OK` +```json +[ + { + "service_id": "p7zm9wqqii", + "project_id": "jz22xtzemv", + "name": "my-production-db", + "region_code": "eu-central-1", + "service_type": "TIMESCALEDB", + "status": "READY", + "created": "2024-01-15T10:30:00Z", + "paused": false, + "resources": [ + { + "id": "resource-1", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "gp2" + } + } + ], + "endpoint": { + "host": "my-service.com", + "port": 5432 + } + } +] +``` + +### Create a Service + +```http +POST /projects/{project_id}/services +``` + +Create a new Tiger Postgres service. This is an asynchronous operation. + +**Request Body:** +```json +{ + "name": "test-2", + "service_type": "TIMESCALEDB", + "region_code": "eu-central-1", + "cpu_millis": 1000, + "memory_gbs": 4 +} +``` + +**Response:** `202 Accepted` +```json +{ + "service_id": "p7zm9wqqii", + "project_id": "jz22xtzemv", + "name": "test-2", + "region_code": "eu-central-1", + "service_type": "TIMESCALEDB", + "created": "2025-09-04T20:46:46.265680278Z", + "paused": false, + "status": "READY", + "resources": [ + { + "id": "100927", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "" + } + } + ], + "metadata": { + "environment": "PROD" + }, + "endpoint": { + "host": "p7zm8wqqii.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 35482 + }, + "initial_password": "oamv8ch9t4ar2j8g" +} +``` + +**Service Types:** +- `TIMESCALEDB`: a Tiger Postgres instance optimized for real-time analytics service For time-stamped data like events, + prices, metrics, sensor readings, or any information that changes over time +- `POSTGRES`: a vanilla Postgres instance +- `VECTOR`: a Tiger Postgres instance with vector extensions + +### Get a Service + +```http +GET /projects/{project_id}/services/{service_id} +``` + +Retrieve details of a specific service. + +**Response:** `200 OK` +```json +{ + "service_id": "p7zm9wqqii", + "project_id": "jz22xtzemv", + "name": "test-2", + "region_code": "eu-central-1", + "service_type": "TIMESCALEDB", + "created": "2025-09-04T20:46:46.26568Z", + "paused": false, + "status": "READY", + "resources": [ + { + "id": "100927", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "" + } + } + ], + "metadata": { + "environment": "DEV" + }, + "endpoint": { + "host": "p7zm8wqqii.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 35482 + } +} +``` + +**Service Status:** +- `QUEUED`: Service creation is queued +- `DELETING`: Service is being deleted +- `CONFIGURING`: Service is being configured +- `READY`: Service is ready for use +- `DELETED`: Service has been deleted +- `UNSTABLE`: Service is in an unstable state +- `PAUSING`: Service is being paused +- `PAUSED`: Service is paused +- `RESUMING`: Service is being resumed +- `UPGRADING`: Service is being upgraded +- `OPTIMIZING`: Service is being optimized + +### Delete a Service + +```http +DELETE /projects/{project_id}/services/{service_id} +``` + +Delete a specific service. This is an asynchronous operation. + +**Response:** `202 Accepted` + +### Resize a Service + +```http +POST /projects/{project_id}/services/{service_id}/resize +``` + +Change CPU and memory allocation for a service. + +**Request Body:** +```json +{ + "cpu_millis": 2000, + "memory_gbs": 8 +} +``` + +**Response:** `202 Accepted` + +### Update Service Password + +```http +POST /projects/{project_id}/services/{service_id}/updatePassword +``` + +Set a new master password for the service. + +**Request Body:** +```json +{ + "password": "a-very-secure-new-password" +} +``` + +**Response:** `204 No Content` + +### Set Service Environment + +```http +POST /projects/{project_id}/services/{service_id}/setEnvironment +``` + +Set the environment type for the service. + +**Request Body:** +```json +{ + "environment": "PROD" +} +``` + +**Environment Values:** +- `PROD`: Production environment +- `DEV`: Development environment + +**Response:** `200 OK` +```json +{ + "message": "Environment set successfully" +} +``` + +### Configure High Availability + +```http +POST /projects/{project_id}/services/{service_id}/setHA +``` + +Change the HA configuration for a service. This is an asynchronous operation. + +**Request Body:** +```json +{ + "replica_count": 1 +} +``` + +**Response:** `202 Accepted` + +### Connection Pooler Management + +#### Enable Connection Pooler + +```http +POST /projects/{project_id}/services/{service_id}/enablePooler +``` + +Activate the connection pooler for a service. + +**Response:** `200 OK` +```json +{ + "message": "Connection pooler enabled successfully" +} +``` + +#### Disable Connection Pooler + +```http +POST /projects/{project_id}/services/{service_id}/disablePooler +``` + +Deactivate the connection pooler for a service. + +**Response:** `200 OK` +```json +{ + "message": "Connection pooler disabled successfully" +} + +### Fork a Service + +```http +POST /projects/{project_id}/services/{service_id}/forkService +``` + +Create a new, independent service by taking a snapshot of an existing one. + +**Request Body:** +```json +{ + "name": "fork-test2", + "region_code": "eu-central-1", + "cpu_millis": 1000, + "memory_gbs": 4 +} +``` + +**Response:** `202 Accepted` +```json +{ + "service_id": "otewd3pem2", + "project_id": "jz22xtzemv", + "name": "fork-test2", + "region_code": "eu-central-1", + "service_type": "TIMESCALEDB", + "created": "2025-09-04T20:54:09.53380732Z", + "paused": false, + "status": "READY", + "resources": [ + { + "id": "100929", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "" + } + } + ], + "forked_from": { + "project_id": "jz22xtzemv", + "service_id": "p7zm9wqqii", + "is_standby": false + }, + "initial_password": "ph33bl5juuri5gem" +} +``` + +## Read Replica Sets + +Manage read replicas for improved read performance. + +### List Read Replica Sets + +```http +GET /projects/{project_id}/services/{service_id}/replicaSets +``` + +Retrieve all read replica sets associated with a primary service. + +**Response:** `200 OK` +```json +[ + { + "id": "l5alxb3s2g", + "name": "replica-set-test2", + "status": "active", + "nodes": 1, + "cpu_millis": 1000, + "memory_gbs": 4, + "endpoint": { + "host": "l5alxb3s2g.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 38448 + }, + "connection_pooler": { + "endpoint": { + "host": "l5alxb3s2g.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 38543 + } + }, + "metadata": { + "environment": "DEV" + } + } +] +``` + +**Replica Set Status:** +- `creating`: Replica set is being created +- `active`: Replica set is active and ready +- `resizing`: Replica set is being resized +- `deleting`: Replica set is being deleted +- `error`: Replica set encountered an error + +### Create a Read Replica Set + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets +``` + +Create a new read replica set. This is an asynchronous operation. + +**Request Body:** +```json +{ + "name": "replica-set-test2", + "cpu_millis": 1000, + "memory_gbs": 4, + "nodes": 1 +} +``` + +**Response:** `202 Accepted` +```json +{ + "id": "dsldm715t2", + "name": "replica-set-test2", + "status": "active", + "nodes": 1, + "cpu_millis": 1000, + "memory_gbs": 4 +} +``` + +### Delete a Read Replica Set + +```http +DELETE /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id} +``` + +Delete a specific read replica set. This is an asynchronous operation. + +**Response:** `202 Accepted` + +### Resize a Read Replica Set + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/resize +``` + +Change resource allocation for a read replica set. This operation is async. + +**Request Body:** +```json +{ + "cpu_millis": 500, + "memory_gbs": 2, + "nodes": 2 +} +``` + +**Response:** `202 Accepted` +```json +{ + "message": "Replica set resize request accepted" +} +``` + +### Read Replica Set Connection Pooler + +#### Enable Replica Set Pooler + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/enablePooler +``` + +Activate the connection pooler for a read replica set. + +**Response:** `200 OK` +```json +{ + "message": "Connection pooler enabled successfully" +} +``` + +#### Disable Replica Set Pooler + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/disablePooler +``` + +Deactivate the connection pooler for a read replica set. + +**Response:** `200 OK` +```json +{ + "message": "Connection pooler disabled successfully" +} +``` + +### Set Replica Set Environment + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/setEnvironment +``` + +Set the environment type for a read replica set. + +**Request Body:** +```json +{ + "environment": "PROD" +} +``` + +**Response:** `200 OK` +```json +{ + "message": "Environment set successfully" +} +``` + +## VPC Management + +Virtual Private Clouds (VPCs) provide network isolation for your TigerData services. + +### List All VPCs + +```http +GET /projects/{project_id}/vpcs +``` + +List all Virtual Private Clouds in a project. + +**Response:** `200 OK` +```json +[ + { + "id": "1234567890", + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" + } +] +``` + +### Create a VPC + +```http +POST /projects/{project_id}/vpcs +``` + +Create a new VPC. + +**Request Body:** +```json +{ + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" +} +``` + +**Response:** `201 Created` +```json +{ + "id": "1234567890", + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" +} +``` + +### Get a VPC + +```http +GET /projects/{project_id}/vpcs/{vpc_id} +``` + +Retrieve details of a specific VPC. + +**Response:** `200 OK` +```json +{ + "id": "1234567890", + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" +} +``` + +### Rename a VPC + +```http +POST /projects/{project_id}/vpcs/{vpc_id}/rename +``` + +Update the name of a specific VPC. + +**Request Body:** +```json +{ + "name": "my-renamed-vpc" +} +``` + +**Response:** `200 OK` +```json +{ + "id": "1234567890", + "name": "my-renamed-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" +} +``` + +### Delete a VPC + +```http +DELETE /projects/{project_id}/vpcs/{vpc_id} +``` + +Delete a specific VPC. + +**Response:** `204 No Content` + +## VPC Peering + +Manage peering connections between VPCs across different accounts and regions. + +### List VPC Peerings + +```http +GET /projects/{project_id}/vpcs/{vpc_id}/peerings +``` + +Retrieve all VPC peering connections for a given VPC. + +**Response:** `200 OK` +```json +[ + { + "id": "1234567890", + "peer_account_id": "acc-12345", + "peer_region_code": "eu-central-1", + "peer_vpc_id": "1234567890", + "provisioned_id": "1234567890", + "status": "active", + "error_message": null + } +] +``` + +### Create VPC Peering + +```http +POST /projects/{project_id}/vpcs/{vpc_id}/peerings +``` + +Create a new VPC peering connection. + +**Request Body:** +```json +{ + "peer_account_id": "acc-12345", + "peer_region_code": "eu-central-1", + "peer_vpc_id": "1234567890" +} +``` + +**Response:** `201 Created` +```json +{ + "id": "1234567890", + "peer_account_id": "acc-12345", + "peer_region_code": "eu-central-1", + "peer_vpc_id": "1234567890", + "provisioned_id": "1234567890", + "status": "pending" +} +``` + +### Get VPC Peering + +```http +GET /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} +``` + +Retrieve details of a specific VPC peering connection. + +### Delete VPC Peering + +```http +DELETE /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} +``` + +Delete a specific VPC peering connection. + +**Response:** `204 No Content` + +## Service VPC Operations + +### Attach Service to VPC + +```http +POST /projects/{project_id}/services/{service_id}/attachToVPC +``` + +Associate a service with a VPC. + +**Request Body:** +```json +{ + "vpc_id": "1234567890" +} +``` + +**Response:** `202 Accepted` + +### Detach Service from VPC + +```http +POST /projects/{project_id}/services/{service_id}/detachFromVPC +``` + +Disassociate a service from its VPC. + +**Request Body:** +```json +{ + "vpc_id": "1234567890" +} +``` + +**Response:** `202 Accepted` + +## Data Models + +### VPC Object +```json +{ + "id": "string", + "name": "string", + "cidr": "string", + "region_code": "string" +} +``` + +### Service Object +```json +{ + "service_id": "string", + "project_id": "string", + "name": "string", + "region_code": "string", + "service_type": "TIMESCALEDB|POSTGRES|VECTOR", + "created": "2024-01-15T10:30:00Z", + "initial_password": "string", + "paused": false, + "status": "READY|CONFIGURING|QUEUED|...", + "resources": [ + { + "id": "string", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "string" + } + } + ], + "metadata": { + "environment": "PROD|DEV" + }, + "endpoint": { + "host": "string", + "port": 5432 + }, + "connection_pooler": { + "endpoint": { + "host": "string", + "port": 5432 + } + } +} +``` + +### Peering Object +```json +{ + "id": "string", + "peer_account_id": "string", + "peer_region_code": "string", + "peer_vpc_id": "string", + "provisioned_id": "string", + "status": "string", + "error_message": "string" +} +``` + +### Read Replica Set Object + +```json +{ + "id": "string", + "name": "string", + "status": "creating|active|resizing|deleting|error", + "nodes": 2, + "cpu_millis": 1000, + "memory_gbs": 4, + "metadata": { + "environment": "PROD|DEV" + }, + "endpoint": { + "host": "string", + "port": 5432 + }, + "connection_pooler": { + "endpoint": { + "host": "string", + "port": 5432 + } + } +} +``` + +## Error Handling + +Tiger Cloud REST API uses standard HTTP status codes and returns error details in JSON format. + +### Error Response Format +```json +{ + "code": "ERROR_CODE", + "message": "Human-readable error description" +} +``` + +### Common Error Codes +- `400 Bad Request`: Invalid request parameters or malformed JSON +- `401 Unauthorized`: Missing or invalid authentication credentials +- `403 Forbidden`: Insufficient permissions for the requested operation +- `404 Not Found`: Requested resource does not exist +- `409 Conflict`: Request conflicts with current resource state +- `500 Internal Server Error`: Unexpected server error + +### Example Error Response +```json +{ + "code": "INVALID_REQUEST", + "message": "The service_type field is required" +} +``` diff --git a/api/page-index/page-index.js b/api/page-index/page-index.js index 20e53fcb4e..b01f46dccd 100644 --- a/api/page-index/page-index.js +++ b/api/page-index/page-index.js @@ -617,6 +617,12 @@ module.exports = [ description: "An overview of what different tags represent in the API section of TigerData Documentation.", }, + { + title: "Tiger Cloud REST API", + href: "api-reference", + description: + "A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, services, and read replicas.", + }, { title: "Glossary", href: "glossary", diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md new file mode 100644 index 0000000000..1258de6b64 --- /dev/null +++ b/getting-started/get-started-devops-as-code.md @@ -0,0 +1,41 @@ +--- +title: "DevOps as code with Tiger" +excerpt: "Configure secure authentication and manage the resources in your Tiger project using REST, the cli or MCP." +keywords: + - authentication + - service creation + - API setup + - security +tags: + - setup + - security + - services + - authentication +--- + + +import RESTGS from "versionContent/_partials/_devops-rest-api-get-started.mdx"; +import CLIGS from "versionContent/_partials/_devops-cli-get-started.mdx"; + + +# DevOps as code with $CLOUD_LONG + +$COMPANY supplies a clean, programmatic control layer for $CLOUD_LONG. This includes RESTful APIs, $CLI commands, and +MCP commands that let humans, machines, and AI agents easily provision, configure, and manage $SERVICE_LONGs +programmatically. + + + + + + + + + + + + + + + + diff --git a/getting-started/page-index/page-index.js b/getting-started/page-index/page-index.js index 94bbf4de17..d33b812fad 100644 --- a/getting-started/page-index/page-index.js +++ b/getting-started/page-index/page-index.js @@ -22,6 +22,11 @@ module.exports = [ href: "services", excerpt: "Create a Tiger service and connect to it", }, + { + title: "DevOps as code with Tiger", + href: "get-started-devops-as-code", + excerpt: "Set up secure authentication for the Tiger REST API and create your first service", + }, { title: "Run your queries from Tiger Console", href: "run-queries-from-console", diff --git a/integrations/find-connection-details.md b/integrations/find-connection-details.md index b804902d69..1dca134090 100644 --- a/integrations/find-connection-details.md +++ b/integrations/find-connection-details.md @@ -41,7 +41,7 @@ To retrieve the connection details for your $CLOUD_LONG project and $SERVICE_LON -1. **Retreive your project ID**: +1. **Retrieve your project ID**: In [$CONSOLE][console-services], click your project name in the upper left corner, then click `Copy` next to the project ID. ![Retrive the project id in $CONSOLE](https://assets.timescale.com/docs/images/tiger-cloud-console/tiger-console-project-id.png) @@ -53,6 +53,31 @@ To retrieve the connection details for your $CLOUD_LONG project and $SERVICE_LON +## Create client credentials + +You use client credentials to obtain access tokens outside of the user context. + +To retrieve the connection details for your $CLOUD_LONG project for programmatic usage +such as Terraform or the [$CLOUD_LONG REST API][rest-api-reference]: + + + +1. **Open the settings for your project**: + + In [$CONSOLE][console-services], click your project name in the upper left corner, then click `Project settings`. + +1. **Create client credentials**: + + 1. Click `Create credentials`, then copy `Public key` and `Secret key` locally. + + ![Retrive the service id in $CONSOLE](https://assets.timescale.com/docs/images/tiger-cloud-console/tiger-cloud-console-client-credentials.png) + + This is the only time you see the `Secret key`. After this, only the `Public key` is visible in this page. + + 1. Click `Done`. + + + @@ -73,3 +98,6 @@ In the `Services` page of the $MST_CONSOLE_LONG, click the service you want to c [console-services]: https://console.cloud.timescale.com/dashboard/services [postgres-config]: https://www.postgresql.org/docs/current/runtime-config-file-locations.html +[rest-api-reference]: /api/:currentVersion:/api-reference/ +[get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id +[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials \ No newline at end of file From 6a30ceaff5e358368eb3b49f495b26b6f887643d Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Tue, 21 Oct 2025 09:32:29 +0200 Subject: [PATCH 2/4] chore: tiger agents doc, first draft. (#4482) * chore: tiger agents doc, first draft. * chore: updates on review. * chore: updates on review. * Apply suggestions from code review Co-authored-by: Anastasiia Tovpeko <114177030+atovpeko@users.noreply.github.com> Signed-off-by: Iain Cox * chore: updates on review. * chore: updates on review. * chore: mcp config update. * chore: update for EON. * chore: update for EON. * chore: update the procedure. * chore: space. * Apply suggestions from code review Co-authored-by: Anastasiia Tovpeko <114177030+atovpeko@users.noreply.github.com> Signed-off-by: Iain Cox * chore: add something about persistent memory. * Apply suggestions from code review Co-authored-by: John Pruitt Signed-off-by: Iain Cox * chore: Updates on review. --------- Signed-off-by: Iain Cox Co-authored-by: billy-the-fish Co-authored-by: Anastasiia Tovpeko <114177030+atovpeko@users.noreply.github.com> Co-authored-by: John Pruitt --- _partials/_prereqs-cloud-project-and-self.md | 8 + ai/page-index/page-index.js | 12 +- ai/tiger-agents-for-work.md | 294 +++++++++++++++++++ ai/tiger-eon.md | 206 +++++++++++++ 4 files changed, 519 insertions(+), 1 deletion(-) create mode 100644 _partials/_prereqs-cloud-project-and-self.md create mode 100644 ai/tiger-agents-for-work.md create mode 100644 ai/tiger-eon.md diff --git a/_partials/_prereqs-cloud-project-and-self.md b/_partials/_prereqs-cloud-project-and-self.md new file mode 100644 index 0000000000..846e6defbc --- /dev/null +++ b/_partials/_prereqs-cloud-project-and-self.md @@ -0,0 +1,8 @@ +To follow the procedure on this page you need to: + +* Create a [$ACCOUNT_LONG][create-account]. + + This procedure also works for [$SELF_LONG][enable-timescaledb]. + +[create-account]: /getting-started/:currentVersion:/services/#create-a-tiger-account +[enable-timescaledb]: /self-hosted/:currentVersion:/install/ diff --git a/ai/page-index/page-index.js b/ai/page-index/page-index.js index 8ec63a7aa0..4bc352130d 100644 --- a/ai/page-index/page-index.js +++ b/ai/page-index/page-index.js @@ -1,12 +1,22 @@ module.exports = [ { - title: "AI and Vector: pgai on Tiger", + title: "AI and Vector", href: "ai", filePath: "index.md", pageComponents: ["featured-cards"], excerpt: "Information about pgai on TigerData and how to use it.", children: [ + { + title: "Aggregate organizational data with AI agents", + href: "tiger-eon", + excerpt: "Unify company knowledge with slack-native AI agents", + }, + { + title: "Integrate a slack-native AI agent", + href: "tiger-agents-for-work", + excerpt: "Configure a Slack-native AI agent to do what you want", + }, { title: "Key vector database concepts", href: "key-vector-database-concepts-for-understanding-pgvector", diff --git a/ai/tiger-agents-for-work.md b/ai/tiger-agents-for-work.md new file mode 100644 index 0000000000..6b3a7910aa --- /dev/null +++ b/ai/tiger-agents-for-work.md @@ -0,0 +1,294 @@ +--- +title: Integrate a slack-native AI agent +excerpt: Unify company knowledge with slack-native AI agents +products: [cloud] +keywords: [ai, vector, pgvector, TigerData vector, pgvectorizer] +tags: [ai, vector, pgvectorizer] +--- + +# Integrate a slack-native AI agent + +import PrereqAccount from "versionContent/_partials/_prereqs-cloud-project-and-self.mdx"; + +$AGENTS_LONG is a Slack-native AI agent that you use to unify the knowledge in your company. This includes your Slack +history, docs, GitHub repositories, Salesforce and so on. You use your $AGENTS_SHORT to get instant answers for real +business, technical, and operations questions in your Slack channels. + +![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-slack.png) + +$AGENTS_LONG can handle concurrent conversations with enterprise-grade reliability. They have the following features: + +- **Durable and atomic event handling**: $PG-backed event claiming ensures exactly-once processing, even under high concurrency and failure conditions +- **Bounded concurrency**: fixed worker pools prevent resource exhaustion while maintaining predictable performance under load +- **Immediate event processing**: $AGENTS_LONG provide real-time responsiveness. Events are processed within milliseconds of arrival rather than waiting for polling cycles +- **Resilient retry logic**: automatic retry with visibility thresholds, plus stuck or expired event cleanup +- **Horizontal scalability**: run multiple $AGENTS_SHORT instances simultaneously with coordinated work distribution across all instances +- **AI-Powered Responses**: use the AI model of your choice, you can also integrate with MCP servers +- **Extensible architecture**: zero code integration for basic agents. For more specialized use cases, easily customize your agent using [Jinja templates][jinja-templates] +- **Complete observability**: detailed tracing of event flow, worker activity, and database operations with full [Logfire][logfire] instrumentation + +This page shows you how to install the $AGENTS_CLI, connect to the $COMPANY MCP server, and customize prompts for +your specific needs. + +## Prerequisites + + + +* The [uv package manager][uv-install] +* An [Anthropic API key][claude-api-key] +* Optional: [Logfire token][logfire] + +## Create a Slack app + +Before installing $AGENTS_LONG, you need to create a Slack app that the $AGENTS_SHORT will connect to. This app +provides the security tokens for Slack integration with your $AGENTS_SHORT: + + + +1. **Create a manifest for your Slack App** + + 1. In a temporary directory, download the $AGENTS_SHORT Slack manifest template: + + ```bash + curl -O https://raw.githubusercontent.com/timescale/tiger-agents-for-work/main/slack-manifest.json + ``` + + 1. Edit `slack-manifest.json` and customize your name and description of your Slack App. For example: + + ```json + "display_information": { + "name": "Tiger Agent", + "description": "Tiger AI Agent helps you easily access your business information, and tune your Tiger services", + "background_color": "#000000" + }, + "features": { + "bot_user": { + "display_name": "Tiger Agent", + "always_online": true + } + }, + ``` + + 1. Copy the contents of `slack-manifest.json` to the clipboard: + + ```shell + cat slack-manifest.json| pbcopy + ``` + +1. **Create the Slack app** + + 1. Go to [api.slack.com/apps](https://api.slack.com/apps). + 1. Click `Create New App`. + 1. Select `From a manifest`. + 1. Choose your workspace, then click `Next`. + 1. Paste the contents of `slack-manifest.json` and click `Next`. + 1. Click `Create`. +1. **Generate an app-level token** + + 1. In your app settings, go to `Basic Information`. + 1. Scroll to `App-Level Tokens`. + 1. Click `Generate Token and Scopes`. + 1. Add a `Token Name`, then click `Add Scope`, add `connections:write` then click `Generate`. + 1. Copy the `xapp-*` token locally and click `Done`. + +1. **Install your app to a Slack workspace** + + 1. In the sidebar, under `Settings`, click `Install App`. + 1. Click `Install to `, then click `Allow`. + 1. Copy the `xoxb-` Bot User OAuth Token locally. + + + +You have created a Slack app and obtained the necessary tokens for $AGENTS_SHORT integration. + + +## Install and configure your $AGENTS_SHORT instance + +$AGENTS_LONG are a production-ready library and CLI written in Python that you use to create Slack-native AI agents. +This section shows you how to configure a $AGENTS_SHORT to connect to your Slack app, and give them access to your +data and analytics stored in $CLOUD_LONG. + + + +1. **Create a project directory** + + ```bash + mkdir my-tiger-agent + cd my-tiger-agent + ``` + +1. **Create a $AGENTS_SHORT environment with your Slack, AI Assistant, and database configuration** + + 1. Download `.env.sample` to a local `.env` file: + ```shell + curl -L -o .env https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/.env.sample + ``` + 1. In `.env`, add your Slack tokens and Anthropic API key: + + ```bash + # Slack tokens (from the Slack app you created) + SLACK_APP_TOKEN=xapp-your-app-token + SLACK_BOT_TOKEN=xoxb-your-bot-token + + # Anthropic API key + ANTHROPIC_API_KEY=sk-ant-your-api-key + + # Optional: Logfire token for enhanced logging + LOGFIRE_TOKEN=your-logfire-token + ``` + 1. Add the [connection details][connection-info] for the $SERVICE_LONG you are using for this $AGENTS_SHORT: + ```bash + PGHOST= + PGDATABASE=tsdb + PGPORT= + PGUSER=tsdbadmin + PGPASSWORD= + ``` + 1. Save and close `.env`. + +1. **Add the default $AGENTS_SHORT prompts to your project** + ```bash + mkdir prompts + curl -L -o prompts/system_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/system_prompt.md + curl -L -o prompts/user_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/user_prompt.md + ``` + +1. **Install $AGENTS_LONG to manage and run your AI-powered Slack bots** + + 1. Install the $AGENTS_CLI using uv. + + ```bash + uv tool install --from git+https://github.com/timescale/tiger-agents-for-work.git tiger-agent + ``` + `tiger-agent` is installed in `~/.local/bin/tiger-agent`. If necessary, add this folder to your `PATH`. + + 1. Verify the installation. + + ```bash + tiger-agent --help + ``` + + You see the $AGENTS_CLI help output with the available commands and options. + + +1. **Connect your $AGENTS_SHORT with Slack** + + 1. Run your $AGENTS_SHORT: + ```bash + tiger-agent run --prompts prompts/ --env .env + ``` + If you open the explorer in [$CONSOLE][portal-ops-mode], you can see the tables used by your $AGENTS_SHORT. + + 1. In Slack, open a public channel app and ask $AGENTS_SHORT a couple of questions. You see the response in your + public channel and log messages in the Terminal. + + ![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-terminal.png) + + + +## Add information from MCP servers to your $AGENTS_SHORT + +To increase the amount of specialized information your AI Assistant can use, you can add MCP servers supplying data +your users need. For example, to add the $COMPANY MCP server to your $AGENTS_SHORT: + + + +1. **Copy the example `mcp_config.json` to your project** + + In `my-tiger-agent`, run the following command: + + ```bash + curl -L -o mcp_config.json https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/examples/mcp_config.json + ``` + +1. **Configure your $AGENTS_SHORT to connect to the most useful MCP servers for your organization** + + For example, to add the $COMPANY documentation MCP server to your $AGENTS_SHORT, update the docs entry to the + following: + ```json + "docs": { + "tool_prefix": "docs", + "url": "https://mcp.tigerdata.com/docs", + "allow_sampling": false + }, + ``` + To avoid errors, delete all entries in `mcp_config.json` with invalid URLS. For example the `github` entry with `http://github-mcp-server/mcp`. + +1. **Restart your $AGENTS_SHORT** + ```bash + tiger-agent run --prompts prompts/ --mcp-config mcp_config.json + ``` + + + +You have configured your $AGENTS_SHORT to connect to the $MCP_SHORT. For more information, +see [MCP Server Configuration][mcp-configuration-docs]. + +## Customize prompts for personalization + +$AGENTS_LONG uses Jinja2 templates for dynamic, context-aware prompt generation. This system allows for sophisticated +prompts that adapt to conversation context, user preferences, and event metadata. $AGENTS_LONG uses the following +templates: + +- `system_prompt.md`: defines the AI Assistant's role, capabilities, and behavior patterns. This template sets the + foundation for the way your $AGENTS_SHORT will respond and interact. +- `user_prompt.md`: formats the user's request with relevant context, providing the AI Assistant with the + information necessary to generate an appropriate response. + +To change the way your $AGENTS_SHORTs interact with users in your Slack app: + + + +1. **Update the prompt** + + For example, in `prompts/system_prompt.md`, add another item in the `Response Protocol` section to fine tune + the behaviour of your $AGENTS_SHORTs. For example: + ```shell + 5. Be snarky but vaguely amusing + ``` + +1. **Test your configuration** + + Run $AGENTS_SHORT with your custom prompt: + + ```bash + tiger-agent run --mcp-config mcp_config.json --prompts prompts/ + ``` + + + +For more information, see [Prompt tempates][prompt-templates]. + +## Advanced configuration options + +For additional customization, you can modify the following $AGENTS_SHORT parameters: + +* `--model`: change AI model (default: `anthropic:claude-sonnet-4-20250514`) +* `--num-workers`: adjust concurrent workers (default: `5`) +* `--max-attempts`: set retry attempts per event (default: `3`) + +Example with custom settings: + +```bash +tiger-agent run \ + --model claude-3-5-sonnet-latest \ + --mcp-config mcp_config.json \ + --prompts prompts/ \ + --num-workers 10 \ + --max-attempts 5 +``` + +Your $AGENTS_SHORTs are now configured with $COMPANY MCP server access and personalized prompts. + + + + +[jinja-templates]: https://jinja.palletsprojects.com/en/stable/ +[logfire]: https://pydantic.dev/logfire +[claude-api-key]: https://console.anthropic.com/settings/keys +[create-a-service]: /getting-started/:currentVersion:/services +[uv-install]: https://docs.astral.sh/uv/getting-started/installation/ +[connection-info]: /integrations/:currentVersion:/find-connection-details/ +[portal-ops-mode]: https://console.cloud.timescale.com/dashboard/services +[mcp-configuration-docs]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/mcp_config.md +[prompt-templates]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/prompt_templates.md \ No newline at end of file diff --git a/ai/tiger-eon.md b/ai/tiger-eon.md new file mode 100644 index 0000000000..2029bcc471 --- /dev/null +++ b/ai/tiger-eon.md @@ -0,0 +1,206 @@ +--- +title: Aggregate organizational data with AI agents +excerpt: Unify company knowledge with slack-native AI agents +products: [cloud, self_hosted] +keywords: [ai, vector, pgvector, TigerData vector, pgvectorizer] +tags: [ai, vector, pgvectorizer] +--- + +import PrereqAccount from "versionContent/_partials/_prereqs-cloud-project-and-self.mdx"; + +# Aggregate organizational data with AI agents + +Your business already has the answers in Slack threads, GitHub pull requests, Linear tasks, your own docs, Salesforce +service tickets, anywhere you store data. However, those answers are scattered, hard to find, and often forgotten. +$EON_LONG automatically integrates $AGENTS_LONG with your organizational data so you can let AI assistants analyse your +company data and give you the answers you need. For example: +- What did we ship last week? +- What's blocking the release? +- Summarize the latest GitHub pull requests. + +$EON_SHORT responds instantly, pulling from the tools you already use. No new UI, no new workflow β€” just answers in Slack. + +![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-eon-big-question.png) + +$EON_LONG: + +- **Unlocks hidden value**: your data in Slack, GitHub, and Linear already contain the insights you need. $EON_SHORT makes them accessible. +- **Enables faster decisions**: no need to search or ask around, you get answers in seconds. +- **Is easy to use**: $EON_SHORT runs a $AGENTS_SHORT and MCP servers statelessly in lightweight Docker containers. +- **Integrates seamlessly with $CLOUD_LONG**: $EON_SHORT uses a $SERVICE_LONG so you securely and reliably store + your company data. Prefer to self-host? Use a [$PG instance with $TIMESCALE_DB][install-self-hosted]. + +$EON_LONGs real-time ingestion system connects to Slack and captures everything: every message, reaction, edit, and +channel update. It can also process historical Slack exports. $EON_SHORT had instant access to years +of institutional knowledge from the very beginning. + +All of this data is stored in your $SERVICE_LONG as time-series data: conversations are events unfolding over time, +and $CLOUD_LONG is purpose-built for precisely this. Your data is optimized by + +- Automatically partitioning the data into 7-day chunks for efficient queries +- Compressing the data after 45 days to save space +- Segmenting by channel for faster retrieval + +When someone asks $EON_SHORT a question, it uses simple SQL to instantly retrieve the full thread context, related +conversations, and historical decisions. No rate limits. No API quotas. Just direct access to your data. + +This page shows you how to install and run $EON_SHORT. + +## Prerequisites + + + +- [Install Docker][install-docker] on your developer device +- Install [$CLI_LONG][tiger-cli] +- Have rights to create an [Anthropic API key][claude-api-key] +- Optionally: + - Have rights to create a [GitHub token][github-token] + - Have rights to create a [Logfire token][logfire-token] + - Have rights to create a [Linear token][linear-token] + +## Interactive setup + +$EON_LONG is a production-ready repository running [$CLI_LONG][tiger-cli] and [$AGENTS_LONG][tiger-agents] that creates +and runs the following components for you: + +- An ingest Slack app that consumes all messages and reactions from public channels in your Slack workspace +- A [$AGENTS_SHORT][tiger-agents] that analyzes your company data for you +- A $SERVICE_LONG instance that stores data from the Slack apps +- MCP servers that connect data sources to $EON_SHORT +- A listener Slack app that passes questions to the $AGENTS_SHORT when you @tag it in a public channel, and returns the + AI analysis on your data + +All local components are run in lightweight Docker containers via Docker Compose. + +This section shows you how to run the $EON_SHORT setup to configure $EON_SHORT to connect to your Slack app, and give them access to your +data and analytics stored in $CLOUD_LONG. + + + +1. **Install $EON_LONG to manage and run your AI-powered Slack bots** + + In a local folder, run the following command from the terminal: + ```shell + git clone git@github.com:timescale/tiger-eon.git + ``` + +1. **Start the $EON_SHORT setup** + + ```shell + cd tiger-eon + ./setup-tiger-eon.sh + ``` + You see a summary of the setup procedure. Type `y` and press `Enter`. + +1. **Create the $SERVICE_LONG to use with $EON_SHORT** + + You see `Do you want to use a free tier Tiger Cloud Database? [y/N]:`. Press `Y` to create a free + $SERVICE_LONG. + + $EON_SHORT opens the $CLOUD_LONG authentication page in your browser. Click `Authorize`. $EON_SHORT creates a + $SERVICE_LONG called [tiger-eon][services-portal] and stores the credentials in your local keychain. + + If you press `N`, the $EON_SHORT setup creates and runs $TIMESCALE_DB in a local Docker container. + +1. **Create the ingest Slack app** + + 1. In the terminal, name your ingest Slack app: + + 1. $EON_SHORT proposes to create an ingest app called `tiger-slack-ingest`, press `Enter`. + 1. Do the same for the App description. + + $EON_SHORT opens `Your Apps` in https://api.slack.com/apps/. + + 1. Start configuring your ingest app in Slack: + + In the Slack `Your Apps` page: + 1. Click `Create New App`, click `From an manifest`, then select a workspace. + 1. Click `Next`. Slack opens `Create app from manifest`. + + 1. Add the Slack app manifest: + 1. In terminal press `Enter`. The setup prints the Slack app manifest to terminal and adds it to your clipboard. + 1. In the Slack `Create app from manifest` window, paste the manifest. + 1. Click `Next`, then click `Create`. + + 1. Configure an app-level token + + 1. In your app settings, go to `Basic Information`. + 1. Scroll to `App-Level Tokens`. + 1. Click `Generate Token and Scopes`. + 1. Add a `Token Name`, then click `Add Scope` add `connections:write`, then click `Generate`. + 1. Copy the `xapp-*` token and click `Done`. + 1. In terminal, paste the token, then press `Enter`. + + 1. Configure a bot user OAuth token: + + 1. In your app settings, under `Features`, click `App Home`. + 1. Scroll down, then enable `Allow users to send Slash commands and messages from the messages tab`. + 1. In your app settings, under `Settings`, click `Install App`. + 1. Click `Install to `, then click `Allow`. + 1. Copy the `xoxb-` Bot User OAuth Token locally. + 1. In terminal, paste the token, then press `Enter`. + +1. **Create the $EON_SHORT Slack app** + + Follow the same procedure as you did for the ingest Slack app. + +1. **Integrate $EON_SHORT with Anthropic** + + The $EON_SHORT setup opens https://console.anthropic.com/settings/keys. Create a Claude Code key, then + paste it in the terminal. + +1. **Integrate $EON_SHORT with Logfire** + + If you would like to integrate logfire with $EON_SHORT, paste your token and press `Enter`. If not, press `Enter`. + +1. **Integrate $EON_SHORT with GitHub** + + The $EON_SHORT setup asks if you would like to `Enable github MCP server?". For $EON_SHORT to answer questions + about the activity in your Github organization`. Press `y` to integrate with GitHub. + +1. **Integrate $EON_SHORT with Linear** + + The $EON_SHORT setup asks if you would like to `Enable linear MCP server? [y/N]:`. Press `y` to integrate with Linear. + +1. **Give $EON_SHORT access to private repositories** + + 1. The setup asks if you would like to include access to private repositories. Press `y`. + 1. Follow the GitHub token creation process. + 1. In the $EON_SHORT setup add your organization name, then paste the GitHub token. + + The setup sets up a new $SERVICE_LONG for you called `tiger-eon`, then starts $EON_SHORT in Docker. + + ![Eon running in Docker](https://assets.timescale.com/docs/images/tiger-eon-docker-services.png) + + + +You have created: +* The $EON_SHORT ingest and chat apps in Slack +* A private MCP server connecting $EON_SHORT to your data in GitHub +* A $SERVICE_LONG that securely stores the data used by $EON_SHORT + +## Integrate $EON_SHORT in your Slack workspace + +To enable your AI Assistant to analyze your data for you when you ask a question, open a public channel, +invite `@eon` to join, then ask a question: + +![Eon running in Docker](https://assets.timescale.com/docs/images/tiger-eon-slack-channel-add.png) + + +[jinja-templates]: https://jinja.palletsprojects.com/en/stable/ +[logfire]: https://pydantic.dev/logfire +[claude-api-key]: https://console.anthropic.com/settings/keys +[github-token]: https://github.com/settings/tokens/new?description=Tiger%20Agent&scopes=repo,read:org +[create-a-service]: /getting-started/:currentVersion:/services +[uv-install]: https://docs.astral.sh/uv/getting-started/installation/ +[connection-info]: /integrations/:currentVersion:/find-connection-details/ +[portal-ops-mode]: https://console.cloud.timescale.com/dashboard/services +[mcp-configuration-docs]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/mcp_config.md +[prompt-templates]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/prompt_templates.md +[install-docker]: https://docs.docker.com/engine/install/ +[tiger-cli]: https://github.com/timescale/tiger-cli/ +[tiger-agents]: https://github.com/timescale/tiger-agents-for-work +[services-portal]: https://console.cloud.timescale.com/dashboard/services +[install-self-hosted]: /self-hosted/:currentVersion:/install/ +[logfire-token]: http://logfire.pydantic.dev/docs/how-to-guides/create-write-tokens/ +[linear-token]: https://linear.app/docs/api-and-webhooks#api-keys \ No newline at end of file From 40347e7049e609cd9bc8ab400745cf0602333106 Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Tue, 21 Oct 2025 11:33:28 +0200 Subject: [PATCH 3/4] 425 docs rfcadd docs for the mcp server (#4477) lots of stuff. --- _partials/_devops-cli-get-started.md | 197 +++------------ _partials/_devops-cli-global-flags.md | 11 + _partials/_devops-cli-install.md | 117 +++++++++ _partials/_devops-cli-reference.md | 84 +++++++ _partials/_devops-mcp-commands-cli.md | 13 + _partials/_devops-mcp-commands.md | 34 +++ _partials/_devops-rest-api-get-started.md | 67 ++--- ai/index.md | 82 ++++-- ai/mcp-server.md | 233 ++++++++++++++++++ ai/page-index/page-index.js | 9 +- api/api-reference.md | 21 +- api/glossary.md | 2 + getting-started/get-started-devops-as-code.md | 15 +- integrations/find-connection-details.md | 27 +- 14 files changed, 666 insertions(+), 246 deletions(-) create mode 100644 _partials/_devops-cli-global-flags.md create mode 100644 _partials/_devops-cli-install.md create mode 100644 _partials/_devops-cli-reference.md create mode 100644 _partials/_devops-mcp-commands-cli.md create mode 100644 _partials/_devops-mcp-commands.md create mode 100644 ai/mcp-server.md diff --git a/_partials/_devops-cli-get-started.md b/_partials/_devops-cli-get-started.md index 16eb6a88e5..6b517072a6 100644 --- a/_partials/_devops-cli-get-started.md +++ b/_partials/_devops-cli-get-started.md @@ -1,4 +1,6 @@ import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; +import CLIINSTALL from "versionContent/_partials/_devops-cli-install.mdx"; +import CLIREF from "versionContent/_partials/_devops-cli-reference.mdx"; $CLI_LONG is a command-line interface that you use to manage $CLOUD_LONG resources including VPCs, services, read replicas, and related infrastructure. $CLI_LONG calls $REST_LONG to communicate with @@ -16,131 +18,22 @@ service. -1. **Install $CLI_LONG** - - Use the terminal to install the $CLI_SHORT: - - - - - ```shell - curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.deb.sh | sudo os=any dist=any bash - sudo apt-get install tiger-cli - ``` - - - - - - ```shell - curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.deb.sh | sudo os=any dist=any bash - sudo apt-get install tiger-cli - ``` - - - - - ```shell - curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.rpm.sh | sudo os=rpm_any dist=rpm_any bash - sudo yum install tiger-cli - ``` - - - - - - ```shell - curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.rpm.sh | sudo os=rpm_any dist=rpm_any bash - sudo yum install tiger-cli - ``` - - - - - - ```shell - brew install --cask timescale/tap/tiger-cli - ``` - - - - - - ```shell - curl -fsSL https://tiger-cli-releases.s3.amazonaws.com/install/install.sh | sh - ``` - - - - - -1. **Set up API credentials** - - 1. Log $CLI_LONG into your $ACCOUNT_LONG: - - ```shell - tiger auth login - ``` - $CLI_LONG opens $CONSOLE_SHORT in your browser. Log in, then click `Authorize`. - - 1. Log $CLI_LONG into your $ACCOUNT_LONG - - ```shell - tiger auth login - ``` - $CLI_LONG opens $CONSOLE_SHORT in your browser. Login, then click `Authorize`. - - 1. Select a $PROJECT_LONG. - - ```terminaloutput - Auth URL is: https://console.cloud.timescale.com/oauth/authorize?client_id=lotsOfURLstuff - Opening browser for authentication... - Select a project: - - > 1. Tiger Project (tgrproject) - 2. YourCompany (Company wide project) (cpnproject) - 3. YourCompany Department (dptproject) - - Use ↑/↓ arrows or number keys to navigate, enter to select, q to quit - ``` - If only one $PROJECT_SHORT is associated with your $ACCOUNT_SHORT, this step is not shown. - - Where possible, $CLI_LONG stores your authentication information in the system keychain/credential manager. - If that fails, the key is stored in `~/.config/tiger/api-key` with restricted file permissions (600). - $CLI_LONG stores your configuration in `~/.config/tiger/config.yaml`. - -1. **Test your authenticated connection to $CLOUD_LONG by listing services** - - ```bash - tiger service list - ``` - - This call returns something like: - - No services: - ```terminaloutput - 🏜️ No services found! Your project is looking a bit empty. - πŸš€ Ready to get started? Create your first service with: tiger service create - ``` - - One or more services: - - ```terminaloutput - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ SERVICE ID β”‚ NAME β”‚ STATUS β”‚ TYPE β”‚ REGION β”‚ CREATED β”‚ - β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ - β”‚ tgrservice β”‚ tiger-agent-service β”‚ READY β”‚ TIMESCALEDB β”‚ eu-central-1 β”‚ 2025-09-25 16:09 β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - ``` + -## Create your first service +## Create your first $SERVICE_LONG Create a new $SERVICE_LONG using $CLI_LONG: -1. **Submit a service creation request** +1. **Submit a $SERVICE_SHORT creation request** + + By default, $CLI_LONG creates a $SERVICE_SHORT for you that matches your [pricing plan][pricing-plans]: + * **Free plan**: shared CPU/memory and the `time-series` and `ai` capabilities + * **Paid plan**: 0.5 CPU and 2 GB memory with the `time-series` capability ```shell tiger service create ``` @@ -149,12 +42,27 @@ Create a new $SERVICE_LONG using $CLI_LONG: ```terminaloutput πŸš€ Creating service 'db-11111' (auto-generated name)... βœ… Service creation request accepted! - πŸ“‹ Service ID: happyservice + πŸ“‹ Service ID: tgrservice πŸ” Password saved to system keyring for automatic authentication - 🎯 Set service 'happyservice' as default service. + 🎯 Set service 'tgrservice' as default service. ⏳ Waiting for service to be ready (wait timeout: 30m0s)... - ⏳ Service status: QUEUED... πŸŽ‰ Service is ready and running! + πŸ”Œ Run 'tiger db connect' to connect to your new service + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ PROPERTY β”‚ VALUE β”‚ + β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ + β”‚ Service ID β”‚ tgrservice β”‚ + β”‚ Name β”‚ db-11111 β”‚ + β”‚ Status β”‚ READY β”‚ + β”‚ Type β”‚ TIMESCALEDB β”‚ + β”‚ Region β”‚ us-east-1 β”‚ + β”‚ CPU β”‚ 0.5 cores (500m) β”‚ + β”‚ Memory β”‚ 2 GB β”‚ + β”‚ Direct Endpoint β”‚ tgrservice.tgrproject.tsdb.cloud.timescale.com:39004 β”‚ + β”‚ Created β”‚ 2025-10-20 20:33:46 UTC β”‚ + β”‚ Connection String β”‚ postgresql://tsdbadmin@tgrservice.tgrproject.tsdb.cloud.timescale.com:0007/tsdb?sslmode=require β”‚ + β”‚ Console URL β”‚ https://console.cloud.timescale.com/dashboard/services/tgrservice β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` This $SERVICE_SHORT is set as default by the $CLI_SHORT. @@ -182,56 +90,11 @@ Create a new $SERVICE_LONG using $CLI_LONG: And that is it, you are ready to use $CLI_LONG to manage your $SERVICE_SHORTs in $CLOUD_LONG. -## Commands - -You can use the following commands with $CLI_LONG. For more information on each command, use the `-h` flag. For example: -`tiger auth login -h` - -| Command | Subcommand | Description | -|---------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| auth | | Manage authentication and the credentials for your $ACCOUNT_LONG | -| | login | Create an authenticated connection to your $ACCOUNT_LONG | -| | logout | Remove the credentials used to create authenticated connections to $CLOUD_LONG | -| | whoami | Show information about the current user | -| version | | Show information about the currently installed version of $CLI_LONG | -| | set `` `` | Set a specific value in your configuration. For example, `tiger config set debug true` | -| config | | Manage your $CLI_LONG configuration | -| | show | Show the current configuration | -| | unset `` | Clear the value of a configuration parameter. For example, `tiger config unset debug` | -| | reset | Reset the configuration to the defaults. This also logs you out from the current $PROJECT_LONG | -| service | | Manage the $SERVICE_LONGs in this $PROJECT_SHORT | -| | create `--addons=` | Create a new $SERVICE_SHORT in this $PROJECT_SHORT. Possible addons are:
  • time-series: with the Timescaledb and Timescaledb Toolkit extensions
  • ai: with the Timescaledb, Timescaledb Toolkit, vector and vectorscale extensions
  • free: free services have fixed compute of 0.25 CPU, 1 GiB RAM, and up to 500mb storage.
  • none: vanilla Postgres
All services have Tiger features such as Tiger Storage, Security, Monitoring and compliance. If you do not use the `addons` flag, the default service is `time-series`. | -| | describe `` | Show detailed information about a specific $SERVICE_SHORT in this $PROJECT_SHORT | -| | delete `` | Delete a $SERVICE_SHORT from this $PROJECT_SHORT | -| | fork `` | Fork of an existing database service. Key features are:
  • Timing options: `--now`, `--last-snapshot`, `--to-timestamp`
  • Resource configuration: `--cpu`, `--memory`
  • Naming: `--name ` . Defaults to {source-service-name}-fork
  • Wait behavior: `--no-wait`, `--wait-timeout`
  • Default service: `--no-set-default`
| -| | list | List all the $SERVICE_SHORTs in this $PROJECT_SHORT | -| | update-password `` | Update the password for a $SERVICE_SHORT | -| db | | Database operations and management | -| | connect `` | Connect to a $SERVICE_SHORT | -| | connection-string `` | Retrieve the connection string for a $SERVICE_SHORT | -| | test-connection `` | Test the connectivity to a $SERVICE_SHORT | -| mcp | | Manage the $MCP_LONG | -| | start | Start the $MCP_LONG. This is the same as `tiger mcp start stdio` | -| | start `stdio` \| `http` | Start the $MCP_LONG with stdio or HTTP transport | - -## Flags - -You can use the following global flags with $CLI_LONG: - -| Flag | Default | Description | -|--|-----------------|-----------------------------------------------------------------------| -| --analytics | `true` | Set to `false` to disable usage analytics | -| --config-dir string | `.config/tiger` | Set the directory that holds `config.yaml` | -| --debug | No debugging | Enable debug logging | -| -o, --output string | table | Set the output format. Options are `json`, `yaml`, or `table` | -| --password-storage string | keyring | Set the password storage method. Options are `keyring`, `pgpass`, or `none` | -| --project-id string | - | Set the $PROJECT_LONG to manage | -| --service-id string | - | Set the $SERVICE_LONG to manage | - - + [rest-api-reference]: /api/:currentVersion:/api-reference/ [rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings [get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id [create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials -[curl]: https://curl.se/ \ No newline at end of file +[curl]: https://curl.se/ +[pricing-plans]: /about/:currentVersion:/pricing-and-account-management/ \ No newline at end of file diff --git a/_partials/_devops-cli-global-flags.md b/_partials/_devops-cli-global-flags.md new file mode 100644 index 0000000000..1fd8c692dc --- /dev/null +++ b/_partials/_devops-cli-global-flags.md @@ -0,0 +1,11 @@ + +| Flag | Default | Description | +|-------------------------------|-------------------|-----------------------------------------------------------------------------| +| `--analytics` | `true` | Set to `false` to disable usage analytics | +| `--color ` | `true` | Set to `false` to disable colored output | +| `--config-dir` string | `.config/tiger` | Set the directory that holds `config.yaml` | +| `--debug` | No debugging | Enable debug logging | +| `--help` | - | Print help about the current command. For example, `tiger service --help` | +| `--password-storage` string | keyring | Set the password storage method. Options are `keyring`, `pgpass`, or `none` | +| `--service-id` string | - | Set the $SERVICE_LONG to manage | +| ` --skip-update-check ` | - | Do not check if a new version of $CLI_LONG is available| \ No newline at end of file diff --git a/_partials/_devops-cli-install.md b/_partials/_devops-cli-install.md new file mode 100644 index 0000000000..d0dab2990e --- /dev/null +++ b/_partials/_devops-cli-install.md @@ -0,0 +1,117 @@ +1. **Install $CLI_LONG** + + Use the terminal to install the $CLI_SHORT: + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.deb.sh | sudo os=any dist=any bash + sudo apt-get install tiger-cli + ``` + + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.deb.sh | sudo os=any dist=any bash + sudo apt-get install tiger-cli + ``` + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.rpm.sh | sudo os=rpm_any dist=rpm_any bash + sudo yum install tiger-cli + ``` + + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.rpm.sh | sudo os=rpm_any dist=rpm_any bash + sudo yum install tiger-cli + ``` + + + + + + ```shell + brew install --cask timescale/tap/tiger-cli + ``` + + + + + + ```shell + curl -fsSL https://cli.tigerdata.com | sh + ``` + + + + + +1. **Set up API credentials** + + 1. Log $CLI_LONG into your $ACCOUNT_LONG: + + ```shell + tiger auth login + ``` + $CLI_LONG opens $CONSOLE_SHORT in your browser. Log in, then click `Authorize`. + + You can have a maximum of 10 active client credentials. If you get an error, open [credentials][rest-api-credentials] + and delete an unused credential. + + 1. Select a $PROJECT_LONG: + + ```terminaloutput + Auth URL is: https://console.cloud.timescale.com/oauth/authorize?client_id=lotsOfURLstuff + Opening browser for authentication... + Select a project: + + > 1. Tiger Project (tgrproject) + 2. YourCompany (Company wide project) (cpnproject) + 3. YourCompany Department (dptproject) + + Use ↑/↓ arrows or number keys to navigate, enter to select, q to quit + ``` + If only one $PROJECT_SHORT is associated with your $ACCOUNT_SHORT, this step is not shown. + + Where possible, $CLI_LONG stores your authentication information in the system keychain/credential manager. + If that fails, the credentials are stored in `~/.config/tiger/credentials` with restricted file permissions (600). + By default, $CLI_LONG stores your configuration in `~/.config/tiger/config.yaml`. + +1. **Test your authenticated connection to $CLOUD_LONG by listing $SERVICE_SHORTs** + + ```bash + tiger service list + ``` + + This call returns something like: + - No $SERVICE_SHORTs: + ```terminaloutput + 🏜️ No services found! Your project is looking a bit empty. + πŸš€ Ready to get started? Create your first service with: tiger service create + ``` + - One or more $SERVICE_SHORTs: + + ```terminaloutput + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ SERVICE ID β”‚ NAME β”‚ STATUS β”‚ TYPE β”‚ REGION β”‚ CREATED β”‚ + β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ + β”‚ tgrservice β”‚ tiger-agent-service β”‚ READY β”‚ TIMESCALEDB β”‚ eu-central-1 β”‚ 2025-09-25 16:09 β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ``` + + +[rest-api-reference]: /api/:currentVersion:/api-reference/ +[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings +[get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id +[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials +[curl]: https://curl.se/ \ No newline at end of file diff --git a/_partials/_devops-cli-reference.md b/_partials/_devops-cli-reference.md new file mode 100644 index 0000000000..c641f17146 --- /dev/null +++ b/_partials/_devops-cli-reference.md @@ -0,0 +1,84 @@ +import GLOBALFLAGS from "versionContent/_partials/_devops-cli-global-flags.mdx"; + +## Commands + +You can use the following commands with $CLI_LONG. For more information on each command, use the `-h` flag. For example: +`tiger auth login -h` + +| Command | Subcommand | Description | +|---------|----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| auth | | Manage authentication and credentials for your $ACCOUNT_LONG | +| | login | Create an authenticated connection to your $ACCOUNT_LONG | +| | logout | Remove the credentials used to create authenticated connections to $CLOUD_LONG | +| | status | Show your current authentication status and project ID | +| version | | Show information about the currently installed version of $CLI_LONG | +| config | | Manage your $CLI_LONG configuration | +| | show | Show the current configuration | +| | set `` `` | Set a specific value in your configuration. For example, `tiger config set debug true` | +| | unset `` | Clear the value of a configuration parameter. For example, `tiger config unset debug` | +| | reset | Reset the configuration to the defaults. This also logs you out from the current $PROJECT_LONG | +| service | | Manage the $SERVICE_LONGs in this $PROJECT_SHORT | +| | create | Create a new $SERVICE_SHORT in this $PROJECT_SHORT. Possible flags are:
  • `--name`: service name (auto-generated if not provided)
  • `--addons`: addons to enable (time-series, ai, or none for PostgreSQL-only)
  • `--region`: region code where the service will be deployed
  • `--cpu-memory`: CPU/memory allocation combination
  • `--replicas`: number of high-availability replicas
  • `--no-wait`: don't wait for the operation to complete
  • `--wait-timeout`: wait timeout duration (for example, 30m, 1h30m, 90s)
  • `--no-set-default`: don't set this service as the default service
  • `--with-password`: include password in output
  • `--output, -o`: output format (`json`, `yaml`, table)

Possible `cpu-memory` combinations are:
  • shared/shared
  • 0.5 CPU/2 GB
  • 1 CPU/4 GB
  • 2 CPU/8 GB
  • 4 CPU/16 GB
  • 8 CPU/32 GB
  • 16 CPU/64 GB
  • 32 CPU/128 GB
| +| | delete `` | Delete a $SERVICE_SHORT from this $PROJECT_SHORT. This operation is irreversible and requires confirmation by typing the service ID | +| | fork `` | Fork an existing service to create a new independent copy. Key features are:
  • Timing options: `--now`, `--last-snapshot`, `--to-timestamp`
  • Resource configuration: `--cpu-memory`
  • Naming: `--name `. Defaults to `{source-service-name}-fork`
  • Wait behavior: `--no-wait`, `--wait-timeout`
  • Default service: `--no-set-default`
| +| | get `` (aliases: describe, show) | Show detailed information about a specific $SERVICE_SHORT in this $PROJECT_SHORT | +| | list | List all the $SERVICE_SHORTs in this $PROJECT_SHORT | +| | update-password `` | Update the master password for a $SERVICE_SHORT | +| db | | Database operations and management | +| | connect `` | Connect to a $SERVICE_SHORT | +| | connection-string `` | Retrieve the connection string for a $SERVICE_SHORT | +| | save-password `` | Save the password for a service | +| | test-connection `` | Test the connectivity to a $SERVICE_SHORT | +| mcp | | Manage the $MCP_LONG for AI Assistant integration | +| | install `[client]` | Install and configure $MCP_LONG for a specific client (`claude-code`, `cursor`, `windsurf`, or other). If no client is specified, you'll be prompted to select one interactively | +| | start | Start the $MCP_LONG. This is the same as `tiger mcp start stdio` | +| | start stdio | Start the $MCP_LONG with stdio transport (default) | +| | start http | Start the $MCP_LONG with HTTP transport. Includes flags: `--port` (default: `8080`), `--host` (default: `localhost`) | + + +## Global flags + +You can use the following global flags with $CLI_LONG: + + + + +## Configuration parameters + +By default, $CLI_LONG stores your configuration in `~/.config/tiger/config.yaml`. The name of these +variables matches the flags you use to update them. However, you can override them using the following +environmental variables: + +- **Configuration parameters** + - `TIGER_CONFIG_DIR`: path to configuration directory (default: `~/.config/tiger`) + - `TIGER_API_URL`: $REST_LONG base endpoint (default: https://console.cloud.timescale.com/public/api/v1) + - `TIGER_CONSOLE_URL`: URL to $CONSOLE (default: https://console.cloud.timescale.com) + - `TIGER_GATEWAY_URL`: URL to the $CONSOLE gateway (default: https://console.cloud.timescale.com/api) + - `TIGER_DOCS_MCP`: enable/disable docs MCP proxy (default: true) + - `TIGER_DOCS_MCP_URL`: URL to the $MCP_SHORT for $COMPANY docs (default: https://mcp.tigerdata.com/docs) + - `TIGER_SERVICE_ID`: ID for the $SERVICE_SHORT updated when you call $CLI_SHORT commands + - `TIGER_ANALYTICS`: enable or disable analytics (default: `true`) + - `TIGER_PASSWORD_STORAGE`: password storage method (keyring, pgpass, or none) + - `TIGER_DEBUG`: enable/disable debug logging (default: `false`) + - `TIGER_COLOR`: Set to `false` to disable colored output (default: `true`) + + +- **Authentication parameters** + + To authenticate without using the interactive login, either: + - Set the following parameters with your [client credentials][rest-api-credentials], then `login`: + ```shell + TIGER_PUBLIC_KEY= TIGER_SECRET_KEY= TIGER_PROJECT_ID=\ + tiger auth login + ``` + - Add your [client credentials][rest-api-credentials] to the `login` command: + ```shell + tiger auth login --public-key= --secret-key= --project-id= + ``` + +[rest-api-reference]: /api/:currentVersion:/api-reference/ +[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings +[get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id +[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials +[curl]: https://curl.se/ +[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings \ No newline at end of file diff --git a/_partials/_devops-mcp-commands-cli.md b/_partials/_devops-mcp-commands-cli.md new file mode 100644 index 0000000000..0f3ba5d10c --- /dev/null +++ b/_partials/_devops-mcp-commands-cli.md @@ -0,0 +1,13 @@ + +You can use the following $CLI_LONG commands to run $MCP_SHORT: + +Usage: `tiger mcp [subcommand] --` + +| Command | Subcommand | Description | +|---------|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| mcp | | Manage the $MCP_LONG | +| | install `[client]` | Install and configure $MCP_SHORT for a specific client installed on your developer device.
Supported clients are: `claude-code`, `cursor`, `windsurf`, `codex`, `gemini/gemini-cli`, `vscode/code/vs-code`.
Flags:
  • `--no-backup`: do not back up the existing configuration
  • `--config-path`: open the configuration file at a specific location
| +| | start | Start the $MCP_SHORT. This is the same as `tiger mcp start stdio` | +| | start stdio | Start the $MCP_SHORT with stdio transport | +| | start http | Start the $MCP_SHORT with HTTP transport. This option is for users who wish to access $MCP_LONG without using stdio. For example, your AI Assistant does not support stdio, or you do not want to run $CLI_SHORT on your device.
Flags are:
  • `--port `: the default is `8000`
  • `--host `: the default is `localhost`
| + diff --git a/_partials/_devops-mcp-commands.md b/_partials/_devops-mcp-commands.md new file mode 100644 index 0000000000..0b91f74756 --- /dev/null +++ b/_partials/_devops-mcp-commands.md @@ -0,0 +1,34 @@ + +$MCP_LONG exposes the following MCP tools to your AI Assistant: + +| Command | Parameter | Required | Description | +|--------------------------|---------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `service_list` | - | - | Returns a list of the $SERVICE_SHORTs in the current $PROJECT_SHORT. | +| `service_get` | - | - | Returns detailed information about a $SERVICE_SHORT. | +| | `service_id` | βœ“ | The unique identifier of the $SERVICE_SHORT (10-character alphanumeric string). | +| | `with_password` | - | Set to `true` to include the password in the response and connection string.
**WARNING**: never do this unless the user explicitly requests the password. | +| `service_create` | - | - | Create a new $SERVICE_SHORT in $CLOUD_LONG.
**WARNING**: creates billable resources. | +| | `name` | - | Set the human-readable name of up to 128 characters for this $SERVICE_SHORT. | +| | `addons` | - | Set the array of [addons][create-service] to enable for the $SERVICE_SHORT. Options:
  • `time-series`: enables $TIMESCALE_DB
  • `ai`: enables the AI and vector extensions
Set an empty array for $PG-only. | +| | `region` | - | Set the [AWS region][cloud-regions] to deploy this $SERVICE_SHORT in. | +| | `cpu_memory` | - | CPU and memory allocation combination.
Available configurations are:
  • shared/shared
  • 0.5 CPU/2 GB
  • 1 CPU/4 GB
  • 2 CPU/8 GB
  • 4 CPU/16 GB
  • 8 CPU/32 GB
  • 16 CPU/64 GB
  • 32 CPU/128 GB
| +| | `replicas` | - | Set the number of [high-availability replicas][readreplica] for fault tolerance. | +| | `wait` | - | Set to `true` to wait for $SERVICE_SHORT to be fully ready before returning. | +| | `timeout_minutes` | - | Set the timeout in minutes to wait for $SERVICE_SHORT to be ready. Only used when `wait=true`. Default: 30 minutes | +| | `set_default` | - | By default, the new $SERVICE_SHORT is the default for following commands in $CLI_SHORT. Set to `false` to keep the previous $SERVICE_SHORT as the default. | +| | `with_password` | - | Set to `true` to include the password for this $SERVICE_SHORT in response and connection string.
**WARNING**: never set to `true` unless user explicitly requests the password. | +| `service_update_password` | - | - | Update the password for the `tsdbadmin` for this $SERVICE_SHORT. The password change takes effect immediately and may terminate existing connections. | +| | `service_id` | βœ“ | The unique identifier of the $SERVICE_SHORT you want to update the password for. | +| | `password` | βœ“ | The new password for the `tsdbadmin` user. | +| `db_execute_query` | - | - | Execute a single SQL query against a $SERVICE_SHORT. This command returns column metadata, result rows, affected row count, and execution time. Multi-statement queries are not supported.
**WARNING**: can execute destructive SQL including INSERT, UPDATE, DELETE, and DDL commands. | +| | `service_id` | βœ“ | The unique identifier of the $SERVICE_SHORT. Use `tiger_service_list` to find $SERVICE_SHORT IDs. | +| | `query` | βœ“ | The SQL query to execute. Single statement queries are supported. | +| | `parameters` | - | Query parameters for parameterized queries. Values are substituted for the `$n` placeholders in the query. | +| | `timeout_seconds` | - | The query timeout in seconds. Default: `30`. | +| | `role` | - | The $SERVICE_SHORT role/username to connect as. Default: `tsdbadmin`. | +| | `pooled` | - | Use [connection pooling][Connection pooling]. This is only available if you have already enabled it for the $SERVICE_SHORT. Default: `false`. | + +[cloud-regions]: /use-timescale/:currentVersion:/regions/ +[create-service]: /getting-started/:currentVersion:/services/ +[readreplica]: /use-timescale/:currentVersion:/ha-replicas/read-scaling/ +[Connection pooling]: /use-timescale/:currentVersion:/services/connection-pooling/ \ No newline at end of file diff --git a/_partials/_devops-rest-api-get-started.md b/_partials/_devops-rest-api-get-started.md index fdf27c3062..b62390fdc5 100644 --- a/_partials/_devops-rest-api-get-started.md +++ b/_partials/_devops-rest-api-get-started.md @@ -21,13 +21,13 @@ proper authentication headers. 1. **Set up API credentials** - 1. In $CONSOLE, copy your [project ID][get-project-id] and store it securely using an environment variable: + 1. In $CONSOLE [copy your project ID][get-project-id] and store it securely using an environment variable: ```bash export TIGERDATA_PROJECT_ID="your-project-id" ``` - 1. [Create your client credentials][create-client-credentials] and store them securely using environment variables: + 1. In $CONSOLE [create your client credentials][create-client-credentials] and store them securely using environment variables: ```bash export TIGERDATA_ACCESS_KEY="Public key" @@ -58,12 +58,12 @@ proper authentication headers. - One or more $SERVICE_SHORTs: ```terminaloutput - [{"service_id":"a59clooxoe","project_id":"c8nmagk8zh","name":"events", - "region_code":"eu-central-1","service_type":"TIMESCALEDB", - "created":"2025-09-09T08:37:15.816443Z","paused":false,"status":"READY", - "resources":[{"id":"101228","spec":{"cpu_millis":500,"memory_gbs":2,"volume_type":""}}], - "metadata":{"environment":"DEV"},"endpoint":{"host":"oh.yeah.tsdb.cloud.timescale.com", - "port":12345}}] + [{"service_id":"tgrservice","project_id":"tgrproject","name":"tiger-eon", + "region_code":"us-east-1","service_type":"TIMESCALEDB", + "created":"2025-10-20T12:21:28.216172Z","paused":false,"status":"READY", + "resources":[{"id":"104977","spec":{"cpu_millis":500,"memory_gbs":2,"volume_type":""}}], + "metadata":{"environment":"DEV"}, + "endpoint":{"host":"tgrservice.tgrproject.tsdb.cloud.timescale.com","port":11111}}] ``` @@ -81,31 +81,29 @@ Create a new $SERVICE_SHORT using the $REST_LONG: -u "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" \ -H "Content-Type: application/json" \ -d '{ - "name": "my-first-service", - "service_type": "TIMESCALEDB", - "region_code": "us-east-1", - "replica_count": 1, - "cpu_millis": 1000, - "memory_gbs": 4 - }' + "name": "my-first-service", + "addons": ["time-series"], + "region_code": "us-east-1", + "replica_count": 1, + "cpu_millis": "1000", + "memory_gbs": "4" + }' ``` $CLOUD_LONG creates a Development environment for you. That is, no delete protection, high-availability, spooling or read replication. You see something like: ```terminaloutput - { - "service_id":"asdfasdfasdf","project_id":"asdasdfasf","name":"my-first-service", - "region_code":"us-east-1", "service_type":"TIMESCALEDB", - "created":"2025-09-09T09:24:31.997767396Z", "paused":false,"status":"READY", - "resources":[{"id":"101240", - "spec":{"cpu_millis":1000,"memory_gbs":4,"volume_type":""}}], - "metadata":{"environment":"PROD"}, - "endpoint":{"host":"oh.yeah.tsdb.cloud.timescale.com","port":123435}, - "initial_password":"very-secret", - "ha_replicas":{"sync_replica_count":0,"replica_count":1} - } + {"service_id":"tgrservice","project_id":"tgrproject","name":"my-first-service", + "region_code":"us-east-1","service_type":"TIMESCALEDB", + "created":"2025-10-20T22:29:33.052075713Z","paused":false,"status":"QUEUED", + "resources":[{"id":"105120","spec":{"cpu_millis":1000,"memory_gbs":4,"volume_type":""}}], + "metadata":{"environment":"PROD"}, + "endpoint":{"host":"tgrservice.tgrproject.tsdb.cloud.timescale.com","port":00001}, + "initial_password":"notTellingYou", + "ha_replicas":{"sync_replica_count":0,"replica_count":1}} ``` -1. **Save `service_id` from the response to a variable** +1. Save `service_id` from the response to a variable: + ```bash # Extract service_id from the JSON response export SERVICE_ID="service_id-from-response" @@ -118,13 +116,15 @@ Create a new $SERVICE_SHORT using the $REST_LONG: -u "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" \ -H "Content-Type: application/json" ``` - You see something like: +You see something like: ```terminaloutput - {"service_id":"tgrservice","project_id":"tgrproject","name":"my-first-service","region_code":"us-east-1", - "service_type":"TIMESCALEDB","created":"2025-09-30T12:08:54.438785Z","paused":false,"status":"READY", - "resources":[{"id":"102879","spec":{"cpu_millis":1000,"memory_gbs":4,"volume_type":""}}], - "metadata":{"environment":"DEV"},"endpoint":{"host":"ohhhh.yeahhhhh.tsdb.cloud.timescale.com","port":33867}, - "ha_replicas":{"sync_replica_count":0,"replica_count":1}} + {"service_id":"tgrservice","project_id":"tgrproject","name":"my-first-service", + "region_code":"us-east-1","service_type":"TIMESCALEDB", + "created":"2025-10-20T22:29:33.052075Z","paused":false,"status":"READY", + "resources":[{"id":"105120","spec":{"cpu_millis":1000,"memory_gbs":4,"volume_type":""}}], + "metadata":{"environment":"DEV"}, + "endpoint":{"host":"tgrservice.tgrproject.tsdb.cloud.timescale.com","port":11111}, + "ha_replicas":{"sync_replica_count":0,"replica_count":1}} ``` @@ -150,6 +150,7 @@ Follow these security guidelines when working with the $REST_LONG: - Implement proper backup and recovery procedures for created services - Follow data residency requirements for your region + [rest-api-reference]: /api/:currentVersion:/api-reference/ [rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings [get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id diff --git a/ai/index.md b/ai/index.md index 0f57113529..df59104433 100644 --- a/ai/index.md +++ b/ai/index.md @@ -1,51 +1,83 @@ --- -title: Power your AI apps with Postgres -excerpt: TigerData pgai is a solution for building search, RAG, and AI agents with Postgres. Learn more about pgai and how to use it +title: Integrate AI with Tiger Data +excerpt: Build AI assistants with Tiger Data using pgvector, Tiger Eon, Tiger Agents, and MCP server for seamless data integration products: [cloud, mst, self_hosted] -keywords: [ai, vector, pgvector, pgvectorscale, pgai] -tags: [ai, vector] +keywords: [ai, vector, pgvector, pgvectorscale, pgai, tiger-eon, tiger-agents, mcp-server] +tags: [ai, vector, agents, assistants] --- +# Integrate AI with Tiger Data -# Power your AI apps with pgai on $CLOUD_LONG +You can build and deploy AI assistants that understand, analyze, and act on your organizational data using +$COMPANY. Whether you're building semantic search applications, recommendation systems, or intelligent agents +that answer complex business questions, $COMPANY provides the tools and infrastructure you need. -pgai on $CLOUD_LONG is a cloud solution for building search, RAG, and AI agents with $PG. This suite of tools empowers you to deploy production AI applications with $PG as your vector database, storing both vector embeddings, relational data (for example, related metadata), and time-based data in the same database. +$COMPANY's AI ecosystem combines $PG with advanced vector capabilities, intelligent agents, and seamless +integrations. Your AI assistants can: - +- Access organizational knowledge from Slack, GitHub, Linear, and other data sources +- Understand context using advanced vector search and embeddings across large datasets +- Execute tasks, generate reports, and interact with your $SERVICE_LONGs through natural language +- Scale reliably with enterprise-grade performance for concurrent conversations -pgai on $CLOUD_LONG is comprised of three extensions: pgvector, pgvectorscale and pgai. pgvector provides the vector data type and HNSW search index. Pgvectorscale provides the StreamingDiskANN index to superpower embedding search and make vector queries performant. pgai allows you to easily call AI embedding and generation models from inside the database. All three extensions are installed in your $CLOUD_LONG instance by default. +## $EON_LONG for complete organizational AI + +[$EON_LONG](/ai/:currentVersion:/tiger-eon/) automatically integrates $AGENTS_LONG with your organizational +data. You can: + +- Get instant access to company knowledge from Slack, GitHub, and Linear +- Process data in real-time as conversations and updates happen +- Store data efficiently with time-series partitioning and compression +- Deploy quickly with Docker and an interactive setup wizard + +Use $EON_SHORT when you want to unlock knowledge from your communication and development tools. + +## $AGENTS_LONG for enterprise Slack AI + +[$AGENTS_LONG](/ai/:currentVersion:/tiger-agents-for-work/) provides enterprise-grade Slack-native AI agents. +You get: + +- Durable event handling with $PG-backed processing +- Horizontal scalability across multiple $AGENTS_SHORT instances +- Flexibility to choose AI models and customize prompts +- Integration with specialized data sources through MCP servers +- Complete observability and monitoring with Logfire + +Use $AGENTS_SHORT when you need reliable, customizable AI agents for high-volume conversations. + +## $MCP_SHORT for direct AI Assistant integration + +The [$MCP_LONG](/ai/:currentVersion:/mcp-server/) integrates directly with popular AI Assistants. You can: + +- Work with Claude Code, Cursor, VS Code, and other editors +- Manage $SERVICE_SHORTs and optimize queries through natural language +- Access comprehensive $COMPANY documentation during development +- Use secure authentication and access control + +Use the $MCP_SHORT when you want to manage $COMPANY resources from your AI assistant. - -## pgvectorscale ❀️ pgvector +## pgvectorscale and️ pgvector + [Pgvector](https://github.com/pgvector/pgvector) is a popular open source extension for vector storage and similarity search in $PG and [pgvectorscale](https://github.com/timescale/pgvectorscale) adds advanced indexing capabilities to pgvector. pgai on $CLOUD_LONG offers both extensions so you can use all the capabilities already available in pgvector (like HNSW and ivfflat indexes) and also make use of the StreamingDiskANN index in pgvectorscale to speed up vector search. This makes it easy to migrate your existing pgvector deployment and take advantage of the additional performance features in pgvectorscale. You also have the flexibility to create different index types suited to your needs. See the [vector search indexing][vector-search-indexing] section for more information. -## What are vector embeddings? Embeddings offer a way to represent the semantic essence of data and to allow comparing data according to how closely related it is in terms of meaning. In the database context, this is extremely powerful: think of this as full-text search on steroids. Vector databases allow storing embeddings associated with data and then searching for embeddings that are similar to a given query. -## Applications of vector embeddings - -There are many applications where vector embeddings can be useful. - -### Semantic search -Transcend the limitations of traditional keyword-driven search methods by creating systems that understand the intent and contextual meaning of a query, thereby returning more relevant results. Semantic search doesn't just seek exact word matches; it grasps the deeper intent behind a user's query. The result? Even if search terms differ in phrasing, relevant results are surfaced. Taking advantage of hybrid search, which marries lexical and semantic search methodologies, offers users a search experience that's both rich and accurate. It's not just about finding direct matches anymore; it's about tapping into contextually and conceptually similar content to meet user needs. +- Semantic search: transcend the limitations of traditional keyword-driven search methods by creating systems that understand the intent and contextual meaning of a query, thereby returning more relevant results. Semantic search doesn't just seek exact word matches; it grasps the deeper intent behind a user's query. The result? Even if search terms differ in phrasing, relevant results are surfaced. Taking advantage of hybrid search, which marries lexical and semantic search methodologies, offers users a search experience that's both rich and accurate. It's not just about finding direct matches anymore; it's about tapping into contextually and conceptually similar content to meet user needs. -### Recommendation systems -Imagine a user who has shown interest in several articles on a singular topic. With embeddings, the recommendation engine can delve deep into the semantic essence of those articles, surfacing other database items that resonate with the same theme. Recommendations, thus, move beyond just the superficial layers like tags or categories and dive into the very heart of the content. +- Recommendation systems: imagine a user who has shown interest in several articles on a singular topic. With embeddings, the recommendation engine can delve deep into the semantic essence of those articles, surfacing other database items that resonate with the same theme. Recommendations, thus, move beyond just the superficial layers like tags or categories and dive into the very heart of the content. -### Retrieval augmented generation (RAG) -Supercharge generative AI by providing additional context to Large Language Models (LLMs) like OpenAI's GPT-4, Anthropic's Claude 2, and open source modes like Llama 2. When a user poses a query, relevant database content is fetched and used to supplement the query as additional information for the LLM. This helps reduce LLM hallucinations, as it ensures the model's output is more grounded in specific and relevant information, even if it wasn't part of the model's original training data. +- Retrieval augmented generation (RAG): supercharge generative AI by providing additional context to Large Language Models (LLMs) like OpenAI's GPT-4, Anthropic's Claude 2, and open source modes like Llama 2. When a user poses a query, relevant database content is fetched and used to supplement the query as additional information for the LLM. This helps reduce LLM hallucinations, as it ensures the model's output is more grounded in specific and relevant information, even if it wasn't part of the model's original training data. -### Clustering -Embeddings also offer a robust solution for clustering data. Transforming data into these vectorized forms allows for nuanced comparisons between data points in a high-dimensional space. Through algorithms like K-means or hierarchical clustering, data can be categorized into semantic categories, offering insights that surface-level attributes might miss. This surfaces inherent data patterns, enriching both exploration and decision-making processes. +- Clustering: embeddings also offer a robust solution for clustering data. Transforming data into these vectorized forms allows for nuanced comparisons between data points in a high-dimensional space. Through algorithms like K-means or hierarchical clustering, data can be categorized into semantic categories, offering insights that surface-level attributes might miss. This surfaces inherent data patterns, enriching both exploration and decision-making processes. -## Vector similarity search: How does it work +### Vector similarity search: How does it work On a high level, embeddings help a database to look for data that is similar to a given piece of information (similarity search). This process includes a few steps: @@ -56,7 +88,7 @@ On a high level, embeddings help a database to look for data that is similar to Under the hood, embeddings are represented as a vector (a list of numbers) that capture the essence of the data. To determine the similarity of two pieces of data, the database uses mathematical operations on vectors to get a distance measure (commonly Euclidean or cosine distance). During a search, the database should return those stored items where the distance between the query embedding and the stored embedding is as small as possible, suggesting the items are most similar. -## Embedding models +### Embedding models pgai on $CLOUD_LONG works with the most popular embedding models that have output vectors of 2,000 dimensions or less.: diff --git a/ai/mcp-server.md b/ai/mcp-server.md new file mode 100644 index 0000000000..13228c8f33 --- /dev/null +++ b/ai/mcp-server.md @@ -0,0 +1,233 @@ +--- +title: Integrate Tiger Cloud with your AI Assistant +excerpt: Manage your services and optimize your schema and queries using your AI Assistant +products: [cloud, self_hosted] +keywords: [ai, mcp, server, security] +tags: [ai] +--- + +import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; +import CLIINSTALL from "versionContent/_partials/_devops-cli-install.mdx"; +import MCPCOMMANDS from "versionContent/_partials/_devops-mcp-commands.mdx"; +import MCPCOMMANDSCLI from "versionContent/_partials/_devops-mcp-commands-cli.mdx"; +import GLOBALFLAGS from "versionContent/_partials/_devops-cli-global-flags.mdx"; + + +# Integrate Tiger Cloud with your AI Assistant + +The $MCP_LONG provides access to your $CLOUD_LONG resources through Claude and other AI Assistants. $MCP_SHORT +mirrors the functionality of $CLI_LONG and is integrated directly into the $CLI_SHORT binary. You manage your +$CLOUD_LONG resources using natural language from your AI Assistant. As $MCP_SHORT is integrated with the +$COMPANY documentation, ask any question and you will get the best answer. + +This page shows you how to install $CLI_LONG and set up secure authentication for $MCP_SHORT, then manage the +resources in your $ACCOUNT_LONG through the $MCP_LONG using your AI Assistant. + +## Prerequisites + + + +* An AI Assistant installed on your developer device with an active API key + + The following AI Assistants are automatically configured by the $MCP_LONG: `claude-code`, `cursor`, `windsurf`, `codex`, `gemini/gemini-cli`, `vscode/code/vs-code` + You can also [manually configure][manual-config] $MCP_SHORT. + +## Install and configure $MCP_SHORT + +The $MCP_SHORT is bundled with $CLI_LONG: + + + + + +1. **Configure your AI Assistant to interact with the $PROJECT_SHORT and $SERVICE_SHORTs in your $ACCOUNT_LONG** + + For example: + ```shell + tiger mcp install + ``` + +1. **Choose the client to integrate with, then press `Enter` ** + + ```shell + Select an MCP client to configure: + + > 1. Claude Code + 2. Codex + 3. Cursor + 4. Gemini CLI + 5. VS Code + 6. Windsurf + + Use ↑/↓ arrows or number keys to navigate, enter to select, q to quit + ``` + + + +And that is it, you are ready to use the $MCP_LONG to manage your $SERVICE_SHORTs in $CLOUD_LONG. + +## Manage the resources in your $ACCOUNT_LONG through your AI Assistant + +Your AI Assistant is connected to your $ACCOUNT_LONG and the $COMPANY documentation, you can now use it to +manage your $SERVICE_SHORTs and learn more about how to implement $CLOUD_LONG features. For example: + + + +1. **Run your AI Assistant** + ```shell + claude + ``` + Claude automatically runs the $MCP_SHORT server that enables you to interact with $CLOUD_LONG from your + AI Assistant. + +1. **Check your $MCP_LONG configuration** + ```shell + > is the tigerdata mcp server active for you? + ``` + You see something like: + ```shell + MCP server is active. I can see the following Tiger Data-related tools available: + + - mcp__tiger__get_guide - Retrieve TimescaleDB guides and best practices + - mcp__tiger__semantic_search_postgres_docs - Search PostgreSQL documentation + - mcp__tiger__semantic_search_tiger_docs - Search Tiger Cloud and TimescaleDB documentation + - mcp__tiger__tiger_service_create - Create new database services + - mcp__tiger__tiger_service_list - List all database services + - mcp__tiger__tiger_service_show - Show detailed service information + - mcp__tiger__tiger_service_update_password - Update service passwords + + Is there something specific you'd like to do with the Tiger Data MCP server? + ``` + +1. **Ask a basic question about your $SERVICE_SHORTs** + ```shell + > can you list my active services please + ``` + You see something like: + ```shell + ⏺ You have 3 active services, all with the same name "my-first-service": + + 1. tgrservice1 - READY - TimescaleDB - us-east-1 - 1 CPU/4GB - Created: 2025-09-30 + 2. tgrservice1 - READY - TimescaleDB - us-east-1 - 1 CPU/4GB - Created: 2025-09-30 + 3. tgrservice1 - READY - TimescaleDB - us-east-1 - 1 CPU/4GB - Created: 2025-09-30 + ``` + +1. **Manage your $SERVICE_SHORTs without having to learn how to** + + For example: + ```shell + Can you create a new ai service called bob with a replica for me please + ``` + You see something like: + ```shell + tiger - Create Database Service (MCP)(name: "bob", addons: ["ai"], replicas: 1, wait: false) + ``` + +1. **Find best practice for things you need to do** + + For example: + ```shell + > I need to migrate a database with 25 million rows of data to Tiger Cloud, + please tell me what service optimizations i should do before migration. + + ``` + + You see something like: + + ```shell + ⏺ For migrating a database with 25 million rows to Tiger Cloud, here are the key service optimizations to do before migration: + + Pre-Migration Service Optimizations + + 1. Right-size your compute resources: + - For 25M rows, start with at least 2 CPU/8GB or 4 CPU/16GB + - You can scale up during migration if needed, then scale down after + + 2. Enable the appropriate addons: + - Use time-series addon if you are working with time-series data + - Use ai addon if you need vector/AI capabilities + + 3. Choose optimal region: + - Select the region closest to your current database to minimize network transfer time + - This significantly reduces migration duration + + 4. Consider enhanced storage (Enterprise only): + - If you expect high write throughput during migration, enhanced storage provides better IOPS (up to 32,000) + + 5. Skip replicas initially: + - Start with 0 replicas during migration + - Add replicas after migration completes to avoid duplicate data copying + + 6. Plan for storage space: + - Estimate your uncompressed data size + - Allocate sufficient high-performance storage (scales automatically but good to plan) + - You can enable tiered storage later for older data + + During Migration Best Practices + + Migration method selection: + - 25M rows: Use schema-then-data migration (migrate schema first, then copy data in chunks) + - Allows restart if a copy operation fails + - Better for databases >10GB + + Database configuration to set AFTER migration: + - Set up compression policies (once data is loaded) + - Configure retention policies + - Create continuous aggregates + - Enable tiered storage for cost optimization + + Connection settings: + - Use the pooled connection endpoint for better performance during bulk inserts + - Disable unnecessary constraints/indexes during migration, re-enable after + + Would you like me to help you create an optimized service for this migration? + ``` + + + +That beats working. Let the $MCP_SHORT do it all for you. + +## Manually configure the $MCP_SHORT + +If your MCP client is not supported by `tiger mcp install`. follow the client's instructions to install +MCP servers. For example, many clients use a JSON file like the following that use `tiger mcp start` to +start $MCP_LONG: + +```json +{ + "mcpServers": { + "tiger": { + "command": "tiger", + "args": [ + "mcp", + "start" + ] + } + } +} +``` + +## $MCP_LONG commands + + + +## $CLI_LONG commands for $MCP_SHORT + + + +## Global flags + +You can use the following $CLI_LONG global flags when you run the $MCP_SHORT: + + + + +[rest-api-reference]: /api/:currentVersion:/api-reference/ +[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings +[get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id +[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials +[curl]: https://curl.se/ +[cloud-regions]: /use-timescale/:currentVersion:/regions/ +[readreplica]: /use-timescale/:currentVersion:/ha-replicas/read-scaling/ +[manual-config]: /ai/:currentVersion:/mcp-server/#manually-configure-the-tiger-mcp-server + \ No newline at end of file diff --git a/ai/page-index/page-index.js b/ai/page-index/page-index.js index 4bc352130d..b3735bbc4d 100644 --- a/ai/page-index/page-index.js +++ b/ai/page-index/page-index.js @@ -1,13 +1,18 @@ module.exports = [ { - title: "AI and Vector", + title: "Integrate AI with Tiger Data", href: "ai", filePath: "index.md", pageComponents: ["featured-cards"], excerpt: - "Information about pgai on TigerData and how to use it.", + "Integrate AI with your Tiger Data products", children: [ { + title: "Integrate Tiger Cloud with your AI Assistant", + href: "mcp-server", + excerpt: "Manage your services and optimize your schema and queries with your AI Assistant", + }, + { title: "Aggregate organizational data with AI agents", href: "tiger-eon", excerpt: "Unify company knowledge with slack-native AI agents", diff --git a/api/api-reference.md b/api/api-reference.md index d682b84a4d..de6baf5b27 100644 --- a/api/api-reference.md +++ b/api/api-reference.md @@ -32,12 +32,14 @@ curl -X GET "https://console.cloud.timescale.com/public/api/v1/projects/{project ## Service Management -You use this endpoint to create and manage the following Tiger Postgres services: +You use this endpoint to create a Tiger Cloud service with one of more of the following addons: -- `TIMESCALEDB`: a Tiger Postgres instance optimized for real-time analytics service For time-stamped data like events, - prices, metrics, sensor readings, or any information that changes over time -- `POSTGRES`: a vanilla Postgres instance -- `VECTOR`: a Tiger Postgres instance with vector extensions +- `time-series`: a Tiger Cloud service optimized for real-time analytics. For time-stamped data like events, + prices, metrics, sensor readings, or any information that changes over time. +- `ai`: a Tiger Cloud service instance with vector extensions. + +To have multiple addons when you create a new service, set `"addons": ["time-series", "ai"]`. To create a +vanilla Postgres instance, set `addons` to an empty list `[]`. ### List All Services @@ -83,13 +85,13 @@ Retrieve all services within a project. POST /projects/{project_id}/services ``` -Create a new Tiger Postgres service. This is an asynchronous operation. +Create a new Tiger Cloud service. This is an asynchronous operation. **Request Body:** ```json { "name": "test-2", - "service_type": "TIMESCALEDB", + "addons": ["time-series"], "region_code": "eu-central-1", "cpu_millis": 1000, "memory_gbs": 4 @@ -129,10 +131,10 @@ Create a new Tiger Postgres service. This is an asynchronous operation. ``` **Service Types:** -- `TIMESCALEDB`: a Tiger Postgres instance optimized for real-time analytics service For time-stamped data like events, +- `TIMESCALEDB`: a Tiger Cloud service instance optimized for real-time analytics service For time-stamped data like events, prices, metrics, sensor readings, or any information that changes over time - `POSTGRES`: a vanilla Postgres instance -- `VECTOR`: a Tiger Postgres instance with vector extensions +- `VECTOR`: a Tiger Cloud service instance with vector extensions ### Get a Service @@ -304,6 +306,7 @@ Deactivate the connection pooler for a service. { "message": "Connection pooler disabled successfully" } +``` ### Fork a Service diff --git a/api/glossary.md b/api/glossary.md index e3c3be4d29..1faadb53f1 100644 --- a/api/glossary.md +++ b/api/glossary.md @@ -163,6 +163,8 @@ This glossary defines technical terms, concepts, and terminology used in $COMPAN **Euclidean distance**: a measure of the straight-line distance between two points in multidimensional space. +**Exactly-once**: a message is delivered and processed precisely once. There is no loss and no duplicates. + **Explain**: a $PG command that shows the execution plan for a query, useful for performance analysis. **Event sourcing**: an architectural pattern storing all changes as a sequence of events, naturally fitting time-series database capabilities. diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index 1258de6b64..33e82b78a9 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -13,28 +13,25 @@ tags: - authentication --- - import RESTGS from "versionContent/_partials/_devops-rest-api-get-started.mdx"; import CLIGS from "versionContent/_partials/_devops-cli-get-started.mdx"; - # DevOps as code with $CLOUD_LONG -$COMPANY supplies a clean, programmatic control layer for $CLOUD_LONG. This includes RESTful APIs, $CLI commands, and -MCP commands that let humans, machines, and AI agents easily provision, configure, and manage $SERVICE_LONGs -programmatically. +$COMPANY supplies a clean, programmatic control layer for $CLOUD_LONG. This includes RESTful APIs and CLI commands +that enable humans, machines, and AI agents easily provision, configure, and manage $SERVICE_LONG programmatically. - + - + - + - + diff --git a/integrations/find-connection-details.md b/integrations/find-connection-details.md index 1dca134090..95953aef44 100644 --- a/integrations/find-connection-details.md +++ b/integrations/find-connection-details.md @@ -37,7 +37,7 @@ Retrieve the connection details for your $SERVICE_LONG: ## Find your project and service ID -To retrieve the connection details for your $CLOUD_LONG project and $SERVICE_LONG: +To retrieve the connection details for your $PROJECT_LONG and $SERVICE_LONG: @@ -78,6 +78,31 @@ such as Terraform or the [$CLOUD_LONG REST API][rest-api-reference]: +## Create client credentials + +You use client credentials to obtain access tokens outside of the user context. + +To retrieve the connection details for your $CLOUD_LONG project for programmatic usage +such as Terraform or the [$CLOUD_LONG REST API][rest-api-reference]: + + + +1. **Open the settings for your project**: + + In [$CONSOLE][console-services], click your project name in the upper left corner, then click `Project settings`. + +1. **Create client credentials**: + + 1. Click `Create credentials`, then copy `Public key` and `Secret key` locally. + + ![Create client credentials in $CONSOLE](https://assets.timescale.com/docs/images/tiger-cloud-console/tiger-cloud-console-client-credentials.png) + + This is the only time you see the `Secret key`. After this, only the `Public key` is visible in this page. + + 1. Click `Done`. + + + From 10a37f87e12fed5b6200fea7e707ffff278d8bb2 Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Tue, 21 Oct 2025 11:45:53 +0200 Subject: [PATCH 4/4] 427 docs rfc add docs about forking services (#4490) forking --- _partials/_devops-cli-service-forks.md | 61 ++++++ _partials/_manage-a-data-exporter.md | 2 +- _partials/_prometheus-integrate.md | 2 +- about/changelog.md | 2 +- about/pricing-and-account-management.md | 2 +- ai/index.md | 4 +- getting-started/page-index/page-index.js | 2 +- integrations/cloudwatch.md | 2 +- integrations/datadog.md | 2 +- use-timescale/backup-restore.md | 29 ++- .../configuration/customize-configuration.md | 2 +- use-timescale/fork-services.md | 184 ++++++++++++++++++ .../metrics-logging/aws-cloudwatch.md | 2 +- use-timescale/metrics-logging/datadog.md | 2 +- use-timescale/page-index/page-index.js | 6 +- use-timescale/security/overview.md | 2 +- use-timescale/services/service-management.md | 15 +- 17 files changed, 294 insertions(+), 27 deletions(-) create mode 100644 _partials/_devops-cli-service-forks.md create mode 100644 use-timescale/fork-services.md diff --git a/_partials/_devops-cli-service-forks.md b/_partials/_devops-cli-service-forks.md new file mode 100644 index 0000000000..88708ebc17 --- /dev/null +++ b/_partials/_devops-cli-service-forks.md @@ -0,0 +1,61 @@ +import CLIINSTALL from "versionContent/_partials/_devops-cli-install.mdx"; + +To manage development forks: + + + + + +1. **Fork the $SERVICE_SHORT** + + ```shell + tiger service fork tgrservice --now --no-wait --name bob + ``` + By default a fork matches the resource of the parent $SERVICE_LONGs. For paid plans specify `--cpu` and/or `--memory` for dedicated resources. + + You see something like: + + ```terminaloutput + 🍴 Forking service 'tgrservice' to create 'bob' at current state... + βœ… Fork request accepted! + πŸ“‹ New Service ID: + πŸ” Password saved to system keyring for automatic authentication + 🎯 Set service '' as default service. + ⏳ Service is being forked. Use 'tiger service list' to check status. + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ PROPERTY β”‚ VALUE β”‚ + β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ + β”‚ Service ID β”‚ β”‚ + β”‚ Name β”‚ bob β”‚ + β”‚ Status β”‚ β”‚ + β”‚ Type β”‚ TIMESCALEDB β”‚ + β”‚ Region β”‚ eu-central-1 β”‚ + β”‚ CPU β”‚ 0.5 cores (500m) β”‚ + β”‚ Memory β”‚ 2 GB β”‚ + β”‚ Direct Endpoint β”‚ ..tsdb.cloud.timescale.com: β”‚ + β”‚ Created β”‚ 2025-10-08 13:58:07 UTC β”‚ + β”‚ Connection String β”‚ postgresql://tsdbadmin@..tsdb.cloud.timescale.com:/tsdb?sslmode=require β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ``` + +1. **When you are done, delete your forked $SERVICE_SHORT** + + 1. Use the CLI to request $SERVICE_SHORT delete: + + ```shell + tiger service delete + ``` + 1. Validate the $SERVICE_SHORT delete: + + ```terminaloutput + Are you sure you want to delete service ''? This operation cannot be undone. + Type the service ID '' to confirm: + + ``` + You see something like: + ```terminaloutput + πŸ—‘οΈ Delete request accepted for service ''. + βœ… Service '' has been successfully deleted. + ``` + + \ No newline at end of file diff --git a/_partials/_manage-a-data-exporter.md b/_partials/_manage-a-data-exporter.md index 96d7cc4641..de90b1d41c 100644 --- a/_partials/_manage-a-data-exporter.md +++ b/_partials/_manage-a-data-exporter.md @@ -109,4 +109,4 @@ It must be one of the following: [console-cloudwatch-configuration]: https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups [console-cloudwatch-create-group]: https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups/create-log-group [services-portal]: https://console.cloud.timescale.com/dashboard/services -[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-plan +[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-pricing-plan diff --git a/_partials/_prometheus-integrate.md b/_partials/_prometheus-integrate.md index 62307cdb28..f8ded461d2 100644 --- a/_partials/_prometheus-integrate.md +++ b/_partials/_prometheus-integrate.md @@ -209,4 +209,4 @@ You can further [visualize your data][grafana-prometheus] with Grafana. Use the [enable-timescaledb]: /self-hosted/:currentVersion:/install/ [prometheus-authentication]: https://prometheus.io/docs/guides/basic-auth/ [scrape-targets]: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config -[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-plan +[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-pricing-plan diff --git a/about/changelog.md b/about/changelog.md index 9c27be4557..7f2b229558 100644 --- a/about/changelog.md +++ b/about/changelog.md @@ -919,7 +919,7 @@ Highlighted features in TimescaleDB v2.17 are: ### HIPAA compliance -Timescale Cloud's [Enterprise plan](https://docs.timescale.com/about/latest/pricing-and-account-management/#features-included-in-each-plan) is now HIPAA (Health Insurance Portability and Accountability Act) compliant. This allows organizations to securely manage and analyze sensitive healthcare data, ensuring they meet regulatory requirements while building compliant applications. +Timescale Cloud's [Enterprise plan](https://docs.timescale.com/about/latest/pricing-and-account-management/#features-included-in-each-pricing-plan) is now HIPAA (Health Insurance Portability and Accountability Act) compliant. This allows organizations to securely manage and analyze sensitive healthcare data, ensuring they meet regulatory requirements while building compliant applications. ### Expanded logging within Timescale Console diff --git a/about/pricing-and-account-management.md b/about/pricing-and-account-management.md index 0ba87ada6b..42e9b38d5b 100644 --- a/about/pricing-and-account-management.md +++ b/about/pricing-and-account-management.md @@ -224,7 +224,7 @@ When you get $CLOUD_LONG at AWS Marketplace, the following pricing options are a [cloud-billing]: https://console.cloud.timescale.com/dashboard/billing/details [commercial-sla]: https://www.timescale.com/legal/timescale-cloud-terms-of-service [pricing-plans]: https://www.timescale.com/pricing -[plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-plan +[plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-pricing-plan [production-support]: https://www.timescale.com/support [hipaa-compliance]: https://www.hhs.gov/hipaa/for-professionals/index.html [aws-pricing]: /about/:currentVersion:/pricing-and-account-management/#aws-marketplace-pricing diff --git a/ai/index.md b/ai/index.md index df59104433..9fa6044fcf 100644 --- a/ai/index.md +++ b/ai/index.md @@ -1,6 +1,6 @@ --- title: Integrate AI with Tiger Data -excerpt: Build AI assistants with Tiger Data using pgvector, Tiger Eon, Tiger Agents, and MCP server for seamless data integration +excerpt: Build AI Assistants with Tiger Data using pgvector, Tiger Eon, Tiger Agents, and MCP server for seamless data integration products: [cloud, mst, self_hosted] keywords: [ai, vector, pgvector, pgvectorscale, pgai, tiger-eon, tiger-agents, mcp-server] tags: [ai, vector, agents, assistants] @@ -54,7 +54,7 @@ The [$MCP_LONG](/ai/:currentVersion:/mcp-server/) integrates directly with popul - Access comprehensive $COMPANY documentation during development - Use secure authentication and access control -Use the $MCP_SHORT when you want to manage $COMPANY resources from your AI assistant. +Use the $MCP_SHORT when you want to manage $COMPANY resources from your AI Assistant. diff --git a/getting-started/page-index/page-index.js b/getting-started/page-index/page-index.js index d33b812fad..459e52ec0e 100644 --- a/getting-started/page-index/page-index.js +++ b/getting-started/page-index/page-index.js @@ -23,7 +23,7 @@ module.exports = [ excerpt: "Create a Tiger service and connect to it", }, { - title: "DevOps as code with Tiger", + title: "DevOps as code with Tiger Cloud", href: "get-started-devops-as-code", excerpt: "Set up secure authentication for the Tiger REST API and create your first service", }, diff --git a/integrations/cloudwatch.md b/integrations/cloudwatch.md index 9901a0a9a1..5872b81e60 100644 --- a/integrations/cloudwatch.md +++ b/integrations/cloudwatch.md @@ -34,7 +34,7 @@ tool. You create an exporter on the [project level][projects], in the same AWS r [projects]: /use-timescale/:currentVersion:/security/members/ -[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-plan +[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-pricing-plan [cloudwatch]: https://aws.amazon.com/cloudwatch/ [cloudwatch-signup]: https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/GettingSetup.html diff --git a/integrations/datadog.md b/integrations/datadog.md index 7cad45fca8..060690d0eb 100644 --- a/integrations/datadog.md +++ b/integrations/datadog.md @@ -143,7 +143,7 @@ comprehensive list of [metrics][datadog-postgres-metrics] collected. [datadog-agent-restart]: https://docs.datadoghq.com/agent/configuration/agent-commands/#start-stop-and-restart-the-agent [projects]: /use-timescale/:currentVersion:/security/members/ [datadog-api-key]: https://docs.datadoghq.com/account_management/api-app-keys/#add-an-api-key-or-client-token -[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-plan +[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-pricing-plan [run-queries]: /getting-started/:currentVersion:/run-queries-from-console/ [open-console]: https://console.cloud.timescale.com/dashboard/services [psql]: /integrations/:currentVersion:/psql/ diff --git a/use-timescale/backup-restore.md b/use-timescale/backup-restore.md index 4c81a15a70..92a7cba99a 100644 --- a/use-timescale/backup-restore.md +++ b/use-timescale/backup-restore.md @@ -1,24 +1,31 @@ --- -title: Back up and recover your Tiger services -excerpt: See how and when Tiger backs up your data, making sure you always have something to fall back on in case of disaster recovery +title: Back up and recover services +excerpt: Tiger Cloud backs up your data, making sure you always have something to fall back on for disaster recovery products: [cloud] keywords: [backups, restore] tags: [recovery, failures] --- -# Back up and recover your $SERVICE_SHORTs +import CLIFORKS from "versionContent/_partials/_devops-cli-service-forks.mdx"; -$CLOUD_LONG automatically handles backup for your $SERVICE_LONGs using the `pgBackRest` tool. You don't need to perform backups manually. What's more, with [cross-region backup][cross-region], you are protected when an entire AWS region goes down. +# Back up and recover $SERVICE_SHORTs -$CLOUD_LONG automatically creates one full backup every week, and -incremental backups every day in the same region as your $SERVICE_SHORT. +$CLOUD_LONG provides comprehensive backup and recovery solutions to protect your data, including automatic daily backups, +cross-region protection, and point-in-time recovery. -On [$SCALE and $PERFORMANCE][pricing-and-account-management] $PRICING_PLANs, you can check the list of backups for the previous 14 days in $CONSOLE_LONG. To do so, select your $SERVICE_SHORT, then click `Operations` > `Backup and restore` > `Backup history`. +## Automatic backups + +$CLOUD_LONG automatically handles backup for your $SERVICE_LONGs using the `pgBackRest` tool. You don't need to perform +backups manually. What's more, with [cross-region backup][cross-region], you are protected when an entire AWS region goes down. -Additionally, all [Write-Ahead Log (WAL)][wal] files are retained back to the oldest full backup. This means that you always have a full backup available for the current and previous week: +$CLOUD_LONG automatically creates one full backup every week, and incremental backups every day in the same region as +your $SERVICE_SHORT. Additionally, all [Write-Ahead Log (WAL)][wal] files are retained back to the oldest full backup. +This means that you always have a full backup available for the current and previous week: ![Backup in Tiger](https://assets.timescale.com/docs/images/database-backup-recovery.png) +On [$SCALE and $PERFORMANCE][pricing-and-account-management] $PRICING_PLANs, you can check the list of backups for the previous 14 days in $CONSOLE_LONG. To do so, select your $SERVICE_SHORT, then click `Operations` > `Backup and restore` > `Backup history`. + In the event of a storage failure, a $SERVICE_SHORT automatically recovers from a backup to the point of failure. If the whole availability zone goes down, your $SERVICE_LONGs are recovered in a different zone. In the event of a user error, you can [create a point-in-time recovery fork][create-fork]. @@ -101,6 +108,7 @@ You initiate a point-in-time recovery from a same-region or cross-region backup 1. Confirm by clicking `Create recovery fork`. A fork of the $SERVICE_SHORT is created. The recovered $SERVICE_SHORT shows in `Services` with a label specifying which $SERVICE_SHORT it has been forked from. + 1. Update the connection strings in your app Since the point-in-time recovery is done in a fork, to migrate your @@ -120,6 +128,11 @@ You initiate a point-in-time recovery from a same-region or cross-region backup +## Create a service fork + + + + [console]: https://console.cloud.timescale.com/dashboard/services [ha-replicas]: /about/use-timescale/:currentVersion:/ha-replicas/ [pricing-and-account-management]: /about/:currentVersion:/pricing-and-account-management/ diff --git a/use-timescale/configuration/customize-configuration.md b/use-timescale/configuration/customize-configuration.md index 4b1644c95e..1ba8aca724 100644 --- a/use-timescale/configuration/customize-configuration.md +++ b/use-timescale/configuration/customize-configuration.md @@ -62,4 +62,4 @@ width={1375} height={944} src="https://assets.timescale.com/docs/images/tsc-settings-confirm.webp" alt="Confirm Tiger configuration changes"/> -[plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-plan \ No newline at end of file +[plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-pricing-plan \ No newline at end of file diff --git a/use-timescale/fork-services.md b/use-timescale/fork-services.md new file mode 100644 index 0000000000..d235281abd --- /dev/null +++ b/use-timescale/fork-services.md @@ -0,0 +1,184 @@ +--- +title: Fork services +excerpt: With developer forks, spin up a branch, run your test, throw it away, or merge it back. +products: [cloud] +price_plans: [performance, scale, enterprise] +keywords: [backups, restore] +tags: [recovery, failures] +--- + +import IntegrationPrereqs from "versionContent/_partials/_integration-prereqs.mdx"; +import CLIFORKS from "versionContent/_partials/_devops-cli-service-forks.mdx"; + +# Fork $SERVICE_SHORTs + +Modern development is highly iterative. Developers and AI agents need safe spaces to test changes before deploying them +to production. Forkable $SERVICE_SHORTs make this natural and easy. Spin up a branch, run your test, throw it away, or +merge it back. + +A fork is an exact copy of a $SERVICE_SHORT at a specific point in time, with its own independent data and configuration, +including: +- The database data and schema +- Configuration +- An admin `tsdbadmin` user with a new password + +Forks are fully independent. Changes to the fork don't affect the parent $SERVICE_SHORT. You can query +them, run migrations, add indexes, or test new features against the fork without affecting the original service. + +Forks are a powerful way to share production-scale data safely. Testing, BI and data science teams often need access +to real datasets to build models or generate insights. With forkable $SERVICE_SHORTs, you easily create fast, zero-copy +branches of a production $SERVICE_SHORT that are isolated from production, but contain all the data needed for +analysis. Rapid fork creation dramatically reduces friction getting insights from live data. + +## Understand $SERVICE_SHORT forks + +You can use $SERVICE_SHORT forks for disaster recovery, CI/CD automation, and testing and development. For example, you +can automatically test a major $PG upgrade on a fork before applying it to your production $SERVICE_SHORT. + +$CLOUD_LONG offers the following fork strategies: + +- `now`: create a fresh fork of your database at the current time. + Use when: + - You need the absolute latest data + - Recent changes must be included in the fork + +- `last-snapshot`: fork from the most recent [automatic backup or snapshot][automatic-backups]. + Use when: + - You want the fastest possible fork creation + - Slightly behind current data is acceptable + +- `timestamp`: fork from a specific point in time within your [retention period][pricing]. + Use when: + - Disaster recovery from a known-good state + - Investigating issues that occurred at a specific time + - Testing "what-if" scenarios from historical data + +The retention period for point-in-time recovery and forking depends on your [pricing plan][pricing-plan-features]. + +### Fork creation speed + +Fork creation speed depends on your type of service you want to create: + +- Free: ~30-90 seconds. Uses a Copy-on-Write storage architecture with zero-copy between a fork and the parent. +- Paid: varies with the size of your $SERVICE_SHORT, typically 5-20+ minutes. Uses tradional storage architecture + with backup restore + WAL replay. + +### Billing + +You can fork a free $SERVICE_SHORT to a free or a paid $SERVICE_SHORT. However, you cannot fork a paid +$SERVICE_SHORT to a free $SERVICE_SHORT. + +Billing on storage works in the following way: + +- High-performance storage: + - Copy-on-Write: you are only billed for storage for the chunks that diverge from the parent $SERVICE_SHORT. + - Traditional: you are billed for storage for the whole $SERVICE_SHORT. +- Object storage tier: + - [Tiered data][data-tiering] is shared across forks using copy-on-write and traditional storage: + - Chunks in tiered storage are only billed once, regardless of the number of forks + - Only new or modified chunks in a fork incur additional costs + +For details, see [Replicas and forks with tiered data][tiered-forks]. + +## Prerequisites + + + +## Manage forks using $CLI_LONG + + + +## Manage forks using $CONSOLE_SHORT + +To manage development forks: + + + +1. In [$CONSOLE][console], from the `Services` list, ensure the $SERVICE_SHORT + you want to recover has a status of `Running` or `Paused`. +1. Navigate to `Operations` > `Service Management` and click `Fork service`. +1. Configure the fork, then click `Fork service`. + + A fork of the $SERVICE_SHORT is created. The forked $SERVICE_SHORT shows in `Services` with a label + specifying which $SERVICE_SHORT it has been forked from. + + ![See the forked service](https://assets.timescale.com/docs/images/tsc-forked-service.webp) + +1. Update the connection strings in your app to use the fork. + + + +## Integrate $SERVICE_SHORT forks in your CI/CD pipeline + +To fork your $SERVICE_LONG using GitHub actions: + + + +1. **Store your $CLOUD_LONG API key as a GitHub Actions secret** + + 1. In [$CONSOLE_LONG][rest-api-credentials], click `Create credentials`. + 2. Save the `Public key` and `Secret key` locally, then click `Done`. + 1. In your GitHub repository, click `Settings`, open `Secrets and variables`, then click `Actions`. + 3. Click `New repository secret`, then set `Name` to `TIGERDATA_API_KEY` + 4. Set `Secret` to your $CLOUD_LONG API key in the following format `:`, then click `Add secret`. + +1. **Add the [GitHub Actions Marketplace][github-action] to your workflow YAML files** + + For example, the following workflow forks a $SERVICE_SHORT when a pull request is opened, + running tests against the fork, then automatically cleans up. + + ```yaml + name: Test on a service fork + on: pull_request + + jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Fork Database + id: fork + uses: timescale/fork-service@v1 + with: + project_id: ${{ secrets.TIGERDATA_PROJECT_ID }} + service_id: ${{ secrets.TIGERDATA_SERVICE_ID }} + api_key: ${{ secrets.TIGERDATA_API_KEY }} + fork_strategy: last-snapshot + cleanup: true + name: pr-${{ github.event.pull_request.number }} + + - name: Run Integration Tests + env: + DATABASE_URL: postgresql://tsdbadmin:${{ steps.fork.outputs.initial_password }}@${{ steps.fork.outputs.host }}:${{ steps.fork.outputs.port }}/tsdb?sslmode=require + run: | + npm install + npm test + - name: Run Migrations + env: + DATABASE_URL: postgresql://tsdbadmin:${{ steps.fork.outputs.initial_password }}@${{ steps.fork.outputs.host }}:${{ steps.fork.outputs.port }}/tsdb?sslmode=require + run: npm run migrate + ``` + + For the full list of inputs, outputs, and configuration options, see the [Tiger Data - Fork Service][github-action] in GitHub marketplace. + + + +[console]: https://console.cloud.timescale.com/dashboard/services +[ha-replicas]: /about/use-timescale/:currentVersion:/ha-replicas/ +[pricing-and-account-management]: /about/:currentVersion:/pricing-and-account-management/ +[wal]: https://www.postgresql.org/docs/current/wal-intro.html +[support]: https://www.timescale.com/contact/ +[pitr]: /use-timescale/:currentVersion:/backup-restore/point-in-time-recovery/ +[rapid-recovery]: /use-timescale/:currentVersion:/ha-replicas/#rapid-recovery +[cross-region]: /use-timescale/:currentVersion:/backup-restore#enable-cross-region-backup +[create-fork]: /use-timescale/:currentVersion:/backup-restore#recover-your-data-in-a-point-in-time-fork +[automatic-backups]: /use-timescale/:currentVersion:/backup-restore/ +[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-pricing-plan +[data-tiering]: /use-timescale/:currentVersion:/data-tiering/ +[tiered-forks]: /use-timescale/:currentVersion:/data-tiering/tiered-data-replicas-forks/ +[github-action]: https://github.com/marketplace/actions/tiger-data-fork-service +[delete-action]: https://github.com/marketplace/actions/tiger-data-delete-service +[connection-details]: /integrations/:currentVersion:/find-connection-details/ +[upgrades]: /use-timescale/:currentVersion:/upgrades/ +[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings \ No newline at end of file diff --git a/use-timescale/metrics-logging/aws-cloudwatch.md b/use-timescale/metrics-logging/aws-cloudwatch.md index 6368a212ee..2b3fb68ea2 100644 --- a/use-timescale/metrics-logging/aws-cloudwatch.md +++ b/use-timescale/metrics-logging/aws-cloudwatch.md @@ -40,5 +40,5 @@ This section shows you how to attach, monitor, edit, and delete a data exporter. [console-integrations]: https://console.cloud.timescale.com/dashboard/integrations [console-services]: https://console.cloud.timescale.com/dashboard/services [services-portal]: https://console.cloud.timescale.com/dashboard/services -[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-plan +[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-pricing-plan [projects]: /use-timescale/:currentVersion:/security/members/ \ No newline at end of file diff --git a/use-timescale/metrics-logging/datadog.md b/use-timescale/metrics-logging/datadog.md index 96c658bbb1..992c60ccca 100644 --- a/use-timescale/metrics-logging/datadog.md +++ b/use-timescale/metrics-logging/datadog.md @@ -41,5 +41,5 @@ This section shows you how to attach, monitor, edit, and delete a data exporter. [console-integrations]: https://console.cloud.timescale.com/dashboard/integrations [console-services]: https://console.cloud.timescale.com/dashboard/services [services-portal]: https://console.cloud.timescale.com/dashboard/services -[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-plan +[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-pricing-plan [projects]: /use-timescale/:currentVersion:/security/members/ diff --git a/use-timescale/page-index/page-index.js b/use-timescale/page-index/page-index.js index 443988e557..77f07d8aa5 100644 --- a/use-timescale/page-index/page-index.js +++ b/use-timescale/page-index/page-index.js @@ -606,9 +606,13 @@ module.exports = [ ], }, { - title: "Back up and recover your services", + title: "Back up and recover services", href: "backup-restore", }, + { + title: "Fork services", + href: "fork-services", + }, { title: "Jobs", href: "jobs", diff --git a/use-timescale/security/overview.md b/use-timescale/security/overview.md index 8741a73d9c..064267a7a5 100644 --- a/use-timescale/security/overview.md +++ b/use-timescale/security/overview.md @@ -107,5 +107,5 @@ $CLOUD_LONG is SOC 2 Type 2 compliant. This ensures that organizations can secur [vpc-peering]: /use-timescale/:currentVersion:/security/vpc [security-at-timescale]: https://www.timescale.com/security [ip-allowlist]: /use-timescale/:currentVersion:/security/ip-allow-list/ -[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-plan +[pricing-plan-features]: /about/:currentVersion:/pricing-and-account-management/#features-included-in-each-pricing-plan [open-support-ticket]: https://console.cloud.timescale.com/dashboard/support \ No newline at end of file diff --git a/use-timescale/services/service-management.md b/use-timescale/services/service-management.md index 98500bbfa4..f8e6bad7f8 100644 --- a/use-timescale/services/service-management.md +++ b/use-timescale/services/service-management.md @@ -10,6 +10,8 @@ cloud_ui: - [create_services, fork, :serviceId] --- +import CLIFORKS from "versionContent/_partials/_devops-cli-service-forks.mdx"; + # $SERVICE_SHORT_CAP management In the `Service management` section of the `Operations` dashboard, you can fork @@ -46,8 +48,6 @@ data discrepancy between $SERVICE_SHORTs. -### Forking a $SERVICE_SHORT - 1. In $CONSOLE_LONG, from the `Services` list, ensure the $SERVICE_SHORT you want to form has a status of `Running` or `Paused`, then click the name of the $SERVICE_SHORT you want to fork. @@ -72,7 +72,12 @@ alt="Fork a Tiger service" -### Reset your $SERVICE_SHORT password +## Create a service fork using the $CLI_SHORT + + + + +## Reset your $SERVICE_SHORT password You can reset your $SERVICE_SHORT password from the `Operations` dashboard. This is the password you use to connect to your $SERVICE_SHORT, not the password for $CONSOLE. To reset your $CONSOLE_SHORT password, navigate to the `Account` page. @@ -86,14 +91,14 @@ digest algorithm 5) are cryptographic authentication mechanisms. $CONSOLE_LONG uses SCRAM by default. It is more secure and strongly recommended. The MD5 option is provided for compatibility with older clients. -### Pause a $SERVICE_SHORT +## Pause a $SERVICE_SHORT You can pause a $SERVICE_SHORT if you want to stop it running temporarily. When you pause a $SERVICE_SHORT, you are no longer billed for compute resources. However, you do need to continue paying for any storage you are using. Pausing a $SERVICE_SHORT ensures that it is still available, and is ready to be restarted at any time. -### Delete a $SERVICE_SHORT +## Delete a $SERVICE_SHORT You can delete a $SERVICE_SHORT to remove it completely. This removes the $SERVICE_SHORT and its underlying data from the server. You cannot recover a deleted