commands

Clear
^

Add-DbaAgDatabase
Author Chrissy LeMaire (@cl), netnerds.net , Andreas Jordan (@JordanOrdix), ordix.de
Availability Windows, Linux, macOS

 

Want to see the source code for this command? Check out Add-DbaAgDatabase on GitHub.
Want to see the Bill Of Health for this command? Check out Add-DbaAgDatabase.

Synopsis

Adds database(s) to an Availability Group on a SQL Server instance.

Description

Adds database(s) to an Availability Group on a SQL Server instance.

After checking for prerequisites, the commands runs these five steps for every database:

  • Step 1: Setting seeding mode if needed.
    • If -SeedingMode is used and the current seeding mode of the replica is not in the desired mode, the seeding mode of the replica is changed.
    • The seeding mode will not be changed back but stay in this mode.
    • If the seeding mode is changed to Automatic, the necessary rights to create databases will be granted.
  • Step 2: Running backup and restore if needed.
    • Action is only taken for replicas with a desired seeding mode of Manual and where the database does not yet exist.
    • If -UseLastBackup is used, the restore will be performed based on the backup history of the database.
    • Otherwise a full and log backup will be taken at the primary and those will be restored at the replica using the same folder structure.
  • Step 3: Add the database to the Availability Group on the primary replica.
    • This step is skipped, if the database is already part of the Availability Group.
  • Step 4: Add the database to the Availability Group on the secondary replicas.
    • This step is skipped for those replicas, where the database is already joined to the Availability Group.
  • Step 5: Wait for the database to finish joining the Availability Group on the secondary replicas.

Use Test-DbaAvailabilityGroup with -AddDatabase to test if all prerequisites are met.

If you have special requirements for the setup for the database at the replicas, perform the backup and restore part with Backup-DbaDatabase and Restore-DbaDatabase in advance. Please make sure that the last log backup has been restored before running Add-DbaAgDatabase.

Syntax

Add-DbaAgDatabase
    [-SqlInstance] <DbaInstanceParameter>
    [-SqlCredential <PSCredential>] -AvailabilityGroup <String> -Database <String[]>
    [-Secondary <DbaInstanceParameter[]>]
    [-SecondarySqlCredential <PSCredential>]
    [-SeedingMode <String>]
    [-SharedPath <String>]
    [-UseLastBackup]
    [-AdvancedBackupParams <Hashtable>]
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Add-DbaAgDatabase
    [-AvailabilityGroup] <String>
    [-Secondary <DbaInstanceParameter[]>]
    [-SecondarySqlCredential <PSCredential>] -InputObject <Database[]>
    [-SeedingMode <String>]
    [-SharedPath <String>]
    [-UseLastBackup]
    [-AdvancedBackupParams <Hashtable>]
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

 

Examples

 

Example: 1
PS C:\> Add-DbaAgDatabase -SqlInstance sql2017a -AvailabilityGroup ag1 -Database db1, db2 -Confirm

Adds db1 and db2 to ag1 on sql2017a. Prompts for confirmation.

Example: 2
PS C:\> Get-DbaDatabase -SqlInstance sql2017a | Out-GridView -Passthru | Add-DbaAgDatabase -AvailabilityGroup ag1

Adds selected databases from sql2017a to ag1

Example: 3
PS C:\> Get-DbaDbSharePoint -SqlInstance sqlcluster | Add-DbaAgDatabase -AvailabilityGroup SharePoint

Adds SharePoint databases as found in SharePoint_Config on sqlcluster to ag1 on sqlcluster

Example: 4
PS C:\> Get-DbaDbSharePoint -SqlInstance sqlcluster -ConfigDatabase SharePoint_Config_2019 | Add-DbaAgDatabase -AvailabilityGroup SharePoint

Adds SharePoint databases as found in SharePoint_Config_2019 on sqlcluster to ag1 on sqlcluster

Example: 5
PS C:\> $adv_param = @{
>>    CompressBackup = $true
>>    FileCount = 3
>> }
PS C:\> $splat = @{
>>   SqlInstance = 'sql2017a'
>>   AvailabilityGroup = 'ag1'
>>   Database = 'db1'
>>   Secondary = 'sql2017b'
>>   SeedingMode = 'Manual'
>>   SharedPath = '\\FS\Backup'
>> }
PS C:\> Add-DbaAgDatabase @splat -AdvancedBackupParams $adv_param

Adds db1 to ag1 on sql2017a and sql2017b. Uses compression and three files while taking the backups.

Required Parameters

-SqlInstance

The primary replica of the Availability Group. Server version must be SQL Server version 2012 or higher.
Alias
Required True
Pipeline false
Default Value
-AvailabilityGroup

The name of the Availability Group where the databases will be added.
Alias
Required True
Pipeline false
Default Value
-Database

The database(s) to add.
Alias
Required True
Pipeline false
Default Value
-InputObject

Enables piping from Get-DbaDatabase, Get-DbaDbSharePoint and more.
Alias
Required True
Pipeline true (ByValue)
Default Value

Optional Parameters

-SqlCredential

Login to the target instance using alternative credentials. Accepts PowerShell credentials (Get-Credential). Windows Authentication, SQL Server Authentication, Active Directory - Password, and Active Directory - Integrated are all supported. For MFA support, please use Connect-DbaInstance.
Alias
Required False
Pipeline false
Default Value
-Secondary

Not required - the command will figure this out. But use this parameter if secondary replicas listen on a non default port. This parameter can be used to only add the databases on specific secondary replicas.
Alias
Required False
Pipeline false
Default Value
-SecondarySqlCredential

Login to the target instance using alternative credentials. Accepts PowerShell credentials (Get-Credential). Windows Authentication, SQL Server Authentication, Active Directory - Password, and Active Directory - Integrated are all supported. For MFA support, please use Connect-DbaInstance.
Alias
Required False
Pipeline false
Default Value
-SeedingMode

Specifies how the secondary replica will be initially seeded. Automatic enables direct seeding. This method will seed the secondary replica over the network. This method does not require you to backup and restore a copy of the primary database on the replica. Manual uses full and log backup to initially transfer the data to the secondary replica. The command skips this if the database is found in restoring state at the secondary replica. If not specified, the setting from the availability group replica will be used. Otherwise the setting will be updated.
Alias
Required False
Pipeline false
Default Value
Accepted Values Automatic,Manual
-SharedPath

The network share where the backups will be backed up and restored from. Each SQL Server service account must have access to this share. NOTE: If a backup / restore is performed, the backups will be left in tact on the network share.
Alias
Required False
Pipeline false
Default Value
-UseLastBackup

Use the last full and log backup of the database. A log backup must be the last backup.
Alias
Required False
Pipeline false
Default Value False
-AdvancedBackupParams

Provide additional parameters to the backup command as a hashtable.
Alias
Required False
Pipeline false
Default Value
-EnableException

By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message. This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables advanced scripting. Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own try/catch.
Alias
Required False
Pipeline false
Default Value False
-WhatIf

Shows what would happen if the command were to run. No actions are actually performed.
Alias wi
Required False
Pipeline false
Default Value
-Confirm

Prompts you for confirmation before executing any changing operations within the command.
Alias cf
Required False
Pipeline false
Default Value