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 to fix all deprecation warnings on the current version before attempting to upgrade.

Upgrading to 2025.2.x

Streamlined party model

The party model has been streamlined to make it easier to understand and use. The Party type has been simplified to only contain a set of claims instead of separate "entity" and "access" claims. All claims now have essentially the same semantics as the old "access" claims. Read more in the Party type documentation and the authorization documentation.

Migrating NPL code

Wherever you previously specified entity or access claims (or both), you should now just specify claims. Typically, this simply entails merging the two arguments into one at the call sites.

Migrating existing protocols

Generally, no action is required to migrate existing protocols. However, there are some edge cases where migrations may be needed prior to upgrading to 2025.2.x in order to change the party claims of existing protocols. This is needed if:

  • There are protocols where the same key is used in both entity and access claims for a specific party
  • There are multiple values for the same entity claim key in the entity claims of a party

Upgrading from 2024.2.x to 2025.1.x

This upgrade contained no incompatible changes.

Upgrading from 2024.1.x to 2024.2.x

Deployment

Database

  • Make sure you are running PostgreSQL 14 or higher before upgrading.
  • The Engine's database user no longer creates Read Model or History database users. Now all required database users must be provided by the project configuration. Accordingly, the configuration of the Engine's database user can be simplified (it no longer needs CREATEROLE privileges). Refer to the configuration section for more details.
  • The History database user no longer requires CREATEROLE privileges, so make sure to remove them. Details are provided in the configuration section.
  • The Read Model database user must be created and configured properly. Note that it does not need a CREATE grant on the database; it suffices to provide a CONNECT grant. For more details, refer to the configuration section.
  • The READ_MODEL_DB_URL environment variable, which replaces POSTGRAPHILE_DB_URL, no longer accepts the Engine's database user credentials. Make sure to provide Read Model database user credentials instead.

Engine

  • The SWAGGER_ADMIN_URL environment variable is no longer supported. Use SWAGGER_ENGINE_ADMIN_URL instead.
  • The SWAGGER_MANAGEMENT_URL environment variable is no longer supported. Use SWAGGER_ENGINE_MANAGEMENT_URL instead.
  • The SWAGGER_KEYCLOAK_URL environment variable is no longer supported. Use SWAGGER_SECURITY_AUTH_URL instead.
  • The SWAGGER_KEYCLOAK_CLIENT_ID environment variable is no longer supported. Use SWAGGER_SECURITY_CLIENT_ID instead.
  • The SWAGGER_KEYCLOAK_CLIENT_SECRET environment variable is no longer supported. Use SWAGGER_SECURITY_CLIENT_SECRET instead.
  • The ENGINE_AUTH_SERVER_BASE_URL and JWT_TRUSTED_ISSUERS environment variables are no longer supported. Use ENGINE_ALLOWED_ISSUERS instead.
  • The JWT_ISSUER_OVERRIDE environment variable is no longer supported. Use ENGINE_ISSUER_OVERRIDE instead.
  • The ENGINE_DB_POOL_MAXIMUM_ACTIVE_CONNECTIONS environment variable is no longer supported. Use ENGINE_DB_POOL_MAXIMUM_POOL_SIZE instead.
  • The ENGINE_DB_POOL_MAXIMUM_CHECKOUT_TIME environment variable is no longer supported. Use ENGINE_DB_POOL_MAXIMUM_CONNECTION_LIFETIME instead.
  • The ENGINE_DB_POOL_MAXIMUM_IDLE_CONNECTIONS and ENGINE_DB_POOL_TIME_TO_WAIT environment variables have been removed (no substitutes).
  • The ENGINE_DB_HISTORY_PASSWORD environment variable has been removed (no substitutes).
  • The ENGINE_DB_POSTGRAPHILE_PASSWORD environment variable has been removed (no substitutes).
  • The ENGINE_POSTGRAPHILE_DB_USER environment variable has been deprecated. Use ENGINE_DB_READ_MODEL_USER instead.

History

  • The SWAGGER_KEYCLOAK_URL environment variable is no longer supported. Use SWAGGER_SECURITY_AUTH_URL instead.
  • The SWAGGER_KEYCLOAK_CLIENT_ID environment variable is no longer supported. Use SWAGGER_SECURITY_CLIENT_ID instead.
  • The SWAGGER_KEYCLOAK_CLIENT_SECRET environment variable is no longer supported. Use SWAGGER_SECURITY_CLIENT_SECRET instead.
  • The HISTORY_DB_POOL_MAXIMUM_ACTIVE_CONNECTIONS environment variable is no longer supported. Use HISTORY_DB_POOL_MAXIMUM_POOL_SIZE instead.
  • The HISTORY_DB_POOL_MAXIMUM_CHECKOUT_TIME environment variable is no longer supported. Use HISTORY_DB_POOL_MAXIMUM_CONNECTION_LIFETIME instead.
  • The HISTORY_DB_POOL_MAXIMUM_IDLE_CONNECTIONS and HISTORY_DB_POOL_TIME_TO_WAIT environment variables have been removed (no substitutes).

Read Model (previously "PostGraphile")

Everything related to "Postgraphile" is now called "Read Model" instead.

  • The Docker image has been renamed from postgraphile to read-model.

  • The POSTGRAPHILE_TRUSTED_ISSUERS environment variable is no longer supported. Use READ_MODEL_ALLOWED_ISSUERS instead.

  • The POSTGRAPHILE_PORT environment variable has been deprecated. Use READ_MODEL_PORT instead.

  • The POSTGRAPHILE_DB_URL environment variable has been deprecated. Use READ_MODEL_DB_URL instead.
  • The POSTGRAPHILE_DB_SCHEMA environment variable has been deprecated. Use READ_MODEL_DB_SCHEMA instead.
  • The POSTGRAPHILE_DB_USER environment variable has been deprecated. Use READ_MODEL_DB_USER instead.
  • The POSTGRAPHILE_ALLOWED_ISSUERS environment variable has been deprecated. Use READ_MODEL_ALLOWED_ISSUERS instead.
  • The POSTGRAPHILE_ISSUER_OVERRIDE environment variable has been deprecated. Use READ_MODEL_ISSUER_OVERRIDE instead.
  • The POSTGRAPHILE_ENGINE_HEALTH_ENDPOINT environment variable has been deprecated. Use READ_MODEL_ENGINE_HEALTH_ENDPOINT instead.
  • The POSTGRAPHILE_ENGINE_HEALTH_TIMEOUT_SECONDS environment variable has been deprecated. Use READ_MODEL_ENGINE_HEALTH_TIMEOUT_SECONDS instead.

If you want to use a different name and password for the role currently assigned to POSTGRAPHILE_DB_USER, we suggest that you rename both before bumping the Platform version.

You can use following commands for that:

alter role postgraphile with password <new_pwd>;
alter role postgraphile rename to <new_name>;

Tooling

Kotlin code generator

The Kotlin code generator has been deprecated. Use the NPL OpenAPI code generator instead, and then use the OpenAPI Generator Maven plugin or similar to generate client code in your desired language.

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_ARCHIVE_SIZE_LIMIT 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.