Viewing and adding foreign keys
Last updated
Last updated
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 Structural 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, Structural ensures that the foreign keys are synchronized with the primary keys.
When Structural 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, Structural offers a virtual foreign key tool to allow you to add additional foreign keys to ensure that all relationships are maintained. Structural 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 Keys 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 Keys 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.
On the Foreign Keys view, the View Foreign Key Relationships tab contains the list of foreign keys in the source database.
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.
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.
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, Structural filters the list.
You can sort the foreign keys by the name of the foreign key column or primary key column.
To sort the list:
Click the Sort dropdown for the column that you want to use to sort the list.
On the sort panel, click the sort order to use.
Required license: Professional or Enterprise
Required workspace permission: Configure virtual foreign keys
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.
You can also create virtual foreign keys from a table details panel in Subsetting view.
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.
To add virtual foreign keys to your source database:
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
.
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.
From the Select Primary Key dropdown list, select the column that provides the values for the selected foreign key columns.
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.
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:
Click Upload Foreign Key JSON. If you already have virtual foreign keys configured, then the button is Update Foreign Key JSON.
On the upload dialog, to search for and select the file, click Browse.
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.
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:
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
.
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:
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:
The companies
table contains:
The addresses
table contains:
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:
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
.
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.
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:
Check the checkbox next to each virtual foreign key to delete.
Click Bulk Delete.
id | first_name | last_name |
---|---|---|
id | company_name |
---|---|
id | address | address_owner_id | address_owner_type |
---|---|---|---|