Skip to content

Commit 00b22bf

Browse files
PiJoCoderrwestMSFT
PiJoCoder
authored and
rwestMSFT
committed
create article on tran repl with linux container subscribers
1 parent dd12c93 commit 00b22bf

2 files changed

Lines changed: 184 additions & 2 deletions

File tree

‎support/sql/database-engine/replication/subscription-exists-linux-containers-transactional.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
---
2+
title: Configuring Transactional Replication on Multiple SQL Server Linux Containers Might Fail
3+
description: Learn about a known issue when configuring transactional replication in SQL Server on Linux containers, including symptoms, cause, workaround, and resolution.
4+
author: pijocoder
5+
ms.author: mlandzic
6+
ms.reviewer: randolphwest
7+
ms.date: 11/03/2025
8+
ms.topic: troubleshooting
9+
---
10+
11+
# Configuring transactional replication on multiple SQL Server Linux containers might fail
12+
13+
This article guides you how to resolve an issue with two SQL Server running on Linux container on the same machine to be configured as replication subscribers.
14+
15+
## Symptoms
16+
17+
When configuring **Transactional Replication** on SQL Server 2022 running in Linux containers, you might encounter the following error:
18+
19+
```output
20+
The subscription already exists.
21+
```
22+
23+
This issue typically occurs when:
24+
25+
- Two SQL Server instances are hosted in separate containers on the same Linux machine.
26+
- Both instances are added as subscribers to the same publisher.
27+
- The connection strings use the same hostname but different port numbers (for example, `LINUXHOST,5455` and `LINUXHOST,5465`).
28+
29+
## Cause
30+
31+
The issue occurs because subscriber metadata doesn't honor port numbers during persistence. Only the hostname is stored, causing the second subscriber to be perceived as a duplicate of the first.
32+
This behavior is specific to Linux container environments where named instances don't exist, and connections rely on hostname and port mapping.
33+
34+
## Workaround
35+
36+
To successfully add multiple subscribers on the same host but different containers:
37+
38+
1. Install **Cumulative Update 20 (CU20)** for SQL Server 2022.
39+
40+
1. Enable trace flag **[15005](/sql/t-sql/database-console-commands/dbcc-traceon-trace-flags-transact-sql#tf15005)**. This trace flag enables using a Subscriber with a nondefault port for transactional replication.
41+
42+
1. Perform the following manual cleanup and configuration steps in Transact-SQL. Make sure to replace `@hostname`, `@port_sub1`, `@port_sub2`, publication, publisher, and subscriber database variables with values specific to your environment:
43+
44+
```sql
45+
DECLARE @hostname AS SYSNAME = 'LinuxSubscriberHostName',
46+
@port_sub1 AS NVARCHAR (10) = '5455',
47+
@port_sub2 AS NVARCHAR (10) = '5465',
48+
@host_and_port_sub1 AS NVARCHAR (100),
49+
@host_and_port_sub2 AS NVARCHAR (100),
50+
@PublicationName AS SYSNAME = 'PublicationName',
51+
@SubscriberDb_Sub1 AS SYSNAME = 'SubscriberDB1',
52+
@SubscriberDb_Sub2 AS SYSNAME = 'SubscriberDB2';
53+
54+
-- Concatenate the hostname and port for each subscriber (for example 'LinuxSubscriberHostName,5455')
55+
SET @host_and_port_sub1 = CONCAT(@hostname, ',', @port_sub1);
56+
SET @host_and_port_sub2 = CONCAT(@hostname, ',', @port_sub2);
57+
58+
-- Step 1: Remove subscription metadata
59+
USE [PublicationDb];
60+
61+
EXECUTE sp_dropsubscription
62+
@publication = @PublicationName,
63+
@article = 'all',
64+
@subscriber = @hostname,
65+
@destination_db = @SubscriberDb_Sub1;
66+
67+
-- Step 2: Remove subscriber from publication
68+
EXECUTE sp_dropsubscriber @subscriber = @hostname;
69+
70+
-- Step 3: Remove server entry for the first subscriber with no port information captured (on Publisher side)
71+
DELETE FROM distribution..MSreplservers
72+
WHERE UPPER(srvname COLLATE database_default) = UPPER(@hostname COLLATE database_default);
73+
74+
IF EXISTS (SELECT 1 FROM sys.servers WHERE name = @hostname)
75+
EXECUTE sp_dropserver @hostname, 'droplogins';
76+
77+
-- Step 4: Re-add linked server on Publisher side
78+
EXECUTE sp_addlinkedserver @server = @host_and_port_sub1;
79+
EXECUTE sp_serveroption @server = @host_and_port_sub1, @optname = 'sub', @optvalue = true;
80+
81+
EXECUTE sp_addlinkedserver @server = @host_and_port_sub2;
82+
EXECUTE sp_serveroption @server = @host_and_port_sub2, @optname = 'sub', @optvalue = true;
83+
84+
--Ensure entries are successful
85+
SELECT * FROM master..sysservers;
86+
87+
--Step 5. Insert information about the subscribers to the Msreplservers table.
88+
INSERT INTO [distribution]..MSreplservers (srvid, srvname)
89+
SELECT srvid, srvname
90+
FROM master.dbo.sysservers
91+
WHERE UPPER(srvname COLLATE database_default) = UPPER(@host_and_port_sub1 COLLATE database_default);
92+
93+
INSERT INTO [distribution]..MSreplservers (srvid, srvname)
94+
SELECT srvid, srvname
95+
FROM master.dbo.sysservers
96+
WHERE UPPER(srvname COLLATE database_default) = UPPER(@host_and_port_sub2 COLLATE database_default);
97+
98+
--Verify entries
99+
SELECT * FROM [distribution]..MSreplservers;
100+
101+
--Step 6. Create subscribers (push subscription)
102+
-----------------BEGIN: Script to be run at Publisher @hostname-----------------;;
103+
104+
--Create subscriber to the first Linux container
105+
USE [PublicationDb];
106+
107+
EXECUTE sp_addsubscription
108+
@publication = @PublicationName,
109+
@subscriber = @host_and_port_sub1,
110+
@destination_db = @SubscriberDb_Sub1,
111+
@subscription_type = N'Push',
112+
@sync_type = N'automatic',
113+
@article = N'all',
114+
@update_mode = N'read only',
115+
@subscriber_type = 0;
116+
117+
EXECUTE sp_addpushsubscription_agent
118+
@publication = @PublicationName,
119+
@subscriber = @host_and_port_sub1,
120+
@subscriber_db = @SubscriberDb_Sub1,
121+
@job_login = NULL,
122+
@job_password = NULL,
123+
@subscriber_security_mode = 1,
124+
@frequency_type = 64,
125+
@frequency_interval = 0,
126+
@frequency_relative_interval = 0,
127+
@frequency_recurrence_factor = 0,
128+
@frequency_subday = 0,
129+
@frequency_subday_interval = 0,
130+
@active_start_time_of_day = 0,
131+
@active_end_time_of_day = 235959,
132+
@active_start_date = 20250711,
133+
@active_end_date = 99991231,
134+
@enabled_for_syncmgr = N'False',
135+
@dts_package_location = N'Distributor';
136+
137+
--Create subscriber to the second Linux container
138+
USE [PublicationDb];
139+
140+
EXECUTE sp_addsubscription
141+
@publication = @PublicationName,
142+
@subscriber = @host_and_port_sub2,
143+
@destination_db = @SubscriberDb_Sub2,
144+
@subscription_type = N'Push',
145+
@sync_type = N'automatic',
146+
@article = N'all',
147+
@update_mode = N'read only',
148+
@subscriber_type = 0;
149+
150+
EXECUTE sp_addpushsubscription_agent
151+
@publication = @PublicationName,
152+
@subscriber = @host_and_port_sub2,
153+
@subscriber_db = @SubscriberDb_Sub2,
154+
@job_login = NULL,
155+
@job_password = NULL,
156+
@subscriber_security_mode = 1,
157+
@frequency_type = 64,
158+
@frequency_interval = 0,
159+
@frequency_relative_interval = 0,
160+
@frequency_recurrence_factor = 0,
161+
@frequency_subday = 0,
162+
@frequency_subday_interval = 0,
163+
@active_start_time_of_day = 0,
164+
@active_end_time_of_day = 235959,
165+
@active_start_date = 20250711,
166+
@active_end_date = 99991231,
167+
@enabled_for_syncmgr = N'False',
168+
@dts_package_location = N'Distributor';
169+
```
170+
171+
## Resolution
172+
173+
As of now, no permanent fix is available. The workaround is the recommended approach.
174+
175+
The product team is evaluating a fix for a future release. When resolved, this article is to be updated or retired accordingly.
176+
177+
## Related content
178+
179+
- [Transactional Replication](/sql/relational-databases/replication/transactional/transactional-replication)
180+
- [Quickstart: Run SQL Server Linux container images with Docker](/sql/linux/quickstart-install-connect-docker)

‎support/sql/database-engine/replication/toc.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
items:
1+
items:
22
- name: 102 and incorrect syntax error with peer-to-peer replication
33
href: peer-to-peer-replication-fails.md
44
- name: 1205 error when you configure transactional replication
55
href: error-1205-configure-transactional-replication.md
66
- name: 20011 error the process could not execute sp_replcmds
77
href: error-replication-log-reader-agent-fails.md
8-
- name: 20598 error the row was not found at the Subscriber when applying the replicated command
8+
- name: 20598 error the row was not found at the Subscriber when applying the replicated command
99
href: troubleshoot-error-20598.md
1010
- name: 213 error when attaching CDC enabled database
1111
href: attach-change-data-capture-database.md
@@ -15,6 +15,8 @@ items:
1515
href: cdc-capture-job-fails-processing-changes-table.md
1616
- name: CDC for Oracle results in transaction log growth
1717
href: sql-transaction-log-grows.md
18+
- name: Configuring transactional replication on multiple SQL Server Linux containers might fail
19+
href: subscription-exists-linux-containers-transactional.md
1820
- name: Error message when you run the Distribution Agent
1921
href: error-run-distribution-agent.md
2022
- name: Fail to enumerate subscription properties

0 commit comments

Comments
 (0)