# Problem Currently, GitLab Geo only supports streaming replication. Streaming replication has some limitations and logical replication can solve some of them. ## Streaming Replication vs. Logical Replication <details> <summary>Click to expand/collapse</summary> | **Feature** | **Streaming Replication** | **Logical Replication** | |:-----------:|:-------------------------:|:-----------------------:| | **Replication Method** | Physical, block-level replication | Logical, row-level replication | | | Replicates entire database at binary level | Replicates specific database objects (tables) | | | Works at WAL file level | Works at SQL/logical change level | | **Granularity** | All-or-nothing approach | Fine-grained control | | | Must replicate entire database instance | Can selectively replicate specific tables | | | Cannot selectively replicate | Supports filtering rows and columns | | **Schema Changes (DDL)** | Automatically replicates all schema changes | Does not automatically replicate schema changes | | | DDL statements replicated as physical changes | Requires manual synchronization of DDL statements | | **Version Compatibility** | Requires identical PostgreSQL versions | Supports cross-version replication | | | Cannot replicate between different major versions | Can replicate between different PostgreSQL versions | | **Performance Impact** | Generally lower CPU overhead | Higher CPU overhead (due to row decoding) | | | Higher network bandwidth requirements | More efficient network usage (only changed rows) | | | Minimal impact on primary server | Slightly higher impact on primary server | | **Use Cases** | Disaster recovery | Data integration between different systems | | | High availability solutions | Selective data distribution | | | Read scaling with identical databases | Upgrading to new major versions with minimal downtime | | **Setup Complexity** | Simpler to set up initially | More complex initial setup | | | Fewer configuration parameters | Requires publication/subscription configuration | | **Conflict Handling** | No conflicts possible (one-way only) | Must handle potential conflicts in bi-directional setups | | | Standby is read-only | Supports conflict detection and resolution mechanisms | </details> ## What pains do customers face with streaming replication that logical replication can solve? - Requires identical PostgreSQL versions - [Requires identical operating system collations](https://docs.gitlab.com/administration/postgresql/upgrading_os/) - Can’t replicate between different AWS accounts, when migration from SM to dedicated. - Initial setup is complicated, long, and a poor migration experience for the customer ## Challenges with LR? - Requires manual synchronisation of DDL statements - schema changes will not be replicated automatically. DDL statements are recommended to be run manually first on a secondary and then on a primary. ## Which customers use cases would be affected positively by this change? - GitLab migrations between GitLab offerings, especially SM -\> Dedicated migrations - Eliminates hours-long dump/restore step - no more maintenance of tooling for this - eliminates risk of retries during a downtime incurring time-critical operation - Cutover will be reduced to the one Geo secondary promotion step - Significantly reduces customer downtime - Logical replication will be possible between the customer's primary DB to Dedicated's RDS from the start - PostgreSQL or OS version upgrades - Geo based acceleration ## How does Org Mover tie into this plan? - This project will prove that Geo code is generally compatible with LR, be it PG’s native LR, Siphon, or cloud DB replicas. We will gain knowledge about LR itself, as well as GitLab-specific challenges such as dynamic partition management. This knowledge, and perhaps some of our solutions, may overlap with the Org Mover case. - However, Org Mover's use case has major differences. It requires moving only organization-wise data from the legacy cell to a target cell. It will not be used to replicate data over a long period of time. So the overlap is not total. ## Implementation ### Iteration 1 Prove that Geo works with logical replication. And, document steps to make it work. - https://gitlab.com/gitlab-org/gitlab/-/issues/588651+ - https://gitlab.com/gitlab-org/gitlab/-/issues/541755+ - https://gitlab.com/gitlab-org/gitlab/-/issues/549964+ ### Iteration 2 Test, demonstrate and document using cross-account AWS RDS logical replication to move data from Self-managed to Dedicated during the initial sync. - https://gitlab.com/gitlab-org/gitlab/-/issues/541754+ - https://gitlab.com/gitlab-org/gitlab/-/issues/549970+ - Add support for logical replication to omnibus-gitlab tooling (issues need to be opened when more details available) - Add support to the `gitlab-ctl` Geo related commands - `gitlab-ctl geo promote` - `geo-replication-pause` - `geo-replication-resume` - `promotion-preflight-checks` - `replicate-geo-database` - `set-geo-primary-node` - Add support for logical replication during setup via the various geo related cookbooks in omnibus-gitlab ### Iteration 3 https://gitlab.com/groups/gitlab-org/-/epics/17331+ ## Excluded technical scope * **Production-Scale**: Validate with realistic data volumes and activity * **Multi-Database**: Test environments with multiple GitLab databases * **Long-Running**: Test replication over extended periods (days/weeks) * **Network Interruptions**: Resilience testing for connection issues ### Participants * @ibaum * @nwestbury * @s_murray * @c_fons * @jburnitz ## Exit Criteria - [ ] GitLab Geo functionality validated with PostgreSQL logical replication - [ ] AWS RDS cross-account logical replication tested and documented <!-- STATUS NOTE START --> ## Status 2026-07-09 :clock1: **total hours spent this week by all contributors**: 30 :tada: **achievements**: - [Define tables excluded in logical replication](https://gitlab.com/gitlab-org/gitlab/-/work_items/600042): closed after the initial excluded-tables list and publication/subscription rake tasks landed. Unblocks automated management of the LR publication - Merged [Rake tasks for managing Geo LR publications and subscriptions](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/237591) :arrow_forward: **next**: - [Sequence synchronization](https://gitlab.com/gitlab-org/gitlab/-/work_items/593337): MR resolved review feedback and is awaiting another review pass - In review: [Add sequence synchronization between geo sites](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/231508) - @dbalexandre scoped 28 new issues across the LR epic, covering remaining work streams such as read-only enforcement, WAL retention monitoring, promotion flows, and DR investigation _Copied from https://gitlab.com/groups/gitlab-org/-/epics/18022#note_3539099424_ <!-- STATUS NOTE END -->