Viewing and adding foreign keys

Foreign keys define relationships between tables. The value of a foreign key column in a table is the primary key of a row from a different table. For example, a transactions table includes a customer_id column. The value of customer_id is a primary key value from the id column in the customers table. A table can also have composite foreign keys that consist of multiple columns.
Tonic uses foreign keys when it generates subsets and when it applies generators to primary or foreign keys.
During data generation, when generators are assigned to primary key columns, Tonic ensures that the foreign keys are synchronized with the primary keys.
When Tonic creates a subset, it uses foreign keys to identify the related tables and rows to include in the subset.
Often, foreign key relationships are defined in the source database. When you have missing relationships or cannot define them in the source database, Tonic offers a virtual foreign key tool to allow you to add additional foreign keys to ensure that all relationships are maintained. Tonic only uses these virtual foreign keys during the generation process. It does not write the virtual foreign keys to the destination database.
From the Foreign Key Relationships view, you can view the current foreign keys (all license tiers) and add virtual foreign keys (Professional and Enterprise tier only). To display the Foreign Key Relationships view:
On the workspace management view, in the workspace navigation bar, click Foreign Keys.
On Workspaces view, from the dropdown menu in the Name column, select Foreign Keys.
Viewing the current foreign keys
On the Foreign Key Relationships view, the View Foreign Key Relationships tab contains the list of foreign keys in the source database.
View Foreign Key Relationships tab
For each foreign key:
Foreign Key contains the name of the columns (tableName.columnName) that contain the foreign key values.
Primary Key contains the name of the column (tableName.columnName) that contains the primary key value used to populate the foreign key column.
Identifying virtual foreign keys
Virtual foreign keys that you added are displayed with a checkbox.
You can delete those keys. You cannot delete keys that are defined in the source database.
Filtering the foreign keys
You can filter the foreign keys by the name of the foreign key column or the primary key column. In the filter field, begin to type text that is in the column name. As you type, Tonic filters the list.
Sorting the foreign keys
You can sort the foreign keys by the name of the foreign key column or primary key column.
To sort the list:
1.Click the Sort dropdown for the column that you want to use to sort the list.
2.On the sort panel, click the sort order to use.
Adding virtual foreign keys
The ability to add virtual foreign keys requires a Professional or Enterprise license.
Tonic allows you to add virtual foreign keys to your source database. You would use this feature to add a specific foreign key that is missing, or if your source database does not use foreign keys.
You can add the foreign keys one at a time from the Add Foreign Key Relationships tab, or you can upload a JSON file that contains the foreign keys.
If your database uses polymorphic keys (typically if you have a Ruby on Rails application), then you must use the JSON file upload to configure those keys.
You cannot create virtual foreign keys from a child workspace. You can only create virtual foreign keys from a parent workspace.
Adding virtual foreign keys from Add Foreign Key Relationships
You can configure virtual foreign keys from the Add Foreign Key Relationships tab. You cannot configure polymorphic keys here. Polymorphic keys must be uploaded from a JSON file.
Add Foreign Key Relationships tab
To add virtual foreign keys to your source database:
1.Under Select Foreign Keys, check the checkboxes to identify the foreign key fields. These are the fields that contain a value that is a primary key from another table.

The Select Foreign Keys list contains the columns that are not already configured as foreign key columns.

The top level of the Select Foreign Keys list displays the unique column names. This is the column name only, without the table name. Next to each column name is the number of times that it appears in the source database.

You can use the sort dropdown list to sort the list either by the column name or by the number of times the column appears.

You expand the column name to display the list of columns that have that name. This list uses the tableName.columnName format.

For example, a database has a customer_id column in both the sales and customers tables. On the Select Foreign Keys tab, the top level entry is customer_id. Under customer_id are entries for sales.customer_id and customers.customer_id.
2.As you select and deselect columns, they are added to or removed from the Foreign Key Preview list.

Under Create New Foreign Key, the number of keys to add is also updated.

From Foreign Key Preview, to remove a selected column, click its delete icon. This performs the same function as unchecking the checkbox in the Select Foreign Keys list.
3.From the Select Primary Key dropdown list, select the column that provides the values for the selected foreign key columns.
4.To create the virtual foreign keys, click Create n foreign keys. n is the number of keys that are created, based on the number of foreign key columns that you selected.
Uploading a JSON file of virtual foreign keys
You can upload a JSON file that contains the virtual foreign keys. For example, you can create a JSON file that can be used to populate virtual foreign keys in multiple workspaces that have the same source data structure.
If you already have configured virtual foreign keys, then the uploaded virtual foreign keys replace the existing ones.
The virtual foreign key JSON also allows you to add polymorphic keys. You cannot add polymorphic keys from the Add Foreign Key Relationships tab.
On the Foreign Key Relationships view, to upload a foreign keys file:
1.Click Upload Foreign Key JSON. If you already have virtual foreign keys configured, then the button is Update Foreign Key JSON.
2.On the upload dialog, to search for and select the file, click Browse.
3.After you select the file, click Upload.
The uploaded keys are added to the View Foreign Key Relationships list. Those keys replace any existing virtual foreign keys.
JSON format for the foreign key file
The foreign key JSON is an array of foreign key entries. Here is an example of a foreign key file that contains a single entry:
[
  {
    "fk_schema": "public",
    "fk_table": "paystubs",
    "fk_columns": ["employee_id"],
    "target_schema": "public",
    "target_table": "employees",
    "target_columns": ["id"]
  }
]
To illustrate the field values, we'll use the following example, which reflects the example entry above. A paystubs table lists the pay stubs that were issued to employees. paystubs contains an employee_id field. employee_id identifies the employee that received the pay stub. employee_id is a foreign key. It contains the value of the id field in employees, which is the primary key field for the employees table. Both paystubs and employees are in the public schema.
In the foreign keys JSON, each entry contains the following fields.
fk_schema - The name of the schema for the table that contains the foreign key. For our example, fk_schema is public.
fk_table - The name of the table that contains the foreign key. For our example, fk_table is paystubs.
fk_columns - An array that contains the names of the foreign key columns. In our example, the fk_columns array contains a single value, employee_id.
target_schema - The name of the schema for the table that contains the referenced primary key. In our example, target_schema is public.
target_table - The name of the table that contains the referenced primary key. In our example, target_table is employees.
target_columns - An array that contains the names of the primary key columns. In our example, the target_columns array contains a single value, id.
JSON format for composite keys
The ability to provide multiple columns in fk_columns and target_columns is used to support composite foreign keys. fk_columns and target_columns must contain the same number of columns. The corresponding columns must be in the same order in both arrays.
For example, a sales table contains sales_person_id and sales_manager_id, which refer to the id and manager_id columns in the employees table.
In the JSON:
fk_table is sales, and fk_columns is [sales_person_id, sales_manager_id].
target_table is employees, and target_columns is [id, manager_id].
The entry for this example would look like:
[
  {
    "fk_schema": "public",
    "fk_table": "sales",
    "fk_columns": ["sales_person_id","sales_manager_id"],
    "target_schema": "public",
    "target_table": "employees",
    "target_columns": ["id","manager_id"]
  }
]
JSON format for polymorphic keys
Some application types have polymorphic keys. Polymorphic keys allow a single column in one table to contain foreign key values that refer to primary keys from multiple other tables. These types of keys cannot be represented in a traditional relational database, but are common in application frameworks such as Ruby on Rails.
For example, a person can have multiple addresses, and a company can have multiple addresses. To support this without complicated joins between tables, the addresses table includes the following columns:
A column that contains the identifier of the company or the person that the address belongs to.
Another column that identifies whether the identifier is a company or a person.
For example, the people table contains:
id
first_name
last_name
1
John
Doe
2
Mary
Smith
The companies table contains:
id
company_name
1
My Company
2
Example Company
The addresses table contains:
id
address
address_owner_id
address_owner_type
1
123 Main Street
1
Person
2
234 Elm Street
1
Company
In the addresses table, to identify the address owner, the address_owner_id column contains an id value from either the people or companies table. The address_owner_type column identifies whether the identifier is a person or a company.
The value of address_owner_id is 1 for both records. However, address 1 belongs to John Doe, and address 2 belongs to My Company.
Each entry in the polymorphic keys JSON identifies the fields that contain the foreign key values and the foreign key type. It also lists the foreign key types, and identifies the source of the identifier for that foreign key type.
The following is the JSON for the example above:
[
  {
    "fk_table": "addresses",
    "fk_schema": "public",
    "fk_columns": ["address_owner_id"],
    "nullable": false,
    "polymorphic_target": { 
      "fk_type_column": "address_owner_type",
      "types": {
        "Person": {
          "target_schema": "public",
          "target_table": "people",
          "target_columns": ["id"]
        },
        "Company": {
          "target_schema": "public",
          "target_table": "companies",
          "target_columns": ["id"]
        }
      }
    }
  }
]
Each entry contains the following fields:
fk_table - The name of the table that contains the foreign key values. In our example, this is the addresses table.
fk_schema - The name of the schema for the table that contains the foreign key. In our example, the schema is public.
fk_columns - An array that contains the names of the columns that contain the foreign key values. In our example, the value is address_owner_id.
nullable - Whether the foreign key column is nullable.
polymorphic_target - Identifies the target types and the identifier source for each type.
polymorphic_target contains the following fields:
fk_type_column - In the table that contains the foreign key, the name of the column that contains the foreign key type. In our example, this is the address_owner_type column in addresses.
types - A list of the target types.
Each entry in types identifies the name of the type. In our example, our types are Person and Company. Note that these are the values of the type column in the polymorphic table, not necessarily the names of the tables they point to. For example, the Person type refers to the people table.
Each type has the following attributes:
target_schema - The schema that contains the target table. In our example, the tables for both types belong to the public schema.
target_table - The table that contains the primary key value. In our example, for the Person type, the target table is people. For the Company type, the target table is companies.
target_columns - An array containing the column that contains the primary key value. In our example, the name of the identifier column in both tables is id.
Downloading virtual foreign keys
If you created virtual foreign keys, then you can download those keys to a JSON file. For example, you might want to upload the same set of virtual foreign keys to another workspace that uses the same source data.
To download the virtual foreign keys, click Download Foreign Key JSON.
Deleting a virtual foreign key
You can delete virtual foreign keys. You cannot delete foreign keys that are defined in the source database.
To delete an individual virtual foreign key, click its delete icon.
To delete multiple virtual foreign keys:
1.Check the checkbox next to each virtual foreign key to delete.
2.Click Bulk Delete.
How Tonic handles circular foreign key dependencies
Foreign key relationships can sometimes have circular dependencies, also referred to as cyclic dependencies.
In the simplest case, a circular dependency occurs when two tables each contain a foreign key that references the other table. In the following example, the Employees table contains a department_id foreign key column that references the Departments table, and the Departments table contains a manager_id foreign key column that references the Employees table.
Circular foreign key dependency between two tables
Circular dependencies can also come from a much longer chain of references, where you follow references through several tables before returning to the original table.
Circular dependencies can also occur when a table references itself. In the following example, the Employees table contains a manager_id foreign key column that contains an employee ID value from the id column.
Circular foreign key dependency within a table
During subsetting, if the circular dependency isn't broken, then there is an endless loop of going back and forth between the tables that reference each other.
To break a circular dependency, Tonic identifies a foreign key column that is NULLable, and sets its values to NULL. When the process reaches a NULL value, it stops looking for additional related records. Tonic applies the minimum number of NULL values that are needed to break the circular dependencies.
If none of the foreign key values are NULLable, then the circular dependency cannot be broken, and the subset generation fails.
id	first_name	last_name
1	John	Doe
2	Mary	Smith
id	company_name
1	My Company
2	Example Company
id	address	address_owner_id	address_owner_type
1	123 Main Street	1	Person
2	234 Elm Street	1	Company
Last modified 1mo ago