Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/modules/ROOT/pages/installation.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<what-is-included>>.
* *Platforms.* Intel Macs, Alpine Linux (musl) and Windows on ARM have no wheel. See <<requirements>>.

[[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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -609,6 +609,22 @@
}
]
},
{
"type": "com.arcadedb.integration.backup.Backup",
"methods": [
{
"name": "<init>",
"parameterTypes": [
"com.arcadedb.database.Database",
"java.lang.String"
]
},
{
"name": "backupDatabase",
"parameterTypes": []
}
]
},
{
"type": "com.arcadedb.log.LogFormatter",
"methods": [
Expand Down
43 changes: 43 additions & 0 deletions tests/test_sql_constraints_and_maintenance.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@

import arcadedb
from arcadedb import ArcadeDBError
from tests.conftest import TEST_PASSWORD, free_port


def _insert(db, statement):
Expand Down Expand Up @@ -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 `<root path>/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
Loading