Invoke-NimDatabaseClone

The Invoke-NimDatabaseClone cmdlet enables you to create clones of SQL databases residing on volumes in a volume collection or a snapshot collection. With this cmdlet, you can assign a drive letter or directory path to the Windows volumes and add the cloned volumes to the cluster as an available resource.

This cmdlet performs the following operations:
  • Detects the volumes belonging to the database using an SQL VSS writer.
  • Creates clones of volumes in a volume collection or snapshots in a snapshot collection.
  • Assigns a drive letter as an access path.
  • Adds a directory as an access path.
  • Assigns a drive letter and adds the clone to the cluster as an available disk.
  • iSCSI environments: Uses the -IsPersistent option to ensure that the connection is persistent.
  • Fibre Channel cluster environments: Creates a temporary initiator group with the name <host>-<guid>-DoNotUse to map the volume to a local node until the volume is ready to be mounted on multiple nodes.
  • When the CrashConsistent option is used, creates crash-consistent snapshots. It uses these as the base snapshots for the clone creation operation.

If you are using synchronous/asynchronous replication, you can use Invoke-NimDatabaseClone and Get-NimDatabaseSnapshot together to create a clone of a snapshot collection of an upstream or downstream. For example, you might enter a command line similar to Get-NimDatabaseSnapshot -NoReplica -DBName <name> -MaxObjects <integer> | Invoke-NimDatabaseClone. See Get-NimDatabaseSnapshot for details about its requirements.

This cmdlet returns a NimbleVolume object, which contains {DeviceName, SerialNumber,GroupManagementIP, NimbleVolumeName, PoolName, DiskSize, BusType, WindowsVolumes, FCTargetMappings, Clone, Snapshot, BaseSnapshotName, and ParentVolumeName}.

Refer to General Best Practices for Using Cmdlets for general tips for working with cmdlets. The Invoke-NimSnapVolumeCollection cmdlet also has the following best practice recommendations:

  • To improve iSCSI connect, disconnect, and disk rescan performance, remove reconnecting sessions using an iSCSI initiator applet.

  • In the array group UI, configure a VLAN for iSCSI initiator groups.

  • Define a single initiator group with all the initiators of each node in the cluster.

  • If you are using a test environment where frequent volume connect and disconnect operations are done, download the DevNodeClean utility from Microsoft and run it periodically. Windows creates phantom devices when you perform those operations.

  • Run CHKDSK after cloning to ensure that the Windows file system is healthy.

The Invoke-NimDatabaseClone cmdlet has the following limitations:
  • The databases being passed in the cmdlet must all reside on volumes that belong to the same group.
  • Your credentials must allow you to access the groups affected by the cmdlet. Use the Set-Configuration cmdlet to configure your credentials.

  • You cannot use both the AssignDriveLetter and AccessPath parameters at the same time.

  • The IsPersistent option is relevant only when you have an iSCSI array.
The Invoke-NimDatabaseClone cmdlet has the following limitations on Windows 2008 R2 clusters:

  • Remote operations on clusters are not supported. You must run the clone cmdlet on the first node without the AddToCluster option. Then switch to the second node and run the Connect-NimVolume cmdlet using the AddToCluster option.

  • Using the AddToCluster option only creates the cluster resource and adds it to the cluster in an offline state. You must manually connect the volume on other nodes and then try to bring the cluster resource online.

  • If you are running the iSCSI protocol and have more than a 2-node cluster, you must manually set the MultiInitiator flag on the cloned volume after calling Invoke from the first node and before calling Connect-NimVolume from the second node. This limitation does not apply to the FC protocol.

If you experience a problem using the Invoke-NimDatabaseClone cmdlet, check the information in Troubleshooting Cmdlet Issues.

Options

The Invoke-NimDatabaseClone cmdlet supports several command options.

-Application <String> option. The name of the application for which database should be cloned. Currently only sql is supported.

-SQLInstance <String[]> option. The name of the SQL instance. You can use this option with the DBName option. When you use it with the DBName option, the cmdlet clones the database in the DBName option and all the databases in the SQL instance. If the database provided in the DBName option is the same as the one in the SQL instance, then only one clone is created. If there are multiple databases in different SQL instances, you can use this parameter to specify the SQL instance that you want to use. For example, you might enter -DBName sqlcluster4/c7a8db1.

-DBName <String[]> option. The name of the database you want to clone. The format of the parameter is instanceName/DBName. If you do not provide an SQL instance as the value for instanceName, the default SQL instance (the localhostname) is used. You can use this option with the SQLInstance option. The value for this option is case sensitive. Wild card characters are not supported.

-NimDatabaseObj <NimDatabase[]> option. This is a pipeline option that clones the NimbleDatabase objects returned by the Get-NimDatabase cmdlet.

-BaseAccessPath <String> option. The name of the directory or drive letter that you want to assign as the base access path to the volume. This option creates a randomly generated child directory under BaseAccessPath to mount the clone.

-AssignDriveLetter [<SwitchParameter>]> option. This option automatically assigns to the cloned volume the next available Windows drive letter. It uses any available drive letter from B-Z. To assign a specific drive letter or mount point to the volume, use the AccessPath option.

-CrashConsistent [<SwitchParameter>] option. This option tells the cmdlet to take a crash-consistent snapshot of the volume collection where the database volumes reside.

-AddToCluster [<SwitchParameter>] option. Specifying this option tells the cmdlet to add the cloned volume to the cluster that contains the local node where the cmdlet is run. The procedure detects whether the cluster is present, gets the cluster nodes, adds the resource to the cluster as an available disk, and connects the cloned volume to all nodes in the cluster.

-IsPersistent [<SwitchParameter>] option. Only use this option in iSCSI environments. The IsPersistent flag is useful when connecting the volumes from an iSCSI array. When the IsPersistent flag is set, iSCSI connections are maintained on reboot.

-Suffix <String> option. This is the string that will be appended to a unique string to create a unique name for the snapshot on the group.

-SnapshotCollectionName <String> option. The name of the snapshot collection on the group that you want to clone. This snapshot collection can be either crash consistent or VSS-enabled. You must use the VolumeCollection option with the SnapshotCollectionName option.

-VolumeCollectionName <String> option. The name of the volume collection on the group that you want to clone. A crash-consistent snapshot of each volume in the volume collection is taken before cloning.
IMPORTANT: The cmdlet does not take an application-consistent (VSS) snapshot. You must specify a VSS-enabled snapshot collection name to clone from a VSS snapshot.

-GroupMgmtIP <IPAddress> option. The IP address for the management group. If you do not specify a value for this option and a value for DBName is provided, then the cmdlet searches for that database on all the arrays configured on the host and clones them. If NimbleDatabaseObj or pipedNimDbSnapshotobj is passed as a option or a pipeline object, then the group management IP property of those objects is used. The group management IP is set by running Set-Configuration. Only the Windows user who ran Set-Configuration can use the information.

-NimDbSnapshotobj <NimDatabaseSnapshot> option. This is a pipeline option that clones the INimDatabaseSnapshot objects returned by the Get-NimDatabaseSnapshot cmdlet.

-InformationAction <ActionPreference> option. This is a default PowerShell option and has no effect on the cmdlet execution.

-InformationVariable <String> option. This is a default PowerShell option and has no effect on the cmdlet execution.

-WhatIf [<SwitchParameter>] option. This option validates the parameter, but does not modify data. When used with the -Verbose option, it displays messages on the console.

-Confirm [<SwitchParameter>] option. This option is used with the -Force option to ensure that a confirmation message is displayed. It has no effect on the cmdlet execution.

-Force [<SwitchParameter>] option. This option suppresses the confirmation warning message and performs the opration. It has no effect on the cmdlet execution.

<CommonParameters>. This cmdlet supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).

Syntax variants

The command options you use with the Invoke-NimDatabaseClone cmdlet vary depending on the type of object you want to remove.

NOTE: For more details about working with the cmdlet, view the cmdlet help by entering Get-Help <cmdlet_name>.

Three examples of generic command lines are shown below. Some examples of using the cmdlet are shown after that:

Invoke-NimDatabaseClone [-Application <String>] [-SQLInstance <String[]>] [-DBName <String[]>] [-NimDatabaseObj <NimDatabase[]>] [-BaseAccessPath <String>] [-AssignDriveLetter <SwitchParameter>] [-CrashConsistent <SwitchParameter>] [-AddToCluster <SwitchParameter>] [-IsPersistent <SwitchParameter>] [-Suffix <String>] [-InformationAction <ActionPreference>] [-InformationVariable <String>] [-WhatIf <SwitchParameter>] [-Confirm <SwitchParameter>] [<CommonParameters>]

Invoke-NimDatabaseClone [-Application <String>] [-SQLInstance <String[]>] [-DBName <String[]>] -SnapshotCollectionName <String> [-Force <SwitchParameter>] -VolumeCollectionName <String> -GroupMgmtIP <IPAddress> [-BaseAccessPath <String>] [-AssignDriveLetter <SwitchParameter>] [-CrashConsistent <SwitchParameter>] [-AddToCluster <SwitchParameter>] [-IsPersistent <SwitchParameter>] [-Suffix <String>] [-InformationAction <ActionPreference>] [-InformationVariable <String>] [-WhatIf <SwitchParameter>] [-Confirm <SwitchParameter>] [<CommonParameters>]

Invoke-NimDatabaseClone [-SQLInstance <String[]>] [-DBName <String[]>] [-NimDbSnapshotobj <NimDatabaseSnapshot[]>] [-Force <SwitchParameter>] [-BaseAccessPath <String>] [-AssignDriveLetter <SwitchParameter>] [-CrashConsistent <SwitchParameter>] [-AddToCluster <SwitchParameter>] ] [-IsPersistent <SwitchParameter>] [-Suffix <String>] [-InformationAction <ActionPreference>] [-InformationVariable <String>] [-WhatIf <SwitchParameter>] [-Confirm <SwitchParameter>] [<CommonParameters>]

Create clone for a single database example:

Invoke-NimDatabaseClone -DBName db1

Clone of multiple databases with the instance name provided in DBName option example:

Invoke-NimDatabaseClone -DBName db1,test1/dbo

Passing a NimbleDatabase object on pipeline to clone example:

Get-NimDatabase -DBName dbo -SQLInstance test1| Invoke-NimDatabaseClone

Cloning a snapshot collection by passing the snap collection name and volume collection name along with the DBName object example:

Invoke-NimDatabaseClone -DBName shubh1/dbo -SnapshotCollectionName dgnh -VolumeCollectionName shubh-snap -GroupMgmtIP 10.00.000.00

Cloning a database and mounting the clones under particular path by passing the BaseAccessPath option example:

Invoke-NimDatabaseClone -DBName db1 -BaseAccessPath c:\temp