Redgate Test Data Manager

Upgrading from v1 to v2

Page last updated 18 December 2024

v2 of the subsetter contains breaking changes in how it is run when upgrading from v1.

Command line executable

v1 had a command line executable called subsetter. 

This has been renamed to rgsubset in v2.

The auth command

v1 would authorise a license using auth --agree-to-eula

In v2, this is now in a login command, and the EULA parameter has been renamed:

  1. rgsubset auth login --i-agree-to-the-eula

The run command

v1 would subset by calling the subsetter command line executable.

In v2, this has been moved to a run sub-command:

  1. rgsubset run ...

Target size

v1 allowed a target size to be set when subsetting.

This has been renamed to "desired size" in v2.

Table definitions

v1 defined tables using a fully-qualified syntax: "Table": "[Production].[Product]".

This has changed in v2. The schema and the name of the table now hove to be explicitly defined with no qualification and no quoting: 

  1. {
  2.   "schema": "Production",
  3.   "name": "Product"
  4. }

Starting table/target size command line options

v1 had the ability to specify a starting tables/target size as a command line option.

In v2, these must be specified in an options file if required. 

v2 also introduces a default behavior where if no starting tables and desired size is specified, a subset of 10% of the database size (up to a maximum of 1GB) will be created.


The options file can be specified on the command line using the --options-file parameter.

Starting tables/desired size can be defined in the options file as:

  1. {
  2.   "startingTables": [
  3.     {
  4.       "schema": "Production",
  5.       "name": "Product"
  6.     }
  7.   ]
  8. }

or

  1. {
  2.   "desiredSize": "1GB"
  3. }

Static data tables

v1 configured static data tables on the starting tables in the configuration file.

This has been extracted to its own section in v2.

  1. {
  2.   "startingTables": [
  3.     {
  4.       "schema": "Production",
  5.       "name": "Product"
  6.     }
  7.   ],
  8.   "staticDataTables": [
  9.     {
  10.       "schema": "Reference",
  11.       "name": "Countries"
  12.     }
  13.   ]
  14. }

Example conversion

Below are some examples of how to run the same subset in v2 compared to previously in v1.

Subsetter v1Subsetter v2

Command line Toggle source code

  1. subsetter.exe
  2. --database-engine SqlServer
  3. --source-connection-string "..."
  4. --target-connection-string "..."
  5. --starting-table "dbo.Users"
  6. --filter-clause "WHERE FirstName LIKE 'Bob%'"

Command line Toggle source code

  1. rgsubset.exe run
  2. --database-engine SqlServer
  3. --source-connection-string "..."
  4. --target-connection-string "..."
  5. --options-file options.json

Options file options.json Toggle source code

  1. {
  2.   "startingTables": [
  3.     {
  4.       "schema": "dbo",
  5.       "name": "Users"
  6.     },
  7.     "filterClause": "WHERE FirstName LIKE 'Bob%'"
  8.   ]
  9. }


Subsetter v1Subsetter v2

Command line Toggle source code

  1. subsetter.exe
  2. --database-engine SqlServer
  3. --source-connection-string "..."
  4. --target-connection-string "..."
  5. --config-file config.json

Configuration file config.json Toggle source code

  1. {
  2.   "StartingTables": [
  3.      {
  4.       "Table": "[Production].[Product]",
  5.       "FilterClause": "WHERE [ProductId] = 1234"
  6.     },
  7.     {
  8.       "Table": "[Reference].[Countries]",
  9.       "IsStaticData": true
  10.     } 
  11.   ],
  12.   "ExcludedTables": [
  13.     "[dbo].[Comments]"
  14.   ],
  15.   "ManualRelationships": [
  16.     {
  17.       "ParentTable": "[dbo].[Orgs]",
  18.       "ParentColumns": ["Id"],
  19.       "ChildTable": "[dbo].[Users]",
  20.       "ChildColumns": ["OrgId"]
  21.     }
  22.   ]
  23. }

Command line Toggle source code

  1. rgsubset.exe run
  2. --database-engine SqlServer
  3. --source-connection-string "..."
  4. --target-connection-string "..."
  5. --options-file options.json

Options file options.json Toggle source code

  1. {
  2.   "startingTables": [
  3.     {
  4.       "table": {
  5.         "schema": "Production",
  6.         "name": "Product"
  7.       },
  8.       "filterClause": "WHERE ProductId = 1234"
  9.     }
  10.   ],
  11.   "staticDataTables": [
  12.     {
  13.       "schema": "Reference",
  14.       "name": "Countries"
  15.     }
  16.   ],
  17.   "excludedTables": [
  18.     {
  19.       "schema": "dbo",
  20.       "name": "Comments"
  21.     }
  22.   ],
  23.   "manualRelationships": [
  24.     {
  25.       "sourceTable":
  26.         {
  27.           "schema": "dbo",
  28.           "name": "Orgs"
  29.         },
  30.       "sourceColumns": [ "Id" ],
  31.       "targetTable":
  32.         {
  33.           "schema": "dbo",
  34.           "name": "Users"
  35.         },
  36.       "targetColumns": [ "OrgId" ],
  37.      }
  38.   ]
  39. }


Didn't find what you were looking for?

Product Articles

Tips and how-to guides for Redgate products

University

Easy to follow video courses

Community Forums

Ask, discuss, and solve questions about Redgate's tools

Events & Friends

Meet us at an event, get sponsored, and join our Friends of Redgate

Simple Talk

In-depth articles and opinion from Redgate's technical journal

Cookies on red-gate.com

This website stores cookies on your computer.

These cookies are used to improve your website experience and provide more personalized services to you, both on this website and through other media.

To find out more about the cookies we use, see our Privacy Policy