Skip to content

Major upgrades

Major versions can contain incompatible changes. The following sections describe how to upgrade to a new major version.

Make sure all deprecation warnings on the current version are fixed before attempting to upgrade as described here.

Upgrading from 2023.3.x to 2024.1.x

NPL

Option type

The Option type has now been completely removed, as have the related standard library methods optionalOf, List.first(), List.indexOf(), List.last(), and Map.get().

If you still use Option in your code, you will need to migrate to Optional, and this can only be done with a platform version between 2022.1.65 and 2023.3.x (i.e., you must migrate before upgrading to 2024.1.x). You can use createOptional to replace values wrapped with Option. ClientOptionValue and ApiOptionValue will remain (but are deprecated) in order to support reading historical protocols.

The GraphQL read model no longer supports the isOption, structIsOption, or collectionIsOption field.

Migrating from Option to Optional

The following is an example of how option values can be replaced with optional values in a migration. Note that this will no longer work in 2024.1.x.

migration("Re-tag protocols to version 1.0.1")
  .transformProtocol("/NPL-1.0.0?/app/LegacyProtocol", "/NPL-1.0.1?/app/LegacyProtocol") {
    replace<OptionValue>("myField") { oldOption ->
      createOptional(oldOption.value, TypeRef.numberValue)
    }
    replace<OptionValue>("myEmptyField") { oldOption ->
      createOptional(oldOption.value, TypeRef.numberValue)
    }
  }
  .retag(prototypes)

APIs

  • The deprecated me parameter in Engine Core and Streams API is no longer supported. Use the Admin API to obtain unauthorized streams.
  • The guard originType in the schemas of Origin and GuardOrigin in Engine Core has been renamed to reflect the upcoming deprecation of the guard keyword in NPL. The schemas use require instead.

Migrations

  • The package com.noumenadigital.dpl no longer exists. Refer to com.noumenadigital.npl instead.
  • The migration utility function mapPrototypesInUpshift has been removed. The replacement function mapPrototypesInMigration should be used instead.

Kotlin integration

  • The engine-client and read-streams-client packages have been discontinued. Use the various clients in the clients package.
  • The engine-client-auth package no longer exists; its contents are now included in the clients package.

Deployment

Database

  • Make sure you are running PostgreSQL 14 or higher before upgrading.
  • Several columns have been removed from the database, but in order to benefit from the space savings, you will need to manually run the vacuum command on your database. We suggest that you do this during a scheduled maintenance window.

Engine

  • The JWT_TRUSTED_ISSUERS environment variable has been deprecated in favor of ENGINE_ALLOWED_ISSUERS. Whereas the deprecated version used prefix-matching to determine allowed issuers of JWT tokens, the new version uses exact matching to prevent unintentional matches.
  • The JWT_ISSUER_OVERRIDE environment variable has been deprecated in favor of ENGINE_ISSUER_OVERRIDE. The behavior is unchanged.

Postgraphile

  • The POSTGRAPHILE_TRUSTED_ISSUERS environment variable has been deprecated in favor of POSTGRAPHILE_ALLOWED_ISSUERS. Whereas the deprecated version used prefix-matching to determine allowed issuers of JWT tokens, the new version uses exact matching to prevent unintentional matches.

Upgrading from 2023.2.x to 2023.3.x

Deployment

Engine

  • The JVM_MAX_RAM_PERCENTAGE environment variable is no longer supported. Use the standard JAVA_TOOL_OPTIONS environment variable to modify Java settings.

    For example, JVM_MAX_RAM_PERCENTAGE=25 would translate to JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=25".

  • The FEATURE_MIGRATION_DESCRIPTOR_NAME_BACKWARD_COMPATIBILITY feature flag has been removed. Migration descriptors now must be called migration.yml instead of upshift.yml.
  • The FEATURE_APPLY_NPL_MIGRATIONS_AT_STARTUP feature flag has been removed. If a migration is present in the directory indicated by ENGINE_NPL_MIGRATION_DIRECTORY_PATH it will always be attempted.

  • The FEATURE_CODEGEN_EMPTY_STRUCT_STATIC_OBJECT feature flag has been removed. Empty structs are now always static.

  • The deprecated ADMIN_HOST variable is no longer supported. Use ENGINE_ADMIN_HOST instead.

  • The deprecated ADMIN_PORT variable is no longer supported. Use ENGINE_ADMIN_PORT instead.
  • The deprecated APPLICATION_MANAGEMENT_HOST variable is no longer supported. Use ENGINE_MANAGEMENT_HOST instead.
  • The deprecated APPLICATION_MANAGEMENT_PORT variable is no longer supported. Use ENGINE_MANAGEMENT_PORT instead.
  • The deprecated APPLICATION_MANAGEMENT_ARCHIVESIZELIMIT variable is no longer supported. Use ENGINE_MANAGEMENT_ARCHIVE_SIZE_LIMIT instead.
  • The deprecated POSTGRAPHILE_DB_USER variable is no longer supported. Use ENGINE_DB_POSTGRAPHILE_USER instead.
  • The deprecated POSTGRAPHILE_DB_PASSWORD variable is no longer supported. Use ENGINE_DB_POSTGRAPHILE_PASSWORD instead. It also no longer has a default value. It now has to be set explicitly.
  • The deprecated ENGINE_NPL_MIGRATION_DIRECTORYPATH variable is no longer supported. Use ENGINE_NPL_MIGRATION_DIRECTORY_PATH instead.
  • The deprecated ENGINE_NPL_MIGRATION_RUNONLY variable is no longer supported. Use ENGINE_NPL_MIGRATION_RUN_ONLY instead.
  • The deprecated ENGINE_ACTUATOR_EXPOSE variable is no longer supported. Use ENGINE_SPRING_ACTUATOR_EXPOSE instead.
  • The ENGINE_DB_PASSWORD variable no longer has a default value. It now has to be set explicitly.

History

  • The JVM_MAX_RAM_PERCENTAGE environment variable is no longer supported. Use the standard JAVA_TOOL_OPTIONS environment variable to modify Java settings.
  • The HISTORY_DB_PASSWORD variable no longer has a default value. It now has to be set explicitly.

Postgraphile

  • The DATABASE_URL environment variable is no longer supported. Use POSTGRAPHILE_DB_URL instead.
  • The ENGINE_HEALTH_ENDPOINT environment variable is no longer supported. Use POSTGRAPHILE_ENGINE_HEALTH_ENDPOINT instead.
  • The ENGINE_TIMEOUT_SECONDS environment variable is no longer supported. Use POSTGRAPHILE_ENGINE_HEALTH_TIMEOUT_SECONDS instead.
  • The ISSUER_OVERRIDE environment variable is no longer supported. Use POSTGRAPHILE_ISSUER_OVERRIDE instead.
  • The PORT environment variable is no longer supported. Use POSTGRAPHILE_PORT instead.
  • The SCHEMA environment variable is no longer supported. Use POSTGRAPHILE_DB_SCHEMA instead.
  • The TRUSTED_ISSUERS environment variable is no longer supported. Use POSTGRAPHILE_TRUSTED_ISSUERS instead.

Upgrading from 2023.1.x to 2023.2.x

This upgrade contained no incompatible changes.