Support non-nullable field additions in schema migrations via @default

packages/node-core/CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- Schema migrations can add a non-nullable field when it declares `@default`: existing rows, including historical versions, are filled with that value
 
 ## [19.3.1] - 2026-04-01
 ### Fixed

packages/node-core/src/db/migration-service/SchemaMigration.service.test.ts

@@ -493,6 +493,75 @@ WHERE event_object_table = :table AND event_object_schema = :schema ;
     expect(result[0]).toEqual({trigger_name: '0x36bc022fc662d7ff'});
   });
 
+  describe('non-nullable fields with @default', () => {
+    it('fills every existing row version and leaves the column NOT NULL without a default', async () => {
+      schemaName = 'test-migrations-21';
+
+      const initialSchema = loadGqlSchema('test_21_1.graphql');
+      const migrationService = await setup(schemaName, initialSchema, sequelize);
+
+      // Two historical versions of one entity, written before the fields existed.
+      await sequelize.query(
+        `INSERT INTO "${schemaName}"."transfers" (id, amount, block_number, _id, _block_range) VALUES
+           ('t1', 1, 10, gen_random_uuid(), int8range(10, 20)),
+           ('t1', 2, 10, gen_random_uuid(), int8range(20, NULL));`
+      );
+
+      const tx = await sequelize.transaction();
+      await migrationService.run(initialSchema, loadGqlSchema('test_21_2000.graphql'), tx);
+      await tx.commit();
+
+      const rows = await sequelize.query(
+        `SELECT fee, retries, ratio, settled, label, status FROM "${schemaName}"."transfers" ORDER BY lower(_block_range);`,
+        {type: QueryTypes.SELECT}
+      );
+      expect(rows).toEqual([
+        {fee: '0', retries: -1, ratio: 0.5, settled: false, label: "it's", status: 'PENDING'},
+        {fee: '0', retries: -1, ratio: 0.5, settled: false, label: "it's", status: 'PENDING'},
+      ]);
+
+      const columns = await sequelize.query<{column_name: string; is_nullable: string; column_default: string | null}>(
+        `SELECT column_name, is_nullable, column_default FROM information_schema.columns
+         WHERE table_schema = :schema AND table_name = 'transfers' AND column_name IN (:columns);`,
+        {
+          type: QueryTypes.SELECT,
+          replacements: {schema: schemaName, columns: ['fee', 'retries', 'ratio', 'settled', 'label', 'status']},
+        }
+      );
+      expect(columns).toHaveLength(6);
+      columns.forEach((column) => {
+        expect(column.is_nullable).toBe('NO');
+        expect(column.column_default).toBeNull();
+      });
+    });
+
+    it('still refuses a non-nullable field without @default', async () => {
+      schemaName = 'test-migrations-23';
+
+      const initialSchema = loadGqlSchema('test_22_1.graphql');
+      const migrationService = await setup(schemaName, initialSchema, sequelize);
+
+      const tx = await sequelize.transaction();
+      await expect(migrationService.run(initialSchema, loadGqlSchema('test_23_2000.graphql'), tx)).rejects.toThrow(
+        'Non-nullable field creation is not supported: fee on Transfer'
+      );
+      await tx.rollback();
+    });
+
+    it('refuses to fill a field that changed from nullable, rather than replace its data', async () => {
+      schemaName = 'test-migrations-22';
+
+      const initialSchema = loadGqlSchema('test_22_1.graphql');
+      const migrationService = await setup(schemaName, initialSchema, sequelize);
+
+      const tx = await sequelize.transaction();
+      await expect(migrationService.run(initialSchema, loadGqlSchema('test_22_2000.graphql'), tx)).rejects.toThrow(
+        'Non-nullable field creation is not supported: memo on Transfer'
+      );
+      await tx.rollback();
+    });
+  });
+
   describe('enum migrations', () => {
     async function queryEnums(): Promise<{enum_type: string; enum_value: string}[]> {
       return sequelize.query<{enum_type: string; enum_value: string}>(

packages/node-core/src/db/migration-service/migration.ts

@@ -34,6 +34,7 @@ export class Migration {
   /* Models that are added or modified during the migration */
   private modifiedModels: ModelStatic<any>[] = [];
   private removedModels: string[] = [];
+  private droppedColumns = new Set<string>();
   /*
   mainQueries are used for executions, that are not reliant on any prior db operations
   extraQueries are executions, that are reliant on certain db operations, e.g. comments on foreignKeys or comments on tables, should be executed only after the table has been created
@@ -212,17 +213,35 @@ export class Migration {
       throw new Error('Primary Key migration upgrade is not allowed');
     }
 
-    if (!columnOptions.allowNull) {
-      throw new Error(`Non-nullable field creation is not supported: ${field.name} on ${model.name}`);
-    }
-
     const dbTableName = modelToTableName(model.name);
     const dbColumnName = formatColumnName(field.name);
 
+    if (!columnOptions.allowNull) {
+      // A changed field arrives as drop + add: filling it with a default would silently replace the dropped data.
+      if (field.defaultValue === undefined || this.droppedColumns.has(`${dbTableName}.${dbColumnName}`)) {
+        throw new Error(`Non-nullable field creation is not supported: ${field.name} on ${model.name}`);
+      }
+    }
+
     const formattedAttributes = formatAttributes(columnOptions, this.schemaName, false);
-    this.mainQueries.push(
-      syncHelper.createColumnQuery(this.schemaName, dbTableName, dbColumnName, formattedAttributes)
-    );
+    if (columnOptions.allowNull) {
+      this.mainQueries.push(
+        syncHelper.createColumnQuery(this.schemaName, dbTableName, dbColumnName, formattedAttributes)
+      );
+    } else {
+      // A constant default is stored once in the catalog, so every existing row and historical version reads it
+      // without a table rewrite or row triggers. Dropping it afterwards leaves new rows to the mappings.
+      this.mainQueries.push(
+        syncHelper.createColumnWithDefaultQuery(
+          this.schemaName,
+          dbTableName,
+          dbColumnName,
+          formattedAttributes,
+          field.defaultValue as string
+        ),
+        syncHelper.dropColumnDefaultQuery(this.schemaName, dbTableName, dbColumnName)
+      );
+    }
 
     if (columnOptions.comment) {
       this.extraQueries.push(
@@ -237,6 +256,7 @@ export class Migration {
     const columnName = formatColumnName(field.name);
     const tableName = modelToTableName(model.name);
     this.mainQueries.push(syncHelper.dropColumnQuery(this.schemaName, columnName, tableName));
+    this.droppedColumns.add(`${tableName}.${columnName}`);
     this.addModelToSequelizeCache(this.createSequelizeModel(model));
   }
 

packages/node-core/src/db/sync-helper.ts

@@ -711,6 +711,20 @@ export const dropColumnQuery = (schema: string, columnName: string, tableName: s
 export const createColumnQuery = (schema: string, table: string, columnName: string, attributes: string): string =>
   `ALTER TABLE ${escapedName(schema, table)} ADD COLUMN IF NOT EXISTS "${columnName}" ${attributes};`;
 
+export const createColumnWithDefaultQuery = (
+  schema: string,
+  table: string,
+  columnName: string,
+  attributes: string,
+  defaultValue: string
+): Query => ({
+  sql: `ALTER TABLE ${escapedName(schema, table)} ADD COLUMN IF NOT EXISTS "${columnName}" ${attributes} DEFAULT ?;`,
+  replacements: [defaultValue],
+});
+
+export const dropColumnDefaultQuery = (schema: string, table: string, columnName: string): string =>
+  `ALTER TABLE ${escapedName(schema, table)} ALTER COLUMN "${columnName}" DROP DEFAULT;`;
+
 // fullTextSearch
 const TS_VECTOR_COL = '_tsv';
 

packages/node-core/test/migration-schemas/test_21_1.graphql

@@ -0,0 +1,6 @@
+type Transfer @entity {
+  id: ID!
+  amount: BigInt!
+  blockNumber: Int!
+  memo: String
+}

packages/node-core/test/migration-schemas/test_21_2000.graphql

@@ -0,0 +1,17 @@
+type Transfer @entity {
+  id: ID!
+  amount: BigInt!
+  blockNumber: Int!
+  memo: String
+  fee: BigInt! @default(value: "0")
+  retries: Int! @default(value: "-1")
+  ratio: Float! @default(value: "0.5")
+  settled: Boolean! @default(value: "false")
+  label: String! @default(value: "it's")
+  status: TransferStatus! @default(value: "PENDING")
+}
+
+enum TransferStatus {
+  PENDING
+  DONE
+}

packages/node-core/test/migration-schemas/test_22_1.graphql

@@ -0,0 +1,5 @@
+type Transfer @entity {
+  id: ID!
+  amount: BigInt!
+  memo: String
+}

packages/node-core/test/migration-schemas/test_22_2000.graphql

@@ -0,0 +1,5 @@
+type Transfer @entity {
+  id: ID!
+  amount: BigInt!
+  memo: String! @default(value: "none")
+}

packages/node-core/test/migration-schemas/test_23_2000.graphql

@@ -0,0 +1,6 @@
+type Transfer @entity {
+  id: ID!
+  amount: BigInt!
+  memo: String
+  fee: BigInt!
+}

packages/utils/CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- `@default(value: String!)` field directive, so a schema migration can add a non-nullable field to an entity that already has rows
 
 ## [2.22.1] - 2025-11-05
 ### Changed

packages/utils/src/graphql/entities.ts

@@ -90,7 +90,12 @@ export function getAllEntitiesRelations(_schema: GraphQLSchema | string | null):
   );
 
   const modelRelations = {models: [], relations: [], enums: [...enums.values()]} as GraphQLModelsRelationsEnums;
-  const [derivedFrom, indexDirective, idDbType] = getDirectives(schema, ['derivedFrom', 'index', 'dbType']);
+  const [derivedFrom, indexDirective, idDbType, defaultDirective] = getDirectives(schema, [
+    'derivedFrom',
+    'index',
+    'dbType',
+    'default',
+  ]);
   for (const entity of entities) {
     const newModel: GraphQLModelsType = {
       name: entity.name,
@@ -113,6 +118,8 @@ export function getAllEntitiesRelations(_schema: GraphQLSchema | string | null):
       const derivedFromDirectValues = field.astNode ? getDirectiveValues(derivedFrom, field.astNode) : undefined;
       const indexDirectiveVal = field.astNode ? getDirectiveValues(indexDirective, field.astNode) : undefined;
       const dbTypeDirectiveVal = field.astNode ? getDirectiveValues(idDbType, field.astNode) : undefined;
+      const defaultDirectiveVal = field.astNode ? getDirectiveValues(defaultDirective, field.astNode) : undefined;
+      const fieldCountBefore = newModel.fields.length;
 
       //If is a basic scalar type
       const typeClass = getTypeByScalarName(typeString);
@@ -211,6 +218,10 @@ export function getAllEntitiesRelations(_schema: GraphQLSchema | string | null):
       } else {
         throw new Error(`${typeString} is not a valid type`);
       }
+      if (defaultDirectiveVal) {
+        const packed = newModel.fields.length > fieldCountBefore ? newModel.fields[fieldCountBefore] : undefined;
+        setDefaultValue(entity.name, field.name, packed, defaultDirectiveVal.value, enums.get(typeString)?.values);
+      }
       // handle indexes
       if (indexDirectiveVal) {
         if (typeString !== 'ID' && typeClass) {
@@ -354,6 +365,41 @@ function getJoinIndexFields(
   });
 }
 
+const defaultValuePatterns: Record<string, RegExp> = {
+  [FieldScalar.Int]: /^-?\d+$/,
+  [FieldScalar.BigInt]: /^-?\d+$/,
+  [FieldScalar.Float]: /^-?\d+(\.\d+)?([eE][-+]?\d+)?$/,
+  [FieldScalar.Boolean]: /^(true|false)$/,
+  [FieldScalar.String]: /^/,
+};
+
+// `@default` exists so a migration can add a non-nullable field to a table that already has rows, so it is only
+// accepted where that column can be filled with one literal.
+function setDefaultValue(
+  entityName: string,
+  fieldName: string,
+  field: GraphQLEntityField | undefined,
+  value: string,
+  enumValues: string[] | undefined
+): void {
+  const where = `"@default" on ${entityName}.${fieldName}`;
+  if (!field || field.isArray || field.jsonInterface || field.name !== fieldName || field.type === FieldScalar.ID) {
+    throw new Error(`${where} is only supported on scalar and enum fields`);
+  }
+  if (field.nullable) {
+    throw new Error(`${where} is only supported on non-nullable fields`);
+  }
+  const valid = field.isEnum ? enumValues?.includes(value) : defaultValuePatterns[field.type]?.test(value);
+  if (!valid) {
+    throw new Error(`${where}: "${value}" is not a valid ${field.type} value`);
+  }
+  // Int is stored as a Postgres integer.
+  if (field.type === FieldScalar.Int && Math.abs(Number(value)) > 2147483647) {
+    throw new Error(`${where}: "${value}" is not a valid Int value`);
+  }
+  field.defaultValue = value;
+}
+
 function packEntityField(
   typeString: FieldScalar | string,
   field: GraphQLField<unknown, unknown>,

packages/utils/src/graphql/graphql.spec.ts

@@ -535,4 +535,74 @@ describe('utils that handle schema.graphql', () => {
       }
     });
   });
+
+  describe('default directive', () => {
+    function parseFields(fields: string) {
+      const schema = buildSchemaFromDocumentNode(gql`
+        type StarterEntity @entity {
+          id: ID!
+          ${fields}
+        }
+
+        type Other @entity {
+          id: ID!
+        }
+
+        enum Status {
+          OPEN
+          CLOSED
+        }
+      `);
+      return getAllEntitiesRelations(schema).models.find((m) => m.name === 'StarterEntity')?.fields;
+    }
+
+    it('sets defaultValue on non-nullable scalar and enum fields', () => {
+      const fields = parseFields(`
+        amount: BigInt! @default(value: "-5")
+        count: Int! @default(value: "0")
+        ratio: Float! @default(value: "1.5e3")
+        done: Boolean! @default(value: "false")
+        note: String! @default(value: "")
+        status: Status! @default(value: "OPEN")
+        plain: Int!
+      `);
+
+      expect(Object.fromEntries((fields ?? []).map((f) => [f.name, f.defaultValue]))).toEqual({
+        id: undefined,
+        amount: '-5',
+        count: '0',
+        ratio: '1.5e3',
+        done: 'false',
+        note: '',
+        status: 'OPEN',
+        plain: undefined,
+      });
+    });
+
+    it('rejects values that do not fit the field type', () => {
+      const cases: [string, string][] = [
+        ['count: Int! @default(value: "1.5")', '"1.5" is not a valid Int value'],
+        ['count: Int! @default(value: "99999999999999999999")', 'is not a valid Int value'],
+        ['amount: BigInt! @default(value: "1e3")', '"1e3" is not a valid BigInt value'],
+        ['done: Boolean! @default(value: "no")', '"no" is not a valid Boolean value'],
+        ['status: Status! @default(value: "LOST")', '"LOST" is not a valid Status value'],
+        ['day: Date! @default(value: "2020-01-01")', 'is not a valid Date value'],
+      ];
+      for (const [field, message] of cases) {
+        expect(() => parseFields(field)).toThrow(message);
+      }
+    });
+
+    it('rejects fields a single literal cannot fill', () => {
+      expect(() => parseFields('note: String @default(value: "x")')).toThrow(
+        '"@default" on StarterEntity.note is only supported on non-nullable fields'
+      );
+      expect(() => parseFields('tags: [String]! @default(value: "x")')).toThrow(
+        '"@default" on StarterEntity.tags is only supported on scalar and enum fields'
+      );
+      expect(() => parseFields('other: Other! @default(value: "x")')).toThrow(
+        '"@default" on StarterEntity.other is only supported on scalar and enum fields'
+      );
+    });
+  });
 });

packages/utils/src/graphql/schema/directives.ts

@@ -11,4 +11,5 @@ export const directives = gql`
   directive @compositeIndexes(fields: [[String]]!) on OBJECT
   directive @fullText(fields: [String!], language: String) on OBJECT
   directive @dbType(type: String!) on FIELD_DEFINITION
+  directive @default(value: String!) on FIELD_DEFINITION
 `;

packages/utils/src/graphql/types.ts

@@ -55,6 +55,11 @@ export interface GraphQLEntityField {
 
   isEnum: boolean;
 
+  /**
+   * Set by `@default`. Only used by schema migrations, to fill existing rows when a non-nullable field is added.
+   */
+  defaultValue?: string;
+
   description?: string;
 }