Chat now with support
Chat with Support

LiteSpeed for SQL Server 8.5 - Configure Log Shipping Guide

xp_objectrecovery

Restores a table from backup files. There are several ways to restore a table:

  • Restore table to a database - Allows you to directly restore the table. If a table with the same name already exists in the destination database, LiteSpeed will not overwrite it. However, you can use @destinationtable to rename the new table and restore it to the database.

  • Restore table to a ship directory - Allows you to restore the table later or on a different location.

  • Restore table to a .csv file - Allows you to open the file with Excel or any other spreadsheet application recognizing .csv file format.

NOTES:

  • You cannot restore objects from Clouds.
  • You cannot restore objects directly from TSM files or tape backups. For more information, see Object Level Restores from TSM Backups.
  • Object Level Recovery does not support SQL Server 2008 Transparent Data Encryption (TDE).
  • LiteSpeed may take a long time to read the backup file for large databases, often with little response in the LiteSpeed UI Console. To prevent this, the Optimize Object Level Recovery speed option on the Backup wizard Options page is selected by default to create the index during the backup.
  • Objects are recovered as they existed at the time they were backed up. You cannot recover data to a random point in time.
  • Direct mode - In scenarios where you want the application to work with SQL Server directly using a TCP/IP connection without involving the SQL Server client, you can enable direct mode which significantly improves deployment and configuration of your applications. You can enable and disable the use of direct mode from the the Recover Table Wizard.
  • Tail log processing - In scenarios when you do not require any transaction log backups and the tail log, you can select to bypass tail log processing. Object Level Recovery operations may work much faster in this case. You can enable and disable bypass tail log processing from the toolbar, and when running the Object Level Recovery Wizard and the Recover Table Wizard.

Syntax

Preview table data

EXEC master.dbo.xp_objectrecovery
@filename = 'backup_file_name' [,...n]
[, @filenumber = n]
[, @encryptionkey = 'encryption_key']
[( , @logfilename = 'log_file_name'
[, @stripedlogfilename = 'striped_log_file_name'] [,...n]
[, @logencryptionkey= 'log_encryption_key']
[, @logfilenumber = n ] ) [,...n]]
[, @difffilename = 'diff_file_name'] [,...n]
[, @difffilenumber = n]
[, @diffencryptionkey = 'diff_encrypt_key']
[, @LSM = 'option' ]
, @objectname = 'object_name'
[, @destinationserver = 'dest_server_name']
[, @tempdirectory = 'recovery_temp_dir']
[, @disablelogprocessing = 0 | 1 ]

Restore table to a database

EXEC master.dbo.xp_objectrecovery
@filename = 'backup_file_name' [,...n]
[, @filenumber = n]
[, @encryptionkey = 'encryption_key']
[( , @logfilename = 'log_file_name'
[, @stripedlogfilename = 'striped_log_file_name'] [,...n]
[, @logencryptionkey= 'log_encryption_key']
[, @logfilenumber = n ] ) [,...n]]
[, @difffilename = 'diff_file_name'] [,...n]
[, @difffilenumber = n]
[, @diffencryptionkey = 'diff_encrypt_key']
[, @LSM = 'option' ]
, @objectname = 'object_name'
, @destinationdatabase = 'database_name'
[, @destinationtable = 'dest_table_name']
[, @prefixtableobjects = N'prefix']
[, @suffixtableobjects = N'suffix']
[, @destinationserver = 'dest_server_name']
[, @tempdirectory = 'recovery_temp_dir']
[, @onfilegroup = 'table_filegroup_name']
[, @textimageonfilegroup = 'blob_filegroup_name']
[, @disablelogprocessing = 0 | 1 ]
[, @includetableobjects = 'options']

Restore table to a ship directory

EXEC master.dbo.xp_objectrecovery
@filename = 'backup_file_name' [,...n]
[, @filenumber = n]
[, @encryptionkey = 'encryption_key']
[( , @logfilename = 'log_file_name'
[, @stripedlogfilename = 'striped_log_file_name'] [,...n]
[, @logencryptionkey = 'log_encryption_key']
[, @logfilenumber = n ] ) [,...n]]
[, @difffilename = 'diff_file_name'] [,...n]
[, @difffilenumber = n]
[, @diffencryptionkey = 'diff_encrypt_key']
[, @LSM = 'option' ]
, @objectname = 'object_name'
, @shipdirectory = 'recovery_ship_dir'
[, @destinationtable = 'dest_table_name']
[, @prefixtableobjects = N'prefix']
[, @suffixtableobjects = N'suffix']
[, @onfilegroup = 'table_filegroup_name']
[, @textimageonfilegroup = 'blob_filegroup_name']
[, @disablelogprocessing = 0 | 1 ]
[, @includetableobjects = 'options']

Restore table to a .csv file

EXEC master.dbo.xp_objectrecovery
@filename = 'backup_file_name' [,...n]
[, @filenumber = n]
[, @encryptionkey = 'encryption_key']
[( , @logfilename = 'log_file_name'
[, @stripedlogfilename = 'striped_log_file_name'] [,...n]
[, @logencryptionkey = 'log_encryption_key']
[, @logfilenumber = n ] ) [,...n]]
[, @difffilename = 'diff_file_name'] [,...n]
[, @difffilenumber = n]
[, @diffencryptionkey = 'diff_encrypt_key']
[, @LSM = 'option' ]
, @objectname = 'object_name'
, @destinationfilename = 'csv_file_name'
[, @disablelogprocessing = 0 | 1 ]
[, @includetableobjects = 'options']

Arguments

Tips:

  • To see the list of accepted arguments and data types for arguments, execute the following:
    exec master.dbo.<procedure_name> show_help

  • To convert the script for use with the command-line utilities, execute the following:
    exec master.dbo.<procedure_name> show_cmd, <xp_arguments>

@AsOnDisk

Instructs LiteSpeed to restore an in-memory table as a regular table. This argument accepts one of the following values:

  • 0—False (Default)
  • 1—True

@backend

Object Level Recovery can restore tables using two different internal techniques to handle the record inserts.

The first and default method uses BCP files and a TSQL BULK INSERT statement. Object Level Recovery will write a BCP format file and an accompanying binary data file to the local file system. These files may become very large depending on the table size and will require permissions to write to a temporary directory. The default TEMP location can be set by using the @TempDirectory parameter or by setting a permanent temp location in the LiteSpeed configuration file.

An alternate insertion method can be specified to use Sql Server’s Sql Native Client capabilities. This method inserts row-data directly into the destination database bypassing any storage on the local file-system. To enable this method, use the parameter @backend='SQLNativeClient' (or -b 1 from the command line). To make this the default method set the value “BackEnd=SQLNativeClient” in the Object Level Recovery section of the LiteSpeed configuration file.

Regardless of the insertion method used, the batch size can be globally managed by setting the value “BulkImportBatchSize=<N>”. This will set the number of row inserts for each batched transaction.

@destinationdatabase

Specifies the destination database.

@destinationfilename

Name of comma separated file (.csv) that is generated instead restoring into a database. This is an ad hoc solution for users want to see the restored data in Excel. You can only use this argument for text data.

@destinationserver

Name of the destination server.

@destinationtable

Specifies the name of the destination table. LiteSpeed will not overwrite an existing table. If you select the same server instance and database as the original table, you must use a different table name.

NOTE: For Execute-Select operations, LiteSpeed will attempt to insert (append) all selected records into existing table.

@diffencryptionkey

Value used to generate the encryption key for the encryption algorithm. If you do not supply encryption key, then the program will not encrypt the backup. If you use the wrong encryption key, the restore will fail.

Caution: When encrypting data, take care not to lose the encryption key; a backup cannot be restored or recovered without the original encryption key.

Example of key: 'Mypassword'

Equivalent to @encryptionkey, but used for differential backups instead of full backup files.

@difffilename

Name of backup file to restore. Used for differential backups instead of full backup files. You can supply multiple instances of this argument.

@difffilenumber

Identifies the backup file within the backup set. Equivalent to @filenumber, but used for differential backups instead of full backup files.

@disablelogprocessing

Instructs LiteSpeed to skip all transaction log backups and tail log processing. This may improve read and recovery times. This argument accepts one of the following values:

  • 0—False (Default).
  • 1—True. LiteSpeed will entirely ignore any transaction log backups specified and will not process the tail log.

@encryptionkey

Value used to generate the encryption key for the encryption algorithm. If you do not supply encryption key, then the program will not encrypt the backup. If you use the wrong encryption key, the restore will fail.

Caution: When encrypting data, take care not to lose the encryption key; a backup cannot be restored or recovered without the original encryption key.

Example of key: 'Mypassword'

@filename

Specifies a backup location (e.g. C:\backups\AdventureWorks.bak). This argument accepts network destinations. You can supply multiple instances of this argument to use stripe backups.

@filenumber

Specifies the particular backup to use when recasting, restoring, extracting or reading from files with multiple appended backups. You can run xp_restore_headeronly to query the files contained within the backup set given by backup_file_name.

@FilestreamOnFileGroup

Specifies a file stream filegroup to include in the object restore.

@includetableobjects

Instructs LiteSpeed to script or recover one or more of the following:

  • Constraints—But not foreign keys
  • ForeignKeys
  • Indexes
  • Statistics
  • Triggers
  • All—All of the above

The value is a list of options, separated with commas.

@logencryptionkey

Value used to generate the encryption key for the encryption algorithm. If you do not supply encryption key, then the program will not encrypt the backup. If you use the wrong encryption key, the restore will fail.

Caution: When encrypting data, take care not to lose the encryption key; a backup cannot be restored or recovered without the original encryption key.

Example of key: 'Mypassword'

Equivalent to @encryptionkey, but used for transaction log backups.

@logfilename

Specifies location and name of the log backup file. You can supply multiple instances of this argument.

Syntax

@logfilenumber

Identifies the log backup file within the backup set. Equivalent to @filenumber, but used for log backups.

@LSM

Specifies handling for OLR LSM mapfile(s).

  • Create—Reads backup and creates a new mapfile. It will ignore attached LSM.
  • Keep—Does not delete mapfile(s) when complete.
  • Delete—Always deletes mapfile(s) when complete.

@objectname

Specifies the name of the object to recover.

@onfilegroup

Filegroup with the object to restore.

@PersistLogProcessing

Instructs LiteSpeed to persist log processing, so the same database backup does not have to be processed for each Object Level Recovery operation. This argument accepts one of the following values:

  • 0—False (Default).
  • 1—True. LiteSpeed will persist transaction log backups specified and the tail log for future use. This option can offer a huge performance gain for working with databases with large tail logs that could possibly take a long time to process.

@prefixtableobjects

Adds a prefix to the names of the table's objects you selected to script or recover.

@shipdirectory

Name of the ship directory. Use this argument when you want to restore the object later or at a different physical location.  This argument creates the following files in the ship directory:

  • CREATE <object_name>.sql

  • BULK INSERT <object_name>.sql

  • <object_name>.fmt

  • <object_name>.bcp

To restore the object, run the CREATE file first, and then run the BULK INSERT file. You will need to slightly modify the BULK INSERT file because of the .fmt and .bcp file path names.

Tip: You can zip the files and send them to someone else.

@Status_FileName

Specifies the status of a backup location.

@stripedlogfilename

Specifies the striped log file name.

NOTE: The striped files for a given log backup must be specified before the next log backup set is specified.

@suffixtableobjects

Adds a suffix to the names of the table's objects you selected to script or recover.

@tempdirectory

Specifies a temporary directory for use with Object Level Recovery. Use this argument when the default Windows temp directory does not have enough free disk space for the restore process.

NOTE: You can specify the default temp directory using the TempPath parameter in the [LiteSpeed] section of the LiteSpeedSettings.ini file. (Usually, C:\Documents and Settings\All Users\Application Data\Quest Software\LiteSpeed\SQL Server\LiteSpeedSettings.ini.)

@textimageonfilegroup

Destination TEXTIMAGE_ON filegroup name. Used to restore a BLOB (binary large object).

Examples

Preview a table from a full backup file

EXEC master.dbo.xp_objectrecovery
@filename='C:\MSSQL\Backup\MyDB_Backup.BAK',
@filenumber = 1,
@objectname='dbo.Customers'

Restore a table from a full backup file into a database

EXEC master.dbo.xp_objectrecovery
@filename = 'C:\MSSQL\Backup\MyDB_Backup.BAK'
, @filenumber = 1,
, @objectname = 'dbo.Customers'
, @destinationdatabase = 'tempdb'

Restore multiple tables and tables' constraints and indexes

exec xp_objectrecovery
@FileName = N'C:\temp\HiServ_full.bak',
@FileNumber = 1,
@ObjectName = N'dbo.Roles',
@DestinationTable = N'[dbo].[Roles]',
@DestinationDatabase = N'HiServ',
@DestinationServer = N'w2k3-22\LITESPEED',
@IncludeTableObjects = N'indexes, constraints, foreignKeys'

exec xp_objectrecovery
@FileName = N'C:\temp\HiServ_full.bak',
@FileNumber = 1,
@ObjectName = N'dbo.Employees',
@DestinationTable = N'[dbo].[Employees]',
@DestinationDatabase = N'HiServ',
@DestinationServer = N'w2k3-22\LITESPEED',
@IncludeTableObjects = N'indexes, constraints, foreignKeys'

exec xp_objectrecovery
@FileName = N'C:\temp\HiServ_full.bak',
@FileNumber = 1,
@ObjectName = N'dbo.Customers',
@DestinationTable = N'[dbo].[Customers]',
@DestinationDatabase = N'HiServ',
@DestinationServer = N'w2k3-22\LITESPEED',
@IncludeTableObjects = N'indexes, constraints, foreignKeys'

exec xp_objectrecovery
@FileName = N'C:\temp\HiServ_full.bak',
@FileNumber = 1,
@ObjectName = N'dbo.Projects',
@DestinationTable = N'[dbo].[Projects]',
@DestinationDatabase = N'HiServ',
@DestinationServer = N'w2k3-22\LITESPEED',
@IncludeTableObjects = N'indexes, constraints, foreignKeys'

exec xp_objectrecovery
@FileName = N'C:\temp\HiServ_full.bak',
@FileNumber = 1,
@ObjectName = N'dbo.Positions',
@DestinationTable = N'[dbo].[Positions]',
@DestinationDatabase = N'HiServ',
@DestinationServer = N'w2k3-22\LITESPEED',
@IncludeTableObjects = N'indexes, constraints, foreignKeys'

Restore a table from a full backup file to a database using table, server, filegroup and temp directory parameters

EXEC master.dbo.xp_objectrecovery
@filename = 'C:\MSSQL\Backup\MyDB_Backup.BAK'
, @objectname = 'dbo.Customers'
, @destinationdatabase = 'tempdb'
, @destinationtable = 'dbo.Restored_Customers'
, @destinationserver = 'MyMachine\SQL2000'
, @tempdirectory = 'D:\temp'
, @onfilegroup = 'Secondary'
, @textimageonfilegroup = 'Secondary'

Restore a table from a striped backup

EXEC master.dbo.xp_objectrecovery
@filename='C:\TestSCriptBackups\full_Mon'
, @filename='C:\TestSCriptBackups\'
, @filenumber=1
, @encryptionkey = 'key'
, @logfilename='C:\TestSCriptBackups\Log_Mon_0900_1'
, @logencryptionkey = 'key'
, @stripedlogfilename='C:\TestSCriptBackups\Log_Mon_0900_2'
, @stripedlogfilename='C:\TestSCriptBackups\Log_Mon_0900_3'
, @logfilenumber=1
, @destinationtable='dbo.employees_recovered'
, @destinationdatabase='OLRRegressionTest'
, @objectname='dbo.employees'

Restore a table from a full backup file to a ship directory

EXEC master.dbo.xp_objectrecovery
@filename = 'C:\MSSQL\Backup\MyDB_Backup.BAK'
, @objectname = 'dbo.Customers'
, @shipdirectory = 'C:\temp\ship'

Restore a table from a full backup file to a .csv file

EXEC master.dbo.xp_objectrecovery
@filename = 'C:\MSSQL\Backup\MyDB_Backup.BAK'
, @objectname = 'dbo.Customers'
, @destinationfilename = 'C:\temp\Customers.csv'

Returns

0 (success) or non-zero (failure). Return codes represent the native error number returned from SQL Server for any errors encountered during the operation.

To capture the output message, run the following:

declare @rmsg varchar(999)
exec master..<procedure_name> <arguments>, @resultmsg=@rmsg output
select @rmsg

To capture the output message and the result code, run the following:

declare @rc int
declare @rmsg varchar(999)
exec master..<procedure_name> <arguments>, @resultmsg=@rmsg output, @resultcode=@rc output
select @rc, @rmsg

Related Documents