diff --git a/docs/modules/ROOT/pages/installation.adoc b/docs/modules/ROOT/pages/installation.adoc index f19ee80..d100205 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 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 0f8d99d..04fb810 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 5ca5a8a..93769ed 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