How to Migrate Business Central Table Fields from Integer to BigInteger.

Hi All,

Business Central version 29 introduces a long-awaited AL compiler capability that allows developers to change an existing table field from Integer to BigInteger without destroying existing data. 

This change is supported when targeting runtime version 18.0 (Fall 2026) or later and is specifically designed for upgrade scenarios where record identifiers, counters, or reference numbers have grown beyond the 32-bit integer limit.

For years, developers who needed to support more than 2,147,483,647 records in a table faced a difficult choice: live with the limitation or perform expensive data migration scripts that recreated tables, moved data, and rewrote references. With version 29, the platform now recognizes Integer to BigInteger as a compatible field upgrade, which means the data conversion happens safely during the extension upgrade process.

However, this is not a change to make casually. Because BigInteger is a 64-bit type and Integer is a 32-bit type, any dependent code that assigns the field back into an Integer, Option, or Enum variable risks overflow or narrowing. To protect dependent extensions, Microsoft added the AppSourceCop rule AS0141, and the compiler now emits warnings when a BigInteger field is used in property contexts that could narrow the value, such as TableRelation or CalcFormula WHERE clauses.

This article explains the feature, the business and technical reasons it exists, where it applies, how to use it, and what warnings you must address before publishing.

What Is This Feature?

The BigInteger field migration feature is a platform-supported way to upgrade an existing table field from the Integer data type to the BigInteger data type. It is part of the AL language and runtime improvements delivered in Business Central version 29.

In plain English: you can now open a table that already contains data, change a field from Integer to BigInteger, and deploy a new version of your extension. The platform will upgrade the schema and convert the stored values without deleting the table or requiring a manual data migration.

This is a significant change because AL has historically treated most data type changes on table fields as destructive or unsupported. Changing a field type usually meant the old field was dropped and a new field was created, which resulted in data loss. For Integer to BigInteger, the platform now understands that the underlying values fit safely inside the new type, so the conversion is non-destructive.

The feature includes two related compiler behaviors:

  1. Field type migration: The schema synchronization process allows Integer → BigInteger changes when the target runtime is 18.0 or later.
  2. Property context warnings: When a BigInteger field is referenced in contexts where the value may be narrowed to Integer, Option, or Enum, the compiler emits warnings to alert you about potential overflow at runtime.

This feature is particularly relevant for tables that store auto-incrementing entry numbers, document line numbers, or any identifier that could theoretically exceed the 32-bit range.

Why Does This Feature Exist?

The Business Problem

Business Central is used by organizations that accumulate millions of records over many years. Tables such as ledger entries, document history, log tables, and custom transaction tables can grow far beyond what was originally anticipated. When an Integer field approaches its maximum value of 2,147,483,647, the application can no longer insert new records. This is not a theoretical problem; it happens in long-running, high-volume systems.

Before version 29, fixing this required either:

  • Archiving or deleting old records, which may violate business or regulatory requirements.
  • Writing a manual upgrade codeunit that created a new BigInteger field, copied data, updated all references, and removed the old field.
  • Accepting a hard limit on business growth.

All of these options were expensive, risky, or unacceptable.

The Technical Problem

From the compiler perspective, Integer and BigInteger are different data types with different storage sizes and different runtime behaviors. Historically, changing a field type meant the platform could not guarantee that existing data would remain valid. Therefore, the change was blocked or treated as destructive.

The technical breakthrough in version 29 is the recognition that every valid Integer value is also a valid BigInteger value. The conversion is widening, not narrowing, so existing data is preserved. The platform can safely upgrade the column in SQL Server and update the metadata without losing rows.

Why Now?

The need for larger numeric identifiers has grown as more customers move to SaaS, run longer without archiving, and build extensions that accumulate their own transaction history. By making this migration supported, Microsoft reduces the operational risk of large Business Central environments and removes a common reason for complex custom upgrade projects.

Where Is It Used?

This feature applies whenever you need to widen an existing Integer table field to BigInteger.

Common scenarios include:

  • Entry number fields in custom ledger or log tables where the number of entries can exceed the 32-bit limit.
  • Line number fields in documents that may contain an extremely large number of lines over time.
  • Auto-incrementing counters that are not reset periodically.
  • Foreign key reference fields that point to tables with BigInteger primary keys.
  • Integration identifiers imported from external systems that use 64-bit integers.

The feature is also relevant for:

  • AppSource publishers who need to future-proof their extensions.
  • Partners maintaining vertical solutions with high-volume tables.
  • Developers building migration tools for customers upgrading from older versions.

Architecture Overview

The feature touches several layers of the Business Central platform:

  • AL Compiler: Validates the field type change and emits warnings for narrowing conversions.
  • AppSourceCop Rule AS0141: Warns AppSource extensions that dependent extensions may be affected by the field type change.
  • Runtime Schema Synchronization: Converts the SQL column from int to bigint during the extension upgrade.
  • Property Evaluator: Checks TableRelation, CalcFormula, and similar properties for overflow risks.
  • CalcFormula Engine: Allows LOOKUP, MAX, and MIN operations between Integer and BigInteger with appropriate warnings.

Key points:

  • The migration is one-directional: Integer → BigInteger is supported, but the reverse is not.
  • The conversion is non-destructive for existing data.
  • Warnings are emitted for dependent expressions that might narrow or overflow the value.
  • AppSourceCop AS0141 is specifically about the impact on dependent extensions.

How It Works

Step 1: Identify the Field

Find the table field that is currently defined as Integer and needs to support larger values. Confirm that the change is widening and that no reverse narrowing is required.

Step 2: Update the Field Definition

Change the field data type from Integer to BigInteger in the table object. For example:

field(1; "Entry No."; BigInteger)
{
    DataClassification = CustomerContent;
}

Step 3: Set the Target Runtime

Ensure your app.json targets runtime version 18.0 or later. This is required because the field type migration is only supported in runtime 18.0 (Fall 2026) and beyond.

{
    "runtime": "18.0"
}

Step 4: Build and Review Warnings

Build your extension. The compiler will:

  • Allow the Integer → BigInteger field type change.
  • Emit warnings for any property context where the BigInteger value is narrowed to Integer, Option, or Enum.
  • Emit AppSourceCop rule AS0141 if you are building an AppSource extension.

Step 5: Fix Narrowing References

Review every warning and decide whether to:

  • Widen the receiving variable or field to BigInteger.
  • Add explicit validation to ensure the value fits in the target type.
  • Refactor the logic to avoid the narrowing conversion.

Step 6: Deploy the Upgrade

Publish the new version of your extension. The platform will synchronize the schema and convert the existing Integer values to BigInteger values without deleting the table or losing data.

Step 7: Verify Dependent Extensions

If other extensions reference the changed field, test those extensions against the new version. The compiler warnings help, but runtime behavior must still be validated.

Business Example

Imagine a custom warehouse transaction log table used by a distribution company. The table has the following fields:

  • Entry No. (Integer)
  • Item No. (Code[20])
  • Quantity (Decimal)

Over ten years, the company processes hundreds of millions of warehouse movements. The Entry No. field approaches the 32-bit limit. Without the BigInteger migration feature, the partner would need to archive old entries or rewrite the table.

With version 29, the partner changes the field to BigInteger, targets runtime 18.0, and publishes the upgrade. Existing entries keep their numbers, and the table can continue to grow. Any custom pages or reports that display Entry No. are reviewed for narrowing issues and updated as needed.

Technical Example

Version 1 of the Extension

table 50100 "Demo Entry"
{
    DataClassification = CustomerContent;

    fields
    {
        field(1; "Entry No."; Integer)
        {
            DataClassification = CustomerContent;
        }
        field(2; "Code"; Code[20])
        {
            DataClassification = CustomerContent;
        }
    }

    keys
    {
        key(PK; "Entry No.")
        {
            Clustered = true;
        }
    }
}

In version 1, ten records are inserted with Entry No. values 1 through 10.

Version 2 of the Extension

table 50100 "Demo Entry"
{
    DataClassification = CustomerContent;

    fields
    {
        field(1; "Entry No."; BigInteger)
        {
            DataClassification = CustomerContent;
        }
        field(2; "Code"; Code[20])
        {
            DataClassification = CustomerContent;
        }
    }

    keys
    {
        key(PK; "Entry No.")
        {
            Clustered = true;
        }
    }
}

The only change is the data type of Entry No. from Integer to BigInteger. When version 2 is published:

  • The platform upgrades the SQL column from int to bigint.
  • The existing ten records remain intact.
  • New records can use values above the 32-bit limit.

Handling Dependent Code

Consider a page that assigns Entry No. to an Integer variable:

procedure GetLastIntegerEntryNo(): Integer
var
    DemoEntry: Record "Demo Entry";
begin
    if DemoEntry.FindLast() then
        exit(DemoEntry."Entry No."); // Warning: BigInteger -> Integer narrowing
end;

The compiler emits a warning because the BigInteger value may not fit into an Integer. The recommended fix is to change the return type to BigInteger:

procedure GetLastEntryNo(): BigInteger
var
    DemoEntry: Record "Demo Entry";
begin
    if DemoEntry.FindLast() then
        exit(DemoEntry."Entry No.");
end;

CalcFormula Example

If another table uses a CalcFormula to look up the maximum Entry No., the compiler allows the conversion but may warn if the result is assigned to a narrower field:

field(100; "Max Entry No."; BigInteger)
{
    FieldClass = FlowField;
    CalcFormula = max("Demo Entry"."Entry No.");
}

This is safe when the receiving field is also BigInteger. If the receiving field were Integer, a warning would be emitted.

Best Practices

  1. Plan before migrating: Confirm that the field genuinely needs 64-bit capacity. Changing a field type affects dependent pages, reports, codeunits, and other extensions.

  2. Target the correct runtime: Only runtime 18.0 (Fall 2026) and later support Integer → BigInteger field migration.

  3. Address every compiler warning: Do not suppress narrowing warnings without understanding the runtime overflow risk.

  4. Update dependent variables: Change variables, parameters, and return types that receive the field value from Integer to BigInteger.

  5. Review CalcFormula assignments: Ensure flow fields that reference the migrated field use compatible target types.

  6. Test with realistic data: Insert values near and above the 32-bit limit to confirm that downstream logic handles them correctly.

  7. Validate dependent extensions: If your extension is used by other extensions, communicate the change and provide an updated version for testing.

  8. Use explicit validation when narrowing is unavoidable: If you must assign a BigInteger to an Integer, validate that the value is within the Integer range first.

  9. Document the migration in release notes: Help consumers of your extension understand why the field type changed and what they need to update.

  10. Avoid unnecessary field type changes: Do not migrate fields unless there is a clear requirement. Every field type change creates upgrade and compatibility work.

Common Mistakes

  1. Ignoring narrowing warnings: A BigInteger value assigned to an Integer can overflow silently or throw a runtime error. Treat every warning as a potential bug.

  2. Forgetting dependent extensions: AppSourceCop AS0141 exists because other extensions may break. Test all dependent extensions before publishing.

  3. Changing the field type without updating variables: Pages, reports, and procedures that use the field may still declare Integer variables, leading to compilation warnings or runtime errors.

  4. Assuming the reverse is supported: BigInteger → Integer is not a supported migration because it is narrowing and can lose data.

  5. Suppressing AS0141 without analysis: AppSourceCop rules are there to protect the ecosystem. Only suppress after understanding the impact.

  6. Not testing boundary values: Insert values above 2,147,483,647 to verify that your code truly supports 64-bit values end to end.

  7. Narrowing in CalcFormula WHERE clauses: Using a BigInteger field in a WHERE clause that compares against an Integer field or value can produce unexpected results. Widen the comparison target when possible.

  8. Changing multiple fields at once: Migrate one field type at a time and validate each change to simplify troubleshooting.

Upgrade Considerations

  • This feature is intended for upgrade scenarios. It is not a general-purpose schema refactoring tool.
  • The migration is supported only for Integer → BigInteger.
  • On-premises and SaaS environments both benefit from the feature as long as the target runtime is 18.0 or later.
  • If you have table extensions that add fields to the same table, those fields are not affected by the migration, but references to the migrated field must be reviewed.
  • Permission sets and table descriptions do not need to change because of the field type migration, but any page field expressions that depend on the data type should be checked.
  • AppSourceCop Rule AS0141: Warns about breaking changes that affect dependent extensions.
  • AL Compiler Warnings: Emits narrowing and overflow warnings for property contexts.
  • CalcFormula: Supports LOOKUP, MAX, and MIN across compatible numeric types.
  • Runtime Schema Synchronization: Performs the underlying SQL column conversion.
  • Upgrade Codeunits: Still useful for data transformations that cannot be handled by schema sync alone.

Summary

Business Central version 29 makes it possible to migrate an existing table field from Integer to BigInteger without losing data. This change is supported when targeting runtime 18.0 or later and is designed for upgrade scenarios where record counts approach the 32-bit limit.

The feature is powerful but requires care. Developers must update dependent variables, fix narrowing warnings, review CalcFormula assignments, and test dependent extensions. AppSource publishers must also account for AppSourceCop rule AS0141, which warns about the impact on dependent extensions.

By following the best practices in this article, you can safely widen your numeric fields and prepare your solutions for long-term growth.

Subscribe to the Saurav Dhyani YouTube channel for Business Central technical tutorials, AL development, APIs, extensions, new features, and practical implementation guidance.

You can also connect with me on: 

LinkedIn

YouTube 

Regards,

Saurav Dhyani