page_type: sample languages:
Latest Stable Version: 1.9.9
Smart, High-Speed, Bulk Copy tool to move data from one Azure SQL / SQL Server database to another. Smartly uses logical or physical partitions to maximize transfer speed using parallel copy tasks.
It can be also used to efficiently and quickly move data from two instances of SQL Server running in two different cloud providers or to move from on-premises to the cloud.
Smart Bulk Copy is also available as a Docker Image. To run Smart Bulk Copy via docker, you have to map a volume where the desired .config file can be found. For example (on Windows):
docker run -it -v c:\work\_git\smart-bulk-copy\client\configs:/app/client/configs yorek/smartbulkcopy:latest /app/client/configs/smartbulkcopy.config.json
You can also run Smart Bulk Copy using Azure Container Instances. Use the provided azure-deploy.sh
script to create an ACI and execute Smart Bulk Copy. Make sure you have created the smartbulkcopy.config.json
file in the client/configs
folder before running the .sh
script.
Smart Bulk Copy uses Bulk Copy API with parallel tasks. A source table is split in partitions, and each partition is copied in parallel with others, up to a defined maximum, in order to use all the available network bandwidth and all the cloud or server resources available to minimize the load times.
When a source table is partitioned, it uses the physical partitions to execute several queries like the following:
SELECT * FROM <sourceTable> WHERE $partition.<partitionFunction>(<partitionColumn>) = <n>
Queries are executed in parallel to load, always in parallel, data into the destination table. TABLOCK
options is used - when possible and needed - on the table to allow fully parallelizable bulk inserts. ORDER
option is also used when possible to minimize the sort operations on the destination table, for example when inserting into a table with an existing clustered rowstore index.
If a source table is not partitioned, then Smart Bulk Copy will use the %%PhysLoc%%
virtual column to logically partition tables into non-overlapping partitions that can be safely read in parallel. %%PhysLoc%%
is not documented, but more info are available here:
Where is a record really located?
If the configuration file specifies a value greater than 1 for logical-partitions
the following query will be used to read the logical partitions in parallel:
SELECT * FROM <sourceTable> WHERE ABS(CAST(%%PhysLoc%% AS BIGINT)) % <logical-partitions-count> = <n>
PLEASE NOTE that the physical position of a row may change at any time if there is any activity on the database (updates, index reorgs, etc...) so it is recommended that this approach is used only in three cases:
From version 1.7 Smart Bulk Copy will smartly copy tables with no clustered index (heaps), and tables with clustered index (rowstore or columnstore it doesn't matter.)
Couple of notes for tables with Clustered Columnstore index:
Download or clone the repository, make sure you have .NET Core 3.1 installed and then build Smart Bulk Copy:
dotnet build
Then, in the client
folder, create a smartbulkcopy.config
file from the provided client/config/smartbulkcopy.config.template
. If you want to start right away just, provide source and destination connection strings and leave all the options as is. Make sure the source database is a database snapshot:
Or that the database is set to be in Read-Only mode:
Setting the database to READ_ONLY
Then just run:
cd client
dotnet run
and Smart Bulk Copy will start to copy data from source database to destination database. Please keep in mind that all destination tables will be truncated by default. This means that Foreign key constraints must be dropped in the destination database before copying. Read more about TRUNCATE TABLE
restrictions here: TRUNCATE TABLE
Here's how you can change Smart Bulk Copy configuration to better suits your needs. Everything is conveniently found in smartbulkcopy.config
file. Aside from the obvious source and destination connection strings, here's the configuration options you can use:
tables
: an array of string values the contains the two-part names of the table you want to copy. For example:
'tables': ['dbo.Table1', 'Sales.Customers']
An asterisk *
will be expanded to all tables available in the source database:
'tables': ['*']
You can use schema to limit the wildcard scope:
'tables': ['dbo.*']
From version 1.7.1 you can also specify tables to be included and excluded:
"tables": {
"include": ["dbo.*"],
"exclude": ["dbo.ORDERS"]
}
Smart Bulk Copy is highly configurable. Read more in the dedicated document: Smart Bulk Copy Configuration Options
Azure SQL is log-rated as described in Transaction Log Rate Governance and it can do 96 MB/sec of log flushing. Smart Bulk Load will report the detected log flush speed every 5 seconds so that you can check if you can actually increase the number of parallel task to go faster or you're already at the limit. Please remember that 96 MB/Sec are done with higher SKU, so if you're already using 7 parallel tasks and you're not seeing something close to 96 MB/Sec please check that
There are a couple of exceptions to what just described:
Tests have been ran using the LINEITEM
table of TPC-H 10GB test database. Uncompressed table size is around 8.8 GB with 59,986,052 rows. Source database was a SQL Server 2017 VM running on Azure and the target was Azure SQL Hyperscale Gen8 8vCores. Smart Bulk Copy was running on the same Virtual Machine where also source database was hosted. Both the VM and the Azure SQL database were in the same region.
Used configuration settings:
"tasks": 7,
"logical-partitions": "auto",
"batch-size": 100000
Here's the result of the tests:
Table | Copy Time (in sec) |
---|---|
HEAP | 135 |
HEAP, PARTITIONED | 111 |
CLUSTERED ROWSTORE | 505 |
CLUSTERED ROWSTORE, PARTITIONED | 207 |
CLUSTERED COLUMNSTORE | 315 |
CLUSTERED COLUMNSTORE, PARTITIONED | 196 |
As the document was getting longer and longer, it has been moved here: Smart Bulk Copy FAQ
This tool has been tested against the following sample database with success:
Note that Foreign Keys and Views were dropped from target table before starting bulk copy
Smart Bulk Copy has been tested with the following SQL Server engine versions: