docs: add ClickHouse migration troubleshooting tip

[isshaddad]

Adds troubleshooting tip for when ClickHouse migrations report "no migrations to run" but the schema is missing. This happens when the goose migration tracker is out of sync with the actual schema state.

---

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3247740

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Walkthrough

This change updates the self-hosting Docker troubleshooting docs: it replaces the previous guidance about "ERROR: schema "graphile_worker" does not exist" with instructions for a ClickHouse/goose migration mismatch where migrations report "no migrations to run" but the schema is missing. It instructs to exec into the webapp container, set the GOOSE environment variables, and run goose reset && goose up to sync the goose migration tracker. A Data Loss Warning was added noting that goose reset is destructive and should only be used in non-production environments with backups.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains what the change does but lacks the structured format required by the template, missing sections like Checklist, Testing, and Changelog.	Follow the repository's PR description template by adding Checklist items, Testing section, and Changelog details to provide complete context.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding ClickHouse migration troubleshooting guidance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/clickhouse-migration-troubleshooting

---

🧹 Recent nitpick comments

docs/self-hosting/docker.mdx (1)

359-363: Consider placing the warning before the destructive command instruction.

The <Warning> block currently sits below the line that tells users to run goose reset && goose up. A user scanning quickly may execute the command before reading the warning. Swapping the order makes the hazard visible first.

Also, the phrase "set the GOOSE env vars (from webapp startup logs)" is vague — listing the specific variable names (e.g. GOOSE_DRIVER, GOOSE_DBSTRING) or showing a short example would reduce user confusion.

✏️ Suggested rewrite

-- **ClickHouse migrations say "no migrations to run" but schema is missing.** The goose migration tracker is out of sync. Exec into the webapp container, set the GOOSE env vars (from webapp startup logs), and run `goose reset && goose up`.
-
-  <Warning>
-    **Data Loss Warning:** The `goose reset` command is destructive and will drop the entire schema. Make sure to backup your data and confirm you are running this in a non-production environment before executing this command.
-  </Warning>
+- **ClickHouse migrations say "no migrations to run" but schema is missing.** The goose migration tracker is out of sync with the actual schema state.
+
+  <Warning>
+    **Data Loss Warning:** The `goose reset` command is destructive and will drop the entire schema. Make sure to back up your ClickHouse data before proceeding. Only run this if you are comfortable with potential data loss or are working in a non-production environment.
+  </Warning>
+
+  To fix this, exec into the webapp container, set the GOOSE env vars (check the webapp startup logs for `GOOSE_DRIVER` and `GOOSE_DBSTRING`), and run `goose reset && goose up`.

📜 Recent review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a01e381 and 3247740.

📒 Files selected for processing (1)

• docs/self-hosting/docker.mdx

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-15T11:50:06.067Z
Learning: Applies to internal-packages/clickhouse/schema/**/*.sql : ClickHouse migrations must use Goose format with `-- +goose Up` and `-- +goose Down` markers

📚 Learning: 2026-01-15T11:50:06.067Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-15T11:50:06.067Z
Learning: Applies to internal-packages/clickhouse/schema/**/*.sql : ClickHouse migrations must use Goose format with `-- +goose Up` and `-- +goose Down` markers

Applied to files:

• docs/self-hosting/docker.mdx

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Analyze (javascript-typescript)

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 1 additional finding.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/self-hosting/docker.mdx`:
- Line 359: Update the ClickHouse migration troubleshooting note that suggests
running "goose reset && goose up" to include a clear, prominent data-loss
warning: explain that "goose reset" is destructive and drops schemas/tables,
instruct users to back up their ClickHouse data or confirm they are on a
non-production environment before running it, and recommend alternative steps
(inspect migration status, export schema/data, or test on a staging instance)
alongside the existing instruction to exec into the webapp container, set the
GOOSE environment variables from the webapp startup logs, and then run the goose
commands.

📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3bb9aac and a01e381.

📒 Files selected for processing (1)

• docs/self-hosting/docker.mdx

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-15T11:50:06.067Z
Learning: Applies to internal-packages/clickhouse/schema/**/*.sql : ClickHouse migrations must use Goose format with `-- +goose Up` and `-- +goose Down` markers

📚 Learning: 2026-01-15T11:50:06.067Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-15T11:50:06.067Z
Learning: Applies to internal-packages/clickhouse/schema/**/*.sql : ClickHouse migrations must use Goose format with `-- +goose Up` and `-- +goose Down` markers

Applied to files:

• docs/self-hosting/docker.mdx

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}