Start-DbaAzMigration

Synopsis

Migrates SQL Server databases to an existing Azure SQL Database logical server using BACPAC files.

Description

Exports selected accessible user databases from one SQL Server instance as BACPAC files and imports them into unique staging databases on an existing Azure SQL Database logical server. Each completed staging import is promoted to the source database name after a final collision check.

This command migrates databases only. It does not provision Azure resources or migrate server-level objects such as logins, credentials, SQL Agent jobs, linked servers, or server roles. Azure SQL Managed Instance migrations should use Copy-DbaDatabase instead.

Microsoft DacFx is supplied through dbatools.library, so no additional module or SqlPackage installation is required. Generated BACPAC files contain data and are removed after each migration by default.

Syntax

Start-DbaAzMigration
    [-Source] <DbaInstanceParameter>
    [-Destination] <DbaInstanceParameter>
    [[-SourceSqlCredential] <PSCredential>]
    [[-DestinationSqlCredential] <PSCredential>]
    [[-DestinationAccessToken] <PSObject>]
    [[-Database] <Object[]>]
    [[-ExcludeDatabase] <Object[]>]
    [[-Path] <String>]
    [[-ExportDacOption] <Object>]
    [[-ImportDacOption] <Object>]
    [-Force]
    [-KeepBacpac]
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Examples

Example 1: Migrates AppDb to the existing Azure SQL logical server and removes the temporary BACPAC after import

PS C:\> Start-DbaAzMigration -Source sql01 -Destination dbatools.database.windows.net -Database AppDb

Example 2: Migrates all accessible user databases and replaces databases that already exist, using the selected Azure...

PS C:\> $options = New-DbaDacOption -Type Bacpac -Action Publish
PS C:\> $options.DatabaseSpecification.Edition = "Standard"
PS C:\> $options.DatabaseSpecification.ServiceObjective = "S0"
PS C:\> Start-DbaAzMigration -Source sql01 -Destination dbatools.database.windows.net -ImportDacOption $options -Force -Confirm:$false

Migrates all accessible user databases and replaces databases that already exist, using the selected Azure service objective.

Required Parameters

-Source

The source SQL Server instance or reusable connected server object.

-Destination

The existing Azure SQL Database logical server or reusable connected server object. The connecting principal must be able to create and, when Force is used, remove databases.

Optional Parameters

-SourceSqlCredential

Credential used to connect to the source SQL Server instance.

-DestinationSqlCredential

Credential used to connect to the destination Azure SQL logical server.

-DestinationAccessToken

Microsoft Entra access token for https://database.windows.net/ used to connect to the destination Azure SQL logical server and publish the BACPAC. Accepts a string, SecureString, a token object
returned by Get-AzAccessToken, or a renewable Microsoft.SqlServer.Management.Common.IRenewableToken object, such as New-DbaAzAccessToken -Type RenewableServicePrincipal.

-Database

The source databases to migrate. When omitted, all accessible user databases are selected.

-ExcludeDatabase

Source databases to exclude after applying the Database filter.

-Path

Directory used for generated BACPAC files. Defaults to the configured dbatools temporary path.

-ExportDacOption

A Microsoft.SqlServer.Dac.DacExportOptions object passed to BACPAC export.

-ImportDacOption

A Microsoft.SqlServer.Dac.DacImportOptions object passed to BACPAC import. Use this option to configure the Azure edition, service objective, maximum size, and DacFx import settings.

-Force

Replaces a destination database when a database with the same name already exists. The existing database remains in place until the replacement has been fully imported into a staging database.

-KeepBacpac

Keeps generated BACPAC files after migration. BACPAC files contain schema and table data and must be secured appropriately.

-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.

-WhatIf

Shows what would happen if the command were to run. No actions are actually performed.

-Confirm

Prompts you for confirmation before executing any changing operations within the command.

Outputs

PSCustomObject

Returns one dbatools.MigrationObject per selected database.

Default display properties (via Select-DefaultView):

• DateTime (DbaDateTime): The date and time when processing of the database began
• SourceServer (String): The connected source SQL Server name
• DestinationServer (String): The connected Azure SQL logical server name
• Name (String): The source database name
• Type (String): The migrated object type, always Database
• Status (String): The migration result, such as Successful, Failed, or Skipped
• Notes (String): Failure, cleanup, or skip details when applicable

Additional properties available:

• DestinationDatabase (String): The final Azure SQL database name
• BacpacPath (String): The generated BACPAC path; the file is removed by default unless KeepBacpac is specified
• Elapsed (prettytimespan): The elapsed processing time for the database