> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fga.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating Relations

> Migrating relations

In the lifecycle of software development, you will need to make updates or changes to the [authorization model](https://docs.fga.dev/fga-concepts.md#what-is-an-authorization-model). In this guide, you will learn best practices for changing your existing authorization model. With these recommendations, you will minimize downtime and ensure your relationship models stay up to date.

## Before you start

This guide assumes you are familiar with the following Auth0 FGA concepts:

* A [Type](https://docs.fga.dev/fga-concepts.md#what-is-a-type): a class of objects that have similar characteristics
* A [User](https://docs.fga.dev/fga-concepts.md#what-is-a-user): an entity in the system that can be related to an object
* A [Relation](https://docs.fga.dev/fga-concepts.md#what-is-a-relation): is a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system
* An [Object](https://docs.fga.dev/fga-concepts.md#what-is-an-object): represents an entity in the system. Users' relationships to it can be defined through relationship tuples and the authorization model
* A [Relationship Tuple](https://docs.fga.dev/fga-concepts.md#what-is-a-relationship-tuple): a grouping consisting of a user, a relation and an object stored in Auth0 FGA
* [Intersection Operator](https://docs.fga.dev/modeling/configuration-language.md#the-intersection-operator): the intersection operator can be used to indicate a relationship exists if the user is in all the sets of users

## Step by step

The document below is an example of a relational authorization model. In this model, you can assign users to the `editor` relation. The `editor` relation has write privileges that regular users do not.

In this scenario, you will migrate the following model:

There are existing [relationship tuples](https://docs.fga.dev/fga-concepts.md#what-is-a-relationship-tuple) associated with editor relation.

```json theme={null}
[
  {
    "user": "user:anne",
    "relation": "editor",
    "object": "document:roadmap"
  },
  {
    "user": "user:charles",
    "relation": "editor",
    "object": "document:roadmap"
  }
]
```

This is the authorization model that you will want to migrate to:

***

### 01. Create a backwards compatible model

To avoid service disruption, you will create a backwards compatible model. The backwards compatible model ensures the existing relationship tuple will still work.

In the example below, `user:Anne` still has write privileges to the `document:roadmap` resource.

Test the `can_edit` definition. It should produce a value of `true`.

### 02. Create a new relationship tuple

Now that you have a backwards compatible model, you can create new relationship tuples with a new relation.

In this example, you will add Bethany to the `writer` relationship.

Run a check in the API for Bethany to ensure correct access.

### 03. Migrate the existing relationship tuples

Next, migrate the existing relationship tuples. The new relation makes this definition obsolete.

Use the `read` API to look up all relationship tuples.

Then filter out the tuples that do not match the object type or relation (in this case, `document` and `editor` respectively), and update the new tuples with the `write` relationship.

Finally, remove the old relationship tuples.

> [!NOTE]
>
> Perform a `write` operation before a `delete` operation to ensure Anne still has access.

Confirm the tuples are correct by running a check on the user.

The old relationship tuple no longer exists.

### 04. Remove obsolete relationship from the model

After you remove the previous relationship tuples, update your authorization model to remove the obsolete relation.

Now, the `write` API will only accept the new relation name.

## Related Sections

Review the following sections for more information on managing relationship tuples.

[Transactional Writes
Learn how to perform transactional write](https://docs.fga.dev/writing-data/transactional-writes.md)

[Migrating Models
Learn how to best perform model changes.](https://docs.fga.dev/modeling/migrating/migrating-models.md)