DEV Community: Gabriela Colombo

How I Migrated a Live Database to a Many-to-Many Relationship

Gabriela Colombo — Sat, 24 Oct 2026 23:50:21 +0000

Most articles about database migrations assume you know the final model before you start. In real products, you often don't. You ship a design, it goes to production, and then a customer conversation tells you the design was wrong.

In 2026, I designed and built a speaker roles feature for an event platform, end to end: database schema, GraphQL API, and changes to both the organizer dashboard and the attendee-facing event app. I shipped it as a one-to-one relationship. After it was live, the requirement changed to many-to-many. This is how I evolved the data model twice without breaking a single existing event, and what I'd ask earlier next time.

The problem: a custom field doing a feature's job

Organizers wanted to label what each speaker does in a session: moderator, host, interviewer. The platform had no concept for this, so organizers worked around it with a generic custom field on the speaker profile. It was free text, it was manual, and nothing in the product understood it.

The goal was to replace that workaround with a real feature: organizers define roles per event and assign them to speakers.

The constraint was the hard part. Existing events were already live, with speakers, integrations, and API clients built on the old data model. None of them could break while the new feature rolled out incrementally.

Version 1: one role per speaker, zero breaking changes

The first design was simple. I added a speaker_role table, scoped to an event, and linked each speaker to one role through a foreign key.

A foreign key creates an obvious problem: every existing speaker now needs a valid role, and so does every speaker created by a client that has never heard of roles. Three decisions solved it:

Every event gets a default role, automatically. When an event is created, the backend creates its default role in the same flow. No event can exist without one.
Existing speakers were migrated to their event's default role. A migration script assigned them before anything depended on the new relationship.
**roleId **is optional in the API. If a client doesn't send it, the backend assigns the event's default role.

The third one is what kept existing integrations working. In the GraphQL schema, it looks like this:

type SpeakerRole {
  id: ID!
  name: String!
  isDefault: Boolean!
}

input CreateSpeakerInput {
  eventId: ID!
  name: String!
  # Optional on purpose: older clients don't know roles exist
  roleId: ID
}

And in the resolver:

const roleId =
  input.roleId ?? (await speakerRoles.getDefaultRoleId(input.eventId));

One line, but it carries the whole compatibility strategy. Clients that know about roles send one. Clients that don't keep working, and their speakers still end up in a valid state. Nobody had to coordinate a release with us.

The data question: migrate the old field or not?

During implementation, a product question came up. Organizers already had speaker types in that custom field. Should the event app keep showing it, or should the new roles replace it? Showing both would display the same information twice.

The tempting answer was to migrate the custom field into the new roles. Before proposing that, I checked production data. Only a small minority of speakers had the custom field filled in. And because it was free text, the values varied too much to map reliably to roles. An automatic migration would have produced wrong roles for real events.

So instead of migrating, I proposed a toggle. Each organizer chooses whether the event app displays the old custom field or the new speaker roles. Organizers who depended on the old field lost nothing. Everyone else got the new feature.

The lesson: a migration is only as good as the data you migrate. When the source data is unreliable, giving users a choice can be safer than guessing for them.

Version 2: the requirement changed after launch

The backend was fully in production when a meeting with the integrations team surfaced something new: a customer needed speakers to hold multiple roles in the same session. A speaker could be both host and interviewer in the same session.

The one-to-one design couldn't express that. A speaker pointed to exactly one role.

The quick fix would have been to duplicate the speaker, one row per role. That didn't work either. The speaker table had a unique index, and other features relied on a speaker existing once. Breaking that assumption would have spread the change far beyond roles.

The honest conclusion was that the model needed a redesign: a pivot table between speakers and roles, a many-to-many relationship. The real question was how to get there while Version 1 was live and in use.

Migrating to many-to-many without changing the API

I didn't replace the old relationship. I added the new one next to it and moved traffic over in steps:

Add the pivot table. speaker_role_assignment links a speaker to a role. The old foreign key stays in place.
Start writing to the new model. The organizer dashboard populates the pivot table on every role change.
Backfill existing data. A migration script copies every existing speaker-role link into the pivot table.
Read new first, fall back to old. A dataloader resolves roles from the pivot table and falls back to the old relationship when no assignment exists yet.
Switch the event app. It reads the new relationship, and the API response shape stays the same.

The old foreign key stays in Version 2, so reads can fall back to it for any speaker not yet in the pivot table.
Because of that, the backfill didn't need to finish before deploying, and no event ever had a window where its speakers lost their roles.

What I ask before designing a relationship now

Looking back, Version 1 wasn't a mistake. It solved the problem as it was described at the time. But a few questions, asked earlier, would have saved a redesign:

"Can this ever be more than one?" Ask it about every one-to-one relationship, and ask the people closest to customers, not only product. The integrations team knew before anyone else.
What happens to clients that don't know this feature exists? Make new inputs optional and give them a safe default.
Can every existing record satisfy the new constraint? If not, create the defaults and migrate before you enforce it.
Is the data I'm about to migrate trustworthy? Check production before promising a migration.
Can old and new models coexist? If reads fall back gracefully, the backfill stops being a deadline.

Conclusion

The hardest part of this feature wasn't the schema or the GraphQL types. It was that production never pauses while you change your mind. Existing events, old integrations, and real organizers were using Version 1 the whole time I built Version 2.

What made it work was treating every change as a transition instead of a replacement: defaults for clients that don't know about roles, a toggle instead of an unreliable migration, and a dataloader that could read both models at once.

The question I ask now isn't only "Does the new feature work?" It's "Can the system move safely from where it is to where it needs to be, even if where it needs to be changes halfway through?"

What I Learned Building Backend Features Used Across Multiple Clients

Gabriela Colombo — Mon, 05 Oct 2026 13:33:33 +0000

When engineers are early in their careers, we often think that if an API is correct, tested, and returns the expected response, the feature is ready.

Working on production systems used by different clients changed this perspective.

Backend changes rarely exist in isolation; the same API can be consumed by web, mobile apps, internal servers, etc. This means a backend change can be technically correct and still break the product if it’s not well planned.

Over the years, I learned to think beyond the endpoint/query/mutation itself. Before any changes to an API, I like to ask, “Who consumes this data today?” “How can this be backward compatible so as not to break anything in production?”

1. Your API Contract Is Bigger Than the Endpoint

An API contract isn't just the route, request body, and response documented in the specification.

Clients can depend on details that may look insignificant from the backend perspective.

For example, imagine an API returning:

{
  "id": "123",
  "role": "speaker"
}

A new requirement allows a user to have multiple roles. From a data-model perspective, changing the response to this might seem natural:

{
  "id": "123",
  "roles": ["speaker", "moderator"]
}

The new model may be better, but replacing role with roles immediately creates a breaking change.

The web application may already support the new model while an older mobile version still expects role.

The backend therefore has to consider not only what the ideal API should look like, but how clients will transition to it.

2. Backward compatibility is part of feature development

Deploying a breaking change to production can affect existing clients and users. For that reason, backward compatibility should be considered during development rather than after the feature is ready to be released.

Depending on the situation, one approach is to introduce new data as optional first and migrate existing records before making it mandatory.

One example I would like to share comes from a feature I developed around speaker roles. The new requirement was that every speaker should have a role assigned, which meant introducing information that would eventually become mandatory.

Making it mandatory immediately, however, would create a problem: thousands of existing speakers had been created before this requirement existed. The new feature had to support them as well.

Instead of assuming that the new requirement could be applied immediately, I treated the change as a transition.

First, the new role information was introduced without requiring it for existing data. This allowed the new backend behavior to coexist with records created under the previous model.

Next, I migrated the existing data. Speakers who already existed in the system needed to receive the appropriate default role so that, after the migration, both old and newly created records followed the same business rules.

Only after the existing data had been migrated could the new requirement safely be treated as mandatory.

Conceptually, the transition looked like this:

Old state:
Existing speakers → no explicit role required

Transition:
New role capability → optional → existing data migrated

New state:
All speakers → role guaranteed

This is an important distinction when developing features for systems already in production. A new business rule does not automatically mean that the existing data satisfies that rule.

The backend needs to provide a safe path between the old and new states.

In this case, backward compatibility was not only about keeping an API response unchanged. It also meant ensuring that existing data remained valid while the product transitioned to a new requirement.

3. Database redesigns need a transition state

The database model can evolve without requiring the API contract to change in the same way.

I faced this when a feature that originally supported a single role per speaker evolved to support multiple roles. The original data model was designed around a single relationship (1:1), but the new requirement needed a many-to-many relationship (1:N).

Instead of replacing the old model immediately, I introduced a new relationship model and treated the change as a transition.

During this transition, the API temporarily had to support both persistence models. When data was created or updated, the backend wrote the relevant information to both the legacy model and the new relationship model.

Conceptually, the flow looked like this:

Phase 1 — Introduce the new model

The new relationship was added while the existing model remained in production.

Phase 2 — Dual write

The backend temporarily persisted the relevant information in both models. This allowed new data to remain consistent while existing data was being migrated.

Phase 3 — Migrate existing data

Existing records were migrated to the new relationship model. During this process, both old and newly created data could continue to work without stopping the application.

Phase 4 — Switch to the new model

Once the migration was complete and the new model contained the expected data, the application could rely on the new relationship.

Phase 5 — Remove the legacy path

The temporary logic that wrote to the old model was removed. Once the application no longer depended on the legacy data, the old database structure could also be safely removed.

The important part was that the database change and the application change could not be treated as a single deployment.

For a period of time, the backend had to understand two representations of the same business concept and keep them consistent.

This approach added temporary complexity to the code, but that complexity had a purpose: it created a safe transition between two data models without requiring the production system to move from one state to another instantly.

It also changed how I think about database redesigns. Sometimes the safest solution is not to replace the old model immediately, but to design an intermediate state where both models can coexist until the migration is complete.

4. ”Nobody uses this field anymore” is a dangerous assumption

Removing legacy code is an important part of evolving a system. However, assuming that something is no longer used just because we cannot find an obvious reference to it can be dangerous.

Searching the codebase is a good starting point, but it doesn’t always show the whole picture. An API can have different consumers, older clients can still be running, and some code paths may only be executed under specific conditions.

Observability can help answer these questions.

For example, before removing an old behavior, we can add temporary logs or metrics around its usage and observe it for a period of time. Instead of assuming that a legacy path is no longer used, we can measure whether it is still being executed.

A removal process can look like:

Identify the legacy behavior → find known consumers → instrument its usage → observe → remove → monitor

This is especially useful during migrations. After moving to a new data model, I don’t want to remove the old path simply because the migration has finished. I also want to know that the application is no longer depending on it.

The goal is to turn “I think nobody uses this anymore” into “we have evidence that this is no longer being used.”

5. Observability after deployment

During development, I try to think about what information I will need after the feature reaches production. This means creating consistent logs around important operations, failures, unexpected states, etc.

Once the feature is deployed, these logs can be observed through tools such as Grafana or other monitoring platforms.

For a migration or a gradual rollout, for example, I want to understand:

if the new code path is being executed as expected
if some records cannot be processed by the new logic
if errors increased after the deployment
if the system reached a state that I didn’t expect during development
The important part is to think about observability before something goes wrong.

A log such as Something went wrong might tell me that an error happened, but it gives me very little information to investigate it. Good logs should provide enough context to understand which operation failed and at which point in the flow, without exposing sensitive information.

This becomes even more important when releasing changes incrementally. If old and new behaviors temporarily coexist, observability helps validate whether the transition is actually happening as expected.

For me, production is the final validation environment. Tests can validate the scenarios we know about, while observability helps us discover the scenarios we didn’t anticipate.

Conclusion

Building backend features for production systems taught me that implementing the expected behavior is only part of the job.

A backend engineer also needs to think about existing data, different consumers, migrations, backward compatibility, safe transitions, and how the system will be observed after deployment.

The question is no longer only:

“Does the new feature work?”

It also becomes:

“Can the system safely move from its current state to the new one?”

That change in perspective has influenced how I design features today. I try to think not only about the final architecture, but also about the path the system needs to take to get there.

Originally published on Medium