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
- UUID in Python — full guide
- UUID v7 ORM Support in 2026
- UUID in Databases — storage and indexing
- UUID v4 vs v7 — performance comparison
- PostgreSQL 18 Ships Native UUID v7
- RFC 9562 — the current UUID standard
External references
- uniq — UUID v7 for Elixir
- Ecto Schema — primary key configuration
- RFC 9562 — UUID standard
- PostgreSQL 18 — uuidv7() function
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.