improvement: Update MigrationGenerator to use uuidv7 when available (#674)

Author: matt-savvy

documentation/topics/development/upgrading-to-postgres-18.md

@@ -0,0 +1,103 @@
+<!--
+SPDX-FileCopyrightText: 2020 Zach Daniel
+
+SPDX-License-Identifier: MIT
+-->
+
+# Using Postgres 18
+
+Postgres 18 adds built-in functions for working with version 7 (time-ordered) UUIDs.
+
+`AshPostgres` adds a `uuid_generate_v7` function to the database as part of the initial migration.
+This Ash function is normally used as the default for `Ash.Type.UUIDv7` types.
+
+## Using Postgres 18's Built-In `uuidv7`
+To take advantage of Postgres 18's built-in `uuidv7` function, you need to update your `Repo.min_pg_version/0` to a `Version` with `major` at 18 or above.
+
+```elixir
+  def min_pg_version do
+    %Version{major: 18, minor: 0, patch: 0}
+  end
+```
+
+Then when you run `ash.codegen`, migrations will be added to update the defaults for your `UUIDv7` type attributes.
+
+```sh
+$ mix ash.codegen update_uuid_v7_default
+```
+
+Giving you migrations like so
+```elixir
+  def up do
+    alter table(:items) do
+      modify(:id, :uuid, default: fragment("uuidv7()"))
+    end
+  end
+
+  def down do
+    alter table(:items) do
+      modify(:id, :uuid, default: fragment("uuid_generate_v7()"))
+    end
+  end
+```
+
+The Ash function `uuid_generate_v7` won't be automatically removed for you, but you can add a migration to remove this on your own.
+```elixir
+
+defmodule SomeProject.Repo.Migrations.RemoveAshUuidv7 do
+  use Ecto.Migration
+
+  def up do
+    execute("DROP FUNCTION IF EXISTS uuid_generate_v7")
+  end
+
+  def down do
+    # copied from initialize_extensions_1 migration
+    execute("""
+    CREATE OR REPLACE FUNCTION uuid_generate_v7()
+    RETURNS UUID
+    AS $$
+    DECLARE
+      timestamp    TIMESTAMPTZ;
+      microseconds INT;
+    BEGIN
+      timestamp    = clock_timestamp();
+      microseconds = (cast(extract(microseconds FROM timestamp)::INT - (floor(extract(milliseconds FROM timestamp))::INT * 1000) AS DOUBLE PRECISION) * 4.096)::INT;
+
+      RETURN encode(
+        set_byte(
+          set_byte(
+            overlay(uuid_send(gen_random_uuid()) placing substring(int8send(floor(extract(epoch FROM timestamp) * 1000)::BIGINT) FROM 3) FROM 1 FOR 6
+          ),
+          6, (b'0111' || (microseconds >> 8)::bit(4))::bit(8)::int
+        ),
+        7, microseconds::bit(8)::int
+      ),
+      'hex')::UUID;
+    END
+    $$
+    LANGUAGE PLPGSQL
+    SET search_path = ''
+    VOLATILE;
+    """)
+  end
+end
+```
+
+## Opt Out of Changing Defaults
+
+If you want to upgrade your `min_pg_version` *without* changing the default for `UUIDv7`s, you can override the `use_builtin_uuidv7_function?` callback in your `Repo` module.
+
+```elixir
+defmodule SomeProject.Repo do
+  use AshPostgres.Repo, otp_app: :some_project
+
+  def min_pg_version do
+    %Version{major: 18, minor: 0, patch: 0}
+  end
+
+  def use_builtin_uuidv7_function?, do: false
+
+  ...
+end
+```

lib/migration_generator/migration_generator.ex

@@ -3500,13 +3500,16 @@ defmodule AshPostgres.MigrationGenerator do
 
   @uuid_functions [&Ash.UUID.generate/0, &Ecto.UUID.generate/0]
 
-  defp default(%{name: name, default: default, type: type}, resource, _repo)
+  defp default(%{name: name, default: default, type: type}, resource, repo)
        when is_function(default) do
     configured_default(resource, name) ||
       cond do
         default in @uuid_functions ->
           ~S[fragment("gen_random_uuid()")]
 
+        default == (&Ash.UUIDv7.generate/0) and repo.use_builtin_uuidv7_function?() ->
+          ~S[fragment("uuidv7()")]
+
         default == (&Ash.UUIDv7.generate/0) ->
           ~S[fragment("uuid_generate_v7()")]
 

lib/repo.ex

@@ -106,6 +106,8 @@ defmodule AshPostgres.Repo do
 
   @doc "Allows overriding a given migration type for *all* fields, for example if you wanted to always use :timestamptz for :utc_datetime fields"
   @callback override_migration_type(atom) :: atom
+  @doc "Whether or not to use the built-in `uuidv7` function (as opposed to the Ash `uuid_generate_v7` function) for `UUIDv7` fields."
+  @callback use_builtin_uuidv7_function? :: boolean
   @doc "Should the repo should be created by `mix ash_postgres.create`?"
   @callback create?() :: boolean
   @doc "Should the repo should be dropped by `mix ash_postgres.drop`?"
@@ -152,6 +154,12 @@ defmodule AshPostgres.Repo do
       def create_schemas_in_migrations?, do: true
       def default_prefix, do: "public"
       def override_migration_type(type), do: type
+
+      def use_builtin_uuidv7_function? do
+        %Version{major: major} = min_pg_version()
+        major >= 18
+      end
+
       def create?, do: true
       def drop?, do: true
       def disable_atomic_actions?, do: false
@@ -328,7 +336,8 @@ defmodule AshPostgres.Repo do
                      drop?: 0,
                      disable_atomic_actions?: 0,
                      disable_expr_error?: 0,
-                     immutable_expr_error?: 0
+                     immutable_expr_error?: 0,
+                     use_builtin_uuidv7_function?: 0
 
       # We do this switch because `!@warn_on_missing_ash_functions` in the function body triggers
       # a dialyzer error

mix.exs

@@ -112,6 +112,7 @@ defmodule AshPostgres.MixProject do
         "documentation/topics/development/migrations-and-tasks.md",
         "documentation/topics/development/testing.md",
         "documentation/topics/development/upgrading-to-2.0.md",
+        "documentation/topics/development/upgrading-to-postgres-18.md",
         "documentation/topics/advanced/expressions.md",
         "documentation/topics/advanced/manual-relationships.md",
         "documentation/topics/advanced/partitioned-tables.md",

test/migration_generator_test.exs

@@ -286,6 +286,59 @@ defmodule AshPostgres.MigrationGeneratorTest do
     end
   end
 
+  describe "creating initial snapshots with native uuidv7 on PG 18" do
+    setup do
+      prev_pg_version_env = System.fetch_env("PG_VERSION")
+      System.put_env("PG_VERSION", "18")
+
+      on_exit(fn ->
+        File.rm_rf!("test_snapshots_path")
+        File.rm_rf!("test_migration_path")
+
+        case prev_pg_version_env do
+          # there was a previous env var set, restore it
+          {:ok, value} -> System.put_env("PG_VERSION", value)
+          # there was nothing set, delete what we set
+          :error -> System.delete_env("PG_VERSION")
+        end
+      end)
+
+      defposts do
+        attributes do
+          uuid_v7_primary_key(:id)
+        end
+      end
+
+      defdomain([Post])
+
+      AshPostgres.MigrationGenerator.generate(Domain,
+        snapshot_path: "test_snapshots_path",
+        migration_path: "test_migration_path",
+        quiet: true,
+        format: false,
+        auto_name: true
+      )
+
+      :ok
+    end
+
+    test "the migration uses the native uuidv7 function" do
+      # the snapshot exists and contains valid json
+      assert File.read!(Path.wildcard("test_snapshots_path/test_repo/posts/*.json"))
+             |> Jason.decode!(keys: :atoms!)
+
+      assert [file] =
+               Path.wildcard("test_migration_path/**/*_migrate_resources*.exs")
+               |> Enum.reject(&String.contains?(&1, "extensions"))
+
+      file_contents = File.read!(file)
+
+      # the migration adds the id using the native uuidv7 function
+      assert file_contents =~
+               ~S[add :id, :uuid, null: false, default: fragment("uuidv7()"), primary_key: true]
+    end
+  end
+
   describe "creating initial snapshots for resources with a schema" do
     setup do
       on_exit(fn ->