How-to: Migrating from the legacy generator

The rewrite generator declares and supports the following directives. Each is documented in the architecture chapter:

These directives are still declared so existing schemas parse, but the rewrite no longer supports them: applying one is a build error. Remove them from your schema (see the migration guide for replacements):

These directives existed in legacy graphitron but are removed in the rewrite. Drop them from your schema (or replace per the notes below) before migrating:

The following directives have argument-shape changes between legacy and rewrite. Consumers must update existing usages:

One replacement pointer for the "Legacy-only directives" list above: legacy @tableMethod bound a consumer-authored static method returning a jOOQ table. The rewrite does not declare it. Where the method wrapped a database function, use @routine, which binds the generated Routines-class call directly; where it applied a filter, express that with @condition.

Legacy schemas used it to mark fields the developer would wire by hand through RuntimeWiring; the rewrite requires every field to be fully described by the schema. Any application is rejected at build time:

The directive is still parsed (so the SDL still validates), but every classify-time application fails with that message. The migration is a one-step delete-and-replace: remove the @notGenerated and add the directive that names the actual data source.

The @notGenerated reference page carries the same matrix; this recipe expands the right-hand column with cross-links to the recipe each replacement is best documented in.

Legacy schemas used @multitableReference(routes: […​]) to declare per-implementation join paths for a field returning a multi-table interface or union. The rewrite generates multi-table interface dispatch from @discriminate / @discriminator (with @reference for the FK-driven join) and does not need a separate per-route description. Any application is rejected at build time:

Migration is a one-step delete-and-rebuild: drop the @multitableReference directive (and its ReferencesForType argument tree) and model the multi-table dispatch through @discriminate / @discriminator. How-to: Polymorphic types covers the supported shapes.

Unlike the two directives above, this one is not even parsed: the argument is undeclared, so the schema fails to load before classification runs.

Replaced with className::

className: takes the FQCN. The legacy name: was a short name resolved through the plugin’s externalReferences: config; the rewrite briefly carried the argument as a deprecated alias resolved through its own <namedReferences> parameter, and both are now gone. The failure names the offending field:

The migration is mechanical: copy the FQCN from the legacy externalReferences: entry into className: at every site, then delete the plugin config block. This applies to all four directives that take an ExternalCodeReference (@service, @externalField, @condition, @enum), including a @condition nested in a @reference path step.

Legacy input types let an ID! (or [ID!]) field carry a column name through @field(name:), and the FK qualifier was inferred from the catalog so the value was decoded as a global ID. That inference is removed: @field(name:) now means what it says everywhere, binding the named column and nothing more, so a field written this way silently becomes an ordinary column filter over the raw value.

This is the one change in this recipe with no build error attached, because both readings resolve. Audit filter inputs whose ID fields carry @field(name:) against an FK column.

Before:

After:

When the FK is ambiguous (more than one path from the consuming field’s table to the target), add an explicit @reference(path: [{key: "fk_constraint_name"}]) alongside the @nodeId. The @reference recipe covers the FK-disambiguation mechanics; the migration is otherwise mechanical.

An input field named for its target’s own id needs no directive at all: id: ID! on an input consumed against a node-backed table reads as that node’s global ID, the same way Node.id does on the type. Where the table backs more than one node type the build fails and asks for @nodeId(typeName:), rather than picking one.

Legacy schemas bound every mutation and filter input to a table with @table on the input type. The rewrite deprecated that location: an input’s fields resolve against each consuming field’s table, so the input-side declaration is redundant, and an input reused across consumers resolves per-consumer. The directive is accepted and then ignored, with a per-usage build warning, and will be rejected in a future release. @table on OBJECT and INTERFACE is unchanged.

Because it is ignored rather than honoured, an input whose @table named a different table from the one its consuming field resolves does not migrate silently-but-correctly: the declared table is discarded and the consumer’s is used. The warning is the only signal, so read it instead of assuming the two agreed.

The migration is per-consumer:

The @table reference page carries the deprecation statement; @mutation documents the write-target derivation.

Historical only: legacy versions of the rewrite would silently promote any @table SDL type to NodeType if its backing jOOQ class carried NODE_TYPE_ID / NODE_KEY_COLUMNS metadata, even without implements Node. This behavior was retired after a mass typeId collision: ~200 backing types each carrying __NODE_TYPE_ID = "195" were promoted in lockstep and then symmetrically demoted to UnclassifiedType.

The current rule: metadata alone promotes nothing, and implements Node is the opt-in. A @table type that does not declare the interface is a regular TableType no matter what its jOOQ class publishes, which is what keeps a nesting projection over a node-bearing table from becoming a second node. A @table type that does declare implements Node over a table publishing that metadata is a node, and takes typeId and keyColumns from the catalog.

So if a schema relied on the auto-promotion (the type was reachable via Query.node or carried @nodeId fields), add implements Node to the declaration. You need @node as well only when the backing jOOQ class publishes no metadata, or when you want to override a published value; the @node reference covers both. Fields inside the type that depend on node behavior follow the rules in the previous two sections.

One case to expect on this path: if the table also has a column literally named id, the type’s id field is ambiguous between the encoded global ID and that column, and the build fails until you write @nodeId or @field(name: "id") on it. The error names both remedies.

Legacy schemas used @record(record: {className: "…​"}) to bind a class-backed SDL type to its Java class. The rewrite now derives that binding by reflection from the type’s producer instead: for an output type, the producing field’s return type (a @service method return or a parent-accessor chain); for an input type, the method parameter the input flows into. The directive still parses (so existing schemas keep loading), but it is ignored.

A reachable type still carrying @record triggers a build WARN telling you to remove it. The WARN distinguishes three cases:

Migration is mechanical: delete the @record(record: {…​}) annotation. Make sure the type’s producer (the @service return, or the @externalField lift’s Field<…​> element type) is the Java class you intend to back the type. How-to: Result-type variants covers the reflected backing-class shapes; the @notGenerated-on-a-class-backed-parent row above covers the child-fetch directives that remain unchanged.

The override coalesces multiple connection-bearing fields onto one synthesised type. The rewrite default produces one Connection type per field (<ParentType><FieldName>Connection); sharing a name across fields conflates distinct semantic contexts (different parents, filters, orders, cursor formats) at the type level.

Migration: drop the argument and let each field own its synthesised connection type. The four reasons for the per-field default and the migration considerations live in How-to: Cursor-paginated connections under "One field, one connection type".

Replaced with @order(index:):

@order is the unified enum-value sort surface; it accepts index:, fields:, or primaryKey: (exactly one). How-to: Sort results covers the column-source choice. @index still works on enum values today; the deprecation notice at parse time is the migration prompt.