Skip to main content

Airtable checklist

Each section contains steps that should be performed in order!

New columns​

Add the column in Airtable​

Add the new column to both the Staging and Production Airtables. This should be a specific type-- usually Text, Single Select, Multi Select, or Checkbox.

  • In Airtable, columns are generally nullable (different from our system)
  • For Single Select and Multi Select, pick reasonable colors for each value
  • If a column is backed by a number/integer in our system, it should be a Number
  • If a column is backed by an enum value in our system, it should always be Single Select
    • Never use Text, even if this enum only has 2 options right now -- since this could change in the future and the migration path is difficult!
  • If a column is backed by a boolean value in our system, it should be a Single Select (we will think of it as an enum with 2 options)
    • Exception: By definition, this column will never take on more than 2 values (i.e. it truly is a boolean) -- then, it can be a Checkbox

Update the sync service definition in Platform​

Update the /syncServices/airtable definition.

Text? Output directly to Airtable.

Single or Multi Select? Never pipe in the enum value directly. Instead, create a new type and map our enum to this type:

type XYZAirtableType = "My Option" | "My Other Option";

const XYZToAirtable: Record<XYZ, XYZAirtableType> = {
  "My Option": "My Option",
  "My Other Option": "My Other Option",
};
danger

Remember, when you update an enum in our system, it will never update the Airtable column definitions automatically!

Why? This way, TS will enforce that there is an Airtable mapping for each enum option. And, if the enum changes, it will complain that the Airtable mapping is invalid, which will remind us that this needs to be updated.

Checkbox? It's OK to resolve this directly without mapping.

File a ticket to resync after deploy​

danger

Do not forget to resync the table to production after your PR deploys to production.

If you add a new column, any existing rows in Airtable will not have the value of that new column. We have to manually trigger a resync of the entire table to populate those values.

File a new sub-ticket, that is blocked by your current ticket, to "Resync Airtable for XYZ".

When your PR merges, you will need to manually trigger the resync to Staging. Then, when your PR is deployed to production, you will need to manually trigger the resync to Production. The gap between all of these things happening can be several days, so it is easy to forget. File a ticket.

Resync the entire table​

Now that it's deployed (once for Staging, once for Production), use the sync-debug to mark the entire table for resync.

File a Launch Coordination ticket​

Now that it's deployed, we need to let the other teams relying on this data know that the new column is live. File a Launch Coordination ticket in the DB Linear.

Change existing column (additive)​

info

Examples of an additive change include adding a new enum option, etc. Removing an enum option? Follow "Remove column" checklist but adapt to the situation.

Update the column in Airtable​

Update the column to both the Staging and Production Airtables.

Update the sync service definition in Platform​

Update the /syncServices/airtable definition.

If you've migrated existing values, file a ticket to resync after deploy​

You only need to do this if you've migrated some existing values to new values (as in the case of adding a new enum option), since those changes won't be picked up by the regular sync service.

File a new sub-ticket, that is blocked by your current ticket, to "Resync Airtable for XYZ".

When your PR merges, you will need to manually trigger the resync to Staging. Then, when your PR is deployed to production, you will need to manually trigger the resync to Production. The gap between all of these things happening can be several days, so it is easy to forget. File a ticket.

When it's deployed (once for Staging, once for Production), use the sync-debug to mark the entire table for resync.

File a Launch Coordination ticket​

Now that it's deployed, we need to let the other teams relying on this data know that the updated column is live. File a Launch Coordination ticket in the DB Linear.

Remove column​

File a Launch Coordination ticket​

note

When we're removing a column (or options from a column), we must let other teams know first -- this data often backs complex processes that Eng is not aware of.

We need to let the other teams relying on this data know that a column will be removed. File a Launch Coordination ticket in the DB Linear.

In your ticket, state clearly what is being removed or changed -- name the specific column and changed behavior, such as if they should reference a different column for this information.

Update the sync service definition in Platform​

Update the /syncServices/airtable definition.

File a ticket to remove the column after deploy​

After your PR merges to Staging, and after it deploys to Production, you'll need to remove the column (since it won't be updated anymore).

This ticket should be blocked by the Launch Coordination ticket you filed earlier.

Deploy after getting the OK​

After the Launch Coordination ticket closes, and all concerns by other teams are resolved, you can merge the PR.

Remove the column​

After the PR merges to production, remove the column on both Staging and Production Airtables.

New table​

You can think of this as basically adding a bunch of new columns all at once -- follow the checklist for new columns.