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:

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:

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: 

{
  "schema": "Production",
  "name": "Product"
}

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:

{
  "startingTables": [
    {
      "schema": "Production",
      "name": "Product"
    }
  ]
}

or

{
  "desiredSize": "1GB"
}

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.

{
  "startingTables": [
    {
      "schema": "Production",
      "name": "Product"
    }
  ],
  "staticDataTables": [
    {
      "schema": "Reference",
      "name": "Countries"
    }
  ]
}

Example conversion

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

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

rgsubset.exe run
--database-engine SqlServer
--source-connection-string "..."
--target-connection-string "..."
--options-file options.json

{
  "startingTables": [
    {
      "schema": "dbo",
      "name": "Users"
    },
    "filterClause": "WHERE FirstName LIKE 'Bob%'"
  ]
}

subsetter.exe
--database-engine SqlServer
--source-connection-string "..."
--target-connection-string "..."
--config-file config.json

{
  "StartingTables": [
     {
      "Table": "[Production].[Product]",
      "FilterClause": "WHERE [ProductId] = 1234"
    },
    {
      "Table": "[Reference].[Countries]",
      "IsStaticData": true
    } 
  ],
  "ExcludedTables": [
    "[dbo].[Comments]"
  ],
  "ManualRelationships": [
    {
      "ParentTable": "[dbo].[Orgs]",
      "ParentColumns": ["Id"],
      "ChildTable": "[dbo].[Users]",
      "ChildColumns": ["OrgId"]
    }
  ],
}

rgsubset.exe run
--database-engine SqlServer
--source-connection-string "..."
--target-connection-string "..."
--options-file options.json

{
  "startingTables": [
    {
      "schema": "Production",
      "name": "Product"
    },
    "filterClause": "WHERE ProductId = 1234"
  ],
  "staticDataTables": [
    {
      "schema": "Reference",
      "name": "Countries"
    }
  ],
  "excludedTables": [
    {
      "schema": "dbo",
      "name": "Comments"
    }
  ],
  "manualRelationships": [
    {
      "sourceTable":
        {
          "schema": "dbo",
          "name": "Orgs"
        },
      "sourceColumns": [ "Id" ],
      "targetTable":
        {
          "schema": "dbo",
          "name": "Users"
        },
      "targetColumns": [ "OrgId" ],
     }
  ]
}