Skip to content

Build: add Tiger CLI/MCP task, safety, and cookbook pages - #407

Merged
atovpeko merged 5 commits into
mainfrom
atovpeko/cli-mcp-build
Jul 28, 2026
Merged

Build: add Tiger CLI/MCP task, safety, and cookbook pages#407
atovpeko merged 5 commits into
mainfrom
atovpeko/cli-mcp-build

Conversation

@atovpeko

@atovpeko atovpeko commented Jul 22, 2026 •
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Collaborator

Describe your changes

Carves the "build" section out of the CLI/MCP docs umbrella (#375), picking up after get-started, reference, and learn already merged. Adds a "Build with Tiger CLI and MCP" sidebar group with three new pages:

  • Common tasks: CLI command vs. MCP prompt, side by side, for service management and everyday SQL work.
  • Best practices for AI agents: read-only mode, forks vs. HA replicas, minimizing data movement, CLAUDE.md guardrails.
  • Cookbook: longer multi-step prompts (schema design, data analysis, performance comparison, safe fork testing, hypertable optimization, slow-query triage) adapted from timescale/pg-ai-cookbook, with links to the full recipes on GitHub.

Affected pages

Related Issues

Checklist before requesting a review

  • - This is ready for review. If not, raise as a draft PR
  • - I have reviewed my changes.
  • - I have confirmed the content is technically accurate.
  • - I have tested any code that is added or updated on the latest available version.
  • - I have confirmed the content is free of typos or grammar errors.
  • - I have verified all images and videos are clear and match production (or dev for unreleased features).
  • - I have checked the component kitchen sink for any visual breakage (only needed if you changed components, styles, or dependencies). A link to this PR's own preview appears under Affected pages once the build deploys.
  • - This references a feature that is public. If not, add a note and we can schedule the merge for after the feature release.

@atovpeko
Build: add Tiger CLI/MCP task, safety, and cookbook pages
205216b 
Carves the "build" section out of the CLI/MCP docs umbrella (#375),
picking up after get-started, reference, and learn already merged.
Adds a "Build with Tiger CLI and MCP" sidebar group with three new
pages (common tasks, agent best practices, and a cookbook adapted
from timescale/pg-ai-cookbook), a DoWithAi callout sprinkled across
the SQL task pages it applies to, and backfills the deferred
cross-links into the already-merged get-started/learn pages.

Every CLI command, MCP tool call, and SQL statement was verified
live against a real Tiger Cloud service, which surfaced and fixed a
few real issues: a hypertable created via the recommended WITH
syntax already carries a default columnstore policy, so the
cookbook's optimization recipe now removes it before adding a
custom one; the read-replica guidance was pointing at the wrong
feature (read-scaling replica sets instead of HA replicas, which is
what `tiger db connect` actually offers to connect to); and the
"read and advice oriented" framing around Tiger MCP's design/analysis
skills didn't hold for the fork-testing step, since forking is itself
blocked in read-only mode.
@vercel

vercel Bot commented Jul 22, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
tiger-data-docs Ready Ready Preview, Comment Jul 28, 2026 8:06am

@atovpeko
atovpeko marked this pull request as ready for review July 22, 2026 13:00
@atovpeko
atovpeko requested a review from a team July 22, 2026 13:00
@github-actions

github-actions Bot commented Jul 22, 2026

Copy link
Copy Markdown

✅ Checklist Complete

Thank you for taking the time to properly review your PR! All checklist items are complete.

@atovpeko
Remove DoWithAi where the agent genuinely can't do the task
67dbe32 
manage-storage.mdx: enabling tiered storage and changing IOPS are
Console-only (confirmed against the full CLI/MCP tool surface, no
equivalent exists), so the callout was pointing readers at an agent
workflow that doesn't exist for that part of the page.

migrate-to-new-form.mdx: this procedure only applies to TimescaleDB
v2.24 and earlier (removed in v2.25); Tiger Cloud runs 2.28.3, so no
Cloud service can ever be in the affected state.
@atovpeko
atovpeko requested review from Askir, antonum and ggodeke July 22, 2026 13:30
Askir
Askir approved these changes Jul 27, 2026
View reviewed changes

@Askir Askir left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The best practice page looks good, although i wonder if we have a bit too many pages now with info spread out thin across them.

There is the build pages:

  • common tasks (giving some sample commands)
  • Best practices (this one)
  • Cookbook (which contains some sample prompts)

The learn page about CLI and MCP which explains how they work.

The getting started pages with:

  • More sample commands on the first page
  • More install instructions on the second page and also the read only instructions
  • A REST API guide (but under the CLi/MCP topic?)

And then the reference pages of course for both the CLI and the MCP.

That's 9 separate pages spread out across the navigation and linking to each other, but imo it's hard to get an overview over "everything CLI/MCP". Took me 10 minutes to even compose this comment. Then again maybe the github repo is the more natural entry point and these are just additional details so its fine. Just some thoughts.

Comment thread src/content/docs/build/tiger-cli-mcp/agent-best-practices.mdx Outdated
@atovpeko
Merge branch 'main' into atovpeko/cli-mcp-build
96c9728 
Signed-off-by: Anastasiia Tovpeko <114177030+atovpeko@users.noreply.github.com>
@ggodeke

ggodeke commented Jul 27, 2026

Copy link
Copy Markdown
Contributor

Overall looks good! I think the replica piece is the only thing we should address before deploying. I agree with Jascha -- maybe in Q3 we can partner to flesh these out a bit more and help users get set up end-to-end with the CLI and MCP.

@atovpeko
atovpeko merged commit 8f27117 into main Jul 28, 2026
6 of 7 checks passed
@atovpeko
atovpeko deleted the atovpeko/cli-mcp-build branch July 28, 2026 08:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ggodeke ggodeke ggodeke approved these changes
@Askir Askir Askir approved these changes
@antonum antonum Awaiting requested review from antonum

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@atovpeko @ggodeke @Askir