Elixir and Phoenix use Ecto as the primary database interaction layer. Ecto stores UUIDs as 16-byte binaries (binary_id type) in PostgreSQL — the most efficient possible storage. UUID v7 integrates cleanly: the binary representation is identical to v4, so no migration is needed to switch generation strategies. See UUID v4 vs v7 for the B-tree performance rationale.

Adding the uniq package

# mix.exs
defp deps do
  [
    {:ecto_sql,   "~> 3.12"},
    {:postgrex,   ">= 0.0.0"},
    {:uniq,       "~> 0.6"},   # provides Uniq.UUID.uuid7/0
  ]
end

The uniq package generates RFC 9562-compliant UUID v7 values and provides an Ecto type for validated UUID storage.

Ecto schema with UUID v7

# lib/my_app/orders/order.ex
defmodule MyApp.Orders.Order do
  use Ecto.Schema
  import Ecto.Changeset

  @primary_key {:id, :binary_id, autogenerate: false}
  @foreign_key_type :binary_id

  schema "orders" do
    field :status,      :string
    field :customer_id, :binary_id
    timestamps()
  end

  def changeset(order, attrs) do
    order
    |> cast(attrs, [:status, :customer_id])
    |> validate_required([:status, :customer_id])
    |> put_uuid7_id()
  end

  defp put_uuid7_id(%Ecto.Changeset{data: %{id: nil}} = cs) do
    put_change(cs, :id, Uniq.UUID.uuid7())
  end
  defp put_uuid7_id(cs), do: cs
end

put_uuid7_id/1 assigns a UUID v7 only when the struct’s id is nil — idempotent on re-runs. See UUID in Databases for why the timestamp prefix matters for B-tree performance.

Context function

# lib/my_app/orders.ex
defmodule MyApp.Orders do
  alias MyApp.Repo
  alias MyApp.Orders.Order

  def create_order(attrs) do
    %Order{}
    |> Order.changeset(attrs)
    |> Repo.insert()
  end

  def list_orders_since(ms) do
    # UUID v7 sorts lexicographically in creation order
    lower = build_uuid7_lower_bound(ms)
    Repo.all(from o in Order, where: o.id >= ^lower, order_by: o.id)
  end

  defp build_uuid7_lower_bound(ms) do
    hex = Integer.to_string(ms, 16) |> String.pad_leading(12, "0")
    "#{String.slice(hex, 0, 8)}-#{String.slice(hex, 8, 4)}-7000-8000-000000000000"
  end
end

PostgreSQL 18 — server-side generation

On PostgreSQL 18, delegate UUID v7 generation to the database:

# migration
defmodule MyApp.Repo.Migrations.CreateOrders do
  use Ecto.Migration

  def change do
    create table(:orders, primary_key: false) do
      add :id,          :uuid, primary_key: true, default: fragment("uuidv7()")
      add :status,      :string, null: false
      add :customer_id, :uuid, null: false
      timestamps()
    end
  end
end

fragment("uuidv7()") calls PostgreSQL 18’s built-in function — UUID v7 is generated even for raw SQL inserts bypassing Ecto. Requires PostgreSQL 18.

Phoenix router — UUID path parameters

# router.ex
scope "/api", MyAppWeb do
  pipe_through :api
  resources "/orders", OrderController, only: [:show, :create]
end

# order_controller.ex
def show(conn, %{"id" => id}) do
  case Ecto.UUID.cast(id) do
    {:ok, uuid} ->
      order = MyApp.Orders.get_order!(uuid)
      render(conn, :show, order: order)
    :error ->
      conn |> put_status(:bad_request) |> json(%{error: "invalid UUID"})
  end
end

Ecto.UUID.cast/1 validates the UUID format and returns an error for malformed values before the database is queried. See UUID in OpenAPI for the OpenAPI schema annotation.

Further reading

External references

Frequently asked questions

How do I use UUID v7 as a primary key in Ecto?

Ecto does not ship a built-in UUID v7 generator as of Ecto 3.12, but the uniq Hex package provides Uniq.UUID.uuid7/0. Set the schema's @primary_key to {:id, :binary_id, autogenerate: false} and use Uniq.UUID.uuid7() in the changeset. Alternatively, use dbgenerated("uuidv7()") on PostgreSQL 18+. See UUID v7 ORM Support in 2026.

Does Phoenix LiveView work with UUID v7 primary keys?

Yes. Phoenix LiveView routes and assigns treat IDs as opaque strings — UUID v7 is passed through param maps and socket assigns without any special handling. Pattern-match on %{"id" => id} in LiveView mount/handle_params exactly as you would with UUID v4. The only visible difference is that UUIDs in URLs will have a consistent time-prefixed structure.