Deleting companies from our data model

Last Updated
Published On
We’ve simplified how Plain groups your customers. Instead of navigating two overlapping concepts—companies and tenants—you can now use accounts to represent both email-domain-based groups and the way your product groups its users. To make that possible, we deleted the Company object, a foundational part of our data model. We managed to do this with no downtime, no disruption for our customers, and full API backwards compatibility. All this whilst powering support for companies with large contact volumes such as Framer, Cursor, and Vercel.
Why delete companies?
We designed Plain with two primitives for grouping customers: companies and tenants. Companies were 1:1 with email domains, so if bob@acme.com got in touch we would automatically create a company called Acme.
Meanwhile, tenants were designed to represent how your own product groups its users. Users of your product might be part of two workspaces: a free personal workspace and their employer’s fancy enterprise workspace. The idea of tenants was that when they get in touch with you for support, it’s important to know whether there’s a problem in their free workspace or their enterprise workspace. Tenants let you do that.
Over time, usage evolved organically until the initially clear distinction became blurry. Tenants were being used to sync data from CRMs and had gotten much more capable with the addition of Tenant Fields. Suddenly we found ourselves on every sales call having to explain what the difference between the two concepts was. Additionally, there were things you could do with one but not the other, which caused friction for customers. People had to figure out which concept to use and work around the differences, rather than having one flexible way to group their customers.
Cooking up a plan
To solve this, we decided to add all the missing functionality from companies to tenants. Since customers can be part of multiple tenants, you can get the out-of-the-box benefits of easy setup that companies gave you, along with the flexibility of tenants. We would then migrate every company to a matching tenant and delete companies. Sounds simple, right? 😅
We added a ton of features, UI polish, and general love to Tenants. The main thing to know for this post is that we added primary and additional domain fields and then started automatically creating tenants based on a customer’s email domain. That means customers can still get the easy, automatic grouping they had with companies, while using tenants’ more flexible model. Once we had these new capabilities in place, it was time to figure out the migration.
Whenever we created a company we started creating one of these new domain-based tenants as well. Then we would link them together so that every company had a ‘mirror tenant.’ Initially we did this as a 1:1 link by setting the existing externalId field of the tenant to be the ID of the company it mirrored.
Then, every time someone changed one of these companies, we propagated the change through to the mirror tenant. This was a massive undertaking since companies are wired through every part of Plain. We had to copy changes over to mirror tenants every time someone:
Changed which tier a company is in
Changed which company a customer is in
Linked a Slack channel to a company
Updated a field such as Account Owner / Contract value on a company
Used a company in a saved view
Used a company in a custom role
Used a company in a help center access list
etc
Clearing the backlog
Once we had that working, we had a system where any new companies that got created would be kept up to date with a mirror tenant, but that still left us with a huge backlog of our customers’ historic company data that needed to be migrated to mirror tenants. So it was time to build a migration job.
The key here is that we put in a mechanism early on that prevented any domain-based tenants from being returned via the API (and hence UI) to existing users of Plain. That let us run the migration gradually to avoid putting undue load on our DB without showing any incomplete or broken data in the process.
One of the requirements for this project was to enable turning domain-based tenants off in a workspace. This gives customers a choice: use automatic domain-based grouping, or turn it off and control tenants purely via the API or their CRM as a source of truth. We achieved this by always creating domain-based tenants in the background and using our release mechanism to allow users of Plain to toggle visibility of them on and off at will. This lets it happen instantaneously and fully reversibly with no downtime or expensive backfills. It even works for reporting data (which was a whole other ordeal…)!
No plan survives contact with the enemy
When we started running the migration job, we quickly hit an issue: it turned out there was some bad historic data that had snuck through our domain validation checks at some time in the past. This included such gems as bob@?, as well as companies that differed only by case (e.g. two companies in the same workspace with domains of Example.com and example.com).
We didn’t want to relax the validation logic of tenants, which left us with two options:
Fix up the bad company data and then re-run the migration
Change the relationship between companies and mirror tenants from 1:1 to n:1
In an ideal world, option 1 would have been simpler, but there were downstream references to companies which made fixing the data ambiguous. Contacting every affected customer to resolve that would have taken too long, so we realised we could fix this going forward, by using option 2.
So we introduced a new table to store the company <> mirror tenant link which lets us point both example.com and Example.com at the same mirror tenant while only storing the correct domain on the tenant. Customers from both company records would share one mirror tenant.
With this implemented, we ran a second migration to move all the mirror tenants we had already created to the new model (yo dawg, I heard you like migrations…), and resumed the original migration job.
Scaling the migration
Our primary concern when writing this migration was not putting too much load on the DB, so we started it off very conservatively.
The migration worked through one workspace at a time and grabbed a page of un-migrated company IDs to process. Then it worked through each company serially:
Setting up the mirror tenant
Adding all the customers to the new tenant
Migrating the rest of the company references to the new tenant
To be extra safe, we only ran this outside peak usage hours (in the evenings and on weekends). This was easy to achieve by using a scheduled cron to trigger a lambda, but it meant we needed to make it safe for the job to gracefully exit early and re-run. We added a checkpoint column to every workspace and company so that we could track which had completed their migration and pick up where we left off on the next run.
After starting the migration, it looked like it would take a month to complete 😅 Luckily, it was only having a tiny impact on the DB so we could aggressively scale it up. Looking at the traces, we saw that it was mostly latency-bound, primarily waiting on calls to the DB to return. The easy thing to do here was to increase the batch sizes on upsert operations (i.e. update 200 customers at a time instead of 50) and to ramp up how many companies we processed at once (shoutout to p-limit).
With these changes deployed on a Friday, it looked like the migration would complete over the weekend, so job done!
What about the API?
Plain is API-first, and our customers have built loads of incredible stuff using it, which is great. But it does make rolling out breaking data model changes harder. We decided that we couldn’t wait for everyone to make code changes before rolling this out which meant we needed to make it backwards compatible.
Since we already had the mirror tenant system in place we set up a feature flag which meant that company queries and mutations would act on and return mirror tenants. That meant customers could keep their existing company API integrations running while we moved to the new model, rather than having to update their code on our rollout schedule.
To test it, one of our engineers found the most prolific users of these endpoints from the logs and did a bunch of research calls with them about the types of things they had built. She then used those findings to write realistic smoke tests which let us compare the outputs of the APIs with and without the flag on across a variety of workspaces to find (and fix) any inconsistencies.
Rolling out the changes
We couldn’t just spring this change on people without giving them plenty of notice beforehand. At every stage we also ran our development workspaces and Plain’s production workspace a few steps ahead of our customers’ workspaces to catch any issues early.
When we first announced this to our existing customers, we also enabled a flag which let them hide companies in the UI to see what things would look like. This was fully reversible, so customers could see how the change would affect their workflows and switch back until they were ready.
After a month of letting people try it out and having our amazing CSMs talk it through with many of our customers, we cut everyone over to the ‘companies hidden’ state. We then gradually rolled out the feature flag to power all the company API requests with tenant data over the course of a week.
Wrapping up
The result is a simpler way for customers to group the people they support: the automatic setup they had with companies, plus the flexibility of tenants, without having to choose between two overlapping concepts. And because we kept the API backwards compatible, customers could get there without interrupting their existing integrations. We’re really happy with how this process panned out. While it was happening we also decided to rename Tenants to Accounts to better suit their expanded role in the platform, which came with its own challenges, but that can be it’s own post later.
More from the blog
Stories and lessons from the Plain team.






