PoolParty 10 Migration Guide

05/10/2026

Note

As of version 10.2, our application has been rebranded. The former PoolParty designation is now replaced by Graph Modeling.

The following chapter serves as an in-depth guide for migrating PoolParty 2025 R2 (9.7) to PoolParty 10 using the official migration tool in a Docker Compose environment. This migration guide includes the following topics:

An introductory overview including what prerequisites need to be met before starting the migration, how the migration tool works, as well as answers to some FAQ's
A step-by-step guide outlining both and host-centric and container-centric migration options, covering the migration process up to Graph Modeling (formerly PoolParty) version 10.2
A guide on how to upgrade Graph Modeling version 10.2 to 10.3 as data migration is handled automatically within the scope of this minor version upgrade
Note
Starting with Graph Modeling 10.3.3, data migration runs automatically during the first startup following an application update. While the manual upgrade page remains accessible, it will no longer be necessary for standard upgrades. Please note that versions prior to 10.3.3 still rely exclusively on the manual data migration process.
A page containing the most frequent troubleshooting topics

Important

This guide is partially based on the official migration tool's README.md file which can be downloaded from this repository, together with the migration tool itself. Please refer to the README.md as the ground truth, as updates to the public documentation may be comparatively slower.

Before beginning the migration, ensure the following conditions are met:

Source Version: Your PoolParty instance must be at least version 2025 R2 (9.7.1).
Host Cleanliness: Stop the running PoolParty instance on the host and verify that no lingering Java processes related to PoolParty are still running to avoid port or resource lockups.
Target Infrastructure: You have a clean GraphDB instance running, a recent version of Docker, and the docker-compose plugin.
Package Retrieval: You have downloaded the latest version of the migration tool and the compose repository.
Important
Always check out the specific release tag that matches your Graph Modeling (formerly PoolParty) version. Do not run your production environment from the main branch, as it is used for ongoing development and may contain breaking changes.
Remote Repositories: Any projects in PoolParty 2025 R2 (9.7) that reside on a remote GraphDB instance must be exported beforehand, as they will not be automatically migrated.
Configuration: Configure the POOLPARTY_9_DIR variable in your .env file to point to the installation directory of your PoolParty 2025 R2 (9.7) instance (e.g., POOLPARTY_9_DIR=/opt/poolparty).
Feature Compatibility:
- If you are migrating to PoolParty 10.1, you will have to manually refresh the index to be able to use the Relevance Scoring feature; for more details refer to Search with useRelevanceScoring.
- If you are migrating to Graph Modeling 10.2 or higher, you will have to upgrade the Elasticsearch to version 9.2.4 to ensure compatibility of versioning between Graph Modeling and GraphDB; for more details refer to Elasticsearch Upgrade Guide.

Caution

Please note that the internal database Keycloak is distributed with is only intended for non-productive environments. All configuration steps assume that you have already switched to an external PostgreSQL DB to be used by Keycloak to avoid any issues during deployment.

The PoolParty 2025 R2 (9.7) to 10 migration tool is a standalone command-line JAR file obtained by downloading a released version. It safely reads your PoolParty 2025 R2 (9.7) installation, processes the configuration and repositories, and writes the migrated files to a new, specified directory. It can be run with java -jar poolparty-10-migration-<VERSION>.jar <arguments> where <VERSION> stands for the latest version number of the migration tool.

The tool performs the following migrations:

The migration tool copies and modifies files and directories from the PoolParty 2025 R2 (9.7) home directory (<from-dir>) to the PoolParty 10 home directory (<to-dir>).
Caution
Note that data/snapshotsRoot will not be copied and any existing snapshots will be lost. The data from data/sesameRoot and data/graphdb will not be copied; however they will be exported from the repositories and then imported into GraphDB. The folders data/elasticsearch and <pp9>/auth_service/keycloak/data will not be copied as they need to be handled separately as part of Elasticsearch and Keycloak data migration. This process is described in the step-by-step procedure below.
The poolparty.properties file is copied and updated with new configuration properties:
- The three separate CORS XML files (cors-config-extractor.xml, cors-config-graphsearch.xml, cors-config-thesaurus.xml) are converted into a single set of properties within the poolparty.properties file.
- New GraphDB, Keycloak, and Elasticsearch configuration properties will be added. These configurations can be skipped by using --disable-graphdb, --disable-keycloak, and --disable-elastic, respectively.

Note

From PoolParty 10.0 onwards, only a single realm client is required to be maintained in Keycloak: the ppt realm client. The other three Keycloak realm clients used in previous PoolParty versions (ppx, ppgs, and recommender) are integrated into the ppt realm client.

The migration tool is run on the command line using the following syntax:

java -jar poolparty-10-migration-<VERSION>.jar [options] <from-dir> <to-dir>

Mandatory Arguments:

--gdb-url <url>: The URL(s) of the remote GraphDB instance.
<from-dir>: The path to the PoolParty 2025 R2 (9.7) home directory.
<to-dir>: The path to the new PoolParty 10 home directory. The tool will create this directory, so it may not already exist or must be empty.

Common Options:

--gdb-username <username>: Username for GraphDB Basic authentication.
--gdb-password <password>: Password for GraphDB Basic authentication.
--skip-remote: Skips migration of projects on remote repositories.
--local-db <dir>: Exports repositories to a local directory instead of a remote GraphDB instance (offline mode).
--gdb-license <file>: Specifies the GraphDB license file. Required for offline mode and for accurate entity index size calculation in GraphDB 10. If omitted, the system falls back to the legacy PP9 license, which may result in compatibility issues and forced default values for index sizes.
--target-pp-version <version>: Specifies the target version for migrated projects (e.g., 10.1.0). Providing a valid version ensures that all projects are correctly updated during the migration process.
--env-file <file>: Writes the configuration for GraphDB, Keycloak, Elasticsearch and CORS as an .env file instead of poolparty.properties. This option allows you to write configurations in a format suitable for various container environments.
--yaml-file <file>: Write the configuration for GraphDB, Keycloak, Elasticsearch and CORS as an environment section of a YAML file instead of poolparty.properties. This option allows you to create a YAML configuration that is compatible with Docker Compose.
--dry-run: Runs a migration simulation without writing any files or data.
--skip-broken-repositories: Skip the migration of broken repositories. This option keeps the migration tool from potentially crashing due to broken repositories and log errors that would have otherwise been caused by them.

Tip

Run the tool without any arguments or with -h/--help to view a help message listing all arguments.

Note

Starting with version 1.1.0, the migration tool includes a --patch-only flag designed to fix issues or gaps left behind by older versions of the tool (such as version 1.0.1). If a previous migration run missed certain data components, you can run the updated tool with this flag to target and fix only those missing pieces. It automatically migrates snapshots, updates GraphDB repository descriptions, organizes custom reports into their correct folders, and restores missing saved SPARQL queries.

Please note that this flag requires your repositories to have already been migrated during a previous run.

This section covers some frequently asked questions related to PoolParty 10 migration.

Both RDF4J and embedded GraphDB repositories from PoolParty 2025 R2 (9.7) are exported and either imported into a remote GraphDB instance or stored locally for offline migration. Repository names are updated to the convention summarized in the table below, where each PoolParty 10 repository must start with the pp_ prefix.

PoolParty 2025 R2 (9.7)	PoolParty 10
`pptSystem`	`pp_system`
`users`	`pp_users`
`graphSearchSystemRepository`	`pp_graphSearch`
`customschemaRepository`	`pp_customSchema`
`corpusMetaInfoRepository`	`pp_corpusMetaInfo`
`corpusRepository_xxx`	`pp_corpus_xxx`
`graphsearch_xxx`	`pp_graphsearch_xxx`
`editorRepository_xxx`	`pp_editor_xxx`
`xxx`	`pp_project_xxx`

Starting with migration tool version 1.1.0, the tool automatically processes your saved SPARQL queries. It logs the exact location of the created backup archive by default.

Example migration log output:

[INFO ] 2026-06-08 10:56:38,614 b.p.m.PoolParty10MigrationApplication] > SPARQL queries archive path: /opt/migration/pp9-data/config/sparqlqueries/sparqlqueries-20260608105501.zip

The archived .zip file is automatically extracted to that same directory on the filesystem, making the individual .sparql files directly accessible:

poolparty@server:/opt/migration/pp9-data/config/sparqlqueries$ ls -l
total 20
-rw-r----- 1 poolparty poolparty  95 Jun  8 10:55 myQuery_001.sparql
-rw-r----- 1 poolparty poolparty  95 Jun  8 10:55 myQuery_002.sparql
-rw-r----- 1 poolparty poolparty  95 Jun  8 10:55 myQuery_003.sparql
-rw-r----- 1 poolparty poolparty  72 Jun  8 10:55 myQuery_004.sparql
-rw-r--r-- 1 poolparty poolparty 867 Jun  8 10:55 sparqlqueries-20260608105501.zip

By default Graph Modeling uses fixed Elasticsearch index names (such as conceptdata, searchdata). This functionality can be enabled after having successfully migrated to Graph Modeling 10.2.

To run multiple Graph Modeling instances against a single Elasticsearch cluster, each instance must be assigned unique index names using a prefix, a suffix, or both.

Tip

For more details please refer to the README files in the docker image.

In this section: