SQL Server

The FastWrappers-TSQL project wraps FastTransfer (and FastBCP) in a CLR Assembly, allowing you to call them directly from T-SQL using extended stored procedures. This enables seamless data transfer operations without leaving your SQL Server environment.

Extension Overview

• Repository: aetperf/FastWrappers-TSQL
• Latest version: v0.7.0
• Platforms: Windows and Linux
• Compatibility: SQL Server 2016+

info

This wrapper includes both FastTransfer (for database-to-database transfers and file imports) and FastBCP (for database-to-file exports). This documentation focuses on the FastTransfer functionality.

Features

• Native SQL Server Integration: Execute FastTransfer commands directly from T-SQL
• Secure Password Management: Built-in AES-256 encryption for sensitive credentials
• CLR Assembly Integration: Runs as extended stored procedures
• Detailed Result Return: Get transfer statistics and performance metrics as SQL results
• Flexible Configuration: Support for all FastTransfer parameters and connection types
• Role-Based Security: Predefined database roles for access control

Prerequisites

• SQL Server 2016 or later
• CLR integration enabled
• Valid FastTransfer binaries
• Valid FastTransfer license (request a trial license)
• Administrator privileges for initial setup

Important

The SQL Server service account must have read/execute permissions on the FastTransfer directory and binaries.

Installation

Download the latest release from the Releases page. Choose the installation method based on your SQL Server version:

Recommended Installation Methods

1. FastWrappers-TSQL.bak - SQL Server Backup file (recommended for SQL Server 2019+ - restore using SSMS)
   Requires manual CLR activation and trusted assembly configuration after restore

2. FastWrappers-TSQL.sql - Pure SQL Script (recommended for SQL Server 2016+ - all-in-one installation)
   Complete installation in a single script - execute using sqlcmd or SSMS

Post-Installation Configuration

info

This section only applies to the .bak installation method. The .sql script includes all necessary configuration steps automatically.

After restoring the database, you must configure CLR integration. Two options are available:

Trusted Assembly (Recommended)

This approach is more secure as it keeps TRUSTWORTHY OFF and doesn't require changing the database owner:

-- Enable CLR integration
EXEC sp_configure 'show advanced options', 1;
RECONFIGURE;
GO

EXEC sp_configure 'clr enabled', 1;
RECONFIGURE;
GO

-- Extract the assembly hash and add it to trusted assemblies
DECLARE @hash VARBINARY(64);

SELECT @hash = HASHBYTES('SHA2_512', content)
FROM sys.assembly_files
WHERE assembly_id = (
    SELECT assembly_id 
    FROM sys.assemblies 
    WHERE name = 'FastWrappers_TSQL'
);

EXEC sys.sp_add_trusted_assembly 
    @hash = @hash,
    @description = N'FastWrappers_TSQL Assembly v0.7.0';
GO

Advantages:

• TRUSTWORTHY remains OFF (more secure)
• No need to change database owner
• Only this specific assembly is trusted

tip

The assembly hash changes with each version. When upgrading, remove the old hash first:

EXEC sys.sp_drop_trusted_assembly @hash = <old_hash>;

TRUSTWORTHY ON (Dev/Test)

This approach is simpler but less secure. Use only for development/testing environments:

-- Enable TRUSTWORTHY for signed UNSAFE assemblies
ALTER DATABASE [FastWrappers-TSQL] SET TRUSTWORTHY ON;
GO

-- Enable CLR integration
EXEC sp_configure 'show advanced options', 1;
RECONFIGURE;
GO

EXEC sp_configure 'clr enabled', 1;
RECONFIGURE;
GO

-- Set database owner to 'sa' (required for signed UNSAFE assemblies)
EXEC sp_changedbowner 'sa';
GO

Critical

The sp_changedbowner 'sa' command is required. Without it, you will encounter error 0x80FC80F1 when executing stored procedures.

Security Roles

FastTransfer_Executor

The FastWrappers-TSQL database includes a predefined database role that grants EXECUTE permission on the xp_RunFastTransfer_secure stored procedure.

-- Add a user to the role
ALTER ROLE [FastTransfer_Executor] ADD MEMBER [YourUserName];
GO

tip

Users also need access to the dbo.EncryptString function to generate encrypted passwords:

GRANT EXECUTE ON dbo.EncryptString TO [YourUserName];
GO

Available Functions

dbo.EncryptString - Password Encryption

Encrypts passwords using AES-256 encryption for secure storage and transmission.

SELECT dbo.EncryptString('YourPassword')

Returns: Base64-encoded encrypted string

Example:

SELECT dbo.EncryptString('MySecretPassword')
-- Returns: wi1/VHz9s+fp45186iLYYQ==

dbo.xp_RunFastTransfer_secure - Data Transfer

Wraps the FastTransfer CLI to transfer data between databases with streaming and parallel processing.

Example:

EXEC dbo.xp_RunFastTransfer_secure
	@fastTransferDir = 'D:\FastTransfer\',
    @sourceConnectionType = 'mssql',
	@sourceServer = 'localhost,11433',
	@sourceUser = 'FastLogin',
	@sourcePasswordSecure = 'wi1/VHz9s+fp45186iLYYQ==',
	@sourceDatabase = 'tpch10',
	@sourceSchema = 'dbo',
	@sourceTable = 'orders',
	@targetConnectionType = 'pgcopy',
	@targetServer = 'localhost:25433',
	@targetUser = 'postgres',
	@targetPasswordSecure = 'RAAFe/XJ7O0P1I5T0rJhjQ==',
	@targetDatabase = 'postgres',
	@targetSchema = 'public',
	@targetTable = 'orders',
	@loadmode = 'Truncate',
	@method = 'Ntile',
	@distributeKeyColumn = 'o_orderkey',
	@degree = 12,
	@mapmethod = 'Name',
	@debug = 1,
	@noBanner = 0,
	@useWorkTables = 0,
	@loglevel = 'debug'

Output and Logging

Transfer Metrics

The xp_RunFastTransfer_secure stored procedure returns a structured result set:

Column	Type	Description
targetdatabase	nvarchar(128)	Target database name
targetSchema	nvarchar(128)	Target schema name
targetTable	nvarchar(128)	Target table name
TotalRows	bigint	Number of rows transferred
TotalColumns	int	Number of columns transferred
TotalCells	bigint	Total cells transferred (rows × columns)
TotalTimeMs	bigint	Total execution time in milliseconds
Status	int	Exit code (0 = success, non-zero = error)
StdErr	nvarchar(max)	Error message if Status ≠ 0

Example output:

targetdatabase  targetSchema  targetTable  TotalRows  TotalColumns  TotalCells   TotalTimeMs  Status
postgres        public        orders       15000000   9             135000000    27502        0

Debug Mode

Set @debug = 1 to output additional information:

• Complete command line being executed (passwords masked)
• Full console output from FastTransfer
• Real-time progress updates
• Performance metrics

EXEC dbo.xp_RunFastTransfer_secure
    @fastTransferDir = 'C:\FastTransfer\latest',
    -- ... other parameters ...
    @debug = 1  -- Enable verbose logging

Usage Examples

SQL Server to SQL Server (12 threads)

Transfer a table between two SQL Server instances using parallel processing:

-- First, encrypt your password
SELECT dbo.EncryptString('YourPassword')
-- Returns: wi1/VHz9s+fp45186iLYYQ==

-- Then execute the transfer
EXEC dbo.xp_RunFastTransfer_secure
    @fastTransferDir = 'C:\FastTransfer\latest\',
    @sourceConnectionType = N'mssql',
    @sourceServer = N'localhost',
    @sourceUser = N'FastUser',
    @sourcePasswordSecure = 'wi1/VHz9s+fp45186iLYYQ==',
    @sourceDatabase = N'tpch_test',
    @sourceSchema = N'dbo',
    @sourceTable = N'orders',
    @targetConnectionType = N'msbulk',
    @targetServer = N'localhost\SS2025',
    @targetUser = N'FastUser',
    @targetPasswordSecure = 'wi1/VHz9s+fp45186iLYYQ==',
    @targetDatabase = N'tpch_test',
    @targetSchema = N'dbo',
    @targetTable = N'orders_copy',
    @loadMode = N'Truncate',
    @batchSize = 130000,
    @method = N'RangeId',
    @distributeKeyColumn = N'o_orderkey',
    @degree = 12,
    @mapmethod = 'Name',
    @runId = N'SQL_to_SQL_Parallel_Transfer';

Oracle to SQL Server (12 threads)

Transfer data from Oracle to SQL Server with parallel RangeId method:

EXEC dbo.xp_RunFastTransfer_secure
    @fastTransferDir = 'C:\FastTransfer\latest\',
    @sourceConnectionType = 'oraodp',
    @sourceServer = 'oracle-server:1521/ORCL',
    @sourceUser = 'oracle_user',
    @sourcePasswordSecure = '<encrypted_password>',
    @sourceSchema = 'SALES',
    @sourceTable = 'ORDERS',
    @targetConnectionType = 'msbulk',
    @targetServer = 'localhost\SS2025',
    @targetUser = 'FastUser',
    @targetPasswordSecure = 'wi1/VHz9s+fp45186iLYYQ==',
    @targetDatabase = 'tpch_test',
    @targetSchema = 'dbo',
    @targetTable = 'orders_from_oracle',
    @loadMode = 'Truncate',
    @batchSize = 130000,
    @method = 'RangeId',
    @distributeKeyColumn = 'order_id',
    @degree = 12,
    @mapmethod = 'Name',
    @runId = 'Oracle_to_SQL_Transfer';

PostgreSQL to SQL Server (8 threads)

Use PostgreSQL's native Ctid method for optimal performance:

EXEC dbo.xp_RunFastTransfer_secure
    @fastTransferDir = 'C:\FastTransfer\latest\',
    @sourceConnectionType = 'pgcopy',
    @sourceServer = 'postgres-server:5432',
    @sourceUser = 'postgres',
    @sourcePasswordSecure = '<encrypted_password>',
    @sourceDatabase = 'sales_db',
    @sourceSchema = 'public',
    @sourceTable = 'customers',
    @targetConnectionType = 'msbulk',
    @targetServer = 'localhost',
    @targetUser = 'FastUser',
    @targetPasswordSecure = 'wi1/VHz9s+fp45186iLYYQ==',
    @targetDatabase = 'crm',
    @targetSchema = 'dbo',
    @targetTable = 'customers',
    @loadMode = 'Append',
    @batchSize = 100000,
    @method = 'Ctid',
    @degree = 8,
    @mapmethod = 'Name',
    @runId = 'PG_to_SQL_Ctid';

Additional Resources

• FastTransfer Documentation
• GitHub Repository

Support

For issues or questions:

• FastWrappers-TSQL: GitHub Issues
• FastTransfer: Contact ARPE Support