diff --git a/astro.config.ts b/astro.config.ts index 77a64c88a..753fc155a 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -363,13 +363,20 @@ export default defineConfig({ ], }, { - label: "Tiger Cloud", + label: "Tiger Console", collapsed: true, items: [ { label: "5-minute quickstart", link: "/get-started/quickstart/quickstart-5-minutes" }, { label: "Create a Tiger Cloud service", link: "/get-started/quickstart/create-service" }, - { label: "Get started with the command line", link: "/get-started/quickstart/cli-rest-api" }, - { label: "Integrate Tiger Cloud with your AI assistant", link: "/get-started/quickstart/mcp-cli" }, + ], + }, + { + label: "Tiger CLI and MCP", + collapsed: true, + items: [ + { label: "Get started with Tiger CLI", link: "/get-started/quickstart/tiger-cli" }, + { label: "Integrate Tiger Cloud with your AI agent", link: "/get-started/quickstart/mcp-cli" }, + { label: "Get started with the REST API", link: "/get-started/quickstart/rest-api" }, ], }, { @@ -416,6 +423,13 @@ export default defineConfig({ { label: "Tiger Cloud essentials", link: "/learn/tiger-cloud/tiger-cloud-essentials" }, ], }, + { + label: "Tiger CLI and MCP", + collapsed: true, + items: [ + { label: "Tiger CLI and Tiger MCP", link: "/learn/tiger-cli-mcp" }, + ], + }, { label: "Capabilities and comparison", collapsed: true, @@ -521,6 +535,15 @@ 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" }, + ], + }, // --- Get hands on: merged Tutorials + How-to + Examples --- { label: "Get hands on", @@ -1909,18 +1932,6 @@ export default defineConfig({ collapsed: true, items: [ { label: "Overview", link: "/reference/tiger-cloud" }, - { - label: "Data tiering", - collapsed: true, - items: [ - { label: "Overview", link: "/reference/tiger-cloud/data-tiering" }, - { label: "add_tiering_policy()", link: "/reference/tiger-cloud/data-tiering/add_tiering_policy" }, - { label: "remove_tiering_policy()", link: "/reference/tiger-cloud/data-tiering/remove_tiering_policy" }, - { label: "tier_chunk()", link: "/reference/tiger-cloud/data-tiering/tier_chunk" }, - { label: "untier_chunk()", link: "/reference/tiger-cloud/data-tiering/untier_chunk" }, - { label: "disable_tiering()", link: "/reference/tiger-cloud/data-tiering/disable_tiering" }, - ], - }, { label: "Tiger CLI", link: "/reference/tiger-cloud/tiger-cli" }, { label: "Tiger MCP", link: "/reference/tiger-cloud/tiger-mcp" }, DOCS_LOCAL_WITHOUT_STAINLESS @@ -1941,6 +1952,18 @@ export default defineConfig({ excludeResourceOverviewPages: true, }), }, + { + label: "Data tiering", + collapsed: true, + items: [ + { label: "Overview", link: "/reference/tiger-cloud/data-tiering" }, + { label: "add_tiering_policy()", link: "/reference/tiger-cloud/data-tiering/add_tiering_policy" }, + { label: "remove_tiering_policy()", link: "/reference/tiger-cloud/data-tiering/remove_tiering_policy" }, + { label: "tier_chunk()", link: "/reference/tiger-cloud/data-tiering/tier_chunk" }, + { label: "untier_chunk()", link: "/reference/tiger-cloud/data-tiering/untier_chunk" }, + { label: "disable_tiering()", link: "/reference/tiger-cloud/data-tiering/disable_tiering" }, + ], + }, ], }, ], @@ -1978,8 +2001,9 @@ export default defineConfig({ "/get-started/install-timescaledb": "/get-started/choose-your-path/install-timescaledb", "/get-started/supported-platforms": "/get-started/choose-your-path/supported-platforms", "/get-started/timescaledb-editions": "/get-started/choose-your-path/timescaledb-editions", - "/get-started/cli-rest-api": "/get-started/quickstart/cli-rest-api", - "/get-started/tools/cli-rest-api": "/get-started/quickstart/cli-rest-api", + "/get-started/cli-rest-api": "/get-started/quickstart/tiger-cli", + "/get-started/tools/cli-rest-api": "/get-started/quickstart/tiger-cli", + "/get-started/quickstart/cli-rest-api": "/get-started/quickstart/tiger-cli", "/get-started/mcp-cli": "/get-started/quickstart/mcp-cli", "/get-started/tools/mcp-cli": "/get-started/quickstart/mcp-cli", "/get-started/key-features-timescale": "/learn/tiger-cloud/tiger-cloud-essentials", diff --git a/src/components/ChangelogEntry.astro b/src/components/ChangelogEntry.astro index 04118213b..fc85bca7f 100644 --- a/src/components/ChangelogEntry.astro +++ b/src/components/ChangelogEntry.astro @@ -25,7 +25,7 @@ interface Props { date: string; // ISO format: YYYY-MM-DD tags: Array< | 'new-feature' - | 'improvement' + | 'improvement' | 'performance' | 'security' | 'integration' @@ -35,6 +35,7 @@ interface Props { | 'breaking-change' | 'beta' | 'ga' + | 'cli-mcp' >; } diff --git a/src/components/ChangelogFilter.astro b/src/components/ChangelogFilter.astro index f6a4fca8a..9495263de 100644 --- a/src/components/ChangelogFilter.astro +++ b/src/components/ChangelogFilter.astro @@ -26,6 +26,7 @@ const tagOptions = [ { value: 'breaking-change', label: 'Breaking', icon: '🚨' }, { value: 'beta', label: 'Beta', icon: '🧪' }, { value: 'ga', label: 'GA', icon: '🎉' }, + { value: 'cli-mcp', label: 'Tiger CLI/MCP', icon: '⌨️' }, ]; --- diff --git a/src/components/ChangelogTag.astro b/src/components/ChangelogTag.astro index 21c8da004..d4588c041 100644 --- a/src/components/ChangelogTag.astro +++ b/src/components/ChangelogTag.astro @@ -20,12 +20,13 @@ * - breaking-change: Changes requiring user action * - beta: Beta/preview releases * - ga: General availability releases + * - cli-mcp: Tiger CLI and MCP updates */ interface Props { - type: + type: | 'new-feature' - | 'improvement' + | 'improvement' | 'performance' | 'security' | 'integration' @@ -34,7 +35,8 @@ interface Props { | 'bug-fix' | 'breaking-change' | 'beta' - | 'ga'; + | 'ga' + | 'cli-mcp'; } const { type } = Astro.props; @@ -95,6 +97,11 @@ const tagConfig: Record diff --git a/src/components/DoWithAi.astro b/src/components/DoWithAi.astro new file mode 100644 index 000000000..ace2a33cb --- /dev/null +++ b/src/components/DoWithAi.astro @@ -0,0 +1,14 @@ +--- +/** + * DoWithAi: a reusable, generic callout promoting the Tiger MCP (AI agent) + * way of working. Same wording and links on every page; no per-page content. + */ +import Callout from "@components/Callout.astro"; +import * as C from "@constants"; + +const base = import.meta.env.BASE_URL.replace(/\/$/, ""); +--- + + +

Prefer to work in natural language? If you have set up {C.MCP_LONG}, ask your AI agent to do this for you instead of running the steps manually. See example prompts to get started, and best practices for AI agents to keep it safe.

+ \ No newline at end of file diff --git a/src/components/NavTabsWithDropdown.astro b/src/components/NavTabsWithDropdown.astro index bcf3123e4..34105166c 100644 --- a/src/components/NavTabsWithDropdown.astro +++ b/src/components/NavTabsWithDropdown.astro @@ -67,6 +67,18 @@ const SECTION_DROPDOWN_HREF: Record = { "Migrate to Tiger Cloud": "/migrate/livesync-replication", "Tiger Cloud on AWS": "/deploy/tiger-cloud/tiger-cloud-aws/configuration/about-configuration", "Tiger Cloud on Azure": "/deploy/tiger-cloud/tiger-cloud-azure/configuration/about-configuration", + "Tiger Cloud REST API": "/reference/tiger-cloud-rest", +}; + +/** + * Dropdown-only: sidebar sections whose children are promoted to individual + * dropdown entries instead of a single section link. Used for the Reference + * "Tiger Cloud" group so the dropdown lists Tiger CLI, Tiger MCP, and the REST API + * as separate entries (not one "Tiger Cloud" overview link), without changing the + * left sidebar. The "Overview" and "Data tiering" children are dropped. + */ +const SECTION_DROPDOWN_EXPAND: Record> = { + Reference: new Set(["Tiger Cloud"]), }; const BASE_PREFIX = import.meta.env.BASE_URL.replace(/\/$/, ""); @@ -174,7 +186,7 @@ function sectionIndexHref(e: SidebarEntryLike): string | undefined { * Only the tab sidebar’s **root** entries appear in the dropdown (same as top-level sidebar groups). * Nested pages are omitted; use the section heading link (sectionIndexHref) or the left sidebar for drill-down. */ -function buildNavTree(entries: unknown[] | undefined): NavTreeNode[] { +function buildNavTree(entries: unknown[] | undefined, tabLabel: string): NavTreeNode[] { const out: NavTreeNode[] = []; if (!Array.isArray(entries)) return out; @@ -186,6 +198,14 @@ function buildNavTree(entries: unknown[] | undefined): NavTreeNode[] { const items = Array.isArray(e.items) ? e.items : []; const hasItems = items.length > 0; + if (hasItems && SECTION_DROPDOWN_EXPAND[tabLabel]?.has(e.label.trim())) { + const childNodes = buildNavTree(items, tabLabel).filter( + (n) => !/^(overview|data tiering)$/i.test(n.label.trim()) + ); + out.push(...childNodes); + continue; + } + if (hasItems) { const href = sectionIndexHref(e); out.push({ @@ -251,8 +271,8 @@ function prefixNavTreeHrefs(nodes: NavTreeNode[]): void { } } -function getNavTreeForSidebar(sidebar: unknown, tabLink: string): NavTreeNode[] { - const tree = buildNavTree(sidebar as unknown[]); +function getNavTreeForSidebar(sidebar: unknown, tabLink: string, tabLabel: string): NavTreeNode[] { + const tree = buildNavTree(sidebar as unknown[], tabLabel); const filtered = filterOverviewDuplicate(tree, tabLink); clearTreeDescriptions(filtered); prefixNavTreeHrefs(filtered); @@ -263,7 +283,7 @@ const dropdownTreeByTab = new Map(); for (const item of navItems) { const sidebar = item.sidebar; if (Array.isArray(sidebar) && sidebar.length > 0) { - dropdownTreeByTab.set(item.label, getNavTreeForSidebar(sidebar, item.link)); + dropdownTreeByTab.set(item.label, getNavTreeForSidebar(sidebar, item.link, item.label)); } } --- diff --git a/src/constants.ts b/src/constants.ts index 5de965e11..db3f69e28 100644 --- a/src/constants.ts +++ b/src/constants.ts @@ -50,6 +50,7 @@ export const REST_LONG = `${PRODUCT_PREFIX} REST API`; export const REST_SHORT = 'REST API'; export const MCP_LONG = `${PRODUCT_PREFIX} MCP`; export const MCP_SHORT = `${PRODUCT_PREFIX} MCP`; +export const CLI_REPO_URL = 'https://github.com/timescale/tiger-cli'; export const AGENTS_LONG = `${PRODUCT_PREFIX} Agents for Work`; export const AGENTS_SHORT = `${PRODUCT_PREFIX} Agent`; export const AGENTS_CLI = `${AGENTS_SHORT} CLI`; diff --git a/src/content/docs/build/columnar-storage/setup-hypercore.mdx b/src/content/docs/build/columnar-storage/setup-hypercore.mdx index 616599368..dff0a4351 100644 --- 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"; @@ -27,6 +28,8 @@ your data. + + ## 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 index fdc884e48..f0b4615ba 100644 --- 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"; @@ -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. + + ## 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 index e8b6df8c6..bb0e6d9ad 100644 --- 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. + + ## 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 index 0af309d7d..013402647 100644 --- 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. + + ## 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 index 6b6c79b33..6777d026f 100644 --- 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. + + ## 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/migrate-to-new-form.mdx b/src/content/docs/build/continuous-aggregates/migrate-to-new-form.mdx index 17bfff3cd..a70839acf 100644 --- a/src/content/docs/build/continuous-aggregates/migrate-to-new-form.mdx +++ b/src/content/docs/build/continuous-aggregates/migrate-to-new-form.mdx @@ -8,6 +8,7 @@ keywords: [continuous aggregates, migrate] import * as C from "@constants"; import { Callout } from "@stainless-api/docs/components"; import CaggMigratePermissions from "../../../../partials/_caggs-migrate-permissions.mdx"; +import DoWithAi from "@components/DoWithAi.astro"; Starting in {C.TIMESCALE_DB} v2.7, {C.CAGG}s use a newer format that performs better and supports more SQL. {C.CAGG_CAP}s created before that release, or created with `timescaledb.finalized` set to `false`, still use the legacy layout until you migrate. @@ -15,6 +16,8 @@ To migrate a {C.CAGG} from the old format to the new format, you can use this procedure. It automatically copies over your data and policies. You can continue to use the {C.CAGG} while the migration is happening. + + This procedure applies to {C.TIMESCALE_DB} v2.24 and earlier. In v2.25, the old format has been fully removed. See the [release notes](https://github.com/timescale/timescaledb/blob/main/CHANGELOG.md#2250-2026-01-29). diff --git a/src/content/docs/build/continuous-aggregates/refresh-policies.mdx b/src/content/docs/build/continuous-aggregates/refresh-policies.mdx index 771b9b089..de6e1018e 100644 --- a/src/content/docs/build/continuous-aggregates/refresh-policies.mdx +++ b/src/content/docs/build/continuous-aggregates/refresh-policies.mdx @@ -10,6 +10,7 @@ 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. @@ -17,6 +18,8 @@ Refresh policies control how and when a materialized {C.CAGG} catches up with it + + ## 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 index 8750d0996..0e873f9a7 100644 --- 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,6 +9,7 @@ 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. @@ -16,6 +17,8 @@ import { Prerequisites } from "@components/Prerequisites"; + + ## 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 index d619a79b7..57ee07f1a 100644 --- 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. + + ## 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 index cc7a1b505..ce5f85b8a 100644 --- 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. + + 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 index bd7a6dc8d..0031f1878 100644 --- 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}. + + 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/example-tiered-storage.mdx b/src/content/docs/build/data-management/example-tiered-storage.mdx index b10aa1d1d..f2079cd04 100644 --- a/src/content/docs/build/data-management/example-tiered-storage.mdx +++ b/src/content/docs/build/data-management/example-tiered-storage.mdx @@ -8,12 +8,15 @@ keywords: [jobs, tablespaces] import * as C from "@constants"; import { Callout } from "@stainless-api/docs/components"; import { NumberedList, NumberedItem } from "@components/NumberedList"; +import DoWithAi from "@components/DoWithAi.astro"; Moving older data to a different tablespace can help you save on storage costs. {C.TIMESCALE_DB} supports automatic tablespace management by providing the `move_chunk` function to move {C.CHUNK}s between tablespaces. To schedule the moves automatically, you can write a custom {C.JOB}. + + On {C.CLOUD_LONG}, use [tiered storage](/build/data-management/storage/manage-storage) which handles this by providing a [tiering policy API](/build/data-management/storage/manage-storage#automate-tiering-with-policies) to move data to low-cost object storage backed by Amazon S3 and Azure Blob storage. 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 index 5309a6736..2ef65f27f 100644 --- 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}. + + ## 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 index c96b17315..3a01d8f89 100644 --- 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. + + ## Basic query examples Here are some examples of basic `SELECT` queries. diff --git a/src/content/docs/build/data-management/storage/manage-storage.mdx b/src/content/docs/build/data-management/storage/manage-storage.mdx index ae381c378..dbe3657d2 100644 --- a/src/content/docs/build/data-management/storage/manage-storage.mdx +++ b/src/content/docs/build/data-management/storage/manage-storage.mdx @@ -16,6 +16,7 @@ import TieredStorageBilling from "../../../../../partials/_tiered-storage-billin import { Image } from "astro:assets"; import imgHighPerformanceStorageTigerConsole from "../../../../../assets/images/build/data-management/high-performance-storage-tiger-console.png"; import imgEnableTieredStorageTigerConsole from "../../../../../assets/images/build/data-management/enable-tiered-storage-tiger-console.png"; +import DoWithAi from "@components/DoWithAi.astro"; Tiering splits hot data on fast local volumes from cold data in cheaper object storage. {C.CLOUD_LONG} implements that as a high-performance tier plus a low-cost object storage tier: @@ -27,6 +28,8 @@ You can query the data on the object storage tier, but you cannot modify it. Mak + + ## High-performance storage tier By default, {C.CLOUD_LONG} stores your {C.SERVICE_SHORT} data in the standard high-performance storage. This gives you up to 64 TB of storage and a configurable IOPS value to better suit your needs: diff --git a/src/content/docs/build/data-management/write-data/delete.mdx b/src/content/docs/build/data-management/write-data/delete.mdx index d1046a565..e01f3acb1 100644 --- a/src/content/docs/build/data-management/write-data/delete.mdx +++ b/src/content/docs/build/data-management/write-data/delete.mdx @@ -6,9 +6,12 @@ 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}. When you need to age out large ranges, dropping {C.CHUNK}s or using a retention policy is usually cheaper than massive `DELETE` scans. + + ## 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 index 939c1f962..887dc646e 100644 --- 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: @@ -26,6 +27,8 @@ Inserts into a {C.HYPERTABLE} are normal {C.PG} writes. Use the usual commands, To improve performance, insert time series data directly to the {C.COLUMNSTORE} using [direct compress](#improve-performance-with-direct-compress). + + ## 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 index 5a994da5b..4c1d90140 100644 --- 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. + + ## Update a single row Update a single row with the syntax `UPDATE ... SET ... WHERE`. For example, to diff --git a/src/content/docs/build/data-management/write-data/upsert.mdx b/src/content/docs/build/data-management/write-data/upsert.mdx index 411ab19b2..888a5206e 100644 --- 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 + + ## Upsert, unique indexes, and constraints Upserts work when you have a unique index or constraint. A matching row is one that has identical values for the columns diff --git a/src/content/docs/build/examples/hybrid-search.mdx b/src/content/docs/build/examples/hybrid-search.mdx index d1c3b524f..4642000c0 100644 --- 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. @@ -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). - + -{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). diff --git a/src/content/docs/build/how-to/basic-compression.mdx b/src/content/docs/build/how-to/basic-compression.mdx index 00e3cf991..2e01e40db 100644 --- 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. + + ## 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. diff --git a/src/content/docs/build/how-to/your-first-hypertable.mdx b/src/content/docs/build/how-to/your-first-hypertable.mdx index be7280e34..352b27a84 100644 --- 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. + + ## 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 new file mode 100644 index 000000000..f277bf5ba --- /dev/null +++ b/src/content/docs/build/tiger-cli-mcp/agent-best-practices.mdx @@ -0,0 +1,64 @@ +--- +title: Best practices for AI agents +description: Use Tiger MCP and Tiger CLI safely with AI agents, including read-only mode, forks and replicas, and effective prompting +products: [cloud] +keywords: [Tiger MCP, read-only, agents, Claude Code, safety] +--- + +import * as C from "@constants"; +import { Callout } from "@stainless-api/docs/components"; + +{C.MCP_LONG} lets an AI agent act on your {C.CLOUD_LONG} {C.SERVICE_SHORT}s: create and fork {C.SERVICE_SHORT}s, run queries, and change data. This page covers how to keep that safe and get better results. New to these tools? See [{C.CLI_LONG} and {C.MCP_LONG}](/learn/tiger-cli-mcp). + +## Restrict agents to read-only + +When you want an agent to explore and query without making any changes, enable read-only mode: + +```bash +tiger config set read_only true +``` + +When read-only mode is on: + +- Mutating {C.MCP_SHORT} tools and {C.CLI_SHORT} commands (`service create`, `fork`, `start`, `stop`, `resize`, `update-password`, and `delete`) are refused. +- Database sessions run in {C.CLOUD_LONG}'s immutable read-only mode, so writes and schema changes (DDL) are rejected by the server. +- Read operations, such as listing {C.SERVICE_SHORT}s and running `SELECT` queries, still work. + +To restrict a single session without changing your saved configuration, set the environment variable instead: + +```bash +TIGER_READ_ONLY=true tiger mcp start +``` + +Turn read-only mode back off with `tiger config unset read_only`. + + +Keep production {C.SERVICE_SHORT}s in read-only mode and only escalate to write access deliberately, for the specific change you intend to make. + + +For an additional layer of security, create a dedicated read-only database role and connect the agent using that role's credentials. Because the restriction is enforced by the database itself, it applies no matter how the agent connects. See [Manage data security in your {C.SERVICE_LONG}](/deploy/tiger-cloud/tiger-cloud-aws/security/read-only-role#create-a-read-only-user). + +## Test against a fork or a read replica + +For exploratory or agent-driven work, point the agent at a copy of your data instead of production: + +- **Fork** a {C.SERVICE_SHORT} to get an isolated, writable copy you can experiment on and then discard. See [Common tasks](/build/tiger-cli-mcp/common-tasks#fork-a-service-to-test-safely). +- **Read replica**: connect the agent to a replica so exploration never touches the primary. + +## Have the database do the work + +Agents sometimes pull large result sets to the client and process them locally, which is slow and can expose more data than needed. Get better results by: + +- Asking for a single computed answer (an aggregate, a ratio, a yes/no) rather than raw rows. +- Setting explicit limits in your prompt, for example "return at most 50 rows." +- Asking the agent to show the SQL it will run so you can verify it before it executes. + +## Guardrails for coding agents + +When you use an agent like Claude Code against your database, add project instructions (for example, in `CLAUDE.md`) that state which {C.SERVICE_SHORT}s are production, that production is read-only, and which {C.PROJECT_SHORT} to use. This reduces mistakes when an agent switches context. + +## Next steps + +- [Common tasks with {C.CLI_LONG} and {C.MCP_LONG}](/build/tiger-cli-mcp/common-tasks): Manage services and work with your data from the CLI or your agent. +- [Integrate Tiger Cloud with your AI agent](/get-started/quickstart/mcp-cli): Set up {C.MCP_LONG} and connect it to your AI agent. +- [File an issue in the {C.CLI_LONG} repo](https://github.com/timescale/tiger-cli): Report bugs or request features to help shape the open-source {C.CLI_LONG} and {C.MCP_LONG}. \ No newline at end of file diff --git a/src/content/docs/build/tiger-cli-mcp/common-tasks.mdx b/src/content/docs/build/tiger-cli-mcp/common-tasks.mdx new file mode 100644 index 000000000..f49e74d57 --- /dev/null +++ b/src/content/docs/build/tiger-cli-mcp/common-tasks.mdx @@ -0,0 +1,77 @@ +--- +title: Common tasks with Tiger CLI and Tiger MCP +description: Manage services and work with your data in Tiger Cloud using Tiger CLI commands or Tiger MCP natural-language prompts +products: [cloud] +keywords: [Tiger CLI, Tiger MCP, create service, fork, hypertable, query, optimize] +--- + +import * as C from "@constants"; +import { Callout } from "@stainless-api/docs/components"; + +{C.CLI_LONG} and {C.MCP_LONG} let you work with {C.CLOUD_LONG} in complementary ways. With {C.CLI_LONG} you run commands in a terminal, which is precise, scriptable, and repeatable. With {C.MCP_LONG} you ask your AI agent in plain language: it runs the same service and data operations, and it can also reason about your database using built-in skills. + +There are two levels to work at: managing your services, which has no SQL, and working with your data, which is all SQL. The examples below show the {C.CLI_SHORT} way, and the equivalent {C.MCP_SHORT} prompt. New to these tools? See [{C.CLI_LONG} and {C.MCP_LONG}](/learn/tiger-cli-mcp). + + +[Install {C.CLI_LONG} and connect your AI agent](/get-started/quickstart/tiger-cli) first. Commands and tools can change between releases, so run `tiger --help` for the current {C.CLI_SHORT}, and see the [{C.CLI_LONG} reference](/reference/tiger-cloud/tiger-cli) and [{C.MCP_LONG} reference](/reference/tiger-cloud/tiger-mcp). For agent safety, see [best practices for AI agents](/build/tiger-cli-mcp/agent-best-practices). + + +## Manage your services + +Every service task is a `tiger service` command in the CLI, and the MCP has a matching tool, so you can instead just describe what you want: + +| Task | CLI command | Ask your agent | +| --- | --- | --- | +| Create a service | `tiger service create --name analytics --region us-east-1` | _"Create a time-series service called analytics in us-east-1."_ | +| Fork a service to test a change safely | `tiger service fork --now` | _"Fork service abc123 so I can test a schema change."_ | +| Resize a service | `tiger service resize --cpu 4 --memory 16` | _"Resize service abc123 to 4 CPU and 16 GB."_ | +| Start or stop a service | `tiger service start `, `tiger service stop ` | _"Stop service abc123."_ | +| Rotate the database password | `tiger service update-password ` | _"Reset the password on service abc123."_ | +| List, inspect, and check logs | `tiger service list`, `tiger service get `, `tiger service logs --tail 100` | _"List my services and show recent logs for abc123."_ | + +For the full walkthroughs, see [create a service](/get-started/quickstart/create-service), [fork services](/deploy/tiger-cloud/tiger-cloud-aws/service-management/fork-services), [change compute resources](/deploy/tiger-cloud/tiger-cloud-aws/service-management/change-resources), and [service management](/deploy/tiger-cloud/tiger-cloud-aws/service-management/service-management). + +## Work with your data + +Everything inside the database is SQL. With {C.CLI_LONG}, open a session and run it (add `--read-only` for a session that blocks writes): + +```bash +tiger db connect +``` + +With {C.MCP_LONG}, you skip the connection and describe the task, and the agent runs the SQL against the {C.SERVICE_SHORT} you name. + +For example, to create a hypertable: + +```sql +CREATE TABLE metrics ( + time timestamptz NOT NULL, + device text, + value double precision +) WITH (tsdb.hypertable, tsdb.partition_column = 'time'); +``` + +Or ask _"Create a hypertable called metrics partitioned by time, with device and value columns."_ + +The same pattern covers the rest of your everyday data work. Run the SQL yourself, or describe it to your agent: + +- Query your data, for example _"What is the hourly average value in metrics over the last day?"_ See [Query data](/build/data-management/query-data/select). +- Load data from a file with `\COPY`, or ask your agent to add small amounts, for example _"Insert a few sample rows into metrics for testing."_ For bulk loads, see [Import data](/migrate/import-terminal). +- Roll up a continuous aggregate, for example _"Create a continuous aggregate on metrics for hourly averages per device."_ See [Continuous aggregates](/build/continuous-aggregates/create-a-continuous-aggregate). +- Add compression and retention, for example _"Convert metrics chunks older than 7 days to the columnstore and drop data older than 30 days."_ See [Hypercore](/build/columnar-storage/setup-hypercore) and [retention](/build/data-management/data-retention/create-a-retention-policy). + +## Analyze, design, and optimize with Tiger MCP + +Some data work goes beyond running SQL. Using its built-in skills, {C.MCP_LONG} can reason about your database, which the {C.CLI_SHORT} cannot do. Because these tasks are read and advice oriented, they work in [read-only mode](/build/tiger-cli-mcp/agent-best-practices): + +- Design a schema: _"Design a Tiger Cloud schema for storing IoT device telemetry."_ See [Design your data model](/learn/data-model/design-your-data-model). +- Find hypertable candidates: _"Analyze my database and tell me which tables should be hypertables."_ See [Choose your migration approach](/migrate/choose-your-approach). +- Review and optimize: _"Review my schema and indexes against best practices and suggest improvements."_ See [Improve hypertable performance](/build/performance-optimization/improve-hypertable-performance). +- Plan a schema change: _"Plan a zero-downtime migration to add a status column to metrics, and test it on a fork first."_ See [Alter table schema](/build/performance-optimization/alter-update-table-schema). + +## Next steps + +- [Best practices for AI agents](/build/tiger-cli-mcp/agent-best-practices): Use read-only mode, forks, and guardrails to work safely with agents. +- [{C.CLI_LONG} reference](/reference/tiger-cloud/tiger-cli): Every command, flag, and configuration parameter. +- [{C.MCP_LONG} reference](/reference/tiger-cloud/tiger-mcp): Every MCP tool and its parameters. +- [File an issue in the {C.CLI_LONG} repo](https://github.com/timescale/tiger-cli): Report bugs or request features to help shape the open-source {C.CLI_LONG} and {C.MCP_LONG}. \ No newline at end of file diff --git a/src/content/docs/deploy/tiger-cloud/tiger-cloud-AWS/security/read-only-role.mdx b/src/content/docs/deploy/tiger-cloud/tiger-cloud-AWS/security/read-only-role.mdx index 9a21ee06d..8b2f0fbfc 100644 --- a/src/content/docs/deploy/tiger-cloud/tiger-cloud-AWS/security/read-only-role.mdx +++ b/src/content/docs/deploy/tiger-cloud/tiger-cloud-AWS/security/read-only-role.mdx @@ -5,6 +5,9 @@ products: [cloud] --- import SecurityReadOnlyRole from "../../../../../../partials/_security-read-only-role.mdx" +import ReadOnlyRoleVsAgentMode from "../../../../../../partials/_read-only-role-vs-agent-mode.mdx" + + {/* Anchors for headings defined in the imported partial, required for link validation */} diff --git a/src/content/docs/deploy/tiger-cloud/tiger-cloud-AWS/service-management/change-resources.mdx b/src/content/docs/deploy/tiger-cloud/tiger-cloud-AWS/service-management/change-resources.mdx index b46074e04..3614c2e26 100644 --- a/src/content/docs/deploy/tiger-cloud/tiger-cloud-AWS/service-management/change-resources.mdx +++ b/src/content/docs/deploy/tiger-cloud/tiger-cloud-AWS/service-management/change-resources.mdx @@ -4,6 +4,30 @@ description: Scale compute resources for a Tiger Cloud service with minimal down products: [cloud] --- +import * as C from "@constants"; +import { Tabs, TabItem } from "@astrojs/starlight/components"; +import DoWithAi from "@components/DoWithAi.astro"; import ChangeResources from "../../../../../../partials/_change-resources.mdx"; - \ No newline at end of file +Change the CPU and memory allocated to a {C.SERVICE_SHORT} from {C.CONSOLE} or {C.CLI_LONG}. + + + + + + + + + + + +Resize a {C.SERVICE_SHORT} to a new CPU and memory allocation: + +```bash +tiger service resize --cpu 4 --memory 16 +``` + +Resizing affects billing, and the {C.SERVICE_SHORT} may be briefly unavailable while the change applies. To wait until the resize completes, add `--wait`. Run `tiger service resize --help` for current flags, or see the [{C.CLI_LONG} reference](/reference/tiger-cloud/tiger-cli). + + + \ No newline at end of file diff --git a/src/content/docs/deploy/tiger-cloud/tiger-cloud-AWS/service-management/service-management.mdx b/src/content/docs/deploy/tiger-cloud/tiger-cloud-AWS/service-management/service-management.mdx index d83e1158c..f29f265f9 100644 --- a/src/content/docs/deploy/tiger-cloud/tiger-cloud-AWS/service-management/service-management.mdx +++ b/src/content/docs/deploy/tiger-cloud/tiger-cloud-AWS/service-management/service-management.mdx @@ -4,11 +4,30 @@ description: Manage your service lifecycle from the Operations dashboard products: [cloud] --- +import * as C from "@constants"; +import { Tabs, TabItem } from "@astrojs/starlight/components"; +import DoWithAi from "@components/DoWithAi.astro"; import ServiceManagement from "../../../../../../partials/_service-management.mdx"; +import ServiceManagementCli from "../../../../../../partials/_service-management-cli.mdx"; + +Manage the lifecycle of your {C.SERVICE_SHORT} from {C.CONSOLE} or {C.CLI_LONG}. + + {/* Anchors for headings defined in the imported partial, required for link validation */} - \ No newline at end of file + + + + + + + + + + + + \ No newline at end of file diff --git a/src/content/docs/deploy/tiger-cloud/tiger-cloud-azure/security/read-only-role.mdx b/src/content/docs/deploy/tiger-cloud/tiger-cloud-azure/security/read-only-role.mdx index 809bf2ab8..0e1e2e4e3 100644 --- a/src/content/docs/deploy/tiger-cloud/tiger-cloud-azure/security/read-only-role.mdx +++ b/src/content/docs/deploy/tiger-cloud/tiger-cloud-azure/security/read-only-role.mdx @@ -5,5 +5,8 @@ products: [cloud] --- import SecurityReadOnlyRole from "../../../../../../partials/_security-read-only-role.mdx" +import ReadOnlyRoleVsAgentMode from "../../../../../../partials/_read-only-role-vs-agent-mode.mdx" + + \ No newline at end of file diff --git a/src/content/docs/deploy/tiger-cloud/tiger-cloud-azure/service-management/change-resources.mdx b/src/content/docs/deploy/tiger-cloud/tiger-cloud-azure/service-management/change-resources.mdx index 1b536bfd3..e39e05106 100644 --- a/src/content/docs/deploy/tiger-cloud/tiger-cloud-azure/service-management/change-resources.mdx +++ b/src/content/docs/deploy/tiger-cloud/tiger-cloud-azure/service-management/change-resources.mdx @@ -4,6 +4,30 @@ description: Resize compute resources for your Tiger Cloud service with minimal products: [cloud] --- +import * as C from "@constants"; +import { Tabs, TabItem } from "@astrojs/starlight/components"; +import DoWithAi from "@components/DoWithAi.astro"; import ChangeResources from "../../../../../../partials/_change-resources.mdx"; - \ No newline at end of file +Change the CPU and memory allocated to a {C.SERVICE_SHORT} from {C.CONSOLE} or {C.CLI_LONG}. + + + + + + + + + + + +Resize a {C.SERVICE_SHORT} to a new CPU and memory allocation: + +```bash +tiger service resize --cpu 4 --memory 16 +``` + +Resizing affects billing, and the {C.SERVICE_SHORT} may be briefly unavailable while the change applies. To wait until the resize completes, add `--wait`. Run `tiger service resize --help` for current flags, or see the [{C.CLI_LONG} reference](/reference/tiger-cloud/tiger-cli). + + + \ No newline at end of file diff --git a/src/content/docs/deploy/tiger-cloud/tiger-cloud-azure/service-management/service-management.mdx b/src/content/docs/deploy/tiger-cloud/tiger-cloud-azure/service-management/service-management.mdx index 3256c7732..5d30cb073 100644 --- a/src/content/docs/deploy/tiger-cloud/tiger-cloud-azure/service-management/service-management.mdx +++ b/src/content/docs/deploy/tiger-cloud/tiger-cloud-azure/service-management/service-management.mdx @@ -4,6 +4,25 @@ description: Manage your Tiger Cloud service lifecycle in Tiger Console products: [cloud] --- +import * as C from "@constants"; +import { Tabs, TabItem } from "@astrojs/starlight/components"; +import DoWithAi from "@components/DoWithAi.astro"; import ServiceManagement from "../../../../../../partials/_service-management.mdx"; +import ServiceManagementCli from "../../../../../../partials/_service-management-cli.mdx"; - \ No newline at end of file +Manage the lifecycle of your {C.SERVICE_SHORT} from {C.CONSOLE} or {C.CLI_LONG}. + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/content/docs/get-started/news/new.mdx b/src/content/docs/get-started/news/new.mdx index 74368d9b9..36db0b9ad 100644 --- a/src/content/docs/get-started/news/new.mdx +++ b/src/content/docs/get-started/news/new.mdx @@ -781,7 +781,7 @@ For complete details, refer to the [TimescaleDB 2.25 release notes](https://gith

CLI and MCP walkthrough in Tiger Console

@@ -1066,7 +1066,7 @@ Major improvements to the S3 source connector with better observability includin

AI and Tiger Cloud major changes!

### Free pricing plan and free services diff --git a/src/content/docs/get-started/quickstart/cli-rest-api.mdx b/src/content/docs/get-started/quickstart/cli-rest-api.mdx deleted file mode 100644 index 81d90899c..000000000 --- a/src/content/docs/get-started/quickstart/cli-rest-api.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Get started with the command line -description: Manage the resources in your Tiger Cloud project using the Tiger CLI or REST API -products: [cloud] -sidebar: - order: 2 ---- - -import * as C from "@constants"; -import { Tabs, TabItem } from "@astrojs/starlight/components"; - -import CLIGetStarted from "../../../../partials/_devops-cli-get-started.mdx"; -import RESTGetStarted from "../../../../partials/_devops-rest-api-get-started.mdx"; - -{C.COMPANY} supplies a clean, programmatic control layer for {C.CLOUD_LONG}. This includes REST APIs and CLI commands -that enable humans, machines, and AI agents to easily provision, configure, and manage {C.SERVICE_LONG}s programmatically. - - - - - - - - - - - - - - - - diff --git a/src/content/docs/get-started/quickstart/create-service.mdx b/src/content/docs/get-started/quickstart/create-service.mdx index c7a804fb9..5175fc318 100644 --- a/src/content/docs/get-started/quickstart/create-service.mdx +++ b/src/content/docs/get-started/quickstart/create-service.mdx @@ -8,6 +8,7 @@ sidebar: import * as C from "@constants"; import { Tabs, TabItem } from "@astrojs/starlight/components"; +import { Callout } from "@stainless-api/docs/components"; import CloudIntro from "../../../../partials/_cloud-intro.mdx"; import ServiceIntro from "../../../../partials/_services-intro.mdx"; @@ -18,6 +19,10 @@ import Connect from "../../../../partials/_cloud-connect-service.mdx"; import InstallAzure from "../../../../partials/_cloud-installation-azure.mdx"; import StartUsingCloudAzure from "../../../../partials/_start-using-cloud-azure.mdx"; + +You can also create a {C.SERVICE_SHORT} from the command line with {C.CLI_LONG}. See [Get started with {C.CLI_LONG}](/get-started/quickstart/tiger-cli). + + diff --git a/src/content/docs/get-started/quickstart/mcp-cli.mdx b/src/content/docs/get-started/quickstart/mcp-cli.mdx index 15e8ad718..19213c1cc 100644 --- a/src/content/docs/get-started/quickstart/mcp-cli.mdx +++ b/src/content/docs/get-started/quickstart/mcp-cli.mdx @@ -1,6 +1,6 @@ --- -title: Integrate Tiger Cloud with your AI Assistant (MCP and CLI) -description: Install Tiger CLI, set up Tiger MCP, and manage Tiger Cloud resources from Claude, Cursor, and other AI assistants +title: Integrate Tiger Cloud with your AI Agent (MCP and CLI) +description: Install Tiger CLI, set up Tiger MCP, and manage Tiger Cloud resources from Claude, Cursor, and other AI agents products: [cloud] sidebar: order: 3 @@ -24,16 +24,16 @@ import { NumberedList, NumberedItem } from "@components/NumberedList"; import RESTPrereqs from "../../../../partials/_prereqs-cloud-account-only.mdx"; import { Prerequisites } from "@components/Prerequisites"; -{C.MCP_LONG} gives your AI assistant access to {C.CLOUD_LONG} so you can manage {C.SERVICE_SHORT}s and query your data using natural language. +{C.MCP_LONG} gives your AI agent access to {C.CLOUD_LONG} so you can manage {C.SERVICE_SHORT}s and query your data using natural language. For how {C.MCP_LONG} compares to {C.CLI_LONG} and where each fits, see [{C.CLI_LONG} and {C.MCP_LONG}](/learn/tiger-cli-mcp). -{C.MCP_LONG} is built into the {C.CLI_LONG} binary. It mirrors {C.CLI_SHORT} functionality and is wired to {C.COMPANY} documentation, so your AI assistant can answer questions with up-to-date guidance. This page walks you through installing {C.CLI_LONG}, configuring authentication for {C.MCP_LONG}, and managing {C.CLOUD_LONG} resources from your AI assistant. +{C.MCP_LONG} is built into the {C.CLI_LONG} binary. Alongside tools to manage {C.SERVICE_SHORT}s and run SQL, it includes built-in skills (for example, schema design, {C.HYPERTABLE} setup, and migration planning) and is wired to {C.COMPANY} documentation, so your AI agent can design, analyze, and recommend improvements with up-to-date guidance. This page walks you through installing {C.CLI_LONG}, configuring authentication for {C.MCP_LONG}, and managing {C.CLOUD_LONG} resources from your AI agent. -- An AI assistant installed on your machine with an active API key. +- An AI agent installed on your machine with an active API key. - The following AI assistants are **automatically** configured by {C.MCP_LONG}: + The following AI agents are **automatically** configured by {C.MCP_LONG}: - [`claude-code`](https://docs.anthropic.com/en/docs/claude-code) - [`cursor`](https://cursor.com) - [`windsurf`](https://windsurf.com) @@ -51,7 +51,7 @@ import { Prerequisites } from "@components/Prerequisites"; - In a terminal, install the {C.CLI_SHORT} using the method for your platform (see [Get started with the command line](/get-started/quickstart/cli-rest-api) for the latest install command). + In a terminal, install the {C.CLI_SHORT} using the method for your platform (see [Get started with Tiger CLI](/get-started/quickstart/tiger-cli) for the latest install instructions). @@ -104,14 +104,14 @@ import { Prerequisites } from "@components/Prerequisites"; -After this, you can use {C.MCP_LONG} from your AI assistant to manage {C.CLOUD_LONG}. +After this, you can use {C.MCP_LONG} from your AI agent to manage {C.CLOUD_LONG}. -## Manage {C.CLOUD_LONG} from your AI assistant +## Manage {C.CLOUD_LONG} from your AI agent -Once connected, you can manage {C.SERVICE_SHORT}s and learn best practices through your assistant. +Once connected, you can manage {C.SERVICE_SHORT}s and learn best practices through your agent. - + (For example, `claude`). It will start the {C.MCP_LONG} server and connect to {C.CLOUD_LONG}. @@ -128,20 +128,20 @@ Ask: _"Can you list my active {C.SERVICE_SHORT}s?"_ to see your {C.CLOUD_LONG} { -For example: _"Create a new AI {C.SERVICE_SHORT} called bob with a replica."_ The assistant will use {C.MCP_SHORT} tools to create the {C.SERVICE_SHORT}. +For example: _"Create a new AI {C.SERVICE_SHORT} called bob with a replica."_ The agent will use {C.MCP_SHORT} tools to create the {C.SERVICE_SHORT}. -For example: _"I need to migrate a database with 25 million rows to {C.CLOUD_LONG}; what {C.SERVICE_SHORT} optimizations should I do before migration?"_ The assistant can use docs and tools to give tailored advice. +For example: _"I need to migrate a database with 25 million rows to {C.CLOUD_LONG}; what {C.SERVICE_SHORT} optimizations should I do before migration?"_ The agent can use docs and tools to give tailored advice. ## Restrict {C.MCP_LONG} to read-only -If you want your AI assistant to explore and query {C.SERVICE_SHORT}s without changing anything, enable read-only mode: +If you want your AI agent to explore and query {C.SERVICE_SHORT}s without changing anything, enable read-only mode: ```bash tiger config set read_only true @@ -178,10 +178,16 @@ If your MCP client isn't supported by `tiger mcp install`, add {C.MCP_LONG} manu Config key names (for example, `mcpServers`) and structure depend on your - client. See your AI assistant's MCP documentation for the exact format and + client. See your AI agent's MCP documentation for the exact format and where to place the file. ## Reference For the full list of {C.MCP_SHORT} tools and `tiger mcp` commands, see the [{C.MCP_LONG} reference](/reference/tiger-cloud/tiger-mcp). For every {C.CLI_SHORT} command, configuration parameter, and global flag, see the [{C.CLI_LONG} reference](/reference/tiger-cloud/tiger-cli). + +## Next steps + +- [Common tasks with {C.CLI_LONG} and {C.MCP_LONG}](/build/tiger-cli-mcp/common-tasks): Manage services and work with your data from the CLI or your agent. +- [Best practices for AI agents](/build/tiger-cli-mcp/agent-best-practices): Use read-only mode, forks, and guardrails to work safely. +- [File an issue in the {C.CLI_LONG} repo](https://github.com/timescale/tiger-cli): Report bugs or request features to help shape the open-source {C.CLI_LONG} and {C.MCP_LONG}. diff --git a/src/content/docs/get-started/quickstart/quickstart-5-minutes.mdx b/src/content/docs/get-started/quickstart/quickstart-5-minutes.mdx index 81b4ef862..0ea73e95c 100644 --- a/src/content/docs/get-started/quickstart/quickstart-5-minutes.mdx +++ b/src/content/docs/get-started/quickstart/quickstart-5-minutes.mdx @@ -19,6 +19,10 @@ For a more extensive lesson on what {C.HYPERTABLE}s are and why they matter, see - A [{C.CLOUD_LONG} account](https://console.cloud.tigerdata.com/) + +Prefer the terminal? You can also create and manage {C.SERVICE_SHORT}s with [{C.CLI_LONG}](/get-started/quickstart/tiger-cli). + + ## Step 1: Create a {C.SERVICE_SHORT} @@ -100,7 +104,7 @@ We'll create a small **{C.HYPERTABLE}** (a table optimized for time-series data) ## Next steps -- **[Integrate {C.CLOUD_LONG} with your AI assistant](/get-started/quickstart/mcp-cli)**: Set up Tiger MCP and manage your {C.SERVICE_SHORT} from Claude, Cursor, and other AI assistants. +- **[Integrate {C.CLOUD_LONG} with your AI agent](/get-started/quickstart/mcp-cli)**: Set up Tiger MCP and manage your {C.SERVICE_SHORT} from Claude, Cursor, and other AI agents. - **[Your first {C.HYPERTABLE}](/build/how-to/your-first-hypertable)**: Go deeper with {C.HYPERTABLE}s, {C.CHUNK}s, and time-series queries. - **[Write and query data](/build/data-management)**: Learn how to write, query, and manage your time-series data. - **[Deploy](/deploy)**: Configure, secure, and manage your {C.CLOUD_LONG} deployment. diff --git a/src/content/docs/get-started/quickstart/rest-api.mdx b/src/content/docs/get-started/quickstart/rest-api.mdx new file mode 100644 index 000000000..d53af61c5 --- /dev/null +++ b/src/content/docs/get-started/quickstart/rest-api.mdx @@ -0,0 +1,16 @@ +--- +title: Get started with the REST API +description: Manage the resources in your Tiger Cloud project programmatically with the Tiger Cloud REST API +products: [cloud] +sidebar: + order: 3 +--- + +import * as C from "@constants"; +import RESTGetStarted from "../../../../partials/_devops-rest-api-get-started.mdx"; + +Use {C.REST_LONG} to build your own integrations or when you need language-native access from an application. The [{C.CLI_LONG}](/get-started/quickstart/tiger-cli) is a convenience wrapper over this API. For how the REST API, {C.CLI_LONG}, and {C.MCP_LONG} compare, see [{C.CLI_LONG} and {C.MCP_LONG}](/learn/tiger-cli-mcp). + + + +For every endpoint, parameter, and response, see the [{C.CLOUD_LONG} REST API reference](/reference/tiger-cloud-rest). \ No newline at end of file diff --git a/src/content/docs/get-started/quickstart/tiger-cli.mdx b/src/content/docs/get-started/quickstart/tiger-cli.mdx new file mode 100644 index 000000000..3957c2a8b --- /dev/null +++ b/src/content/docs/get-started/quickstart/tiger-cli.mdx @@ -0,0 +1,22 @@ +--- +title: Get started with Tiger CLI +description: Install Tiger CLI and manage the resources in your Tiger Cloud project from the command line +products: [cloud] +sidebar: + order: 2 +--- + +import * as C from "@constants"; +import CLIGetStarted from "../../../../partials/_devops-cli-get-started.mdx"; + +{C.CLI_LONG} is a command-line interface for managing {C.CLOUD_LONG} programmatically. It lets you, your scripts, and AI agents provision, configure, and manage {C.SERVICE_LONG}s. {C.CLI_LONG} calls {C.REST_LONG} under the hood and bundles {C.MCP_LONG} for AI agents. For how these compare and where each fits, see [{C.CLI_LONG} and {C.MCP_LONG}](/learn/tiger-cli-mcp). + + + +## Next steps + +- [Integrate Tiger Cloud with your AI agent](/get-started/quickstart/mcp-cli): Set up {C.MCP_LONG} so your AI agent can manage services and run queries. +- [Common tasks with {C.CLI_LONG} and {C.MCP_LONG}](/build/tiger-cli-mcp/common-tasks): Manage services and work with your data from the terminal or your agent. +- [Get started with the REST API](/get-started/quickstart/rest-api): Manage the same resources over raw HTTP for custom integrations. +- [{C.CLI_LONG} reference](/reference/tiger-cloud/tiger-cli): Every command, flag, and configuration parameter. +- [File an issue in the {C.CLI_LONG} repo](https://github.com/timescale/tiger-cli): Report bugs or request features to help shape the open-source {C.CLI_LONG} and {C.MCP_LONG}. \ No newline at end of file diff --git a/src/content/docs/integrate/find-connection-details.mdx b/src/content/docs/integrate/find-connection-details.mdx index b2010d65a..274005dc2 100644 --- a/src/content/docs/integrate/find-connection-details.mdx +++ b/src/content/docs/integrate/find-connection-details.mdx @@ -70,7 +70,7 @@ Once you have these, connect using any {C.PG} client. Find the connection method You use client credentials to obtain access tokens outside of the user context. To retrieve the connection details for your {C.CLOUD_LONG} {C.PROJECT_SHORT} for programmatic usage - such as Terraform or the [{C.CLOUD_LONG} REST API](/get-started/quickstart/cli-rest-api): + such as Terraform or the [{C.CLOUD_LONG} REST API](/get-started/quickstart/rest-api): diff --git a/src/content/docs/learn/tiger-cli-mcp/index.mdx b/src/content/docs/learn/tiger-cli-mcp/index.mdx new file mode 100644 index 000000000..c8c1bffe3 --- /dev/null +++ b/src/content/docs/learn/tiger-cli-mcp/index.mdx @@ -0,0 +1,68 @@ +--- +title: Tiger CLI and Tiger MCP +description: Understand Tiger CLI and Tiger MCP, how they compare to the REST API, and where they fit in your development lifecycle +products: [cloud] +keywords: [Tiger CLI, Tiger MCP, AI agent, REST API] +--- + +import * as C from "@constants"; +import { Callout } from "@stainless-api/docs/components"; + +{C.CLI_LONG} and {C.MCP_LONG} give you, your scripts, and your AI agent a programmatic control layer for {C.CLOUD_LONG}. Instead of clicking through {C.CONSOLE_SHORT}, you provision, configure, query, and manage {C.SERVICE_SHORT}s from your terminal or directly from tools like Claude Code, Cursor, and Codex. + +This page explains what each tool is, how they relate, and where they fit in your workflow. To install and start using them, see [Get started with Tiger CLI](/get-started/quickstart/tiger-cli) and [Integrate Tiger Cloud with your AI agent](/get-started/quickstart/mcp-cli). + +## What each tool is + +- **{C.CLI_LONG}**: a single binary that manages {C.CLOUD_LONG} resources, including {C.SERVICE_SHORT}s, read replicas, VPCs, and related infrastructure. It is scriptable and verifiable, which makes it a good fit for automation, CI/CD, and day-to-day operations. {C.CLI_LONG} calls {C.REST_LONG} under the hood. +- **{C.MCP_LONG}**: a Model Context Protocol server bundled inside the {C.CLI_LONG} binary. It gives your AI agent tools to manage {C.SERVICE_SHORT}s and run SQL, plus built-in skills (for example, schema design, {C.HYPERTABLE} setup, and migration planning) and access to {C.COMPANY} documentation. Beyond running operations, it can design schemas, analyze your database, and recommend improvements in plain language. +- **{C.REST_LONG}**: the underlying HTTP API. Use it directly when you build your own integrations or need language-native access from an application. + + +{C.MCP_LONG} ships inside {C.CLI_LONG}, so a single `tiger` install gives you the command line and the MCP server. Both authenticate the same way and respect the same permissions. + + +## When to use which + +| You want to... | Use | +| --- | --- | +| Script, automate, or run repeatable operations (CI/CD, pipelines) | {C.CLI_LONG} | +| Work in natural language, or get design, analysis, and optimization help | {C.MCP_LONG} | +| Build a custom integration or app in your own language | {C.REST_LONG} | + +### They are complementary, not the same + +{C.CLI_LONG} and {C.MCP_LONG} share authentication and can perform many of the same operations, but they are not interchangeable: + +- Only {C.MCP_LONG} can **reason about your database**. Using its built-in skills and the documentation, it designs schemas, finds {C.HYPERTABLE} candidates, plans migrations, and recommends improvements in plain language. The {C.CLI_SHORT} has no command for this. +- Only {C.CLI_LONG} gives you **deterministic, scriptable execution**: interactive `psql` sessions, connection strings, and repeatable commands for automation and CI/CD. {C.MCP_SHORT} runs one statement at a time and, as an AI agent, is non-deterministic. + +Use {C.MCP_LONG} for exploration, design, and analysis, and {C.CLI_LONG} for automation and precise, repeatable operations. Many workflows combine them: let an agent explore and suggest changes with {C.MCP_SHORT}, then apply and verify them with {C.CLI_SHORT}. + +## Where they fit in your lifecycle + +{C.CLI_LONG} and {C.MCP_LONG} support each stage of working with {C.CLOUD_LONG}: + +1. **Get started and set up**: install the tools, authenticate, and connect your AI agent. +1. **Build**: create {C.SERVICE_SHORT}s, design {C.HYPERTABLE}s, add continuous aggregates, and configure jobs and policies. +1. **Validate**: ask your agent to review a schema against best practices, or fork a {C.SERVICE_SHORT} to test a change safely. +1. **Operate day to day**: run queries, manage credentials, resize, and inspect service state. +1. **Monitor and debug**: pull logs and investigate performance without leaving your terminal or agent. + +## Use agents safely + +Because {C.MCP_LONG} can act on your database, control what an agent is allowed to do: + +- Enable **read-only mode** so an agent can explore and query without making changes. See [Best practices for AI agents](/build/tiger-cli-mcp/agent-best-practices). +- Point agents at a **read replica or a fork** for exploratory work, so production is never at risk. +- Prefer having the database do the work: ask for a single answer computed in-database rather than exporting raw rows to the client. + +## Next steps + +- [Get started with Tiger CLI](/get-started/quickstart/tiger-cli): Install the CLI, authenticate, and create your first {C.SERVICE_SHORT} from the terminal. +- [Integrate Tiger Cloud with your AI agent](/get-started/quickstart/mcp-cli): Set up {C.MCP_LONG} and connect it to Claude Code, Cursor, or another agent. +- [Get started with the REST API](/get-started/quickstart/rest-api): Manage the same resources over raw HTTP for custom integrations. +- [Common tasks with Tiger CLI and Tiger MCP](/build/tiger-cli-mcp/common-tasks): Manage services and work with your data, with the CLI command and MCP prompt for each. +- [Best practices for AI agents](/build/tiger-cli-mcp/agent-best-practices): Use read-only mode, forks, and guardrails to work safely with agents. +- [Tiger CLI reference](/reference/tiger-cloud/tiger-cli) and [Tiger MCP reference](/reference/tiger-cloud/tiger-mcp): Every command, tool, flag, and parameter. +- [File an issue in the {C.CLI_LONG} repo](https://github.com/timescale/tiger-cli): Report bugs or request features to help shape the open-source {C.CLI_LONG} and {C.MCP_LONG}. \ No newline at end of file diff --git a/src/content/docs/reference/index.mdx b/src/content/docs/reference/index.mdx index 358a03520..61a0ec8e8 100644 --- a/src/content/docs/reference/index.mdx +++ b/src/content/docs/reference/index.mdx @@ -33,5 +33,5 @@ Everything you need to manage {C.CLOUD_LONG} {C.SERVICE_SHORT}s programmatically - [Data tiering](/reference/tiger-cloud/data-tiering): SQL functions that move older {C.CHUNK}s to low-cost object storage while keeping them queryable. - [{C.CLI_LONG}](/reference/tiger-cloud/tiger-cli): every {C.CLI_LONG} command, configuration parameter, and global flag. -- [{C.MCP_LONG}](/reference/tiger-cloud/tiger-mcp): the {C.MCP_LONG} tools and `tiger mcp` commands that let your AI assistant manage {C.CLOUD_LONG}. +- [{C.MCP_LONG}](/reference/tiger-cloud/tiger-mcp): the {C.MCP_LONG} tools and `tiger mcp` commands that let your AI agent manage {C.CLOUD_LONG}. - [{C.REST_LONG}](/reference/tiger-cloud-rest): create, resize, and configure {C.SERVICE_SHORT}s over HTTP. \ No newline at end of file diff --git a/src/content/docs/reference/tiger-cloud/index.mdx b/src/content/docs/reference/tiger-cloud/index.mdx index a0008c06e..134579405 100644 --- a/src/content/docs/reference/tiger-cloud/index.mdx +++ b/src/content/docs/reference/tiger-cloud/index.mdx @@ -23,7 +23,7 @@ import { CardGroup, Card } from '@stainless-api/docs/stainless-docs/mintlify-com - The {C.MCP_LONG} tools and `tiger mcp` commands that let your AI assistant manage {C.CLOUD_LONG} + The {C.MCP_LONG} tools and `tiger mcp` commands that let your AI agent manage {C.CLOUD_LONG} diff --git a/src/content/docs/reference/tiger-cloud/tiger-cli.mdx b/src/content/docs/reference/tiger-cloud/tiger-cli.mdx index f91d0c305..92383fed0 100644 --- a/src/content/docs/reference/tiger-cloud/tiger-cli.mdx +++ b/src/content/docs/reference/tiger-cloud/tiger-cli.mdx @@ -13,6 +13,8 @@ import CLIREF from "../../../../partials/_devops-cli-reference.mdx"; {C.CLI_LONG} is a command-line interface that you use to manage {C.CLOUD_LONG} resources including VPCs, {C.SERVICE_SHORT}s, read replicas, and related infrastructure. {C.CLI_LONG} calls {C.REST_LONG} to communicate with {C.CLOUD_LONG}. -To install {C.CLI_SHORT}, configure authentication, and create your first {C.SERVICE_SHORT}, see [Get started with the command line](/get-started/quickstart/cli-rest-api). This page is the reference for every {C.CLI_SHORT} command and configuration parameter. +To install {C.CLI_SHORT}, configure authentication, and create your first {C.SERVICE_SHORT}, see [Get started with Tiger CLI](/get-started/quickstart/tiger-cli). This page is the reference for every {C.CLI_SHORT} command and configuration parameter. For an overview of {C.CLI_LONG} and {C.MCP_LONG}, see [{C.CLI_LONG} and {C.MCP_LONG}](/learn/tiger-cli-mcp). + +{C.CLI_LONG} (which bundles {C.MCP_LONG}) is open source. [File an issue in the repo](https://github.com/timescale/tiger-cli) to report bugs or request features and help shape the product. \ No newline at end of file diff --git a/src/content/docs/reference/tiger-cloud/tiger-mcp.mdx b/src/content/docs/reference/tiger-cloud/tiger-mcp.mdx index 33f233b13..40b80313b 100644 --- a/src/content/docs/reference/tiger-cloud/tiger-mcp.mdx +++ b/src/content/docs/reference/tiger-cloud/tiger-mcp.mdx @@ -2,28 +2,25 @@ title: Tiger MCP reference sidebar: label: Tiger MCP -description: Tool and command reference for Tiger MCP, the Model Context Protocol server bundled with Tiger CLI -keywords: [Tiger MCP, MCP, reference, tools, AI assistant] +description: Tool reference for Tiger MCP, the Model Context Protocol server bundled with Tiger CLI +keywords: [Tiger MCP, MCP, reference, tools, AI agent] products: [cloud] --- import * as C from "@constants"; import MCPCommands from "../../../../partials/_devops-mcp-commands.mdx"; -import MCPCommandsCLI from "../../../../partials/_devops-mcp-commands-cli.mdx"; -{C.MCP_LONG} gives your AI assistant access to {C.CLOUD_LONG} so you can manage {C.SERVICE_SHORT}s and query your data using natural language. It is built into the {C.CLI_LONG} binary and mirrors {C.CLI_SHORT} functionality. +{C.MCP_LONG} gives your AI agent access to {C.CLOUD_LONG} so you can manage {C.SERVICE_SHORT}s and query your data in natural language. It is built into the {C.CLI_LONG} binary. -To install and configure {C.MCP_LONG} for your AI assistant, see [Integrate Tiger Cloud with your AI assistant](/get-started/quickstart/mcp-cli). This page is the reference for the {C.MCP_SHORT} tools and the `tiger mcp` commands that control them. +To install and configure {C.MCP_LONG} for your AI agent, see [Integrate Tiger Cloud with your AI agent](/get-started/quickstart/mcp-cli). This page is the reference for the {C.MCP_SHORT} tools your agent can call. For an overview of {C.MCP_LONG} and {C.CLI_LONG}, see [{C.CLI_LONG} and {C.MCP_LONG}](/learn/tiger-cli-mcp). ## {C.MCP_LONG} tools -## {C.CLI_LONG} commands for {C.MCP_SHORT} +## Manage the {C.MCP_SHORT} server - +To install, list, inspect, and start {C.MCP_LONG}, use the `tiger mcp` commands, documented in the [{C.CLI_LONG} reference](/reference/tiger-cloud/tiger-cli#mcp). Global flags that apply when running {C.MCP_SHORT} are in the [configuration parameters](/reference/tiger-cloud/tiger-cli#configuration-parameters). -## Global flags - -When running {C.CLI_LONG} (including {C.MCP_SHORT} commands), you can use the global flags documented in the [{C.CLI_LONG} reference](/reference/tiger-cloud/tiger-cli). \ No newline at end of file +{C.MCP_LONG} ships inside the open-source {C.CLI_LONG}. [File an issue in the repo](https://github.com/timescale/tiger-cli) to report bugs or request features and help shape the product. \ No newline at end of file diff --git a/src/partials/_devops-cli-install.mdx b/src/partials/_devops-cli-install.mdx index a40f8664c..aadf40d3d 100644 --- a/src/partials/_devops-cli-install.mdx +++ b/src/partials/_devops-cli-install.mdx @@ -7,6 +7,14 @@ import { NumberedList, NumberedItem } from "@components/NumberedList"; Use the terminal to install the {C.CLI_SHORT}: + + + ```shell + brew install --cask timescale/tap/tiger-cli + ``` + + + ```shell @@ -42,14 +50,6 @@ Use the terminal to install the {C.CLI_SHORT}: - - - ```shell - brew install --cask timescale/tap/tiger-cli - ``` - - - ```shell diff --git a/src/partials/_devops-cli-reference.mdx b/src/partials/_devops-cli-reference.mdx index 31fc09b5a..cf5d081cd 100644 --- a/src/partials/_devops-cli-reference.mdx +++ b/src/partials/_devops-cli-reference.mdx @@ -3,77 +3,344 @@ import * as C from "@constants"; import GLOBALFLAGS from "./_devops-cli-global-flags.mdx"; import CONFIGOPTIONS from "./_devops-cli-config-options.mdx"; -## Commands - -You can use the following commands with {C.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 {C.ACCOUNT_LONG} | -| | login | Create an authenticated connection to your {C.ACCOUNT_LONG}. For non-interactive login, use flags:
  • `--public-key`: public key for authentication
  • `--secret-key`: secret key for authentication
You can also use environment variables `TIGER_PUBLIC_KEY`, `TIGER_SECRET_KEY`, and `TIGER_PROJECT_ID` | -| | logout | Remove the credentials used to create authenticated connections to {C.CLOUD_LONG} | -| | status | Show your current authentication status and project ID. Possible flags are:
  • `--output, -o`: set output format to `json`, `yaml`, or `table`
| -| version | | Show information about the currently installed version of {C.CLI_LONG}. Possible flags are:
  • `--check`: force check for updates (regardless of last check time)
  • `--output, -o`: set output format to `table`, `json`, `yaml`, or `bare`
| -| config | | Manage your {C.CLI_LONG} configuration | -| | show | Show the current configuration. Possible flags are:
  • `--output, -o`: set output format to `json`, `yaml`, or `table`
  • `--no-defaults`: do not show default values for unset fields
  • `--with-env`: apply environment variable overrides
| -| | 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 {C.PROJECT_LONG} | -| service | | Manage the {C.SERVICE_LONG}s in this {C.PROJECT_SHORT} | -| | create | Create a new {C.SERVICE_SHORT} in this {C.PROJECT_SHORT}. Possible flags are:
  • `--name`: service name (auto-generated if not provided)
  • `--addons`: addons to enable. Possible values are `time-series`, `ai`. Set to `none` for vanilla {C.PG}
  • `--region`: region code where the service will be deployed. Free services (shared CPU/memory) must use `us-east-1`
  • `--cpu`: CPU allocation in millicores. Set to `shared` to create a free service. See the allowed CPU/memory configurations below.
  • `--memory`: memory allocation in gigabytes. Set to `shared` to create a free service. See the allowed CPU/memory configurations below.
  • `--replicas`: number of high-availability replicas
  • `--environment`: environment tag. Possible values: `DEV`, `PROD` (default: `DEV`)
  • `--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`: set the output format to `json`, `yaml`, `env`, or `table`

Allowed CPU/memory configurations are:
  • shared / shared (only available in `us-east-1`)
  • 0.5 CPU (500m) / 2GB
  • 1 CPU (1000m) / 4GB
  • 2 CPU (2000m) / 8GB
  • 4 CPU (4000m) / 16GB
  • 8 CPU (8000m) / 32GB
  • 16 CPU (16000m) / 64GB
  • 32 CPU (32000m) / 128GB
Note: You can specify both CPU and memory together, or specify only one (the other will be automatically configured). | -| | delete `` | Delete a {C.SERVICE_SHORT} from this {C.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 (exactly one required):
    • `--now`: fork at current database state
    • `--last-snapshot`: fork at last existing snapshot (faster)
    • `--to-timestamp`: fork at specific point in time (RFC3339 format)
  • Resource configuration:
    • `--cpu`: CPU allocation in millicores. Set to `shared` to create a free service. If not specified, inherits from source service. See the allowed CPU/memory configurations in the `create` subcommand
    • `--memory`: memory allocation in gigabytes. Set to `shared` to create a free service. If not specified, inherits from source service. See the allowed CPU/memory configurations in the `create` subcommand
  • Naming and environment:
    • `--name `: defaults to `{source-service-name}-fork`
    • `--environment`: environment tag. Possible values: `DEV`, `PROD` (default: `DEV`)
  • Wait behavior:
    • `--no-wait`: don't wait for operation to complete
    • `--wait-timeout`: wait timeout duration (default: 30m)
  • Default service and output:
    • `--no-set-default`: don't set forked service as default
    • `--with-password`: include password in output
    • `--output, -o`: set output format to `json`, `yaml`, `env`, or `table`
| -| | get ``
aliases: `describe`, `show` | Show detailed information about a specific {C.SERVICE_SHORT} in this {C.PROJECT_SHORT}. Possible flags are:
  • `--with-password`: include password in output
  • `--output, -o`: set output format to `json`, `yaml`, `env`, or `table`
| -| | list | List all the {C.SERVICE_SHORT}s in this {C.PROJECT_SHORT}. Possible flags are:
  • `--output, -o`: set output format to `json`, `yaml`, or `table`
| -| | update-password `` | Update the master password for a {C.SERVICE_SHORT}. Possible flags are:
  • `--new-password`: new password for the tsdbadmin user
  • `--auto-generate`: auto-generate a secure password (mutually exclusive with `--new-password`)
| -| | start `` | Start a {C.SERVICE_SHORT} that is currently inactive. Possible flags are:
  • `--no-wait`: don't wait for the operation to complete
  • `--wait-timeout`: set the maximum wait time for this operation to complete. For example, `10m` (default), `30m`, `1h30m`, `90s`
| -| | stop `` | Stop a {C.SERVICE_SHORT} that is currently active. After you run this command `` no longer accepts connections. Possible flags are:
  • `--no-wait`: don't wait for the operation to complete
  • `--wait-timeout`: set the maximum wait time for this operation to complete. For example, `10m` (default), `30m`, `1h30m`, `90s`
| -| | resize `` | Resize a {C.SERVICE_SHORT} by changing CPU and memory allocation. The service may be temporarily unavailable during the resize operation. Possible flags are:
  • `--cpu`: CPU allocation in millicores. See the allowed CPU/memory configurations in the `create` subcommand
  • `--memory`: memory allocation in gigabytes. See the allowed CPU/memory configurations in the `create` subcommand
  • `--no-wait`: don't wait for the operation to complete
  • `--wait-timeout`: set the maximum wait time for this operation to complete. For example, `10m` (default), `30m`, `1h30m`, `90s`
Note: You can specify both `--cpu` and `--memory` together, or specify only one (the other will be automatically configured). | -| | logs ``
alias: `log` | View logs for a {C.SERVICE_SHORT}. Log lines are colorized by severity when the global `--color` flag is enabled (default). Possible flags are:
  • `--tail`: number of log lines to show (default: `100`)
  • `--since`: fetch logs after this timestamp (RFC3339 format, for example `2024-01-15T09:00:00Z`)
  • `--until`: fetch logs before this timestamp (RFC3339 format, for example `2024-01-15T10:00:00Z`)
  • `--node`: fetch logs from a specific service node by ordinal. Omit this flag to fetch logs from the current primary
  • `--output, -o`: set output format to `text`, `json`, or `yaml` (default: `text`)
| -| db | | Database operations and management | -| | connect `` | Connect to a {C.SERVICE_SHORT} using psql. Possible flags are:
  • `--pooled`: use connection pooling (default: `false`)
  • `--role`: database role/username (default: `tsdbadmin`)
  • `--read-only`: open the session in {C.CLOUD_LONG}'s immutable read-only mode, so writes and DDL are rejected by the server. The global [`read_only` config option](#configuration-parameters), or `TIGER_READ_ONLY=true`, also forces this behavior
You can also pass additional flags to psql after `--`. For example: `tiger db connect -- --single-transaction --quiet` | -| | connection-string `` | Retrieve the connection string for a {C.SERVICE_SHORT}. Possible flags are:
  • `--pooled`: use connection pooling (default: `false`)
  • `--role`: database role/username (default: `tsdbadmin`)
  • `--with-password`: include password in connection string (default: `false`, less secure)
  • `--read-only`: emit a connection string that opens the session in {C.CLOUD_LONG}'s immutable read-only mode, so writes and DDL are rejected by the server. The global [`read_only` config option](#configuration-parameters), or `TIGER_READ_ONLY=true`, also forces this behavior
| -| | create role `` | Create a new database role. Possible flags are:
  • `--name` (required): the name for the role you are creating
  • `--read-only`: enable permanent read-only enforcement for `--name` using `tsdb_admin.read_only_role`
  • `--from`: inherit grants from one or more roles. For example, `--from app_role`, `--from readonly_role`, `--from app_role,readonly_role`
  • `--statement-timeout`: set the statement timeout for `--name`. For example, `30s`, `5m`
  • `--password`: set the password for `--name`. If not provided, the CLI checks the `TIGER_NEW_PASSWORD` environment variable. If you have not defined `TIGER_NEW_PASSWORD` the CLI auto-generates a secure random password.
  • `-o, --output`: set the output format to `json`, `yaml`, or `table`
| -| | save-password `` | Save the password for a service. Possible flags are:
  • `--role`: database role/username (default: `tsdbadmin`)
  • `--password`: password value (you can also use the `TIGER_NEW_PASSWORD` environment variable)
| -| | test-connection `` | Test the connectivity to a {C.SERVICE_SHORT}. Possible flags are:
  • `--timeout, -t`: connection timeout (default: `3s`, use `0` for no timeout)
  • `--pooled`: use connection pooling (default: `false`)
  • `--role`: database role/username (default: `tsdbadmin`)
| -| mcp | | Manage {C.MCP_LONG} for AI Assistant integration | -| | install `[client]` | Install and configure {C.MCP_LONG} for a specific client. Supported clients: `claude-code`, `codex`, `cursor`, `gemini`, `vscode`, `windsurf`. If no client is specified, you'll be prompted to select one interactively | -| | list | List all available {C.MCP_SHORT} tools, prompts, and resources. Possible flags are:
  • `--output, -o`: set output format to `json`, `yaml`, or `table`
| -| | get ``
aliases: `describe`, `show` | Get detailed information about a specific {C.MCP_SHORT} capability (tool, prompt, or resource). Possible flags are:
  • `--output, -o`: set output format to `json`, `yaml`, or `table`
| -| | start | Start {C.MCP_LONG}. This is the same as `tiger mcp start stdio` | -| | start stdio | Start {C.MCP_LONG} with stdio transport (default) | -| | start http | Start {C.MCP_LONG} with HTTP transport. Includes flags: `--port` (default: `8080`), `--host` (default: `localhost`) | +Use the following commands to manage {C.CLOUD_LONG} from the terminal. Every command supports `-h` for inline help, for example `tiger service create -h`. +## Authentication +### `tiger auth login` + +Create an authenticated connection to your {C.ACCOUNT_LONG}. This opens a browser to authorize. For non-interactive login, pass credentials as flags. + +```bash +tiger auth login +``` + +- `--public-key`: public key for non-interactive login. +- `--secret-key`: secret key for non-interactive login. + +You can also set the `TIGER_PUBLIC_KEY`, `TIGER_SECRET_KEY`, and `TIGER_PROJECT_ID` environment variables. See [Authentication parameters](#authentication-parameters). + +### `tiger auth logout` + +Remove the credentials used to connect to {C.CLOUD_LONG}. + +```bash +tiger auth logout +``` + +### `tiger auth status` + +Show your current authentication status and {C.PROJECT_SHORT} ID. + +```bash +tiger auth status +``` + +- `--output, -o`: output format: `json`, `yaml`, or `table`. + +## Version + +### `tiger version` + +Show the installed {C.CLI_LONG} version. + +```bash +tiger version +``` + +- `--check`: force a check for updates, regardless of the last check time. +- `--output, -o`: output format: `table`, `json`, `yaml`, or `bare`. + +## Configuration + +### `tiger config show` + +Show the current configuration. + +```bash +tiger config show +``` + +- `--output, -o`: output format: `json`, `yaml`, or `table`. +- `--no-defaults`: do not show default values for unset fields. +- `--with-env`: apply environment variable overrides. + +### `tiger config set` + +Set a configuration value. See [Configuration parameters](#configuration-parameters) for the available keys. + +```bash +tiger config set +# for example +tiger config set read_only true +``` + +### `tiger config unset` + +Clear a configuration value. + +```bash +tiger config unset +``` + +### `tiger config reset` + +Reset the configuration to defaults. This also logs you out of the current {C.PROJECT_LONG}. + +```bash +tiger config reset +``` + +## Services + +### `tiger service create` + +Create a new {C.SERVICE_SHORT} in the current {C.PROJECT_SHORT}. + +```bash +tiger service create --name analytics --region us-east-1 +``` + +- `--name`: service name (auto-generated if omitted). +- `--addons`: addons to enable: `time-series`, `ai`. Set to `none` for vanilla {C.PG}. +- `--region`: region code. Free services (shared CPU/memory) must use `us-east-1`. +- `--cpu`: CPU allocation in millicores. Set to `shared` for a free service. +- `--memory`: memory allocation in gigabytes. Set to `shared` for a free service. +- `--replicas`: number of high-availability replicas. +- `--environment`: environment tag: `DEV` or `PROD` (default: `DEV`). +- `--no-wait`: return without waiting for the operation to complete. +- `--wait-timeout`: wait timeout (for example, `30m`, `1h30m`, `90s`). +- `--no-set-default`: do not set this service as the default. +- `--with-password`: include the password in the output. +- `--output, -o`: output format: `json`, `yaml`, `env`, or `table`. + +Allowed compute configurations: `shared`/`shared` (only in `us-east-1`), 0.5 CPU/2 GB, 1/4, 2/8, 4/16, 8/32, 16/64, 32/128. Specify `--cpu` and `--memory` together, or set one and the other is configured automatically. + +### `tiger service list` + +List the {C.SERVICE_SHORT}s in the current {C.PROJECT_SHORT}. + +```bash +tiger service list +``` + +- `--output, -o`: output format: `json`, `yaml`, or `table`. + +### `tiger service get` + +Show detailed information about a {C.SERVICE_SHORT}. Aliases: `describe`, `show`. + +```bash +tiger service get +``` + +- `--with-password`: include the password in the output. +- `--output, -o`: output format: `json`, `yaml`, `env`, or `table`. + +### `tiger service fork` + +Fork an existing {C.SERVICE_SHORT} into a new, independent copy. Choose exactly one timing option. + +```bash +tiger service fork --now +``` + +- `--now`: fork at the current database state. +- `--last-snapshot`: fork at the last snapshot (faster). +- `--to-timestamp`: fork at a point in time (RFC3339). +- `--cpu`, `--memory`: compute for the fork (inherits from the source if omitted). See [`service create`](#tiger-service-create) for allowed configurations. +- `--name`: fork name (default: `{source-service-name}-fork`). +- `--environment`: environment tag: `DEV` or `PROD` (default: `DEV`). +- `--no-wait`, `--wait-timeout`: wait behavior (default timeout: `30m`). +- `--no-set-default`, `--with-password`, `--output, -o`: default-service and output options. + +### `tiger service resize` + +Change a {C.SERVICE_SHORT}'s CPU and memory. The service may be briefly unavailable during the resize. + +```bash +tiger service resize --cpu 4 --memory 16 +``` + +- `--cpu`, `--memory`: new allocation. See [`service create`](#tiger-service-create) for allowed configurations. +- `--no-wait`, `--wait-timeout`: wait behavior (default timeout: `10m`). + +### `tiger service start` + +Start an inactive {C.SERVICE_SHORT}. + +```bash +tiger service start +``` + +- `--no-wait`, `--wait-timeout`: wait behavior (default timeout: `10m`). + +### `tiger service stop` + +Stop an active {C.SERVICE_SHORT}. After stopping, the service no longer accepts connections. + +```bash +tiger service stop +``` + +- `--no-wait`, `--wait-timeout`: wait behavior (default timeout: `10m`). + +### `tiger service update-password` + +Update the master password for a {C.SERVICE_SHORT}. + +```bash +tiger service update-password +``` + +- `--new-password`: new password for the `tsdbadmin` user. +- `--auto-generate`: auto-generate a secure password (mutually exclusive with `--new-password`). + +### `tiger service delete` + +Delete a {C.SERVICE_SHORT}. This is irreversible and requires confirmation by typing the service ID. + +```bash +tiger service delete +``` + +## Database + +### `tiger db connect` + +Connect to a {C.SERVICE_SHORT} with `psql`. Pass extra `psql` flags after `--`, for example `tiger db connect -- --single-transaction`. + +```bash +tiger db connect +``` + +- `--pooled`: use connection pooling (default: `false`). +- `--role`: database role (default: `tsdbadmin`). +- `--read-only`: open the session in {C.CLOUD_LONG}'s immutable read-only mode, so writes and DDL are rejected by the server. The [`read_only` config option](#configuration-parameters) or `TIGER_READ_ONLY=true` forces the same behavior. + +### `tiger db connection-string` + +Print the connection string for a {C.SERVICE_SHORT}. + +```bash +tiger db connection-string +``` + +- `--pooled`: use connection pooling (default: `false`). +- `--role`: database role (default: `tsdbadmin`). +- `--with-password`: include the password (default: `false`, less secure). +- `--read-only`: emit a read-only connection string. + +### `tiger db create role` + +Create a database role. + +```bash +tiger db create role --name app_role +``` + +- `--name` (required): the role to create. +- `--read-only`: enforce permanent read-only for the role using `tsdb_admin.read_only_role`. +- `--from`: inherit grants from one or more roles, for example `--from app_role,readonly_role`. +- `--statement-timeout`: statement timeout for the role, for example `30s`, `5m`. +- `--password`: role password (falls back to `TIGER_NEW_PASSWORD`, otherwise auto-generated). +- `--output, -o`: output format: `json`, `yaml`, or `table`. + +### `tiger db save-password` + +Save the password for a {C.SERVICE_SHORT} to the keychain. + +```bash +tiger db save-password +``` + +- `--role`: database role (default: `tsdbadmin`). +- `--password`: password value (or use `TIGER_NEW_PASSWORD`). + +### `tiger db test-connection` + +Test connectivity to a {C.SERVICE_SHORT}. + +```bash +tiger db test-connection +``` + +- `--timeout, -t`: connection timeout (default: `3s`, `0` for none). +- `--pooled`: use connection pooling (default: `false`). +- `--role`: database role (default: `tsdbadmin`). + +## MCP + +### `tiger mcp install` + +Install and configure {C.MCP_LONG} for an AI agent. Supported clients: `claude-code`, `codex`, `cursor`, `gemini`, `vscode`, `windsurf`. If no client is given, you are prompted to choose. + +```bash +tiger mcp install claude-code +``` + +- `--no-backup`: do not back up the client's existing config before writing. +- `--config-path`: path to the client config file to update. + +### `tiger mcp list` + +List the available {C.MCP_SHORT} tools, prompts, and resources. + +```bash +tiger mcp list +``` + +- `--output, -o`: output format: `json`, `yaml`, or `table`. + +### `tiger mcp get` + +Show detailed information about a {C.MCP_SHORT} tool, prompt, or resource, including skills. Aliases: `describe`, `show`. + +```bash +tiger mcp get service_create +tiger mcp get setup-timescaledb-hypertables +``` + +- `--output, -o`: output format: `json`, `yaml`, or `table`. + +### `tiger mcp start` + +Start {C.MCP_LONG}. `tiger mcp start` is the same as `tiger mcp start stdio`. + +```bash +tiger mcp start +``` + +- `stdio`: stdio transport (default). +- `http`: HTTP transport, with `--port` (default: `8080`) and `--host` (default: `localhost`). ## Configuration parameters -By default, {C.CLI_LONG} stores your configuration in `~/.config/tiger/config.yaml`. The location of the config -directory can be adjusted via the `--config-dir` flag or the `TIGER_CONFIG_DIR` environment variable. +By default, {C.CLI_LONG} stores your configuration in `~/.config/tiger/config.yaml`. Change the config directory with the `--config-dir` flag or the `TIGER_CONFIG_DIR` environment variable. + +### Configuration options + +Set these with `tiger config set `: -- **Configuration options** + - You set the following configuration options using `tiger config set `: +### Global flags - +These flags are available on all commands and take precedence over both environment variables and configuration file values: -- **Global Flags** + - These flags are available on all commands and take precedence over both environment variables and configuration file values: +### Authentication parameters - +To authenticate without the interactive browser login, either set your [client credentials](https://console.cloud.tigerdata.com/dashboard/settings) as environment variables, then log in: -- **Authentication parameters** +```shell +TIGER_PUBLIC_KEY= TIGER_SECRET_KEY= TIGER_PROJECT_ID= \ +tiger auth login +``` - To authenticate without using the interactive login, either: - - Set the following parameters with your [client credentials](https://console.cloud.tigerdata.com/dashboard/settings), then `login`: - ```shell - TIGER_PUBLIC_KEY= TIGER_SECRET_KEY= TIGER_PROJECT_ID=\ - tiger auth login - ``` - - Add your [client credentials](https://console.cloud.tigerdata.com/dashboard/settings) to the `login` command: - ```shell - tiger auth login --public-key= --secret-key= --project-id= - ``` +Or pass them to the `login` command: +```shell +tiger auth login --public-key= --secret-key= --project-id= +``` \ No newline at end of file diff --git a/src/partials/_devops-mcp-commands-cli.mdx b/src/partials/_devops-mcp-commands-cli.mdx deleted file mode 100644 index 7dd9bb31f..000000000 --- a/src/partials/_devops-mcp-commands-cli.mdx +++ /dev/null @@ -1,12 +0,0 @@ -import * as C from "@constants"; - -Use these under the `tiger mcp` namespace. **Subcommands and flags may be updated in new {C.CLI_SHORT} releases.** - -| Command | Description | -|--------|-------------| -| `tiger mcp install [client]` | Configure {C.MCP_LONG} for a client (for example, `claude-code`, `cursor`, `windsurf`, `codex`, `gemini/gemini-cli`, `vscode/code/vs-code`). Flags: `--no-backup`, `--config-path`. | -| `tiger mcp list` | List {C.MCP_SHORT} tools, prompts, and resources. Optional: `--output` / `-o` (json, yaml, table). | -| `tiger mcp get ` | Details for one capability (for example, `tiger mcp get service_create` or `tiger mcp get setup-timescaledb-hypertables`). Aliases: `describe`, `show`. | -| `tiger mcp start` | Start {C.MCP_LONG} (same as `tiger mcp start stdio`). | -| `tiger mcp start stdio` | Start {C.MCP_SHORT} with stdio transport. | -| `tiger mcp start http` | Start {C.MCP_SHORT} with HTTP (for example, if your assistant doesn't support stdio). Flags: `--port` (default 8080), `--host` (default localhost). | \ No newline at end of file diff --git a/src/partials/_devops-mcp-commands.mdx b/src/partials/_devops-mcp-commands.mdx index f2d8502da..eeab50102 100644 --- a/src/partials/_devops-mcp-commands.mdx +++ b/src/partials/_devops-mcp-commands.mdx @@ -1,16 +1,90 @@ import * as C from "@constants"; +import { Callout } from "@stainless-api/docs/components"; -{C.MCP_LONG} exposes the following tools to your AI assistant. **Parameter names and required/optional fields may change with new {C.MCP_SHORT} versions**; use `tiger mcp get ` for current definitions. - -| Tool | Key parameters | Description | -|------|----------------|-------------| -| `service_list` | (none) | List {C.SERVICE_SHORT}s in the current {C.PROJECT_SHORT}. | -| `service_get` | `service_id` (required), `with_password` | Detailed info for one {C.SERVICE_SHORT}. Only set `with_password` if the user explicitly asks for the password. | -| `service_create` | `name`, `addons`, `region`, `cpu_memory`, `replicas`, `wait`, `timeout_minutes`, `set_default`, `with_password` | Create a new {C.SERVICE_SHORT}. **WARNING:** creates billable resources. Addons: `time-series` ({C.TIMESCALE_DB}), `ai` (AI/vector). | -| `service_fork` | `service_id` (required), `fork_strategy` (required: NOW \| LAST_SNAPSHOT \| PITR), `target_time` (for PITR), `name`, `cpu_memory`, `wait`, `timeout_minutes`, `set_default`, `with_password` | Fork a {C.SERVICE_SHORT}. **WARNING:** creates billable resources. | -| `service_update_password` | `service_id` (required), `password` (required) | Update `tsdbadmin` password; may disconnect existing sessions. | -| `service_start` | `service_id` (required), `wait`, `timeout_minutes` | Start a stopped {C.SERVICE_SHORT}. | -| `service_stop` | `service_id` (required), `wait`, `timeout_minutes` | Stop a running {C.SERVICE_SHORT}. | -| `service_resize` | `service_id` (required), `cpu_memory` (required), `wait`, `timeout_minutes` | Change CPU/memory. **WARNING:** affects billing; {C.SERVICE_SHORT} may be briefly unavailable. | -| `service_logs` | `service_id` (required), `tail`, `since`, `until`, `node` | Fetch {C.SERVICE_SHORT} logs (for example, tail length, time range, node). | -| `db_execute_query` | `service_id` (required), `query` (required), `parameters`, `timeout_seconds`, `role`, `pooled` | Run a single SQL statement. **WARNING:** can run destructive SQL (INSERT/UPDATE/DELETE/DDL). Multi-statement not supported. | \ No newline at end of file +{C.MCP_LONG} exposes the following tools to your AI agent. You do not call these directly; you describe what you want and the agent selects the tool. + + +Parameter names and required or optional fields can change with new {C.MCP_SHORT} versions. Run `tiger mcp get ` for the current definition of any tool. + + +## Service tools + +### `service_list` + +List the {C.SERVICE_SHORT}s in the current {C.PROJECT_SHORT}. No parameters. + +### `service_get` + +Show detailed information about one {C.SERVICE_SHORT}. + +- `service_id` (required): the target {C.SERVICE_SHORT}. +- `with_password`: include the password. Only set this if you explicitly ask for the password. + +### `service_create` + +Create a new {C.SERVICE_SHORT}. Addons: `time-series` ({C.TIMESCALE_DB}) and `ai` (AI/vector). + +- `name`, `addons`, `region`, `cpu_memory`, `replicas`, `wait`, `timeout_minutes`, `set_default`, `with_password`. + + +`service_create` provisions billable infrastructure. + + +### `service_fork` + +Fork a {C.SERVICE_SHORT} into an independent copy. + +- `service_id` (required): the source {C.SERVICE_SHORT}. +- `fork_strategy` (required): `NOW`, `LAST_SNAPSHOT`, or `PITR`. +- `target_time`: point in time, for `PITR`. +- `name`, `cpu_memory`, `wait`, `timeout_minutes`, `set_default`, `with_password`. + + +`service_fork` provisions billable infrastructure. + + +### `service_resize` + +Change a {C.SERVICE_SHORT}'s CPU and memory. + +- `service_id` (required), `cpu_memory` (required), `wait`, `timeout_minutes`. + + +`service_resize` affects billing, and the {C.SERVICE_SHORT} may be briefly unavailable. + + +### `service_start` + +Start a stopped {C.SERVICE_SHORT}. + +- `service_id` (required), `wait`, `timeout_minutes`. + +### `service_stop` + +Stop a running {C.SERVICE_SHORT}. + +- `service_id` (required), `wait`, `timeout_minutes`. + +### `service_update_password` + +Update the `tsdbadmin` password. May disconnect existing sessions. + +- `service_id` (required), `password` (required). + +### `service_logs` + +Fetch {C.SERVICE_SHORT} logs. + +- `service_id` (required), `tail`, `since`, `until`, `node`. + +## Database tools + +### `db_execute_query` + +Run a single SQL statement against a {C.SERVICE_SHORT}. + +- `service_id` (required), `query` (required), `parameters`, `timeout_seconds`, `role`, `pooled`. + + +`db_execute_query` can run `INSERT`, `UPDATE`, `DELETE`, and DDL. Multi-statement queries are not supported. In [read-only mode](/build/tiger-cli-mcp/agent-best-practices), writes and DDL are rejected by the server. + \ No newline at end of file diff --git a/src/partials/_read-only-role-vs-agent-mode.mdx b/src/partials/_read-only-role-vs-agent-mode.mdx new file mode 100644 index 000000000..d13267b7e --- /dev/null +++ b/src/partials/_read-only-role-vs-agent-mode.mdx @@ -0,0 +1,6 @@ +import * as C from "@constants"; +import { Callout } from "@stainless-api/docs/components"; + + +This page covers read-only {C.PG} roles, which limit a database user's privileges. To restrict what an AI agent can do through {C.MCP_LONG}, see [best practices for AI agents](/build/tiger-cli-mcp/agent-best-practices). + \ No newline at end of file diff --git a/src/partials/_service-management-cli.mdx b/src/partials/_service-management-cli.mdx new file mode 100644 index 000000000..44ec1cd9a --- /dev/null +++ b/src/partials/_service-management-cli.mdx @@ -0,0 +1,58 @@ +import * as C from "@constants"; +import { Callout } from "@stainless-api/docs/components"; + +Use `tiger service list` to find the ID of the {C.SERVICE_SHORT} you want to manage, then run the relevant command below. All commands require you to be [logged in](/get-started/quickstart/tiger-cli). + +## Reset your {C.SERVICE_SHORT} password + +To reset the password used to connect to your {C.SERVICE_SHORT}: + +```bash +tiger service update-password +``` + +Use `--new-password` to supply a password directly, or `--auto-generate` to let {C.CLI_SHORT} generate one for you: + +```bash +# Prompt for a new password interactively +tiger service update-password + +# Auto-generate a secure password +tiger service update-password --auto-generate +``` + +This updates the password for the `tsdbadmin` database user, not your {C.CONSOLE_SHORT} account. + + +Resetting the password immediately invalidates the old one. Any application, automation, or integration that connects with the previous credentials loses access until you update its connection details. + + +## Change the {C.SERVICE_SHORT} environment + +Changing the environment tag between `DEV` and `PROD` is only available from {C.CONSOLE}. See the {C.CONSOLE_SHORT} tab above. + +## Convert a free {C.SERVICE_SHORT} to a standard one + +Converting a free {C.SERVICE_SHORT} to a standard one is only available from {C.CONSOLE}. See the {C.CONSOLE_SHORT} tab above. + +## Pause a {C.SERVICE_SHORT} + +To stop a {C.SERVICE_SHORT} temporarily without deleting it: + +```bash +tiger service stop +``` + +The {C.SERVICE_SHORT} stops accepting connections. You are no longer billed for compute, but storage billing continues. To start the {C.SERVICE_SHORT} again: + +```bash +tiger service start +``` + +## Delete a {C.SERVICE_SHORT} + +Deleting a {C.SERVICE_SHORT} is irreversible and permanently removes it and all its data. {C.CLI_SHORT} requires you to confirm by typing the service ID: + +```bash +tiger service delete +``` \ No newline at end of file diff --git a/src/partials/_service-management.mdx b/src/partials/_service-management.mdx index 181efb351..4896aeea4 100644 --- a/src/partials/_service-management.mdx +++ b/src/partials/_service-management.mdx @@ -1,5 +1,6 @@ import * as C from "@constants"; import { NumberedList, NumberedItem } from "@components/NumberedList"; +import { Callout } from "@stainless-api/docs/components"; From the `Operations` dashboard, you can reset the password, change the environment, convert a free {C.SERVICE_SHORT} to a standard one, pause, or delete the {C.SERVICE_SHORT}. To fork a {C.SERVICE_SHORT}, see [Fork {C.SERVICE_SHORT}s](../service-management/fork-services). @@ -17,6 +18,10 @@ digest algorithm 5) are cryptographic authentication mechanisms. {C.CONSOLE_LONG uses SCRAM by default. It is more secure and strongly recommended. The MD5 option is provided for compatibility with older clients. + +Resetting the password immediately invalidates the old one. Any application, automation, or integration that connects with the previous credentials loses access until you update its connection details. Update every connection string that uses this {C.SERVICE_SHORT} before or right after you reset the password. + + ## Change the {C.SERVICE_SHORT} environment In {C.CLOUD_LONG}, you create {C.SERVICE_SHORT}s for the following environments: