< Back

Start-DbaMigration

Mon Jan 13, 2020 5:50 pm

NAME Start-DbaMigration



SYNOPSIS

Migrates SQL Server *ALL* databases, logins, database mail profiles/accounts, credentials, SQL Agent objects,

linked servers,

Central Management Server objects, server configuration settings (sp_configure), user objects in systems databases,

system triggers and backup devices from one SQL Server to another.



For more granular control, please use Exclude or use the other functions available within the dbatools module.





SYNTAX

Start-DbaMigration [[-Source] <DbaInstanceParameter>] [[-Destination]

<Sqlcollaborative.Dbatools.Parameter.DbaInstanceParameter[]>] [-DetachAttach <Switch>] [-Reattach <Switch>]

[-BackupRestore <Switch>] [[-SharedPath] <String>] [-WithReplace <Switch>] [-NoRecovery <Switch>]

[-SetSourceReadOnly <Switch>] [-ReuseSourceFolderStructure <Switch>] [-IncludeSupportDbs <Switch>]

[[-SourceSqlCredential] <Pscredential>] [[-DestinationSqlCredential] <Pscredential>] [[-Exclude]

<System.String[]>] [-DisableJobsOnDestination <Switch>] [-DisableJobsOnSource <Switch>] [-ExcludeSaRename

<Switch>] [-UseLastBackup <Switch>] [-Continue <Switch>] [-Force <Switch>] [[-AzureCredential] <String>]

[-EnableException <Switch>] [<CommonParameters>]





DESCRIPTION

Start-DbaMigration consolidates most of the migration tools in dbatools into one command. This is useful when

you're looking to migrate entire instances. It less flexible than using the underlying functions. Think of it as

an easy button. It migrates:



All user databases to exclude support databases such as ReportServerTempDB (Use -IncludeSupportDbs for this). Use

-Exclude Databases to skip.



All logins. Use -Exclude Logins to skip.



All database mail objects. Use -Exclude DatabaseMail



All credentials. Use -Exclude Credentials to skip.



All objects within the Job Server (SQL Agent). Use -Exclude AgentServer to skip.



All linked servers. Use -Exclude LinkedServers to skip.



All groups and servers within Central Management Server. Use -Exclude CentralManagementServer to skip.



All SQL Server configuration objects (everything in sp_configure). Use -Exclude SpConfigure to skip.



All user objects in system databases. Use -Exclude SysDbUserObjects to skip.



All system triggers. Use -Exclude SystemTriggers to skip.



All system backup devices. Use -Exclude BackupDevices to skip.



All Audits. Use -Exclude Audits to skip.



All Endpoints. Use -Exclude Endpoints to skip.



All Extended Events. Use -Exclude ExtendedEvents to skip.



All Policy Management objects. Use -Exclude PolicyManagement to skip.



All Resource Governor objects. Use -Exclude ResourceGovernor to skip.



All Server Audit Specifications. Use -Exclude ServerAuditSpecifications to skip.



All Custom Errors (User Defined Messages). Use -Exclude CustomErrors to skip.



All Data Collector collection sets. Does not configure the server. Use -Exclude DataCollector to skip.



All startup procedures. Use -Exclude StartupProcedures to skip.



This script provides the ability to migrate databases using detach/copy/attach or backup/restore. SQL Server

logins, including passwords, SID and database/server roles can also be migrated. In addition, job server objects

can be migrated and server configuration settings can be exported or migrated. This script works with named

instances, clusters and SQL Express.



By default, databases will be migrated to the destination SQL Server's default data and log directories. You can

override this by specifying -ReuseSourceFolderStructure. Filestreams and filegroups are also migrated. Safety is

emphasized.





PARAMETERS

-AzureCredential [<String>]

Name of the AzureCredential if SharedPath is Azure page blob



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-BackupRestore [<Switch>]

If this switch is enabled, the Copy-Only backup and restore method is used to perform database migrations. You

must specify -SharedPath with a valid UNC format as well (\\\\server\\share).



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-Continue [<Switch>]

If specified, will to attempt to restore transaction log backups on top of existing database(s) in Recovering

or Standby states. Only usable with -UseLastBackup



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-Destination [<Sqlcollaborative.Dbatools.Parameter.DbaInstanceParameter[]>]

Destination SQL Server. You may specify multiple servers.



Note that when using -BackupRestore with multiple servers, the backup will only be performed once and backups

will be deleted at the end (if you didn't specify -ExcludeBackupCleanup).



When using -DetachAttach with multiple servers, -Reattach must be specified.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-DestinationSqlCredential [<Pscredential>]

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.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-DetachAttach [<Switch>]

If this switch is enabled, the the detach/copy/attach method is used to perform database migrations. No files

are deleted on Source. If the destination attachment fails, the source database will be reattached. File

copies are performed over administrative shares (\\\\server\\x$\\mssql) using BITS. If a database is being

mirrored, the mirror will be broken prior to migration.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-DisableJobsOnDestination [<Switch>]

If this switch is enabled, migrated SQL Agent jobs will be disabled on the destination instance.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-DisableJobsOnSource [<Switch>]

If this switch is enabled, SQL Agent jobs will be disabled on the source instance.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-EnableException [<Switch>]

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.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-Exclude [<System.String[]>]

Exclude one or more objects to migrate



Databases

Logins

AgentServer

Credentials

LinkedServers

SpConfigure

CentralManagementServer

DatabaseMail

SysDbUserObjects

SystemTriggers

BackupDevices

Audits

Endpoints

ExtendedEvents

PolicyManagement

ResourceGovernor

ServerAuditSpecifications

CustomErrors

DataCollector

StartupProcedures

AgentServerProperties



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-ExcludeSaRename [<Switch>]

If this switch is enabled, the sa account will not be renamed on the destination instance to match the source.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-Force [<Switch>]

If migrating users, forces drop and recreate of SQL and Windows logins.

If migrating databases, deletes existing databases with matching names.

If using -DetachAttach, -Force will break mirrors and drop dbs from Availability Groups.



For other migration objects, it will just drop existing items and readd, if -force is supported within the

underlying function.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-IncludeSupportDbs [<Switch>]

If this switch is enabled, the ReportServer, ReportServerTempDb, SSIDb, and distribution databases will be

migrated if they exist. A logfile named $SOURCE-$DESTINATION-$date-Sqls.csv will be written to the current

directory. Requires -BackupRestore or -DetachAttach.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-NoRecovery [<Switch>]

If this switch is enabled, databases will be left in the No Recovery state to enable further backups to be

added.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-Reattach [<Switch>]

If this switch is enabled, all databases are reattached to Source after a DetachAttach migration is complete.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-ReuseSourceFolderStructure [<Switch>]

If this switch is enabled, the data and log directory structures on Source will be kept on Destination.

Otherwise, databases will be migrated to Destination's default data and log directories.



Consider this if you're migrating between different versions and use part of Microsoft's default SQL structure

(MSSQL12.INSTANCE, etc.).



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-SetSourceReadOnly [<Switch>]

If this switch is enabled, all migrated databases will be set to ReadOnly on the source instance prior to

detach/attach & backup/restore. If -Reattach is specified, the database is set to read-only after reattaching.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-SharedPath [<String>]

Specifies the network location for the backup files. The SQL Server service accounts on both Source and

Destination must have read/write permission to access this location.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-Source [<DbaInstanceParameter>]

Source SQL Server.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-SourceSqlCredential [<Pscredential>]

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.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-UseLastBackup [<Switch>]

Use the last full, diff and logs instead of performing backups. Note that the backups must exist in a location

accessible by all destination servers, such a network share.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-WithReplace [<Switch>]

If this switch is enabled, databases are restored from backup using WITH REPLACE. This is useful if you want

to stage some complex file paths.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



<CommonParameters>

This cmdlet supports the common parameters: Verbose, Debug,

ErrorAction, ErrorVariable, WarningAction, WarningVariable,

OutBuffer, PipelineVariable, and OutVariable. For more information, see

about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).



INPUTS



OUTPUTS



NOTES





Tags: Migration

Author: Chrissy LeMaire (@cl), netnerds.net



Website: https://dbatools.io

Copyright: (c) 2018 by dbatools, licensed under MIT

License: MIT https://opensource.org/licenses/MIT



-------------------------- EXAMPLE 1 --------------------------



PS C:\\>Start-DbaMigration -Source sqlserver\\instance -Destination sqlcluster -DetachAttach



All databases, logins, job objects and sp_configure options will be migrated from sqlserver\\instance to

sqlcluster. Databases will be migrated using the detach/copy files/attach method. Dbowner will be updated. User

passwords, SIDs, database roles and server roles will be migrated along with the login.

-------------------------- EXAMPLE 2 --------------------------



PS C:\\>$params = @{



>> Source = "sqlcluster"

>> Destination = "sql2016"

>> SourceSqlCredential = $scred

>> DestinationSqlCredential = $cred

>> SharedPath = "\\\\fileserver\\share\\sqlbackups\\Migration"

>> BackupRestore = $true

>> ReuseSourceFolderStructure = $true

>> Force = $true

>> }

>>

PS C:\\> Start-DbaMigration @params -Verbose



Utilizes splatting technique to set all the needed parameters. This will migrate databases using the

backup/restore method. It will also include migration of the logins, database mail configuration, credentials, SQL

Agent, Central Management Server, and SQL Server global configuration.

-------------------------- EXAMPLE 3 --------------------------



PS C:\\>Start-DbaMigration -Verbose -Source sqlcluster -Destination sql2016 -DetachAttach -Reattach

-SetSourceReadonly



Migrates databases using detach/copy/attach. Reattach at source and set source databases read-only. Also migrates

everything else.

-------------------------- EXAMPLE 4 --------------------------



PS C:\\>$PSDefaultParameters = @{



>> "dbatools:Source" = "sqlcluster"

>> "dbatools:Destination" = "sql2016"

>> }

>>

PS C:\\> Start-DbaMigration -Verbose -Exclude Databases, Logins



Utilizes the PSDefaultParameterValues system variable, and sets the Source and Destination parameters for any

function in the module that has those parameter names. This prevents the need from passing them in constantly.

The execution of the function will migrate everything but logins and databases.



RELATED LINKS

https://dbatools.io/Start-DbaMigration