MS SQL Server

Connect to your MS SQL Server databases.

Getting Started

Prerequisites to create a MS SQL based workflow. You will need

1. A source MS SQL connection.

2. (optional) A list of tables OR SQL queries.

3. (optional) A destination MS SQL connection.

For the source database connection, we recommend using a backup or clone with read-only permissions, instead of connecting directly to your production database.

Do not use your input database connection as an output connector. This action can result in the unintended overwriting of existing data.

Create a Connection

A mssql connection is created using the following parameters:

Connection Creation Parameters

name	Display name of your choosing used to identify your connection within Gretel.	my-mssql-connection
username	Unique identifier associated with specific account authorized to access database.	john
password	Security credential to authenticate username.	...
host	Fully qualified domain name (FQDN) used to establish connection to database server.	myserver.example.com
port	Port number; If left empty, the default value - 1403- will be used.	1403
database	Name of database to connect to.	mydatabase
(optional) schema	Optional Name of specific schema	dbo
(optional) params	Optional JDBC URL parameters that can be used for advanced configuration.	TrustServerCertificate=True

Creating Connections

CLI

First, create a file on your local computer containing the connection credentials. This file should also include type, name , config, and credentials. The config and credentials fields should contain fields that are specific to the connection being created.

Below is an example MS SQL connection:

{
    "type": "mssql",
    "name": "my-mssql-connection",
    "config": {
        "username": "john",
        "host": "myserver.example.com",
        "port": 1443,
        "database": "mydatabase",
        "schema": "dbo",
        "params": "TrustServerCertificate=True"
    },
    "credentials": {
        "password": "..."
    }
}

Now that you've created the credentials file, use the CLI to create the connection

gretel connections create --project [project id] --from-file [credential_file.json]

Console

• Navigate to the Connections page using the menu item in the left sidebar.

• Click the New Connection button.

• Step 1, choose the Type for the Connection - MS SQL Server.

• Step 2, choose the Project for your Connection.

• Step 3, fill in the credentials and select Add Connection.

Step 1, choose the Type of connection

Step 3, fill in credentials

SDK

from gretel_client import create_or_get_unique_project
from gretel_client.config import get_session_config
from gretel_client.rest_v1.api.connections_api import ConnectionsApi
from gretel_client.rest_v1.models import (
    CreateConnectionRequest,
    UpdateConnectionRequest,
)

session = get_session_config()
connection_api = session.get_v1_api(ConnectionsApi)

project = create_or_get_unique_project(name="mssql-workflow")

connection = connection_api.create_connection(
    CreateConnectionRequest(
        name="my-mssql-connection",
        project_id=project.project_guid,
        type="mssql",
        config={
            "username": "john",
            "host": "myserver.example.com",
            "database": "mydatabase",
            #"port": 1433,
            #"schema": "dbo",
            #"params": "TrustServerCertificate=True",
        },
        # note: best practice is to read in credentials from a file
        # or secret instead of directly embedding sensitive values
        # in python code.
        credentials={
            "password": "...",
        },
    )
)

MS SQL Source Action

Type	mssql_source
Connection	mssql

The mssql_source action reads data from your MS SQL database. It can be used to extract:

• an entire database, OR

• selected tables from a database, OR

• the results of SQL query/queries against a database.

Each time the workflow is run the source action will extract the most recent data from the source database.

When combined in a workflow, the data extracted from the mssql_source action is used to train models and generate synthetic data with the gretel_tabular action, and can be written to an output database with the mssql_destination action.

For the source database connection, we recommend using a backup or clone with read-only permissions, instead of connecting directly to your production database.

Inputs

The mssql_source action takes slightly different inputs depending on the type of data you wish to extract. Flip through the tabs below to see the input config parameters and example action YAMLs for each type of extraction.

Entire Database

Entire Database

sync.mode

full - extracts all records from tables in database (coming soon) subset - extract percentage of records from tables in database

Example Source Action YAML

actions:
  - name: extract-database
    type: mssql_source
    connection: conn_1
    config:
      sync:
          mode: full

Selected Tables

Selected Tables

sync.mode	full - extracts all records from selected tables in database (coming soon) subset - extract percentage of records from selected tables in database
tables: - name: - ...	Sequence of mappings that lists the table(s) in the database to extract. name - table name

Example Source Action YAML

actions:
  - name: extract-selected-tables
    type: mssql_source
    connection: conn_1
    config:
      tables:
        - name: client
        - name: location
      sync:
          mode: full

SQL Queries

SQL Query/Queries

queries: - name: query: ...

name - name of query; will be treated as name of resulting table query - SQL statement used to query connected database Additional name and query mappings can be provided to include multiple SQL queries

Example Source Action YAML

actions:
  - name: extract-sql-queries
    type: mssql_source
    connection: conn_1
    config:
      queries:
        - name: people
          query: select first_name, last_name from client
        - name: cities
          query: select city, state, country from location

Outputs

Whether you are extracting an entire database, selected tables, or querying against a database, the mssql_source action always provides a single output, dataset.

dataset

A reference to the data extracted from the database, including tables and relationships/schema.

The output of a mssql_source action can be used as the input to a gretel_tabular action in order to transform and/or synthesize a database.

MS SQL Destination Action

Type	mssql_destination
Connection	mssql

The mssql_destination action can be used to write gretel_tabular action outputs to MS SQL destination databases.

Inputs

Whether you are writing an entire database, selected tables, or table(s) created via SQL query, the mssql_destination action always takes the same input, dataset.

dataset	A reference to the table(s) generated by Gretel and (if applicable) the relationship schema extracted from the source database.
sync.mode	replace - overwrites any existing data in table(s) at destination append - add generated data to existing table(s); only supported for query-created tables without primary keys

Example Destination Action YAML

actions:
...
  - name: mssql-write
    type: mssql_destination
    connection: conn_2
    input: synthesize
    config:
      sync:
        mode: replace
      dataset: {outputs.synthesize.dataset}

Sync Modes

There are multiple strategies for writing records into the destination database. These strategies are configured from the sync.mode field on a destination config.

sync.mode may be one of truncate, replace, or append.

Sync Mode: Truncate

When sync.mode is configured with truncate, records are first truncated from the destination table using the TRUNCATE TABLE DML command.

When sync mode is configured with truncate the destination table must already exist in the database.

Sync Mode: Replace

When sync.mode is configured with replace, the destination table is first dropped and then recreated using a schema inferred from the input dataset.

When the schema is inferred from the input dataset, certain column types or constraints may not be maintained from the source table. If you want to maintain the same schema from your source database, please use sync mode truncate.

When sync mode is configured with replace the destination table does not need to exist in the destination.

To respect foreign key constraints and referential integrity, tables without foreign keys are inserted first, and tables with foreign key references are inserted last.

When applying table DML for truncate or replace, operations are applied in reverse insertion order. This is to ensure records aren't deleted with incoming foreign key references.

It's also important to note: all table data is first dropped from the database before inserting new records back in. These operations are not atomic, so there may be periods of time when the destination database is in an incomplete state.

Sync Mode: Append

When sync.mode is configured with append, the destination action will simply insert records into the table, leaving any existing records in place.

When using the append sync mode, referential integrity is difficult to maintain. It's only recommended to use append mode when syncing adhoc queries to a destination table.

If append mode is configured with a source that syncs an entire database, it's likely the destination will be unable to insert records while maintaining foreign key constraints or referential integrity, causing the action to fail.

Example Workflow Configs

Create a synthetic version of your MS SQL database.

The following config will extract the entire MS SQL database, train and run a synthetic model, then write the outputs of the model back to a destination MS SQL database while maintaining referential integrity.

name: sample-mssql-workflow-full-db

actions:
  - name: mssql-read
    type: mssql_source
    connection: conn_1
    config:
      sync:
          mode: full

  - name: synthesize
    type: gretel_tabular
    input: mssql-read
    config:
      project_id: proj_1
      train:
        model: "synthetics/tabular-actgan"
        dataset: {outputs.mssql-read.dataset}
      run:
        num_records_multiplier: 1.0

  - name: mssql-write
    type: mssql_destination
    connection: conn_2
    input: synthesize
    config:
      sync:
        mode: replace
      dataset: {outputs.synthesize.dataset}

Create a synthetic version of selected tables from your MS SQL database

The following config will extract two tables from your database, train and run a synthetic model, then write the outputs of the model back to a destination MS SQL database while maintaining any key relationships between the tables.

name: sample-mssql-workflow-selected-tables

actions:
  - name: mssql-read
    type: mssql_source
    connection: conn_1
    config:
      tables:
        - name: client
        - name: location
      sync:
          mode: full

  - name: synthesize
    type: gretel_tabular
    input: mssql-read
    config:
      project_id: proj_1
      train:
        model: "synthetics/tabular-actgan"
        dataset: {outputs.mssql-read.dataset}
      run:
        num_records_multiplier: 1.0

  - name: mssql-write
    type: mssql_destination
    connection: conn_2
    input: synthesize
    config:
      sync:
        mode: replace
      dataset: {outputs.synthesize.dataset}

.

Create a synthetic version of a dataset formed by querying your MS SQL database

The following config will execute a SQL query against your MS SQL database to create a table containing data from across the database. Then, it will train and run a synthetic model to generate a synthetic table.

name: sample-mssql-workflow-sql-query

actions:
  - name: mssql-read
    type: mssql_source
    connection: conn_1
    config:
      queries:
        - name: status_by_location
          query: SELECT location.city, location.state, location.zip, account.vip_status
            FROM client JOIN account ON client.client_id = account.client_id
            JOIN location ON client.client_id = location.client_id

  - name: synthesize
    type: gretel_tabular
    input: mssql-read
    config:
      project_id: proj_1
      train:
        model: "synthetics/tabular-actgan"
        dataset: {outputs.mssql-read.dataset}
      run:
        num_records_multiplier: 1.0