189 enhancement/polymorphic on delete option needs refining and potentially moving

.formatter.exs

@@ -44,6 +44,7 @@ spark_locals_without_parens = [
   on_update: 1,
   on_update_message: 1,
   polymorphic?: 1,
+  polymorphic_name: 1,
   polymorphic_on_delete: 1,
   polymorphic_on_update: 1,
   prefix: 1,

documentation/dsls/DSL-AshPostgres.DataLayer.md

@@ -261,6 +261,12 @@ A section for configuring the references (foreign keys) in resource migrations.
 This section is only relevant if you are using the migration generator with this resource.
 Otherwise, it has no effect.
 
+> ### Deprecated polymorphic options {: .warning}
+>
+> `polymorphic_on_delete`, `polymorphic_on_update`, and `polymorphic_name` are
+> deprecated but remain supported. Use the relationship context described in
+> [Polymorphic references](./../topics/resources/polymorphic-resources.md#polymorphic-references) instead.
+
 
 ### Nested DSLs
  * [reference](#postgres-references-reference)
@@ -281,8 +287,9 @@ end
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`polymorphic_on_delete`](#postgres-references-polymorphic_on_delete){: #postgres-references-polymorphic_on_delete } | `:delete \| :nilify \| :nothing \| :restrict \| {:nilify, atom \| list(atom)}` |  | For polymorphic resources, configures the on_delete behavior of the automatically generated foreign keys to source tables. |
-| [`polymorphic_on_update`](#postgres-references-polymorphic_on_update){: #postgres-references-polymorphic_on_update } | `:update \| :nilify \| :nothing \| :restrict` |  | For polymorphic resources, configures the on_update behavior of the automatically generated foreign keys to source tables. |
+| [`polymorphic_on_delete`](#postgres-references-polymorphic_on_delete){: #postgres-references-polymorphic_on_delete } | `:delete \| :nilify \| :nothing \| :restrict \| {:nilify, atom \| list(atom)}` |  | For polymorphic resources, configures the `on_delete` behavior of the automatically generated foreign keys to source tables. This option is deprecated; use `relationship_context: %{data_layer: %{references: %{on_delete: ...}}}` on the relationship instead. |
+| [`polymorphic_on_update`](#postgres-references-polymorphic_on_update){: #postgres-references-polymorphic_on_update } | `:update \| :nilify \| :nothing \| :restrict` |  | For polymorphic resources, configures the `on_update` behavior of the automatically generated foreign keys to source tables. This option is deprecated; use `relationship_context: %{data_layer: %{references: %{on_update: ...}}}` on the relationship instead. |
+| [`polymorphic_name`](#postgres-references-polymorphic_name){: #postgres-references-polymorphic_name } | `String.t` |  | For polymorphic resources, configures the name of the generated foreign-key constraint to the source table. This option is deprecated; use `relationship_context: %{data_layer: %{references: %{name: ...}}}` on the relationship instead. |
 
 
 

documentation/topics/resources/polymorphic-resources.md

@@ -90,3 +90,40 @@ all resources that are related to it, that set the `%{data_layer: %{table: "tabl
 For each of those, a migration is generated/managed automatically. This means that adding reactions
 to a new resource is as easy as adding the relationship and table context, and then running
 `mix ash.codegen`.
+
+## Polymorphic references
+
+For each `has_many` or `has_one` relationship from a source resource to a polymorphic resource that supplies a table context, AshPostgres generates a foreign key that points to the source resource’s table. This foreign key is created in the `table` specified by the relationship’s `data_layer` context.
+
+To configure the foreign key, add a `references` map alongside `table` in the relationship’s `data_layer` context:
+
+```elixir
+relationships do
+  has_many :event_locations, MyApp.EventLocation,
+    relationship_context: %{
+      data_layer: %{
+        table: "event_locations",
+        references: %{
+          on_delete: :delete,
+          on_update: :update,
+          name: "event_locations_event_id_fkey"
+        }
+      }
+    },
+    destination_attribute: :event_id
+end
+```
+
+### Options
+
+The following options go inside `relationship_context.data_layer.references`:
+
+| Name | Type | Default | Docs |
+|------|------|---------|------|
+| `on_delete` | `:delete \| :nilify \| :nothing \| :restrict \| {:nilify, atom \| list(atom)}` | `:nothing` | Configures what happens when a source-table row is deleted. |
+| `on_update` | `:update \| :nilify \| :nothing \| :restrict` | `:nothing` | Configures what happens when the referenced column in the source table is updated. |
+| `name` | `String.t` | generated | Sets the name of the generated foreign-key constraint. |
+
+The legacy `polymorphic_on_delete`, `polymorphic_on_update`, and `polymorphic_name` options are deprecated but remain supported for backwards compatibility. New configurations should use `relationship_context.data_layer.references`. See the [DSL reference](../../dsls/DSL-AshPostgres.DataLayer.md#postgres-references) for the legacy options.
+
+Remove the corresponding legacy option when moving a setting into the relationship context. Configuring both forms for the same setting raises an error, even when their values match.

lib/data_layer.ex

@@ -193,7 +193,7 @@ defmodule AshPostgres.DataLayer do
       polymorphic_name: [
         type: :string,
         doc:
-          "For polymorphic resources, then index name to use for the foreign key to the source table."
+          "For polymorphic resources, configures the name of the foreign-key constraint to the source table."
       ]
     ]
   }
@@ -238,11 +238,25 @@ defmodule AshPostgres.DataLayer do
 
   @references %Spark.Dsl.Section{
     name: :references,
+    deprecations: [
+      polymorphic_on_delete:
+        "Use `relationship_context: %{data_layer: %{references: %{on_delete: ...}}}` on the relationship instead.",
+      polymorphic_on_update:
+        "Use `relationship_context: %{data_layer: %{references: %{on_update: ...}}}` on the relationship instead.",
+      polymorphic_name:
+        "Use `relationship_context: %{data_layer: %{references: %{name: ...}}}` on the relationship instead."
+    ],
     describe: """
     A section for configuring the references (foreign keys) in resource migrations.
 
     This section is only relevant if you are using the migration generator with this resource.
     Otherwise, it has no effect.
+
+    > ### Deprecated polymorphic options {: .warning}
+    >
+    > `polymorphic_on_delete`, `polymorphic_on_update`, and `polymorphic_name` are
+    > deprecated but remain supported. Use the relationship context described in
+    > [Polymorphic references](./../topics/resources/polymorphic-resources.md#polymorphic-references) instead.
     """,
     examples: [
       """
@@ -261,12 +275,17 @@ defmodule AshPostgres.DataLayer do
              {:tagged_tuple, :nilify, {:wrap_list, :atom}}
            ]},
         doc:
-          "For polymorphic resources, configures the on_delete behavior of the automatically generated foreign keys to source tables."
+          "For polymorphic resources, configures the `on_delete` behavior of the automatically generated foreign keys to source tables. This option is deprecated; use `relationship_context: %{data_layer: %{references: %{on_delete: ...}}}` on the relationship instead."
       ],
       polymorphic_on_update: [
         type: {:one_of, [:update, :nilify, :nothing, :restrict]},
         doc:
-          "For polymorphic resources, configures the on_update behavior of the automatically generated foreign keys to source tables."
+          "For polymorphic resources, configures the `on_update` behavior of the automatically generated foreign keys to source tables. This option is deprecated; use `relationship_context: %{data_layer: %{references: %{on_update: ...}}}` on the relationship instead."
+      ],
+      polymorphic_name: [
+        type: :string,
+        doc:
+          "For polymorphic resources, configures the name of the generated foreign-key constraint to the source table. This option is deprecated; use `relationship_context: %{data_layer: %{references: %{name: ...}}}` on the relationship instead."
       ]
     ]
   }

lib/migration_generator/migration_generator.ex

@@ -3837,12 +3837,10 @@ defmodule AshPostgres.MigrationGenerator do
                 multitenancy: multitenancy(relationship.source),
                 table: AshPostgres.DataLayer.Info.table(relationship.source),
                 schema: AshPostgres.DataLayer.Info.schema(relationship.source),
-                on_delete: AshPostgres.DataLayer.Info.polymorphic_on_delete(relationship.source),
-                on_update: AshPostgres.DataLayer.Info.polymorphic_on_update(relationship.source),
+                on_delete: polymorphic_on_delete(relationship),
+                on_update: polymorphic_on_update(relationship),
                 primary_key?: source_attribute.primary_key?,
-                name:
-                  AshPostgres.DataLayer.Info.polymorphic_name(relationship.source) ||
-                    "#{relationship.context[:data_layer][:table]}_#{destination_attribute_source}_fkey"
+                name: polymorphic_name(relationship, destination_attribute_source)
               })
             else
               attribute
@@ -3855,6 +3853,45 @@ defmodule AshPostgres.MigrationGenerator do
     end
   end
 
+  defp polymorphic_on_delete(relationship) do
+    relationship_context_on_delete =
+      get_in(relationship.context, [:data_layer, :references, :on_delete])
+
+    legacy_on_delete = AshPostgres.DataLayer.Info.polymorphic_on_delete(relationship.source)
+
+    if relationship_context_on_delete && legacy_on_delete do
+      raise "Conflicting configurations for references: both relationship_context references on_delete and polymorphic_on_delete are configured"
+    end
+
+    relationship_context_on_delete || legacy_on_delete
+  end
+
+  defp polymorphic_on_update(relationship) do
+    relationship_context_on_update =
+      get_in(relationship.context, [:data_layer, :references, :on_update])
+
+    legacy_on_update = AshPostgres.DataLayer.Info.polymorphic_on_update(relationship.source)
+
+    if relationship_context_on_update && legacy_on_update do
+      raise "Conflicting configurations for references: both relationship_context references on_update and polymorphic_on_update are configured"
+    end
+
+    relationship_context_on_update || legacy_on_update
+  end
+
+  defp polymorphic_name(relationship, destination_attribute_source) do
+    relationship_context_name = get_in(relationship.context, [:data_layer, :references, :name])
+
+    legacy_name = AshPostgres.DataLayer.Info.polymorphic_name(relationship.source)
+
+    if relationship_context_name && legacy_name do
+      raise "Conflicting configurations for references: both relationship_context references name and polymorphic_name are configured"
+    end
+
+    relationship_context_name || legacy_name ||
+      "#{relationship.context[:data_layer][:table]}_#{destination_attribute_source}_fkey"
+  end
+
   defp do_snapshot(resource, table, schema \\ nil) do
     %{
       attributes: attributes(resource, table),