Merge pull request #407 from timescale/atovpeko/cli-mcp-build

atovpeko · web-flow · commit 8f2711742383 · 2026-07-28T11:08:25.000+03:00
Build: add Tiger CLI/MCP task, safety, and cookbook pages
diff --git a/astro.config.ts b/astro.config.ts
@@ -536,6 +536,16 @@ export default defineConfig({
           link: "/build",
           sidebar: [
             { label: "Overview", link: "/build" },
+            // --- Tiger CLI and MCP: manage Tiger Cloud and drive the DB with agents ---
+            {
+              label: "Build with Tiger CLI and MCP",
+              collapsed: true,
+              items: [
+                { label: "Common tasks", link: "/build/tiger-cli-mcp/common-tasks" },
+                { label: "Best practices for AI agents", link: "/build/tiger-cli-mcp/agent-best-practices" },
+                { label: "Cookbook", link: "/build/tiger-cli-mcp/cookbook" },
+              ],
+            },
             // --- Quickstarts ---
             {
               label: "Quickstarts",
diff --git a/src/components/DoWithAi.astro b/src/components/DoWithAi.astro
@@ -0,0 +1,10 @@
+---
+import Callout from "@components/Callout.astro";
+import * as C from "@constants";
+
+const base = import.meta.env.BASE_URL.replace(/\/$/, "");
+---
+
+<Callout variant="tip" title="Try this with your AI agent">
+  <p>In {C.CLOUD_LONG}, <a href={`${base}/get-started/quickstart/mcp-cli`}>set up {C.MCP_LONG}</a> and ask your AI agent to do this for you. See <a href={`${base}/build/tiger-cli-mcp/common-tasks`}>example prompts</a> to get started, and <a href={`${base}/build/tiger-cli-mcp/agent-best-practices`}>best practices</a> to keep it safe.</p>
+</Callout>
diff --git a/src/content/docs/build/columnar-storage/setup-hypercore.mdx b/src/content/docs/build/columnar-storage/setup-hypercore.mdx
@@ -11,6 +11,7 @@ import { Prerequisites } from "@components/Prerequisites";
 import HypercoreIntroShort from "../../../../partials/_hypercore-intro-short.mdx";
 import HCConversionOverview from "../../../../partials/_hypercore-conversion-overview.mdx";
 import HCPolicyWorkflow from "../../../../partials/_hypercore_policy_workflow.mdx";
+import DoWithAi from "@components/DoWithAi.astro";
 
 <HypercoreIntroShort />
 
@@ -27,6 +28,8 @@ your data.
 <ConnectionDetails />
 </Prerequisites>
 
+<DoWithAi />
+
 ## Convert your data to the {C.COLUMNSTORE}
 
 The compression ratio and query performance of data in the {C.COLUMNSTORE} is dependent on the order and structure of your
diff --git a/src/content/docs/build/continuous-aggregates/compression-on-continuous-aggregates.mdx b/src/content/docs/build/continuous-aggregates/compression-on-continuous-aggregates.mdx
@@ -8,6 +8,7 @@ keywords: [continuous aggregates, compression]
 import * as C from "@constants";
 import { NumberedList, NumberedItem } from "@components/NumberedList";
 import SinceRelease from "@components/SinceRelease.astro";
+import DoWithAi from "@components/DoWithAi.astro";
 
 <SinceRelease version="2.20.0" product="tsdb" />
 
@@ -20,6 +21,8 @@ To save on storage costs, you use {C.HYPERCORE} to downsample historical data st
 in the {C.CAGG}, and [ordered by](/reference/timescaledb/continuous-aggregates/alter_materialized_view#arguments) the time column. [{C.RTAGG_CAP}](/learn/continuous-aggregates/real-time-aggregates)
 is disabled by default.
 
+<DoWithAi />
+
 ## Configure {C.COLUMNSTORE} on {C.CAGG}s
 
 For an [existing {C.CAGG}](/build/continuous-aggregates/create-a-continuous-aggregate):
diff --git a/src/content/docs/build/continuous-aggregates/create-a-continuous-aggregate.mdx b/src/content/docs/build/continuous-aggregates/create-a-continuous-aggregate.mdx
@@ -9,6 +9,7 @@ import * as C from "@constants";
 import { Callout } from "@stainless-api/docs/components";
 import { NumberedList, NumberedItem } from "@components/NumberedList";
 import SinceRelease from "@components/SinceRelease.astro";
+import DoWithAi from "@components/DoWithAi.astro";
 
 A {C.CAGG} stores precomputed rollups so analytical queries avoid rescanning all raw rows. You create the materialized view first, then wire up refresh (policy or manual). You can build on a {C.HYPERTABLE} or stack another {C.CAGG}, and you can define more than one {C.CAGG} per source.
 
@@ -26,6 +27,8 @@ example, if the original {C.HYPERTABLE}'s {C.CHUNK} time interval is 7 days, the
 {C.CAGG}s that are on top of it have a 70 day {C.CHUNK} time
 interval.
 
+<DoWithAi />
+
 ## Create a {C.CAGG}
 
 In this example, we are using a {C.HYPERTABLE} called `conditions`, and creating a
diff --git a/src/content/docs/build/continuous-aggregates/create-index.mdx b/src/content/docs/build/continuous-aggregates/create-index.mdx
@@ -5,9 +5,12 @@ products: [cloud, self_hosted]
 keywords: [continuous aggregates, indexes]
 ---
 import * as C from "@constants";
+import DoWithAi from "@components/DoWithAi.astro";
 
 {C.CAGG_CAP}s create helpful composite indexes by default, but you can turn that off or add your own for specific filters. This page covers the automatic indexes, how to disable them, and how to manage custom ones.
 
+<DoWithAi />
+
 ## Automatically created indexes
 
 When you create a {C.CAGG}, an index is automatically created for
diff --git a/src/content/docs/build/continuous-aggregates/drop-data.mdx b/src/content/docs/build/continuous-aggregates/drop-data.mdx
@@ -7,11 +7,14 @@ keywords: [continuous aggregates, hypertables, delete]
 
 import * as C from "@constants";
 import { NumberedList, NumberedItem } from "@components/NumberedList";
+import DoWithAi from "@components/DoWithAi.astro";
 
 You can remove a {C.CAGG} view, trim raw rows from the source {C.HYPERTABLE}, or rely on [refresh](/build/continuous-aggregates/refresh-policies) plus retention policies to keep coarse long-term aggregates while dropping detailed history.
 
 Watch for retention rules that delete raw {C.HYPERTABLE} rows your {C.CAGG} still needs to rebuild or refresh correctly.
 
+<DoWithAi />
+
 ## Drop a {C.CAGG} view
 
 You can drop a {C.CAGG} view using the `DROP MATERIALIZED VIEW`
diff --git a/src/content/docs/build/continuous-aggregates/refresh-policies.mdx b/src/content/docs/build/continuous-aggregates/refresh-policies.mdx
@@ -10,13 +10,16 @@ import { Callout } from "@stainless-api/docs/components";
 import { NumberedList, NumberedItem } from "@components/NumberedList";
 import PrereqCloudSelf from "../../../../partials/_prereqs-cloud-and-self.mdx";
 import { Prerequisites } from "@components/Prerequisites";
+import DoWithAi from "@components/DoWithAi.astro";
 
 Refresh policies control how and when a materialized {C.CAGG} catches up with its source {C.HYPERTABLE}. You can run refreshes on a schedule or trigger them manually when you need a one-off catch-up.
 
 <Prerequisites context="procedure">
 <PrereqCloudSelf />
 </Prerequisites>
 
+<DoWithAi />
+
 ## Change the refresh policy
 
 {C.CAGG_CAP}s require a policy for automatic refreshing. You can adjust
diff --git a/src/content/docs/build/data-management/create-and-manage-jobs.mdx b/src/content/docs/build/data-management/create-and-manage-jobs.mdx
@@ -9,13 +9,16 @@ import * as C from "@constants";
 import { NumberedList, NumberedItem } from "@components/NumberedList";
 import PrereqCloudOrSelf from "../../../../partials/_prereqs-cloud-or-self.mdx";
 import { Prerequisites } from "@components/Prerequisites";
+import DoWithAi from "@components/DoWithAi.astro";
 
 {C.JOB_CAP}s are custom functions or procedures that {C.TIMESCALE_DB} runs on your schedule. The sections below show how to register one, test it, and change or remove it safely.
 
 <Prerequisites context="procedure">
 <PrereqCloudOrSelf />
 </Prerequisites>
 
+<DoWithAi />
+
 ## Create a {C.JOB}
 
 To create a {C.JOB}, create a [{C.PG} function](https://www.postgresql.org/docs/current/xfunc.html) or [procedure](https://www.postgresql.org/docs/current/xproc.html) that you want your database to execute, then set it up to run on a schedule.
diff --git a/src/content/docs/build/data-management/data-retention/create-a-retention-policy.mdx b/src/content/docs/build/data-management/data-retention/create-a-retention-policy.mdx
@@ -8,9 +8,12 @@ keywords: [data retention, policies]
 import * as C from "@constants";
 import { Callout } from "@stainless-api/docs/components";
 import { NumberedList, NumberedItem } from "@components/NumberedList";
+import DoWithAi from "@components/DoWithAi.astro";
 
 Retention policies drop entire {C.CHUNK}s once their time range falls outside your window, which is cheaper than deleting millions of rows one by one. {C.TIMESCALE_DB} schedules a background {C.JOB} to apply the policy for you.
 
+<DoWithAi />
+
 ## Add a data retention policy
 
 Add a data retention policy by using the
diff --git a/src/content/docs/build/data-management/example-downsample-and-compress.mdx b/src/content/docs/build/data-management/example-downsample-and-compress.mdx
@@ -7,11 +7,14 @@ keywords: [jobs, compression, downsample]
 
 import * as C from "@constants";
 import { NumberedList, NumberedItem } from "@components/NumberedList";
+import DoWithAi from "@components/DoWithAi.astro";
 
 {C.TIMESCALE_DB} lets you downsample and convert {C.CHUNK}s to the {C.COLUMNSTORE} by combining a [{C.CAGG} refresh policy](/build/continuous-aggregates/refresh-policies) with
 [{C.HYPERCORE}](/learn/columnar-storage/understand-hypercore). If you want to implement features not supported by those policies, you can write
 a {C.JOB} to downsample and convert {C.CHUNK}s to the {C.COLUMNSTORE} instead.
 
+<DoWithAi />
+
 The following example downsamples raw data to an average over hourly data. This is an
 illustrative example, which can be done more simply with a {C.CAGG} policy. But you can make the query
 arbitrarily complex.
diff --git a/src/content/docs/build/data-management/example-generic-retention.mdx b/src/content/docs/build/data-management/example-generic-retention.mdx
@@ -8,9 +8,12 @@ keywords: [jobs, data retention]
 import * as C from "@constants";
 import { Callout } from "@stainless-api/docs/components";
 import { NumberedList, NumberedItem } from "@components/NumberedList";
+import DoWithAi from "@components/DoWithAi.astro";
 
 Per-{C.HYPERTABLE} [built-in retention policies](/build/data-management/data-retention/create-a-retention-policy) cover most cases. When you need one rule that walks every {C.HYPERTABLE} in the database, implement it with a custom {C.JOB}.
 
+<DoWithAi />
+
 <NumberedList>
 <NumberedItem title="Create a procedure to drop old chunks">
 Create a procedure that drops {C.CHUNK}s from any {C.HYPERTABLE} if they are older
diff --git a/src/content/docs/build/data-management/query-data/advanced-analytic-queries.mdx b/src/content/docs/build/data-management/query-data/advanced-analytic-queries.mdx
@@ -6,9 +6,12 @@ products: [cloud, self_hosted]
 
 import * as C from "@constants";
 import CreateHypertablePolicyNote from "../../../../../partials/_create-hypertable-columnstore-policy-note.mdx";
+import DoWithAi from "@components/DoWithAi.astro";
 
 Beyond basic aggregates, these patterns cover medians, moving windows, histograms, gap filling, and toolkit-backed shortcuts. Some use core {C.PG}; others come from {C.TIMESCALE_DB} and {C.TOOLKIT_LONG}.
 
+<DoWithAi />
+
 ## Calculate the median and percentile
 
 Use [`percentile_cont`](https://www.postgresql.org/docs/current/functions-aggregate.html#FUNCTIONS-ORDEREDSET-TABLE) to calculate percentiles. You can also
diff --git a/src/content/docs/build/data-management/query-data/select.mdx b/src/content/docs/build/data-management/query-data/select.mdx
@@ -5,9 +5,12 @@ products: [cloud, self_hosted]
 ---
 
 import * as C from "@constants";
+import DoWithAi from "@components/DoWithAi.astro";
 
 [`SELECT`](https://www.postgresql.org/docs/current/sql-select.html) against a {C.HYPERTABLE} works like any other table: filters, joins, aggregates, and window functions all apply. The examples below cover common time-window patterns.
 
+<DoWithAi />
+
 ## Basic query examples
 
 Here are some examples of basic `SELECT` queries.
diff --git a/src/content/docs/build/data-management/write-data/delete.mdx b/src/content/docs/build/data-management/write-data/delete.mdx
@@ -6,11 +6,14 @@ products: [cloud, self_hosted]
 
 import * as C from "@constants";
 import { Callout } from "@stainless-api/docs/components";
+import DoWithAi from "@components/DoWithAi.astro";
 
 Row deletes use the standard [`DELETE`](https://www.postgresql.org/docs/current/sql-delete.html) statement against a {C.HYPERTABLE}. This works the same whether the {C.CHUNK} is in the {C.ROWSTORE} or the {C.COLUMNSTORE}. You don't
 need to decompress a {C.CHUNK} before deleting from it: {C.TIMESCALE_DB} decompresses only the rows your
 statement touches, not the whole {C.CHUNK}. When you need to age out large ranges, dropping {C.CHUNK}s or using a retention policy is usually cheaper than massive `DELETE` scans.
 
+<DoWithAi />
+
 ## Delete data with DELETE command
 
 To delete data from a table, use the syntax `DELETE FROM ...`. In this example,
diff --git a/src/content/docs/build/data-management/write-data/insert.mdx b/src/content/docs/build/data-management/write-data/insert.mdx
@@ -18,6 +18,7 @@ learnMore:
 import * as C from "@constants";
 import { Callout } from "@stainless-api/docs/components";
 import HypercoreDirectCompress from "../../../../../partials/_hypercore-direct-compress.mdx";
+import DoWithAi from "@components/DoWithAi.astro";
 
 Inserts into a {C.HYPERTABLE} are normal {C.PG} writes. Use the usual commands, and lean on batching when you can:
 
@@ -30,6 +31,8 @@ touches, not the whole {C.CHUNK}.
 
 To improve performance, insert time series data directly to the {C.COLUMNSTORE} using [direct compress](#improve-performance-with-direct-compress).
 
+<DoWithAi />
+
 ## Insert a single row
 
 To insert a single row into a {C.HYPERTABLE}, use the syntax `INSERT INTO ... VALUES`:
diff --git a/src/content/docs/build/data-management/write-data/update.mdx b/src/content/docs/build/data-management/write-data/update.mdx
@@ -5,9 +5,12 @@ products: [cloud, self_hosted]
 ---
 
 import * as C from "@constants";
+import DoWithAi from "@components/DoWithAi.astro";
 
 Point fixes and time-bounded corrections both use [`UPDATE`](https://www.postgresql.org/docs/current/sql-update.html) against a {C.HYPERTABLE}, just like a regular table.
 
+<DoWithAi />
+
 This works the same whether the {C.CHUNK} is in the {C.ROWSTORE} or the {C.COLUMNSTORE}. You don't need to
 decompress a {C.CHUNK} before updating it: {C.TIMESCALE_DB} decompresses only the rows your statement touches,
 not the whole {C.CHUNK}.
diff --git a/src/content/docs/build/data-management/write-data/upsert.mdx b/src/content/docs/build/data-management/write-data/upsert.mdx
@@ -6,12 +6,15 @@ products: [cloud, self_hosted]
 
 import * as C from "@constants";
 import { NumberedList, NumberedItem } from "@components/NumberedList";
+import DoWithAi from "@components/DoWithAi.astro";
 
 An upsert either inserts a new row or reconciles with an existing one in a single round trip. That helps with idempotent ingestion and late-arriving measurements:
 
 * **A matching row does not exist**: inserts a new row
 * **A matching row exists**: either updates the existing row, or does nothing
 
+<DoWithAi />
+
 This works the same whether the {C.CHUNK} is in the {C.ROWSTORE} or the {C.COLUMNSTORE}. You don't need to
 decompress a {C.CHUNK} before upserting into it: {C.TIMESCALE_DB} decompresses only the rows your statement
 touches, not the whole {C.CHUNK}.
diff --git a/src/content/docs/build/examples/hybrid-search.mdx b/src/content/docs/build/examples/hybrid-search.mdx
@@ -89,7 +89,7 @@ services running {C.PG} 17+ already have `pg_textsearch` and `pgvectorscale`
 installed and ready to use.
 
 You can manage your {C.CLOUD_LONG} service through the web console, the {C.CLI_LONG}, or
-the {C.MCP_LONG} from your AI assistant. The steps below cover all three options.
+the {C.MCP_LONG} from your AI agent. The steps below cover all three options.
 
 <NumberedList>
 <NumberedItem title={`Install the ${C.CLI_LONG} (optional but recommended)`}>
@@ -119,12 +119,12 @@ tiger service list
 ```
 
 For the full setup guide, see
-[Get started with the command line](/get-started/quickstart/cli-rest-api).
+[Get started with Tiger CLI](/get-started/quickstart/tiger-cli).
 
 </NumberedItem>
-<NumberedItem title={`Set up ${C.MCP_LONG} for your AI assistant (optional)`}>
+<NumberedItem title={`Set up ${C.MCP_LONG} for your AI agent (optional)`}>
 
-{C.MCP_LONG} gives your AI assistant (Claude Code, Cursor, Windsurf, and others) direct
+{C.MCP_LONG} gives your AI agent (Claude Code, Cursor, Windsurf, and others) direct
 access to {C.CLOUD_LONG} so you can manage services and run queries using natural
 language. It's bundled with the {C.CLI_LONG} you just installed.
 
@@ -134,12 +134,12 @@ Run the following in your terminal:
 tiger mcp install
 ```
 
-Choose your AI assistant from the list (for example, `claude-code`, `cursor`, `windsurf`)
-and press Enter. After installation, start your AI assistant and ask: _"Is the
+Choose your AI agent from the list (for example, `claude-code`, `cursor`, `windsurf`)
+and press Enter. After installation, start your AI agent and ask: _"Is the
 {C.MCP_LONG} server active?"_ to confirm it's connected.
 
 For the full setup guide, see
-[Integrate Tiger Cloud with your AI assistant](/get-started/quickstart/mcp-cli).
+[Integrate Tiger Cloud with your AI agent](/get-started/quickstart/mcp-cli).
 
 </NumberedItem>
 <NumberedItem title={`Create or select a ${C.SERVICE_LONG}`}>
diff --git a/src/content/docs/build/how-to/basic-compression.mdx b/src/content/docs/build/how-to/basic-compression.mdx
@@ -17,9 +17,12 @@ import * as C from "@constants";
 import { Callout } from "@stainless-api/docs/components";
 import { Prerequisites } from "@components/Prerequisites";
 import PrereqCloudOrSelf from "../../../../partials/_prereqs-cloud-or-self.mdx";
+import DoWithAi from "@components/DoWithAi.astro";
 
 {C.HYPERCORE_CAP} is {C.TIMESCALE_DB}'s hybrid row-columnar storage engine. It automatically compresses {C.CHUNK}s from the {C.ROWSTORE} into the {C.COLUMNSTORE}, typically reducing storage by 90–98% while making analytical queries significantly faster.
 
+<DoWithAi />
+
 ## How it works
 
 When you create a {C.HYPERTABLE} with `segmentby` and `orderby` options, {C.TIMESCALE_DB} automatically creates a [{C.COLUMNSTORE} policy](/reference/timescaledb/hypercore/add_columnstore_policy) that converts older {C.CHUNK}s into columnar format. Recent data stays in the {C.ROWSTORE} for fast inserts, while older data is compressed in the {C.COLUMNSTORE} for efficient scans. {C.COLUMNSTORE_CAP} {C.CHUNK}s still accept inserts, updates, and deletes directly, without needing to decompress them first.
diff --git a/src/content/docs/build/how-to/your-first-hypertable.mdx b/src/content/docs/build/how-to/your-first-hypertable.mdx
@@ -16,9 +16,12 @@ import { Callout } from "@stainless-api/docs/components";
 import { NumberedList, NumberedItem } from "@components/NumberedList";
 import { Prerequisites } from "@components/Prerequisites";
 import PrereqCloudOrSelf from "../../../../partials/_prereqs-cloud-or-self.mdx";
+import DoWithAi from "@components/DoWithAi.astro";
 
 You will create a {C.HYPERTABLE} from scratch, see why time-based partitioning matters, and finish with queries you can reuse. Expect the same SQL surface you already know, with {C.CHUNK}-aware planning underneath.
 
+<DoWithAi />
+
 ## What is a {C.HYPERTABLE}?
 
 A {C.HYPERTABLE} is the main abstraction {C.TIMESCALE_DB} uses for time-series data. To your application it looks and behaves like a regular {C.PG} table: you `INSERT`, `SELECT`, `UPDATE`, and `DELETE` using standard SQL. Under the hood, the database automatically partitions your rows by time into storage units called {C.CHUNK}s. Each {C.CHUNK} holds a time range of data (for example, one day or one week). When you run a query, {C.TIMESCALE_DB} figures out which {C.CHUNK}s are relevant and only touches those, instead of scanning the whole table. That is why {C.HYPERTABLE}s can scale to very large volumes while keeping queries fast.
diff --git a/src/content/docs/build/tiger-cli-mcp/agent-best-practices.mdx b/src/content/docs/build/tiger-cli-mcp/agent-best-practices.mdx
diff --git a/src/content/docs/build/tiger-cli-mcp/common-tasks.mdx b/src/content/docs/build/tiger-cli-mcp/common-tasks.mdx
diff --git a/src/content/docs/build/tiger-cli-mcp/cookbook.mdx b/src/content/docs/build/tiger-cli-mcp/cookbook.mdx
diff --git a/src/content/docs/get-started/quickstart/mcp-cli.mdx b/src/content/docs/get-started/quickstart/mcp-cli.mdx
diff --git a/src/content/docs/get-started/quickstart/tiger-cli.mdx b/src/content/docs/get-started/quickstart/tiger-cli.mdx
diff --git a/src/content/docs/learn/tiger-cli-mcp/index.mdx b/src/content/docs/learn/tiger-cli-mcp/index.mdx
