Skip to content

Commit 3a8f350

Browse files
AttinderPalSinghJillGrant615
AttinderPalSingh
and
JillGrant615
authored
Create article sql-server-linux-availability-group-configure-custom-ha (#34978)
* Learn Editor: Update sql-server-linux-availability-group-configure-custom-ha.md * Update docs/linux/business-continuity/high-availability/configure-custom-logic.md --------- Co-authored-by: Jill Grant <72043882+JillGrant615@users.noreply.github.com>
1 parent 9443a6a commit 3a8f350

2 files changed

Lines changed: 204 additions & 0 deletions

File tree

‎docs/linux/business-continuity/high-availability/configure-custom-logic.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
---
2+
title: Configure SQL Server Availability Group with Custom High Availability Logic
3+
description: How to configure a SQL Server Always On availability group using custom high availability and failover logic.
4+
author: rwestMSFT
5+
ms.author: randolphwest
6+
ms.reviewer: atsingh, amitkh-msft
7+
ms.date: 01/13/2026
8+
ms.service: sql
9+
ms.subservice: linux
10+
ms.topic: design-pattern
11+
---
12+
# Configure SQL Server availability group with custom high availability logic on Linux
13+
14+
[!INCLUDE [SQL Server - Linux](../../../includes/applies-to-version/sql-linux.md)]
15+
16+
This article explains how to configure a SQL Server Always On availability group (AG) on Linux using custom high availability and failover logic. This architecture uses `CLUSTER_TYPE = EXTERNAL` to allow manual or script-driven control over replica management. It's ideal for environments requiring tailored high availability and failover strategies. While data synchronization between replicas is handled by SQL Server, the high availability and failover mechanisms must be implemented externally.
17+
18+
## Types of availability group architectures
19+
20+
### High availability architecture
21+
22+
- Uses a *cluster manager* to provide automated failover and enhanced business continuity.
23+
24+
- Recommended for production environments requiring minimal downtime.
25+
26+
- To configure this setup, see [Configure SQL Server availability group for high availability on Linux](../../sql-server-linux-availability-group-configure-ha.md).
27+
28+
### Read-scale architecture
29+
30+
- Configured with `CLUSTER_TYPE = NONE`, this model **doesn't** use a cluster manager.
31+
32+
- Supports read-only workloads and can include replicas across different operating systems.
33+
34+
- Not suitable for high availability scenarios.
35+
36+
- For setup instructions, see [Configure a SQL Server availability group for read-scale on Linux](../../sql-server-linux-availability-group-configure-rs.md).
37+
38+
### Custom high availability and failover logic
39+
40+
- Offers flexibility to implement **custom failover logic** using external scripts.
41+
- Configured with `CLUSTER_TYPE = EXTERNAL`, allowing manual or scripted management of availability replicas.
42+
- Ideal for environments with specialized high availability requirements or nonstandard clustering solutions.
43+
44+
[!INCLUDE [Create prerequisites](../../includes/cluster-availability-group-create-prereq.md)]
45+
46+
## Create the availability group
47+
48+
Create the AG. Set `CLUSTER_TYPE = EXTERNAL`. In addition, set each replica with `FAILOVER_MODE = EXTERNAL`. Depending on the environment's requirements, set `AVAILABILITY_MODE` to either `SYNCHRONOUS_COMMIT` or `ASYNCHRONOUS_COMMIT.`
49+
50+
**Paxos protocol** plays a critical role in the internal communication and configuration consistency of AlwaysOn availability groups (AGs) in SQL Server, particularly in cluster-agnostic or external cluster configurations. Paxos maintains consistency of the AG configuration across replicas, prevent split-brain scenarios, and ensures only primary is responsible for configuration updates.
51+
52+
The following Transact-SQL script creates an AG named `ag1`. The script configures the AG replicas with `SEEDING_MODE = MANUAL`. This setting requires you to manually initialize secondary replicas with a copy of the database before adding them to the AG. Update the following script for your environment. Replace the `<node1>`, `<node2>`, and `<node3>` values with the names of the SQL Server instances that host the replicas. This AG also configures the configuration only replica `<node3>`. The configuration only replica maintains configuration information about the availability group in the `master` database but doesn't contain the user databases in the availability group. Replace the `<5022>` value with the port you set for the endpoint. Run the following Transact-SQL script on the primary SQL Server replica:
53+
54+
```sql
55+
CREATE availability group [ag1]
56+
WITH (CLUSTER_TYPE = EXTERNAL)
57+
FOR REPLICA ON
58+
N'<node1>' WITH (
59+
ENDPOINT_URL = N'tcp://<node1>:<5022>',
60+
AVAILABILITY_MODE = SYNCHRONOUS_COMMIT,
61+
FAILOVER_MODE = EXTERNAL,
62+
SEEDING_MODE = MANUAL,
63+
SECONDARY_ROLE (ALLOW_CONNECTIONS = ALL)
64+
),
65+
N'<node2>' WITH (
66+
ENDPOINT_URL = N'tcp://<node2>:<5022>',
67+
AVAILABILITY_MODE = SYNCHRONOUS_COMMIT,
68+
FAILOVER_MODE = EXTERNAL,
69+
SEEDING_MODE = MANUAL,
70+
SECONDARY_ROLE (ALLOW_CONNECTIONS = ALL)
71+
72+
N'<node3>' WITH (
73+
ENDPOINT_URL = N'tcp://<node3>:<5022>',
74+
AVAILABILITY_MODE = CONFIGURATION_ONLY
75+
);
76+
77+
ALTER availability group [ag1] GRANT CREATE ANY DATABASE;
78+
```
79+
80+
### Join secondary SQL Server instances to the AG
81+
82+
The following Transact-SQL script joins a server to an AG named `ag1`. Update the script for your environment. On each secondary SQL Server replica, run the following Transact-SQL script to join the AG:
83+
84+
```sql
85+
ALTER availability group [ag1] JOIN WITH (CLUSTER_TYPE = EXTERNAL);
86+
87+
ALTER availability group [ag1] GRANT CREATE ANY DATABASE;
88+
```
89+
90+
[!INCLUDE [Create post](../../includes/cluster-availability-group-create-post.md)]
91+
92+
## Fail over the primary replica in a custom high availability and failover logic
93+
94+
Each availability group has only one primary replica. The primary replica allows reads and writes. To change which replica is primary, you can fail over. In a typical availability group, the cluster manager automates the failover process. In an availability group with cluster type `EXTERNAL`, with **custom failover logic** using external scripts or third-party tools the failover process can be manual or automated by implementing the custom health check and failover logic.
95+
96+
Manual fail over the primary replica can be done in two ways:
97+
98+
- Manual failover without data loss
99+
100+
- Forced manual failover with data loss
101+
102+
### Manual failover without data loss
103+
104+
Use this method when the primary replica is available, but you need to temporarily or permanently change which instance hosts the primary replica. To avoid potential data loss, before you issue the manual failover, ensure that the target secondary replica is up to date.
105+
106+
To manually fail over without data loss:
107+
108+
1. Make the current primary and target secondary replica `SYNCHRONOUS_COMMIT`.
109+
110+
```sql
111+
ALTER AVAILABILITY GROUP [ag1] MODIFY REPLICA ON N'<node2>' WITH (AVAILABILITY_MODE = SYNCHRONOUS_COMMIT);
112+
```
113+
114+
1. To identify that active transactions are committed to the primary replica and at least one synchronous secondary replica, run the following query:
115+
116+
```sql
117+
SELECT AG.NAME,
118+
DRS.DATABASE_ID,
119+
DRS.GROUP_ID,
120+
DRS.REPLICA_ID,
121+
DRS.SYNCHRONIZATION_STATE_DESC,
122+
AG.SEQUENCE_NUMBER
123+
FROM SYS.DM_HADR_DATABASE_REPLICA_STATES AS DRS, SYS.AVAILABILITY_GROUPS AS AG
124+
WHERE DRS.GROUP_ID = AG.GROUP_ID;
125+
```
126+
127+
The secondary replica is synchronized when `synchronization_state_desc` is `SYNCHRONIZED`.
128+
129+
1. Set the primary replica and the secondary replicas not participating in the failover offline to prepare for the role change:
130+
131+
```sql
132+
ALTER AVAILABILITY GROUP [ag1] OFFLINE;
133+
```
134+
135+
1. Promote the target secondary replica to primary
136+
137+
```sql
138+
ALTER AVAILABILITY GROUP ag1 FORCE_FAILOVER_ALLOW_DATA_LOSS;
139+
```
140+
141+
1. Update the role of the old primary and other secondaries to `SECONDARY`, then run the following command on the SQL Server instance that hosts the old primary replica:
142+
143+
```sql
144+
ALTER availability group [ag1] SET (ROLE = SECONDARY);
145+
```
146+
147+
1. Resume data movement, run the following command for every database in the availability group on the SQL Server instance that hosts the primary replica:
148+
149+
```sql
150+
ALTER DATABASE [db1]
151+
SET HADR RESUME;
152+
```
153+
154+
### Forced manual failover with data loss
155+
156+
If the primary replica isn't available and can't immediately be recovered, then you need to force a failover to the secondary replica with data loss. However, if the original primary replica recovers after failover, it will assume the primary role. To avoid having each replica be in a different state, remove the original primary from the availability group after a forced failover with data loss. Once the original primary comes back online, remove the availability group from it entirely.
157+
158+
To force a manual failover with data loss from primary replica N1 to secondary replica N2, follow these steps:
159+
160+
1. On the secondary replica (N2), initiate the forced failover:
161+
162+
```sql
163+
ALTER AVAILABILITY GROUP [ag1] FORCE_FAILOVER_ALLOW_DATA_LOSS;
164+
```
165+
166+
1. On the new primary replica (N2), remove the original primary (N1):
167+
168+
```sql
169+
ALTER AVAILABILITY GROUP [ag1] REMOVE REPLICA ON N'N1';
170+
```
171+
172+
1. Validate that all application traffic is pointed to the listener and/or the new primary replica.
173+
174+
```sql
175+
ALTER AVAILABILITY GROUP [ag1] OFFLINE;
176+
```
177+
178+
1. If there's data, or unsynchronized changes, preserve this data via backups or other data replicating options that suit your business needs.
179+
180+
1. Next, remove the availability group from the original primary (N1):
181+
182+
```sql
183+
DROP AVAILABILITY GROUP [ag1];
184+
```
185+
186+
1. Drop the availability group database on original primary replica (N1)
187+
188+
```sql
189+
USE [master];
190+
GO
191+
192+
DROP DATABASE [db1];
193+
GO
194+
```
195+
196+
1. (Optional) If desired, you can now add N1 back as a new secondary replica to the availability group AG1.
197+
198+
## Related content
199+
200+
- [Distributed availability groups](../../../database-engine/availability-groups/windows/distributed-availability-groups.md)
201+
- [What is an Always On availability group?](../../../database-engine/availability-groups/windows/overview-of-always-on-availability-groups-sql-server.md)
202+
- [Perform a forced manual failover of an Always On availability group (SQL Server)](../../../database-engine/availability-groups/windows/perform-a-forced-manual-failover-of-an-availability-group-sql-server.md)

‎docs/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9292,6 +9292,8 @@ items:
92929292
href: linux/sql-server-linux-availability-group-overview.md
92939293
- name: Create and configure availability groups
92949294
href: linux/sql-server-linux-create-availability-group.md
9295+
- name: Configure with custom high availability logic
9296+
href: linux/business-continuity/high-availability/configure-custom-logic.md
92959297
- name: Configure machine key for contained AG
92969298
href: linux/sql-server-linux-availability-group-prepare-machine-key.md
92979299
- name: High availability

0 commit comments

Comments
 (0)