Ecto.ShortUUID

Ecto.ShortUUID is a custom Ecto.Type which allows for Ecto to automatically encode UUIDs to ShortUUIDs.

ShortUUID is binary-compatible with UUID, so it can be stored in a uuid column in a database.

ShortUUIDs can be used alongside :binary_id or as drop-in replacement for :binary_id primary and foreign keys, basically anywhere Ecto.UUID can be used.

If you're already using :binary_id(Ecto.UUID) for primary keys it is possible to simply switch from :binary_id to using Ecto.ShortUUID and vice versa, neither the underlying data nor DB schema need to be changed.

For example, we can see that calls to Ecto.ShortUUID.dump/1 and Ecto.UUID.dump/1 will return the same binary in the following case:

# let's get the encoded value
iex> Ecto.ShortUUID.cast("2a162ee5-02f4-4701-9e87-72762cbce5e2")
{:ok, "9VprZJ9U7Tgg2PJ8BfTAek"}

# and show off that dump/1 works with both ShortUUIDs and UUIDs
iex> Ecto.ShortUUID.dump("9VprZJ9U7Tgg2PJ8BfTAek")
{:ok, <<42, 22, 46, 229, 2, 244, 71, 1, 158, 135, 114, 118, 44, 188, 229, 226>>}

# dump/1 continues to work with regular UUIDs
iex> Ecto.ShortUUID.dump("2a162ee5-02f4-4701-9e87-72762cbce5e2")
{:ok, <<42, 22, 46, 229, 2, 244, 71, 1, 158, 135, 114, 118, 44, 188, 229, 226>>}

iex> Ecto.UUID.dump("2a162ee5-02f4-4701-9e87-72762cbce5e2")
{:ok, <<42, 22, 46, 229, 2, 244, 71, 1, 158, 135, 114, 118, 44, 188, 229, 226>>}

# when a key is retrieved load/1 is called
# with the binary representation of the UUID 2a162ee5-02f4-4701-9e87-72762cbce5e2
iex> Ecto.ShortUUID.load(<<42, 22, 46, 229, 2, 244, 71, 1, 158, 135, 114, 118, 44, 188, 229, 226>>)
{:ok, "9VprZJ9U7Tgg2PJ8BfTAek"}

# the same binary key continues to work with Ecto.UUID
iex> Ecto.UUID.load(<<42, 22, 46, 229, 2, 244, 71, 1, 158, 135, 114, 118, 44, 188, 229, 226>>)
{:ok, "2a162ee5-02f4-4701-9e87-72762cbce5e2"}

We can see that Ecto.ShortUUID.dump/1 is backwards compatible and still accepts regular UUIDs and the value stored in the DB is exactly the same as when using the regular :binary_id type.

Installation

If available in Hex, the package can be installed by adding ecto_shortuuid to your list of dependencies in mix.exs:

def deps do
  [
    {:ecto_shortuuid, "~> 0.4.0"}
  ]
end

Example project

You can check out the example project ecto_shortuuid_example with defined config, schemas and seeds to quickly try out ecto_shortuuid for yourself.

Usage

Using Ecto.ShortUUID is similar to using Ecto.UUID.

Schema

You can use the ShortUUID for a regular field

defmodule Post do
  use Ecto.Schema

  schema "posts" do
    field :test, Ecto.ShortUUID
  end
end

To use ShortUUIDs as primary keys we define the @primary_key attribute like this:

defmodule MyApp.User do
  use Ecto.Schema

  @primary_key {:id, Ecto.ShortUUID, autogenerate: true}

  schema "users" do
    field :name, :string
    field :age, :integer, default: 0
    has_many :posts, Post
  end
end

To avoid having to define the primary key type in every schema in case you're using binary ids throughout you can make ShortUUIDs the default by defining the following in the underlying schema module.

# Define a module to be used as base
defmodule MyApp.Schema do
  defmacro __using__(_) do
    quote do
      use Ecto.Schema
      @primary_key {:id, Ecto.ShortUUID, autogenerate: true}
      @foreign_key_type Ecto.ShortUUID
    end
  end
end

# Now use MyApp.Schema to define new schemas
defmodule MyApp.User do
  use MyApp.Schema

  schema "users" do
    field :name, :string
    field :age, :integer, default: 0
    has_many :posts, Post
  end
end

This exactly the same as when using :binary_id as defined in the Ecto docs - Schema attributes.

Migration

The key has to be also defined as :uuid in the migration

defmodule MyApp.Repo.Migrations.CreateUser do
  use Ecto.Migration

  def change do
    create table(:users, primary_key: false) do
      add :id, :uuid, primary_key: true
      add :name, :string
      add :age, :integer
      add :company_id, references(:companies, type: :uuid)

      timestamps
  end
end

Alternatively if starting from scratch you can configure the default migration primary key type as:

config :app, MyApp.Repo,
  migration_primary_key: [name: :id, type: :binary_id]

Read more about config options in the Ecto docs - Repo Configuration.

Custom Alphabets

Starting with version 0.4.0 Ecto.ShortUUID supports custom alphabets through two approaches.

Note: Custom alphabets are available in ShortUUID starting from version 4.0.0, and the ShortUUID.Behaviour is available since version 4.1.0.

To ensure you have the right version of ShortUUID for custom alphabets, you can explicitly specify it in your dependencies:

def deps do
  [
    {:ecto_shortuuid, "~> 0.4.0"},
    {:shortuuid, "~> 4.1"}  # Explicitly specify for custom alphabets/behaviors
  ]
end

Approach 1: Using ShortUUID.Builder

You can define a custom ShortUUID module with a specific alphabet using ShortUUID.Builder, then create a custom Ecto type with Ecto.ShortUUID.Builder:

# Define a custom ShortUUID implementation with a specific alphabet
defmodule MyApp.Base58UUID do
  use ShortUUID.Builder, alphabet: :base58
end

# Create a custom Ecto type that uses your ShortUUID implementation
defmodule MyApp.Base58EctoUUID do
  use Ecto.ShortUUID.Builder, encoder: MyApp.Base58UUID
end

# Use in your schema
defmodule MyApp.User do
  use Ecto.Schema
  
  @primary_key {:id, MyApp.Base58EctoUUID, autogenerate: true}
  @foreign_key_type MyApp.Base58EctoUUID
  
  schema "users" do
    # ...
  end
end

ShortUUID supports these predefined alphabets:

• :base57_shortuuid - Default alphabet, omits ambiguous characters like "l", "1", "I", "O", "0"
• :base58 - Bitcoin alphabet
• :base62 - Alphanumeric alphabet
• :base32, :base32_hex, :base32_crockford, :base32_z - Various base32 encodings
• :base64, :base64_url - Base64 encodings

You can also define a custom alphabet string with at least 16 unique characters:

defmodule MyApp.CustomAlphabetUUID do
  use ShortUUID.Builder, alphabet: "0123456789ABCDEF-_+"
end

Approach 2: Implementing ShortUUID.Behaviour

For more control, you can implement the ShortUUID.Behaviour (available since ShortUUID v4.1.0) directly:

defmodule MyApp.CustomShortUUID do
  @behaviour ShortUUID.Behaviour
  
  @impl true
  def encode(uuid) do
    # Your custom implementation
    {:ok, "custom-" <> uuid}
  end
  
  @impl true
  def encode!(uuid) do
    case encode(uuid) do
      {:ok, encoded} -> encoded
      {:error, reason} -> raise ArgumentError, message: reason
    end
  end
  
  @impl true
  def decode("custom-" <> uuid) do
    # Your custom implementation
    {:ok, uuid}
  end
  
  @impl true
  def decode!(encoded) do
    case decode(encoded) do
      {:ok, decoded} -> decoded
      {:error, reason} -> raise ArgumentError, message: reason
    end
  end
end

# Create an Ecto type with your custom implementation
defmodule MyApp.CustomEctoUUID do
  use Ecto.ShortUUID.Builder, encoder: MyApp.CustomShortUUID
end

This gives you complete control over encoding and decoding while maintaining compatibility with Ecto.

Documentation

Additional documentation can be found at https://hexdocs.pm/ecto_shortuuid.