fix(replication): detect misconfigered run replication publication and output helpful error messages

[ericallam]

Add validation for logical replication publication configuration. Helps diagnose an issue where runs are no longer replicated to clickhouse because of a configuration issue with the replication publication.

Problem

The LogicalReplicationClient only checked if a publication existed, not if it was correctly configured. This caused a silent failure where:

• Replication would start successfully
• Transaction boundaries (begin/commit) were received
• But no actual data changes were replicated

This happened when a publication existed but:

1. Had no tables associated with it
2. Was missing required actions (e.g., delete)

Solution

Added #validatePublicationConfiguration() method that validates:

• ✅ Publication includes the expected table
• ✅ Publication has all required actions configured

When validation fails, error messages include the exact SQL command to fix the issue:

Missing table:

Publication 'task_runs_to_clickhouse_v1_publication' exists but has NO TABLES configured. 
Expected table: "public.TaskRun". 
Run: ALTER PUBLICATION task_runs_to_clickhouse_v1_publication ADD TABLE "TaskRun";

Missing actions:

Publication 'task_runs_to_clickhouse_v1_publication' is missing required actions. 
Expected: [insert, update, delete], Current: [insert, update], Missing: [delete]. 
Run: ALTER PUBLICATION task_runs_to_clickhouse_v1_publication SET (publish = 'insert, update, delete');

This prevents silent data loss and makes debugging configuration issues much easier.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 040a214

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

A private method #validatePublicationConfiguration() was added to the LogicalReplicationClient to validate publication configuration details. The #createPublication() method was refactored to check publication existence, invoke validation if the publication exists, and handle validation errors through logging and event emission. The previous logic that automatically treated existing publications as valid was removed, replacing it with conditional validation-based logic that determines success or failure.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–25 minutes

• Behavioral logic changes: The #createPublication() method's control flow was significantly altered, requiring careful verification that the new validation-based approach handles all edge cases correctly.
• Error handling paths: New error handling with logging and event emission requires verification that errors are appropriately propagated and logged.
• Validation method: The new #validatePublicationConfiguration() method's implementation and its return contract (string | null) should be reviewed for correctness and consistency with the calling code.
• State management: Verify that the local variable storing the #doesPublicationExist() result is used correctly and that no redundant checks occur.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The pull request description is missing entirely. No checklist, testing notes, changelog, or other template sections were provided.	Add a comprehensive PR description following the template, including testing steps, a changelog entry, and confirmation of the contributing guide checklist.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding detection for misconfigured replication publications with improved error handling.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch ea-branch-106

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 341e27d and 040a214.

📒 Files selected for processing (1)

• internal-packages/replication/src/client.ts (2 hunks)

🧰 Additional context used

📓 Path-based instructions (3)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

**/*.{ts,tsx}: Use types over interfaces for TypeScript
Avoid using enums; prefer string unions or const objects instead

Files:

• internal-packages/replication/src/client.ts

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use function declarations instead of default exports

Files:

• internal-packages/replication/src/client.ts

**/*.{js,ts,jsx,tsx,json,md,css,scss}

📄 CodeRabbit inference engine (AGENTS.md)

Format code using Prettier

Files:

• internal-packages/replication/src/client.ts

🧬 Code graph analysis (1)

internal-packages/replication/src/client.ts (1)

internal-packages/replication/src/errors.ts (1)

• LogicalReplicationClientError (1-5)

⏰ 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). (23)

• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: units / internal / 🧪 Unit Tests: Internal (8, 8)
• GitHub Check: units / internal / 🧪 Unit Tests: Internal (5, 8)
• GitHub Check: units / internal / 🧪 Unit Tests: Internal (3, 8)
• GitHub Check: units / internal / 🧪 Unit Tests: Internal (4, 8)
• GitHub Check: units / internal / 🧪 Unit Tests: Internal (6, 8)
• GitHub Check: units / internal / 🧪 Unit Tests: Internal (1, 8)
• GitHub Check: units / internal / 🧪 Unit Tests: Internal (7, 8)
• GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (8, 8)
• GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (6, 8)
• GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (5, 8)
• GitHub Check: units / internal / 🧪 Unit Tests: Internal (2, 8)
• GitHub Check: e2e / 🧪 CLI v3 tests (ubuntu-latest - pnpm)
• GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (4, 8)
• GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (7, 8)
• GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (1, 8)
• GitHub Check: e2e / 🧪 CLI v3 tests (windows-latest - pnpm)
• GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (3, 8)
• GitHub Check: e2e / 🧪 CLI v3 tests (windows-latest - npm)
• GitHub Check: units / packages / 🧪 Unit Tests: Packages (1, 1)
• GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (2, 8)
• GitHub Check: e2e / 🧪 CLI v3 tests (ubuntu-latest - npm)
• GitHub Check: typecheck / typecheck

🔇 Additional comments (3)

internal-packages/replication/src/client.ts (3)

416-442: LGTM!

The refactored #createPublication method correctly handles publication validation. The flow is clear: check existence → validate configuration → emit appropriate errors or success. Error handling is consistent with the rest of the class.

---

486-568: Well-structured validation with helpful error messages.

The #validatePublicationConfiguration method provides clear, actionable error messages that include the exact SQL commands needed to fix misconfiguration issues. The return type string | null is a clean pattern for validation results.

---

502-504: The hardcoded "public" schema is intentional and appropriate.

The schema is not configurable in LogicalReplicationClientOptions — only the table name is accepted. This aligns with how CREATE PUBLICATION is called (without schema qualification, which defaults to "public" in PostgreSQL). The validation correctly enforces this constraint, and the error messages clearly communicate the expected behavior.

---

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.}