activeadmin-graphql 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5fc45489403fdf5c4d16bd66966cc4c7c5641440663d3f5b229b0d627a0d0978
-  data.tar.gz: '04786131baffbec749af13c347660836c1ca31efa074c73eddfc49c5fbfb588e'
+  metadata.gz: 95e56a00a0c78ea55f44c186012af72c1ba6ff80ada2adbf905ce9b2d190c47d
+  data.tar.gz: 1e1dc89e1ffd41d05c6f2962a83857188a239ba677e6f492dbc304a09bb123b9
 SHA512:
-  metadata.gz: 1c93c24f91a208c8eb00076d1fd3d8b398c99d155a8ce92f4aaa075b6615ea321a3303b2186e85fa32178a4e8ad158fb4ab1f081752993c6a44e5466fad1ac83
-  data.tar.gz: f5c1acc62e5f1aa0cd925234c4df76d9870dd592cb97aeae7927df578340d70936e02bcf727635a8f07d7caacfb84316e037383c7666b35cb472d11b8776240e
+  metadata.gz: 02533503de4c86355e28bc7212115b043a9d7da293db40d1134251f7892539fca8257d6c03140c110d12da8e4de1b4112668c7e6fc2d721273c990d9fff930e3
+  data.tar.gz: 6e13f9a69b6cc7df900cf9883ab60600be21bfea50196209c7324306030d74784cb3e66082ffc3ec225192c3c0c385fffb3f24840061e9f12415b60479de9d3c

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.3.2 (2026-10-10)
+
+- Add `graphql { identity ... }` so keyless views can declare GraphQL id columns, optional `separator`, and `encode` / `decode` (RFC 0007).
+- Fail schema build when a registered model has neither a primary key nor an `id` column and no `identity` declaration; set `self.primary_key`, use `identity`, or `graphql { disable! }`.
+
 ## 0.3.1 (2026-10-10)
 
 - Fix GraphQL identity handling for database views and nonconventional primary keys: keep one `id` field, support inferred `id` lookups, reject ambiguous identifiers, and honor attribute filters.

data/docs/changelogs/20261010101500_nonconventional-id-fields.md

@@ -11,7 +11,10 @@ primary key is blank. Object types skip emitting a column field named `id`
 (interface owns GraphQL `id`) and expose a single non-`id` primary-key column
 as a readable scalar unless the resource's attribute configuration omits it.
 Models with neither a primary key nor an `id` column fail schema build with an
-`ArgumentError` that asks for `self.primary_key`. Inferred `id` values must be
+`ArgumentError` that asks for `self.primary_key`. On 0.3.0 those models could
+still enter the schema with a broken GraphQL `id`. Apps that keep such a
+resource registered must set `self.primary_key` or use `graphql { disable! }`
+so the rest of the namespace schema still builds. Inferred `id` values must be
 unique and non-null; ambiguous member and batched lookups fail closed.
 
 Member lookup uses the inferred column while preserving an explicitly
@@ -21,9 +24,19 @@ entries for distinct records when ActiveRecord has no declared primary key.
 Dummy coverage includes SQLite views that project `code AS id` and
 `id AS row_key`, plus a table with an `id` column and no primary key.
 
+## Later pass 2026-10-10
+
+Downstream check: a database view with neither primary key nor `id` column
+could stay GraphQL-disabled via `graphql { disable! }`. Spec covers that
+escape hatch next to the ArgumentError path.
+
+Later the same day: RFC 0007 adds `graphql { identity ... }` so those views
+can stay enabled when columns (and optional separator) are declared. See
+docs/changelogs/20261010110600_graphql-identity-dsl.md.
+
 ## Next
 
-Folded into 0.3.1 release metadata. Tag and gem push wait on make release.
+Core fix shipped in 0.3.1. Identity DSL follow-on is 0.3.2.
 
 ## Source
 
@@ -32,3 +45,4 @@ Folded into 0.3.1 release metadata. Tag and gem push wait on make release.
   `spec/unit/resource_query_proxy_identity_spec.rb`,
   `spec/unit/policy_set_cache_spec.rb`
 - Views: `spec/dummy/db/schema.rb` (`string_id_records`, `alternate_key_records`)
+- Follow-on: docs/changelogs/20261010110600_graphql-identity-dsl.md

data/docs/changelogs/20261010103800_release-0-3-1.md

@@ -6,7 +6,11 @@ Andrei Makarov
 
 ## Decisions
 
-Cut 0.3.1 after published 0.3.0. One user-visible fix: GraphQL identity for database views and nonconventional primary keys.
+Cut 0.3.1 after published 0.3.0. User-visible work: GraphQL identity for
+database views and nonconventional primary keys; fail-closed when a model has
+neither a primary key nor an `id` column without configuration; and
+`graphql { identity ... }` (RFC 0007) for keyless views with a virtual
+composite id.
 
 CHANGELOG 0.3.1 dated 2026-10-10. Version constant is 0.3.1. Path gem pins in Gemfile.lock and appraisal lockfiles match.
 
@@ -24,9 +28,12 @@ PATH specs for activeadmin-graphql in Gemfile.lock, gemfiles/rails72.gemfile.loc
 
 ## Next
 
-Run make release from a clean tree when ready to push the gem and tag 0.3.1.
+0.3.1 tagged and published on RubyGems. Post-tag identity DSL work ships in
+0.3.2; see docs/changelogs/20261010111800_release-0-3-2.md.
 
 ## Source
 
 docs/changelogs/20261010101500_nonconventional-id-fields.md
+docs/changelogs/20261010110600_graphql-identity-dsl.md
+rfcs/0007-graphql-identity.md
 usr/bin/release.rb

data/docs/changelogs/20261010110600_graphql-identity-dsl.md

@@ -0,0 +1,34 @@
+# GraphQL identity DSL (RFC 0007)
+
+## Decisions
+
+Ship `graphql { identity *columns, separator:, encode:, decode: }` so resources
+without an ActiveRecord primary key and without an `id` column can stay in the
+schema. Prefer resource configuration over forcing `self.primary_key`.
+
+Separator form matches HTML admins that use a virtual `id` method such as
+`[entry_type, entry_id, event_type].join(":")`. Without separator, multi-column
+identity keeps the existing composite JSON string.
+
+## Effects
+
+Schema build, member lookup, mutations that resolve by where/id, and policy
+cache keys go through `ActiveAdmin::GraphQL::ResourceIdentity` when identity is
+configured. Ambiguous matches still fail closed.
+
+Dummy coverage: view `alert_events` / model `AlertEvent` with virtual composite
+`id`.
+
+## Next
+
+Folded into 0.3.2 release metadata (0.3.1 already published without this DSL).
+Tag and gem push wait on make release.
+
+## Source
+
+rfcs/0007-graphql-identity.md
+docs/changelogs/20261010101500_nonconventional-id-fields.md
+docs/issues/20261010111159_rails-composite-primary-keys-alignment.md
+https://guides.rubyonrails.org/active_record_composite_primary_keys.html
+spec/unit/resource_identity_spec.rb
+spec/requests/graphql_identity_dsl_spec.rb

data/docs/changelogs/20261010111800_release-0-3-2.md

@@ -0,0 +1,46 @@
+# Release 0.3.2 metadata
+
+## Participants
+
+Andrei Makarov
+
+## Decisions
+
+Cut 0.3.2 after published 0.3.1. User-visible work since the 0.3.1 tag:
+`graphql { identity ... }` (RFC 0007) for keyless views, and schema-build
+error text that names `identity` alongside `self.primary_key` and `disable!`.
+
+CHANGELOG 0.3.1 restored to the published one-bullet text. Identity DSL bullets
+live under 0.3.2 dated 2026-10-10.
+
+Version constant is 0.3.2. Path gem pins in Gemfile.lock and appraisal
+lockfiles match.
+
+Docs-only notes (Rails composite PK alignment, partitions/shards unsupported,
+federation unsupported) stay out of CHANGELOG.md.
+
+make release (usr/bin/release.rb) still owns gem build, gem push, git tag, and
+GitHub release. This pass only prepares metadata.
+
+## Effects
+
+lib/active_admin/graphql/version.rb VERSION is 0.3.2.
+
+CHANGELOG identity DSL bullets moved from the post-tag 0.3.1 draft under 0.3.2.
+
+PATH specs for activeadmin-graphql in Gemfile.lock,
+gemfiles/rails72.gemfile.lock, gemfiles/rails8ruby4.gemfile.lock, and
+gemfiles/rails8ruby34.gemfile.lock are 0.3.2.
+
+## Next
+
+Run make release from a clean tree when ready to push the gem and tag 0.3.2.
+
+## Source
+
+docs/changelogs/20261010110600_graphql-identity-dsl.md
+rfcs/0007-graphql-identity.md
+docs/issues/20261010111159_rails-composite-primary-keys-alignment.md
+docs/issues/20261010111300_partitions-and-shards-support.md
+docs/issues/20261010111500_graphql-federation-support.md
+usr/bin/release.rb

data/docs/graphql-api.md

@@ -229,12 +229,28 @@ GraphQL `id` always comes from `ActiveAdminResource` (`ID!`). An ActiveRecord
 `id` column is never added as a second field. When `self.primary_key` is blank
 but the model still has an `id` column (common for database views that project
 `… AS id`), that column supplies the GraphQL `id` value. When the model has
-neither a primary key nor an `id` column, schema build raises until you set
-`self.primary_key` on the model (for example a view keyed by `row_key`). A
-single-column primary key named something other than `id` is also exposed as
-its own readable field beside `id`, unless `only` or `exclude` omits it. An
-inferred `id` column must contain a unique, non-null value for every row;
-ambiguous member and batched lookups fail instead of selecting one row.
+neither a primary key nor an `id` column, declare GraphQL identity on the
+resource (RFC 0007), set `self.primary_key` on the model, or omit the resource
+with `graphql { disable! }`. A single-column primary key named something other
+than `id` is also exposed as its own readable field beside `id`, unless `only`
+or `exclude` omits it. An inferred `id` column must contain a unique, non-null
+value for every row; ambiguous member and batched lookups fail instead of
+selecting one row.
+
+```ruby
+# View with no PK and no id column; virtual identity matches HTML admin.
+ActiveAdmin.register AlertEvent do
+  graphql do
+    identity :entry_type, :entry_id, :event_type, separator: ":"
+    # optional: encode: ->(record) { record.id }, decode: ->(id) { ... }
+  end
+end
+```
+
+With `separator: ":"`, GraphQL `id` is `entry_type:entry_id:event_type`. Keep
+the model’s `def id` (if any) in the same shape so HTML and GraphQL share
+member ids. Without `separator`, multi-column identity uses the same JSON
+object string as composite ActiveRecord primary keys.
 
 ### Composite primary keys (Rails 7.1+)
 
@@ -242,8 +258,10 @@ For models with `self.primary_key = [:book_code, :seq]` (and no separate `id`
 column), Active Admin treats GraphQL as follows:
 
 * `id` on the object type — JSON object string with all key columns in
-  model order (same format Rails uses when casting composite ids), for example
-  `{"book_code":"CPK","seq":7}`.
+  model order, for example `{"book_code":"CPK","seq":7}`. This is the GraphQL
+  wire format. It is not the Rails form/URL underscore packing described in
+  the Composite Primary Keys guide (`/books/2_25` with
+  `params.extract_value(:id)`).
 * Readable fields — each primary-key column is also exposed as its own field
   (in addition to `id`) so clients can load scalars without parsing JSON.
 * `LibraryEditionWhereInput` (and similar) — either optional `id` (that JSON
@@ -255,12 +273,20 @@ column), Active Admin treats GraphQL as follows:
   inputs (unlike single `id` tables, where the key is omitted from assignable
   attributes).
 
-For REST/HTML member routes, `ResourceController#find_resource` must resolve composite ids from `params[:id]` (JSON string) or from individual primary-key params. Stock ActiveAdmin 3.x only passes a single `params[:id]` into `find`; an ActiveAdmin fork (or patch) that implements composite-aware `find_resource` keeps the admin UI aligned with GraphQL. The GraphQL layer also works with `ActiveAdmin::GraphQL::ResourceQueryProxy` using Rails’ tuple id convention for `Relation#find`.
+For REST/HTML member routes, `ResourceController#find_resource` must resolve
+composite ids from `params[:id]` or from individual primary-key params. Stock
+ActiveAdmin 3.x only passes a single `params[:id]` into `find`; an ActiveAdmin
+fork (or patch) that implements composite-aware `find_resource` keeps the
+admin UI aligned with GraphQL. After decoding the GraphQL JSON `id`, the gem
+uses Rails’ array/tuple conventions for `Relation#find` and
+`where(primary_key => [tuple, …])` as in the guide.
 
-The gem ships `ActiveAdmin::PrimaryKey` when the core constant is missing (upstream). A fork may define `PrimaryKey` and extended `find_resource` in `ResourceController` instead.
+The gem ships `ActiveAdmin::PrimaryKey` when the core constant is missing
+(upstream). A fork may define `PrimaryKey` and extended `find_resource` in
+`ResourceController` instead.
 
-`ActiveAdmin::GraphQL::RecordSource` batch-loads composite associations using
-Rails `where(primary_key => [tuple, …])`.
+Alignment notes versus the Rails guide:
+`docs/issues/20261010111159_rails-composite-primary-keys-alignment.md`.
 
 ### Collection query arguments
 
@@ -359,6 +385,7 @@ Inside `ActiveAdmin.register` you can narrow the GraphQL surface:
 ActiveAdmin.register Post do
   graphql do
     disable!                          # omit this resource from the schema
+    # identity :entry_type, :entry_id, :event_type, separator: ":"  # RFC 0007
     type_name "BlogPost"              # GraphQL object / mutation type basename (`graphql_name` alias)
     only :title, :body, :published_at # expose only these attributes on queries
     exclude :internal_score           # or `except` / `exclude`
@@ -379,6 +406,9 @@ end
 ```
 
 * `disable!` — resource is not included in Query or Mutation.
+* `identity` — declare GraphQL id columns (and optional `separator`, `encode`,
+  `decode`) when the model has no ActiveRecord primary key and no `id` column
+  (RFC 0007).
 * `type_name` (or `graphql_name`) — overrides the default GraphQL type name
   derived from the model (object types, mutations, and Rails enum GraphQL
   types use this basename).

data/docs/issues/20261010111159_rails-composite-primary-keys-alignment.md

@@ -0,0 +1,81 @@
+# Rails composite primary keys alignment
+
+## Participants
+
+Andrei Makarov
+
+## Decisions
+
+Treat ActiveRecord composite primary keys and GraphQL `identity` as related but
+not identical contracts. Keep GraphQL `id` as a single `ID!` string. Do not
+adopt Rails form URL underscore packing as the default GraphQL id encoding.
+
+Record alignment against the Rails guide Composite Primary Keys
+(https://guides.rubyonrails.org/active_record_composite_primary_keys.html)
+after shipping inferred id columns and RFC 0007 identity DSL.
+
+## Effects
+
+Compared gem behavior to the guide’s model, query, form, and parameter rules.
+
+ActiveRecord composite primary key (self.primary_key = array):
+
+- Aligns: model declares composite key the same way as the guide’s
+  `self.primary_key = [:store_id, :sku]` style. Dummy `LibraryEdition` uses
+  `[:book_code, :seq]`.
+- Aligns: internal batch and find paths convert that string id into an ordered
+  value list and use Rails tuple/`Relation#find` style lookups
+  (`ActiveAdmin::PrimaryKey.dataloader_tuple`, `ResourceQueryProxy` composite
+  branch). That matches the guide’s `Product.find([3, "XYZ12345"])` and
+  `where(primary_key => [[...], [...]])` idea at the Ruby API layer.
+- Diverges: GraphQL and the published docs encode composite `id` as a JSON
+  object string (`{"book_code":"CPK","seq":7}`), not as the guide’s form/URL
+  underscore packing (`/books/2_25` with `params.extract_value(:id)`). JSON
+  keeps column names explicit and avoids ambiguity when a key value contains
+  `_`. Underscore packing is not accepted as GraphQL `id` today.
+- Diverges: GraphQL also accepts per-key arguments and `WhereInput` fields for
+  composite models. The guide’s controller example extracts one `:id` param
+  into an array; we keep named keys as a GraphQL-friendly alternate.
+- Aligns with guide caution: `where(id: ...)` / `find_by(id:)` on composite
+  models can mean an `:id` attribute, not the full primary key. The gem’s
+  GraphQL `id` field is the ActiveAdminResource identity string, not
+  necessarily an ActiveRecord `:id` column. Member lookup uses primary-key
+  columns (or configured identity), not a bare `where(id: graphql_id)` on
+  composite models.
+
+Keyless views and RFC 0007 `graphql { identity ... }`:
+
+- Outside the guide’s scope. The guide assumes a declared composite primary
+  key on the table/model. AlertEvent-style views with `primary_key = nil` and
+  a virtual Ruby `id` are not Rails composite primary keys.
+- `identity :a, :b, :c, separator: ":"` is an application-level encoding so
+  GraphQL can share the same string as a hand-rolled `def id; [...].join(":")`.
+  That separator form is closer in spirit to Rails’ delimited URL id than our
+  JSON composite encoding, but the delimiter and segment rules are app-chosen,
+  not `extract_value`’s underscore default.
+- Without `separator`, configured multi-column identity reuses the gem’s JSON
+  object string so keyless and AR-composite GraphQL ids stay one family.
+
+Stock ActiveAdmin HTML member routes still need a composite-aware
+`find_resource` (or custom finder) for AR composite keys; GraphQL does not
+make Rails form URLs use JSON.
+
+## Next
+
+Leave GraphQL composite `id` as JSON for AR composite primary keys unless a
+later RFC deliberately adds underscore (or `extract_value`-compatible) accept
+and emit. Document that choice next to the Rails guide, not as “the same
+format Rails uses for casting composite ids” without qualification.
+
+No change required for RFC 0007 separator identity; it is the escape hatch
+when the model is not a Rails composite primary key.
+
+## Source
+
+https://guides.rubyonrails.org/active_record_composite_primary_keys.html
+docs/graphql-api.md (Nonconventional primary keys, Composite primary keys)
+rfcs/0007-graphql-identity.md
+lib/active_admin/primary_key.rb
+lib/active_admin/graphql/resource_identity.rb
+spec/dummy/app/models/library_edition.rb
+spec/dummy/app/models/alert_event.rb

data/docs/issues/20261010111300_partitions-and-shards-support.md

@@ -0,0 +1,55 @@
+# Table partitions and database shards support
+
+## Participants
+
+Andrei Makarov
+
+## Decisions
+
+activeadmin-graphql does not treat database table partitions or Rails
+database shards as a GraphQL configuration surface. Identity DSL (RFC 0007)
+and ActiveRecord composite primary keys only encode lookup columns into
+GraphQL `id`. They do not select a shard, connection role, or physical
+partition.
+
+App-level Rails multi-database setup (`connects_to`, `connected_to`,
+horizontal shards, tenant middleware) may still apply implicitly: GraphQL
+resolvers reuse ActiveAdmin `scoped_collection` / `find_resource` on whatever
+connection the request process already has. That inheritance is undocumented
+as a product feature and untested in this gem.
+
+## Effects
+
+Searched lib, docs, rfcs, and spec for partition, shard, connects_to,
+multiple database, tenant routing, writing_role, and reading_role.
+
+Product code has no shard or partition API. Hits for “shard” and “partition”
+are Polyrun/CI test parallelism and agent IO-fault vocabulary, not databases.
+
+Dummy app uses one SQLite database (`spec/dummy/config/database.yml`). No
+multi-DB, no partitioned table fixtures, no `connected_to` specs.
+
+`RecordSource`, `PrimaryKey`, and `ResourceIdentity` run `where` / encode on
+the current model class only. A partition-key column can appear in
+`graphql { identity ... }` as part of the id string; that still queries the
+already-selected connection and does not prune or route partitions.
+
+## Next
+
+If a host needs GraphQL across shards or partitioned tables, keep routing in
+the Rails/ActiveAdmin request boundary (middleware, `connected_to`, custom
+finder). Do not invent gem DSL until a concrete host failure and RFC name the
+contract (shard key in GraphQL args, role switching, cross-shard batch limits).
+
+Optional later: document “unsupported / inherited only” next to identity in
+`docs/graphql-api.md` when a reader asks again.
+
+## Source
+
+lib/active_admin/graphql/resource_identity.rb
+lib/active_admin/graphql/record_source.rb
+lib/active_admin/graphql/resource_query_proxy.rb
+spec/dummy/config/database.yml
+rfcs/0007-graphql-identity.md
+docs/issues/20261010111159_rails-composite-primary-keys-alignment.md
+polyrun.yml (test shards only)

data/docs/issues/20261010111500_graphql-federation-support.md

@@ -0,0 +1,46 @@
+# GraphQL Federation support
+
+## Participants
+
+Andrei Makarov
+
+## Decisions
+
+activeadmin-graphql does not implement GraphQL Federation (Apollo Federation
+v1/v2, subgraph/supergraph, `@key` entities, `_entities` / `_service`). The
+product is one graphql-ruby schema per ActiveAdmin namespace for that admin
+HTTP endpoint.
+
+RFC 0007 `graphql { identity ... }` and `ActiveAdminResource.id` are record
+lookup identity inside that schema. They are not federation entity keys and
+do not emit federation SDL directives.
+
+## Effects
+
+Searched lib, docs, rfcs, spec, and the gemspec for federation, subgraph,
+supergraph, Apollo, `@key`, shareable, apollo-federation, `_entities`, and
+`_service`. No product hits.
+
+Runtime dependencies are `activeadmin` and `graphql` only. Schema build is
+`Class.new(::GraphQL::Schema)` with query, mutation, dataloader, and optional
+visibility (`lib/active_admin/graphql/schema_builder/build.rb`).
+`ResourceInterface` is a local interface for fragment reuse, not a federation
+entity type.
+
+An app could in principle call `graphql_configure_schema` on the built schema
+and layer a federation library itself. That path is neither documented nor
+tested here.
+
+## Next
+
+Keep federation out of scope until a host names a concrete subgraph contract
+and an RFC. Prefer documenting “single-schema admin API; federation
+unsupported” if readers keep asking.
+
+## Source
+
+activeadmin-graphql.gemspec
+lib/active_admin/graphql/schema_builder/build.rb
+lib/active_admin/graphql/resource_interface.rb
+rfcs/0007-graphql-identity.md
+docs/issues/20261010111300_partitions-and-shards-support.md

data/lib/active_admin/graphql/policy_set_cache.rb

@@ -34,7 +34,7 @@ module ActiveAdmin
 
         def cache_key(subject_owner, subject)
           owner_key = subject_owner_key(subject_owner)
-          "#{owner_key}:#{subject_key(subject)}"
+          "#{owner_key}:#{subject_key(subject_owner, subject)}"
         end
 
         private
@@ -47,13 +47,18 @@ module ActiveAdmin
           end
         end
 
-        def subject_key(subject)
+        def subject_key(subject_owner, subject)
           if subject.is_a?(Class)
             "class:#{subject.name}"
           elsif subject.is_a?(ActiveAdmin::Page)
             "page:#{subject.name}"
           elsif subject.is_a?(ActiveRecord::Base)
-            identity = PrimaryKey.graphql_id_value(subject)
+            identity =
+              if subject_owner.respond_to?(:graphql_config)
+                ResourceIdentity.graphql_id_value(subject_owner, subject)
+              else
+                PrimaryKey.graphql_id_value(subject)
+              end
             identity = "#{identity}:object:#{subject.object_id}" if subject.class.primary_key.blank?
             "record:#{subject.class.name}:#{identity}"
           else

data/lib/active_admin/graphql/resource_config.rb

@@ -14,6 +14,10 @@ module ActiveAdmin
       attr_accessor :permit_params_attributes
       attr_accessor :html_permit_params_attributes
       attr_accessor :extension_block
+      attr_accessor :identity_columns
+      attr_accessor :identity_separator
+      attr_accessor :identity_encode_proc
+      attr_accessor :identity_decode_proc
 
       # Optional resolver overrides (set from +graphql do+). SchemaBuilder still owns field names,
       # arguments, and types; procs replace only the Ruby resolution body.

data/lib/active_admin/graphql/resource_definition_dsl.rb

@@ -16,6 +16,15 @@ module ActiveAdmin
         @config.enabled = false
       end
 
+      # Declare GraphQL identity columns when ActiveRecord has no primary key / id column.
+      # See RFC 0007.
+      def identity(*columns, separator: nil, encode: nil, decode: nil)
+        @config.identity_columns = columns.flatten.map(&:to_s)
+        @config.identity_separator = separator
+        @config.identity_encode_proc = encode
+        @config.identity_decode_proc = decode
+      end
+
       def type_name(name)
         @config.graphql_type_name = name.to_s
       end

data/lib/active_admin/graphql/resource_identity.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ActiveAdmin
+  module GraphQL
+    # Resolves GraphQL identity columns and id encode/decode for a registered resource.
+    # Prefer `graphql { identity ... }` when ActiveRecord has no primary key / id column.
+    module ResourceIdentity
+      module_function
+
+      def configured?(aa_res)
+        aa_res.graphql_config.identity_columns.present?
+      end
+
+      def columns(aa_res)
+        configured = aa_res.graphql_config.identity_columns
+        return configured if configured.present?
+
+        ActiveAdmin::PrimaryKey.columns(aa_res.resource_class)
+      end
+
+      def graphql_id_value(aa_res, record)
+        cfg = aa_res.graphql_config
+        if (encode = cfg.identity_encode_proc)
+          return encode.call(record).to_s
+        end
+
+        cols = columns(aa_res)
+        return ActiveAdmin::PrimaryKey.graphql_id_value(record) unless configured?(aa_res)
+
+        encode_columns(record, cols, cfg.identity_separator)
+      end
+
+      def attributes_for_id(aa_res, id)
+        cfg = aa_res.graphql_config
+        if (decode = cfg.identity_decode_proc)
+          return stringify_attrs(decode.call(id))
+        end
+
+        cols = columns(aa_res)
+        return ActiveAdmin::PrimaryKey.find_attributes(aa_res.resource_class, id) unless configured?(aa_res)
+
+        decode_columns(cols, id, cfg.identity_separator)
+      end
+
+      def encode_columns(record, cols, separator)
+        if cols.size == 1
+          record.public_send(cols.first).to_s
+        elsif separator
+          cols.map { |c| record.public_send(c) }.join(separator)
+        else
+          payload = cols.each_with_object({}) { |c, memo| memo[c] = record.read_attribute(c) }
+          JSON.generate(payload)
+        end
+      end
+
+      def decode_columns(cols, id, separator)
+        if cols.size == 1
+          {cols.first => id.to_s}
+        elsif separator
+          parts = id.to_s.split(separator, cols.size)
+          raise ArgumentError, "identity id segment count mismatch" if parts.size != cols.size
+
+          cols.zip(parts).to_h
+        else
+          parsed = JSON.parse(id.to_s)
+          raise ArgumentError, "composite id must be a JSON object" unless parsed.is_a?(Hash)
+
+          parsed.stringify_keys.slice(*cols)
+        end
+      end
+
+      def field_kw_to_param_hash(aa_res, id:, **kw)
+        return ActiveAdmin::PrimaryKey.field_kw_to_param_hash(aa_res.resource_class, id: id, **kw) unless configured?(aa_res)
+
+        raise ArgumentError, "id is required" if id.blank?
+
+        {"id" => id.to_s}
+      end
+
+      def member_param_hash(aa_res, blob)
+        return ActiveAdmin::PrimaryKey.member_param_hash(aa_res.resource_class, blob) unless configured?(aa_res)
+
+        blob = blob.stringify_keys
+        raise ArgumentError, "id is required" if blob["id"].blank?
+
+        {"id" => blob["id"].to_s}
+      end
+
+      def stringify_attrs(hash)
+        raise ArgumentError, "identity decode must return a Hash" unless hash.is_a?(Hash)
+
+        hash.stringify_keys.transform_values { |value| value&.to_s }
+      end
+    end
+  end
+end

data/lib/active_admin/graphql/resource_methods.rb

@@ -22,7 +22,7 @@ module ActiveAdmin
 
         def graphql_assignable_attribute_names
           names = attributes_for_graphql.map(&:to_s)
-          pk_cols = ActiveAdmin::PrimaryKey.columns(resource_class)
+          pk_cols = ActiveAdmin::GraphQL::ResourceIdentity.columns(self)
           return names if pk_cols.size > 1
 
           names - pk_cols

data/lib/active_admin/graphql/resource_query_proxy/identity.rb

@@ -6,11 +6,11 @@ module ActiveAdmin
       module Identity
         private
 
-        def find_inferred_member(controller, model, id)
-          primary_key = ActiveAdmin::PrimaryKey.columns(model).first
-          raise ActiveRecord::RecordNotFound unless primary_key
+        def find_identity_member(controller, model, id)
+          attrs = ActiveAdmin::GraphQL::ResourceIdentity.attributes_for_id(@aa_resource, id)
+          raise ActiveRecord::RecordNotFound if attrs.blank?
 
-          records = controller.send(:scoped_collection).where(primary_key => id).limit(2).to_a
+          records = controller.send(:scoped_collection).where(attrs).limit(2).to_a
           raise_ambiguous_id!(model) if records.size > 1
 
           records.first || raise(ActiveRecord::RecordNotFound)

data/lib/active_admin/graphql/resource_query_proxy.rb

@@ -31,8 +31,8 @@ module ActiveAdmin
         finder = controller.send(:method_for_find)
         return controller.send(:find_resource) if model.primary_key.present? || finder != :find
 
-        find_inferred_member(controller, model, extra.fetch("id"))
-      rescue ActiveRecord::RecordNotFound
+        find_identity_member(controller, model, extra.fetch("id"))
+      rescue ActiveRecord::RecordNotFound, ArgumentError
         nil
       end
 
@@ -41,13 +41,14 @@ module ActiveAdmin
         return {} if string_ids.empty?
 
         model = @aa_resource.resource_class
-        if ActiveAdmin::PrimaryKey.composite?(model)
+        identity_cols = ActiveAdmin::GraphQL::ResourceIdentity.columns(@aa_resource)
+        if ActiveAdmin::PrimaryKey.composite?(model) || identity_cols.size > 1
           return string_ids.index_with { |identifier| find_member(identifier) }
         end
 
         controller = controller_for("index")
         relation = controller.send(:apply_authorization_scope, controller.send(:scoped_collection))
-        primary_key = ActiveAdmin::PrimaryKey.columns(model).first&.to_sym
+        primary_key = identity_cols.first&.to_sym
         return string_ids.index_with { nil } if primary_key.nil?
 
         indexed = index_records_by_id(relation.where(primary_key => string_ids), model, primary_key)

data/lib/active_admin/graphql/schema_builder/mutation_update_destroy.rb

@@ -24,7 +24,7 @@ module ActiveAdmin
               blob = where.to_h.stringify_keys
               graph = sb.graph_params_from_find_blob(aa_res, blob)
               begin
-                rid = ActiveAdmin::PrimaryKey.member_param_hash(model, blob)
+                rid = ActiveAdmin::GraphQL::ResourceIdentity.member_param_hash(aa_res, blob)
               rescue ArgumentError => e
                 raise ::GraphQL::ExecutionError, e.message
               end
@@ -90,7 +90,7 @@ module ActiveAdmin
               blob = where.to_h.stringify_keys
               graph = sb.graph_params_from_find_blob(aa_res, blob)
               begin
-                rid = ActiveAdmin::PrimaryKey.member_param_hash(model, blob)
+                rid = ActiveAdmin::GraphQL::ResourceIdentity.member_param_hash(aa_res, blob)
               rescue ArgumentError => e
                 raise ::GraphQL::ExecutionError, e.message
               end

data/lib/active_admin/graphql/schema_builder/query_type_member.rb

@@ -51,10 +51,12 @@ module ActiveAdmin
                 if where
                   blob = where.to_h.stringify_keys
                   graph = builder.graph_params_from_find_blob(aa_res, blob)
-                  rid = ActiveAdmin::PrimaryKey.member_param_hash(model, blob)
+                  rid = ActiveAdmin::GraphQL::ResourceIdentity.member_param_hash(aa_res, blob)
                 else
                   graph = builder.graph_params_for_mutation(aa_res, kw)
-                  rid = ActiveAdmin::PrimaryKey.field_kw_to_param_hash(model, id: id, **kw)
+                  rid = ActiveAdmin::GraphQL::ResourceIdentity.field_kw_to_param_hash(
+                    aa_res, id: id, **kw
+                  )
                 end
               rescue ArgumentError => e
                 raise ::GraphQL::ExecutionError, e.message

data/lib/active_admin/graphql/schema_builder/types_object.rb

@@ -82,14 +82,20 @@ module ActiveAdmin
             define_singleton_method(:activeadmin_graphql_resource) { aa_res }
           end
 
-          pk_cols = ActiveAdmin::PrimaryKey.columns(model)
+          pk_cols = ActiveAdmin::GraphQL::ResourceIdentity.columns(aa_res)
           if pk_cols.empty?
             raise ArgumentError,
-              "#{model.name} has no primary key for GraphQL `id`; set self.primary_key on the model"
+              "#{model.name} has no primary key for GraphQL `id`; set self.primary_key on the model " \
+              "or graphql { identity ... }"
           end
 
           type_class.field :id, ::GraphQL::Types::ID, null: false, authorize: false
-          type_class.define_method(:id) { ActiveAdmin::PrimaryKey.graphql_id_value(object) }
+          type_class.define_method(:id) do
+            ActiveAdmin::GraphQL::ResourceIdentity.graphql_id_value(
+              self.class.activeadmin_graphql_resource,
+              object
+            )
+          end
 
           # ActiveAdmin omits a single-column primary key from resource_attributes; still expose
           # non-id key columns as scalars (composite keys already remain in attributes).

data/lib/active_admin/graphql/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveAdmin
   module GraphQL
-    VERSION = "0.3.1"
+    VERSION = "0.3.2"
   end
 end

data/lib/active_admin/graphql.rb

@@ -71,6 +71,7 @@ module ActiveAdmin
           graphql/schema_field
           graphql/auth_context
           graphql/record_source
+          graphql/resource_identity
           graphql/resource_query_proxy
           graphql/run_action_payload
           graphql/run_action_mutation_config

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activeadmin-graphql
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Andrei Makarov
@@ -376,6 +376,8 @@ files:
 - docs/changelogs/20260921120000_graphql-floor-and-activeadmin-4.md
 - docs/changelogs/20261010101500_nonconventional-id-fields.md
 - docs/changelogs/20261010103800_release-0-3-1.md
+- docs/changelogs/20261010110600_graphql-identity-dsl.md
+- docs/changelogs/20261010111800_release-0-3-2.md
 - docs/dependencies/20260907141000_json-cve-2026-71847.md
 - docs/dependencies/20260907141000_sqlite3-ghsa-mwm8-39rw-8826.md
 - docs/dependencies/20260921114000_rails-json-parse-kwargs.md
@@ -388,6 +390,9 @@ files:
 - docs/issues/20260921104400_convention-alignment-audit.md
 - docs/issues/20260921114500_dependency-audit.md
 - docs/issues/20260921115500_file-length-metrics.md
+- docs/issues/20261010111159_rails-composite-primary-keys-alignment.md
+- docs/issues/20261010111300_partitions-and-shards-support.md
+- docs/issues/20261010111500_graphql-federation-support.md
 - docs/plan/20260817201500_rfc-starter.md
 - lib/active_admin/graphql.rb
 - lib/active_admin/graphql/auth_context.rb
@@ -402,6 +407,7 @@ files:
 - lib/active_admin/graphql/record_source.rb
 - lib/active_admin/graphql/resource_config.rb
 - lib/active_admin/graphql/resource_definition_dsl.rb
+- lib/active_admin/graphql/resource_identity.rb
 - lib/active_admin/graphql/resource_interface.rb
 - lib/active_admin/graphql/resource_methods.rb
 - lib/active_admin/graphql/resource_query_proxy.rb