Ecto.UUID
SourceAn Ecto type for UUID strings.
Autogeneration
This type can be used for any UUID field in your schemas. It is used when autogenerating binary IDs in Ecto.Schema. By default, autogenerated UUIDs use version 4 (random):
use Ecto.Schema
@primary_key {:id, :binary_id, autogenerate: true}
To use UUID v7 (time-ordered) instead:
use Ecto.Schema
@primary_key {:id, Ecto.UUID, autogenerate: [version: 7]}
To use UUID v7 (time-ordered) monotonic:
use Ecto.Schema
@primary_key {:id, Ecto.UUID, autogenerate: [version: 7, precision: :monotonic]}
According to RFC 9562: "Monotonicity (each subsequent value being greater than the last) is the backbone of time-based sortable UUIDs."
Summary
- option()
Supported options:
:versionand:precision(v7-only).- raw()
A raw binary representation of a UUID.
- t()
A hex-encoded UUID string.
Types
- bingenerate(opts \\ [])
Generates a uuid with the given options in binary format. See
generate/1for details and available options.- cast(uuid)
Casts either a string in the canonical, human-readable UUID format or a 16-byte binary to a UUID in its canonical, human-readable UUID format.
- cast!(uuid)
Same as
cast/1but raisesEcto.CastErroron invalid arguments.- dump(uuid_string)
Converts a string representing a UUID into a raw binary.
- dump!(uuid)
Same as
dump/1but raisesEcto.ArgumentErroron invalid arguments.- embed_as(_)
Callback implementation for
Ecto.Type.embed_as/1.- equal?(term1, term2)
Callback implementation for
Ecto.Type.equal?/2.- generate(opts \\ [])
Generates a UUID string.
- load(raw_uuid)
Converts a binary UUID into a string.
- load!(value)
Same as
load/1but raisesEcto.ArgumentErroron invalid arguments.
Functions
Types
option()Source
@type option() :: {:version, 4 | 7} | {:precision, :millisecond | :monotonic} Supported options: :version and :precision (v7-only).
options()Source
@type options() :: [option()]
raw()Source
@type raw() :: <<_::128>>
A raw binary representation of a UUID.
t()Source
@type t() :: <<_::288>>
A hex-encoded UUID string.
Functions
bingenerate(opts \\ [])Source
@spec bingenerate(options()) :: raw()
Generates a uuid with the given options in binary format. See generate/1 for details and available options.
cast(uuid)Source
@spec cast(t() | raw() | any()) :: {:ok, t()} | :error Casts either a string in the canonical, human-readable UUID format or a 16-byte binary to a UUID in its canonical, human-readable UUID format.
If uuid is neither of these, :error will be returned.
Since both binaries and strings are represented as binaries, this means some strings you may not expect are actually also valid UUIDs in their binary form and so will be casted into their string form.
If you need further-restricted behavior or validation, you should define your own custom Ecto.Type. There is also Ecto.UUID.load/1 if you only want to process raw UUIDs, which may be a more suitable reverse operation to Ecto.UUID.dump/1.
Examples
iex> Ecto.UUID.cast(<<0x60, 0x1D, 0x74, 0xE4, 0xA8, 0xD3, 0x4B, 0x6E,
...> 0x83, 0x65, 0xED, 0xDB, 0x4C, 0x89, 0x33, 0x27>>)
{:ok, "601d74e4-a8d3-4b6e-8365-eddb4c893327"}
iex> Ecto.UUID.cast("601d74e4-a8d3-4b6e-8365-eddb4c893327")
{:ok, "601d74e4-a8d3-4b6e-8365-eddb4c893327"}
iex> Ecto.UUID.cast("warehouse worker")
{:ok, "77617265-686f-7573-6520-776f726b6572"} cast!(uuid)Source
@spec cast!(t() | raw() | any()) :: t()
Same as cast/1 but raises Ecto.CastError on invalid arguments.
dump(uuid_string)Source
@spec dump(uuid_string :: t() | any()) :: {:ok, raw()} | :error Converts a string representing a UUID into a raw binary.
dump!(uuid)Source
@spec dump!(t() | any()) :: raw()
Same as dump/1 but raises Ecto.ArgumentError on invalid arguments.
embed_as(_)Source
Callback implementation for Ecto.Type.embed_as/1.
equal?(term1, term2)Source
Callback implementation for Ecto.Type.equal?/2.
generate(opts \\ [])Source
@spec generate(options()) :: t()
Generates a UUID string.
Options
-
:version- The UUID version to generate. Supported values are4(random) and7(time-ordered). Defaults to4.
Options (version 7 only)
-
:precision- The timestamp precision for version 7 UUIDs. Supported values are:millisecondand:monotonic. Defaults to:millisecond.
Monotonic precision
When using :monotonic, sub-millisecond precision is encoded in the rand_a field. The generated version 7 UUIDs are strictly monotonically increasing (per node), even when multiple UUIDs are generated within the same timestamp. This is useful for maintaining insertion order in databases.
Examples
> Ecto.UUID.generate() "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11" > Ecto.UUID.generate(version: 7) "018ec4c1-ae46-7f5a-8f5a-6f5a8f5a6f5a" > Ecto.UUID.generate(version: 7, precision: :millisecond) "018ec4c1-ae46-7f5a-8f5a-6f5a8f5a6f5a" > Ecto.UUID.generate(version: 7, precision: :monotonic) "018ec4c1-ae46-7f5a-8f5a-6f5a8f5a6f5a"
load(raw_uuid)Source
@spec load(raw() | any()) :: {:ok, t()} | :error Converts a binary UUID into a string.
load!(value)Source
@spec load!(raw() | any()) :: t()
Same as load/1 but raises Ecto.ArgumentError on invalid arguments.
© 2014 Chris McCord
Licensed under the MIT License.
https://ecto.hexdocs.pm/Ecto.UUID.html
