This guide covers provisioning a Microsoft SQL Server Virtual Database (VDB) using dct-toolkit.

Prerequisites

  • dct-toolkit installed and configured (create_config completed)

  • Access to a SQL Server dSource

  • Target Windows environment with a SQL Server instance available

  • Appropriate DCT permissions to provision VDBs

Step 1: Identify the source dSource

# List all dSources
				dct-toolkit get_dsources

				# Search for SQL Server dSources specifically
			dct-toolkit search_dsources database_type="MSSql" --columns=id,name,engine_name sort=name

Step 2: List available snapshots

dct-toolkit get_dsource_snapshots dsource_id=<DSOURCE_ID_OR_NAME>

				# Sort by most recent
			dct-toolkit search_snapshots dataset_id=<DSOURCE_ID_OR_NAME> sort=-timestamp

Step 3: Identify the target environment and repository

By default, DCT selects a compatible SQL Server instance automatically. If there are multiple instances on the target host, identify the specific one you want.

Option A: Find the Windows target environment

dct-toolkit search_environments --is_windows_target --columns=id,name,engine_name

				# Confirm a specific environment and its repositories
			dct-toolkit search_environments name=<ENVIRONMENT_NAME> -js

Option B: Search for compatible repositories

dct-toolkit compatible_repositories_by_snapshot source_data_id=<DSOURCE_ID_OR_NAME>

Results include repository ID, environment ID, SQL Server version, and instance name.

Step 4: View provisioning defaults (optional)

dct-toolkit provision_vdb_by_snapshot_defaults source_data_id=<DSOURCE_ID_OR_NAME>

Step 5: Provision the VDB

From the latest snapshot

dct-toolkit provision_vdb_by_snapshot mssql \
				name=<NEW_VDB_NAME> \
				source_data_id=<DSOURCE_ID_OR_NAME> \
			environment_id=<TARGET_ENVIRONMENT_ID>

With a specific repository

dct-toolkit provision_vdb_by_snapshot mssql \
				name=<NEW_VDB_NAME> \
				source_data_id=<DSOURCE_ID_OR_NAME> \
				environment_id=<TARGET_ENVIRONMENT_ID> \
			repository_id=<REPOSITORY_ID>

From a specific snapshot

dct-toolkit provision_vdb_by_snapshot mssql \
				name=<NEW_VDB_NAME> \
				snapshot_id=<SNAPSHOT_ID> \
			environment_id=<TARGET_ENVIRONMENT_ID>

From a specific timestamp

Timestamps use ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

dct-toolkit provision_vdb_by_timestamp mssql \
				name=<NEW_VDB_NAME> \
				source_data_id=<DSOURCE_ID_OR_NAME> \
				timestamp=<TIMESTAMP> \
			environment_id=<TARGET_ENVIRONMENT_ID>

From a bookmark

dct-toolkit provision_vdb_from_bookmark mssql \
				name=<NEW_VDB_NAME> \
				bookmark_id=<BOOKMARK_ID> \
			environment_id=<TARGET_ENVIRONMENT_ID>

With advanced parameters

dct-toolkit provision_vdb_by_snapshot mssql \
				name=<NEW_VDB_NAME> \
				source_data_id=<DSOURCE_ID_OR_NAME> \
				environment_id=<TARGET_ENVIRONMENT_ID> \
				repository_id=<REPOSITORY_ID> \
				target_group_id=<DATASET_GROUP_ID> \
				environment_user_id=<ENVIRONMENT_USER_ID> \
				database_name=<DATABASE_NAME> \
				recovery_model=<SIMPLE|FULL|BULK_LOGGED> \
			vdb_restart=true

Use dct-toolkit provision_vdb_by_snapshot mssql -h to see all available parameters.

Step 6: Verify VDB creation

dct-toolkit get_vdbs --columns=id,name,database_type,status
			dct-toolkit get_vdb_by_id vdb_id=<VDB_NAME_OR_ID> -js

Complete example

# 1. Find the SQL Server dSource
				dct-toolkit search_dsources database_type="MSSql" --columns=id,name

				# 2. List recent snapshots
				dct-toolkit get_dsource_snapshots dsource_id=SQLPROD_DB sort=-timestamp --columns=id,timestamp

				# 3. Find compatible repositories
				dct-toolkit compatible_repositories_by_snapshot source_data_id=SQLPROD_DB

				# 4. Provision the VDB
				dct-toolkit provision_vdb_by_snapshot mssql \
				name=SQLDEV_VDB \
				source_data_id=SQLPROD_DB \
				environment_id=1-WINDOWS_HOST_ENVIRONMENT-5 \
				repository_id=1-MSSQL_INSTALL-3 \
				vdb_restart=true

				# 5. Verify
			dct-toolkit get_vdb_by_id vdb_id=SQLDEV_VDB

SQL Server-specific considerations

  • Multiple SQL Server instances on the same Windows host appear as separate repositories. Identify the correct one using compatible_repositories_by_snapshot.

  • The provisioning environment user must have appropriate Windows permissions and the SQL Server sysadmin role or equivalent.

Troubleshooting

Error Resolution
Cannot find compatible repository Verify the target environment has a SQL Server instance installed, the version is compatible with the source, and the repository is enabled in DCT.
Insufficient permissions Verify your DCT account has appropriate permissions. Check that the environment user has SQL Server sysadmin privileges and Windows authentication is configured correctly.
Invalid snapshot Confirm the snapshot ID exists and has not been deleted. Verify the snapshot is from a compatible dSource.
Last updated
Oct 8, 2026