docs: add guide for ingesting from a dedicated PostgreSQL replica#37023
Open
josharenberg wants to merge 2 commits into
Open
docs: add guide for ingesting from a dedicated PostgreSQL replica#37023josharenberg wants to merge 2 commits into
josharenberg wants to merge 2 commits into
Conversation
Adds a goal-first guide for the "sidecar" pattern: standing up a dedicated PostgreSQL replica via native logical replication and pointing a Materialize PostgreSQL source at it instead of the production primary. Previously this pattern was only mentioned inside the PostgreSQL source FAQ, filed under "what if I can't use REPLICA IDENTITY FULL?" — so users whose actual motivation was keeping replication load/WAL-retention risk off their primary, or who couldn't reconfigure the primary, had no discoverable entry point. The new page is titled and framed around that goal and is reachable directly from the PostgreSQL ingest menu. The guide makes explicit the two logical-replication hops involved (primary -> replica via native PG logical replication, then replica -> Materialize), which means the replica itself needs wal_level = logical, REPLICA IDENTITY FULL on its tables, and a separate publication for Materialize. It leads with a strong recommendation to connect directly to the primary and frames the replica as an exception path, then hands off to the self-hosted guide for source creation rather than duplicating it. Cross-links added from the FAQ sidecar entry and the self-hosted guide so both motivations funnel into the new page. No code changes; documentation only.
Contributor
|
Thanks for this. I'll put up a patch to address some tweaks and slight reordering to try to minimize switching from primary to replica. |
kay-kim
approved these changes
Jun 13, 2026
kay-kim
left a comment
kay-kim
left a comment
Contributor
There was a problem hiding this comment.
I left a comment about being able to use mermaid diagram. Not sure if we want that. Just let me know if you do. But, this can also go as is.
| There are **two** logical-replication hops to set up: | ||
|
|
||
| ``` | ||
| primary ──(native PG logical replication)──▶ replica ──(Materialize source)──▶ Materialize |
Contributor
There was a problem hiding this comment.
We can have this be a mermaid diagram if you want. We just need to
- set in the frontmatter
mermaid: true - modify this to a flowchart LR ...
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a goal-first guide for the "sidecar" pattern: standing up a dedicated PostgreSQL replica via native logical replication and pointing a Materialize PostgreSQL source at it instead of the production primary.
Previously this pattern was only mentioned inside the PostgreSQL source FAQ, filed under "what if I can't use REPLICA IDENTITY FULL?" — so users whose actual motivation was keeping replication load/WAL-retention risk off their primary, or who couldn't reconfigure the primary, had no discoverable entry point. The new page is titled and framed around that goal and is reachable directly from the PostgreSQL ingest menu.
The guide makes explicit the two logical-replication hops involved (primary -> replica via native PG logical replication, then replica -> Materialize), which means the replica itself needs wal_level = logical, REPLICA IDENTITY FULL on its tables, and a separate publication for Materialize. It leads with a strong recommendation to connect directly to the primary and frames the replica as an exception path, then hands off to the self-hosted guide for source creation rather than duplicating it.
Cross-links added from the FAQ sidecar entry and the self-hosted guide so both motivations funnel into the new page.
No code changes; documentation only.
Remove these sections if your commit already has a good description!
Motivation
Why does this change exist? Link to a GitHub issue, design doc, Slack
thread, or explain the problem in a sentence or two. A reviewer who has
no context should understand why after reading this section.
If this implements or addresses an existing issue, it's enough to link to that:
Closes
Fixes
etc.
Description
What does this PR actually do? Focus on the approach and any non-obvious
decisions. The diff shows the code --- use this space to explain what the
diff can't tell a reviewer.
Verification
How do you know this change is correct? Describe new or existing automated
tests, or manual steps you took.