ent/doc/md/globalid.mdx

---
id: globalid-migrate
title: Migrate Globally Unique ID
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Prior to the baked-in global id feature flag, the migration tool had a `WithGlobalUniqueID` option that allowed users to 
migrate their schema to use globally unique ids. This option is now deprecated and users should use the global id 
feature flag instead. Existing users can migrate their schema to use globally unique ids by following the steps below.

The previous solution utilized a table called `ent_types` to store mapping information between an Ent schema, and it's
associated id range. The new solution uses a static configuration file to store this mapping. In order to migrate to the
new globalid feature, one can use the `entfix` command to migrate an existing `ent_types` table to the new configuration 
file.

:::warning Attention
Please note, that the 'ent_types' table might differ between different environments where your app is deployed. This is 
especially true if you are using auto-migration instead of versioned migrations. Please check, that all 'ent_types' 
tables for all deployments are equal. If they aren't you cannot convert to the new global id feature. 
:::

The first step is to install the `entfix` tool by running the following command:

```shell
go install entgo.io/ent/cmd/entfix@latest
```

Next, you can run the `entfix globalid` command to migrate your schema to use the global id feature. The command 
requires access to a database to read the `ent_types` table. You can either connect to your deployed database, or 
connect to a read replica or in case of versioned migrations, to an ephemeral database where you have applied all your 
migrations.

```shell
entfix globalid --dialect mysql --dsn "root:pass@tcp(localhost:3306)/app" --path ./ent
IMPORTANT INFORMATION

  'entfix globalid' will convert the allocated id ranges for your nodes from the 
  database stored 'ent_types' table to the new static configuration on the ent 
  schema itself.

  Please note, that the 'ent_types' table might differ between different environments 
  where your app is deployed. This is especially true if you are using 
  auto-migration instead of versioned migrations.

  Please check, that all 'ent_types' tables for all deployments are equal!

  Only 'yes' will be accepted to approve.

  Enter a value: yes

Success! Please run code generation to complete the process.
```

Finish the migration by running once again the code generation once. You should see a new file `internal/globalid.go` 
in the generated code, containing just one line starting with `const IncrementStarts`, indicating the process finished 
successfully. Last step is to make sure to remove the `migrate.WithGlobalUniqueID(true)` option from your migration 
setup.

# Optional: Keep `ent_types` table

It might be desired to keep the `ent_types` in the database and not drop it until you are sure you do not need to 
rollback compute. You can do this by using an Atlas composite schema:

<Tabs
defaultValue="schema"
values={[
{label: 'schema.my.sql', value: 'schema'},
{label: 'atlas-hcl', value: 'atlas'},
]}>
<TabItem value="schema">

```hcl
schema "ent" {}

table "ent_types" {
  schema  = schema.ent
  collate = "utf8mb4_bin"
  column "id" {
    null           = false
    type           = bigint
    unsigned       = true
    auto_increment = true
  }
  column "type" {
    null = false
    type = varchar(255)
  }
  primary_key {
    columns = [column.id]
  }
  index "type" {
    unique  = true
    columns = [column.type]
  }
}
```

</TabItem>
<TabItem value="atlas">

```hcl
data "composite_schema" "ent" {
  schema "ent" {
    url = "ent://./ent/schema?globalid=static"
  }
  # This exists to not delete the ent_types table yet.
  schema "ent" {
    url = "file://./schema.my.hcl"
  }
}

env {
  name = atlas.env
  src = data.composite_schema.ent.url
  dev = "docker://mysql/8/ent"
  migration {
    dir = "file://./ent/migrate/migrations"
  }
}
```

</TabItem>
</Tabs>

## Universal IDs (deprecated migration option)

By default, SQL primary-keys start from 1 for each table; which means that multiple entities of different types
can share the same ID. Unlike AWS Neptune, where node IDs are UUIDs.

This does not work well if you work with [GraphQL](https://graphql.org/learn/schema/#scalar-types), which requires the object ID to be unique.

To enable the Universal-IDs support for your project, pass the `WithGlobalUniqueID` option to the migration.

:::note
Versioned-migration users should follow [the documentation](versioned-migrations.mdx#a-word-on-global-unique-ids)
when using `WithGlobalUniqueID` on MySQL 5.*.
:::

```go
package main

import (
	"context"
	"log"
	
	"<project>/ent"
	"<project>/ent/migrate"
)

func main() {
	client, err := ent.Open("mysql", "root:pass@tcp(localhost:3306)/test")
	if err != nil {
		log.Fatalf("failed connecting to mysql: %v", err)
	}
	defer client.Close()
	ctx := context.Background()
	// Run migration.
	if err := client.Schema.Create(ctx, migrate.WithGlobalUniqueID(true)); err != nil {
		log.Fatalf("failed creating schema resources: %v", err)
	}
}
```

**How does it work?** `ent` migration allocates a 1<<32 range for the IDs of each entity (table),
and store this information in a table named `ent_types`. For example, type `A` will have the range
of `[1,4294967296)` for its IDs, and type `B` will have the range of `[4294967296,8589934592)`, etc.

Note that if this option is enabled, the maximum number of possible tables is **65535**.