From 1782425bcb7baa4fed4b297baeab87c50de4a97e Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Fri, 20 Nov 2026 13:27:46 +0900 Subject: [PATCH 1/2] Native image: keep Backup.backupDatabase() for BACKUP DATABASE, and test the statement on both wheels Upstream ArcadeData/arcadedb#12556 (fcc52e0f) registered com.arcadedb.integration.backup.Backup in its own reachability metadata: the (Database, String) constructor and backupDatabase(). BACKUP DATABASE finds the class by name; since #12412 (after the 26.11.1 release) it looks the method up inside a lambda, which native-image cannot fold, so the nightly native build lost the method (NoSuchMethodException). This file had no entry. The entry is copied as upstream has it (same type, same two methods, no flags), in this file's one-space indent and alphabetical place. At the pinned engine 26.11.1 the lookup is not yet in a lambda, so the entry is not needed there; it is needed from the first engine release that contains #12412, and it does no harm before. The only BACKUP DATABASE test is JVM-only because it sets the engine's global backup directory through JPype. The new test starts a server (the default backup directory is /backups, so nothing global is set), runs BACKUP DATABASE, finds the archive, unzips it and opens it, so it runs on the native wheel too. Not run here: no tests could be run on the authoring host. Co-Authored-By: Claude Sonnet 5.5 --- .../reachability-metadata.json | 16 +++++++ tests/test_sql_constraints_and_maintenance.py | 43 +++++++++++++++++++ 2 files changed, 59 insertions(+) diff --git a/native/src/main/resources/META-INF/native-image/org.humemai/arcadedb-native-lib/reachability-metadata.json b/native/src/main/resources/META-INF/native-image/org.humemai/arcadedb-native-lib/reachability-metadata.json index 0f8d99d8..04fb8109 100644 --- a/native/src/main/resources/META-INF/native-image/org.humemai/arcadedb-native-lib/reachability-metadata.json +++ b/native/src/main/resources/META-INF/native-image/org.humemai/arcadedb-native-lib/reachability-metadata.json @@ -609,6 +609,22 @@ } ] }, + { + "type": "com.arcadedb.integration.backup.Backup", + "methods": [ + { + "name": "", + "parameterTypes": [ + "com.arcadedb.database.Database", + "java.lang.String" + ] + }, + { + "name": "backupDatabase", + "parameterTypes": [] + } + ] + }, { "type": "com.arcadedb.log.LogFormatter", "methods": [ diff --git a/tests/test_sql_constraints_and_maintenance.py b/tests/test_sql_constraints_and_maintenance.py index 5ca5a8a7..93769ed1 100644 --- a/tests/test_sql_constraints_and_maintenance.py +++ b/tests/test_sql_constraints_and_maintenance.py @@ -17,6 +17,7 @@ import arcadedb from arcadedb import ArcadeDBError +from tests.conftest import TEST_PASSWORD, free_port def _insert(db, statement): @@ -173,3 +174,45 @@ def test_backup_check_and_rebuild_index_statements(temp_db, tmp_path): "sql", "SELECT FROM Person WHERE email = 'p7@x.org'" ).to_list() assert len(found) == 1 + + +def test_backup_database_runs_through_a_server_on_both_wheels(tmp_path): + """BACKUP DATABASE on the JVM and on the native wheel (the test above is JVM-only). + + That test sets the engine's global backup directory through JPype, which the native wheel has no JVM for. A server + takes its root path as an argument, and the default backup directory is `/backups`, so this one sets + nothing global and runs on both wheels. The statement looks `com.arcadedb.integration.backup.Backup` up by name, + and a native image keeps that class and its `backupDatabase()` method only when its reachability metadata names + them (ArcadeData/arcadedb#12556). + """ + root = tmp_path / "server" + with arcadedb.create_server( + root_path=str(root), + root_password=TEST_PASSWORD, + config={"http_port": free_port()}, + ) as server: + db = server.create_database("people") + db.command("sql", "CREATE DOCUMENT TYPE Person") + with db.transaction(): + for i in range(20): + db.command("sql", f"INSERT INTO Person SET email = 'p{i}@x.org'") + + result = db.command("sql", "BACKUP DATABASE 'person.zip'").first().to_dict() + assert result["result"] == "OK" + assert result["operation"] == "backup database" + db.close() + + archives = list(root.rglob("person.zip")) + assert [a.parent.name for a in archives] == ["people"] + assert archives[0].stat().st_size > 0 + + # the archive is the database: unzip it and open it + restored = tmp_path / "restored" + with zipfile.ZipFile(archives[0]) as zf: + zf.extractall(restored) + with arcadedb.open_database(str(restored)) as copy: + assert copy.count_type("Person") == 20 + found = copy.query( + "sql", "SELECT FROM Person WHERE email = 'p7@x.org'" + ).to_list() + assert len(found) == 1 From b752f468754016f83af7076f39094598834c1631 Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Fri, 20 Nov 2026 13:28:59 +0900 Subject: [PATCH 2/2] docs: say that a 26.11.x database must not be opened with an older wheel 26.11.1 wheels write float and double arrays in the fixed-width form (binary types 36 and 37, arcadedb.serializer.fixedWidthFloatArrays, on by default). Read from upstream: the setting's default and text at 26.11.1, ArcadeData/arcadedb#12234 (26.10.x and 26.9.1 open such a database without an error, read the arrays as null, and the next UPDATE drops them) and #12239 (fd18fce4, main only: the dictionary is labelled format version 2 while the setting is on, at the first read-write open, and builds from 26.8.1 to 26.11.x refuse it; setting it to false before that open keeps a rollback possible). The page has no upgrade or downgrade section, so a new one goes on the installation page, with the safe rule and the system property route that the durability page already documents. No static release-notes file exists: the release notes are built from pull request titles (scripts/release_notes.py). Not run: the Antora build (the Docs workflow does it). Co-Authored-By: Claude Sonnet 5.5 --- docs/modules/ROOT/pages/installation.adoc | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/modules/ROOT/pages/installation.adoc b/docs/modules/ROOT/pages/installation.adoc index f19ee806..d1002055 100644 --- a/docs/modules/ROOT/pages/installation.adoc +++ b/docs/modules/ROOT/pages/installation.adoc @@ -273,6 +273,18 @@ What the native package cannot do, or does differently from `{jvm-pkg-name}`. Re * *Engine modules left out.* The gRPC and MongoDB wire protocols, Raft HA, Gremlin and the polyglot languages (JavaScript, Python as a query language) are not in the image. See <>. * *Platforms.* Intel Macs, Alpine Linux (musl) and Windows on ARM have no wheel. See <>. +[[older-wheel]] +== Open a database with an older wheel + +Do not open a database that a 26.11.x wheel has written with a 26.10.x or older wheel. Keep a backup of the database directory before you upgrade, because a backup is the only way back. + +The wheels of both packages whose engine is 26.11.1 or later write float and double arrays, a vector embedding included, in a fixed-width form (binary types 36 and 37). The engine setting `arcadedb.serializer.fixedWidthFloatArrays` is on by default (ArcadeData/arcadedb#10904, in 26.11.1). What an older wheel does with such a database: + +* *Today, no refusal.* 26.10.x and 26.9.1 open the database without an error. Every array in the new form reads as `null`, `vector.neighbors()` never returns those records, and the next `UPDATE` of such a record, even of an unrelated property, rewrites it without its arrays. Opening the database again with a 26.11.x wheel shows them gone for good. This is what the reporter measured on 26.10.1 and 26.9.1 (ArcadeData/arcadedb#12234). In the same test, a database with a `UNIQUE_HASH` index was refused by 26.10.1 for another reason, its page layout. Do not count on that. +* *A later wheel refuses.* ArcadeData/arcadedb#12239 (merged on 2026-11-18, not in 26.11.1) labels the dictionary file of the database as format version 2 while the setting is on: a new database is created with the label, and an existing one gets it at its first read-write open, whether or not it holds an array. Builds from 26.8.1 to 26.11.x refuse to open a labelled database, so after that open 26.11.1 refuses it too. To keep the files openable by an older build, set the setting to `false` before the database is first opened by the new wheel. Turning it off later does not remove the label. The setting is read when the database opens, and records already written keep their form until they are updated. + +Set the setting as a system property before the engine starts, the way xref:how-to/durability.adoc[Durability settings] sets `arcadedb.fileSync`: `-Darcadedb.serializer.fixedWidthFloatArrays=false` in `jvm_kwargs={"jvm_args": [...]}` or in `ARCADEDB_JVM_ARGS` for `{jvm-pkg-name}`, and in `ARCADEDB_NATIVE_ISOLATE_ARGS` for `{native-pkg-name}`. No test here sets it. Check the release notes of the wheel you install to see whether it has the label. + [[in-a-container]] == In a container