NuvexaDB 1.0.7: One Embedded .nvx File for .NET, MAUI, and Every Other Host

A mobile app, a Kotlin service, and a desktop workbench can share one database file when they all run the same engine.

NuvexaDB is that engine. Version 1.0.7 stores BSON documents in a single portable .nvx file, queries them with NQL (Nuvexa Query Language), and can seal the file with AES-256-GCM. It runs in-process. .NET and .NET MAUI call the managed library. Java, Kotlin, Swift, Flutter, React Native, Python, Node.js, Go, and C++ load a Native AOT build of the same library through nuvexa.h (ABI v2).

A file written from Kotlin is the file Nuvexa Data Studio, a MAUI app, and a Swift host open.

The package id is Nuventra.NuvexaDB. The MauiEssentials catalog is published under Nuvyntra Labs. Both spellings are intentional.

What NuvexaDB is

NuvexaDB is a standalone embedded NoSQL database. MIT licensed. One process holds an exclusive lock on a path. Concurrent reads on that open handle are allowed. Writes stay exclusive.

It does two jobs for the host:

1. Nuventra.NuvexaDB is the engine: pages, WAL, B+tree indexes, NQL, and optional encryption. A .NET app references this package and talks to NuvexaDatabase.
2. Nuventra.NuvexaDB.Native is the same engine compiled to a shared library. Language SDKs pass UTF-8 JSON in and JSON out. They leave page layout inside the engine.

1.0.7 installs from the GitHub Release zip that matches your language and CPU. nuget.org and the language package registries are not the install path for this version. Download one zip (plus the native library when the guide says so). Leave the rest of the release page alone.

Why one file

An embedded store keeps the database next to the app: no server process, no connection string, no second deployment. NuvexaDB adds a written file format so that choice survives a language change.

Documents on new pages are BSON. Public APIs stay JSON: NuvexaDocument.Parse, NQL, Data Studio, and the C ABI. A payload that still looks like {…} reads as legacy UTF-8 JSON, so mixed files stay valid.

What you need

<rid> is the runtime id in the file name: osx-arm64, osx-x64, win-x64, win-arm64, linux-x64, linux-arm64.

Native library names inside the zip:

Python, Node, Flutter desktop, and the JVM fallback read NUVEXA_NATIVE_LIB (full path of the library). Swift, Go, and C++ read NUVEXA_NATIVE_DIR (the folder that contains it).

Create a database from .NET

dotnet new console -n Acme.Store -f net10.0
cd Acme.Store
dotnet add package Nuventra.NuvexaDB --source /path/to/unzipped-nuget

/path/to/unzipped-nuget is the folder that contains Nuventra.NuvexaDB.1.0.7.nupkg after you extract NuvexaDB-NuGet.zip.

using Nuventra.NuvexaDB;

await using var db = NuvexaDatabase.Create("app.nvx", new NuvexaCreateOptions
{
    EncryptionKey = "correct-horse" // omit or null for a plaintext file
});
// db.FormatVersion == 2

var users = db.GetCollection("users");
await users.InsertAsync(NuvexaDocument.Parse("""{"name":"Ada","age":36}"""));
await users.EnsureIndexAsync("age");
await users.EnsureIndexAsync(["city", "status"]);

var rows = await db.ExecuteAsync(
    """db.users.find({ age: { $gte: 21 } }).sort({ name: 1 }).limit(20)""");

GetCollection creates the collection when it is missing. await using closes the file. One process per path.

On MAUI, put the file under FileSystem.AppDataDirectory so the iOS and Android sandbox rules apply. Open it the same way on a later launch:

if (NuvexaDatabase.IsEncrypted(path) && string.IsNullOrEmpty(key))
{
    throw new InvalidOperationException("This .nvx is encrypted. Supply EncryptionKey.");
}

await using var opened = NuvexaDatabase.Open(path, new NuvexaOpenOptions
{
    EncryptionKey = key
});

There is no DropDatabase API. Dispose the handle, then delete the .nvx and its -wal sibling.

Typed LINQ stays on .NET:

var adults = await db.GetCollection<Person>("people").ToListAsync(p => p.Age >= 21);

The same file from another language

Other SDKs call nuvexa_create, nuvexa_insert, and nuvexa_execute. Status codes cross the boundary (0 ok, 2 encryption, 3 integrity). The SDK frees every returned string with nuvexa_free.

Kotlin:

NuvexaDatabase.create("app.nvx", "correct-horse").use { db ->
    db.insert("users", """{"name":"Ada","age":36}""")
    db.execute("db.users.find({ age: { \$gte: 21 } }).limit(20)")
}

Swift:

let db = try NuvexaDatabase.create("app.nvx", key: "correct-horse")
_ = try db.insert(collection: "users", json: #"{"name":"Ada","age":36}"#)
_ = try db.execute("db.users.find({ age: { $gte: 21 } }).limit(20)")

Each host guide on the integration page covers the empty project, the zip to unzip, create / open / close, collections, documents, and the encryption password.

NQL

NQL is the query text for Data Studio, ExecuteAsync, nuvexa query, and nuvexa_execute. Unquoted keys are accepted.

db.users.find({ "address.city": "Bengaluru", age: { $gte: 21 } })
  .sort({ lastName: 1 })
  .limit(20)
  .project({ email: 1 })

db.tickets.find({}).page(2, 200)

explain() reports ID, IXSCAN, COLLSCAN, AGGREGATE, UPDATE, or DELETE. Equality on an index prefix can IXSCAN. $lookup refuses a foreign collection larger than LookupMaxDocuments (default 100 000; 0 disables the cap).

db.<collection>.update and delete need engine 1.0.2 or later. GridFS-style bytes go through db.Files.UploadAsync / DownloadAsync (fs.files / fs.chunks).

Encryption

Pass a non-empty EncryptionKey at create time and on every later open. The passphrase is UTF-8. It is never written into the file.

The engine derives a key-encryption key with Argon2id (app Create() defaults to 16 MiB, which is the mobile setting; Data Studio and the CLI use 64 MiB). A random 32-byte data key wraps the page cipher. A verifier fails a wrong passphrase before any data page is touched. ChangeEncryptionKeyAsync re-wraps that data key. Pages stay as they are.

Opening an encrypted file without the key throws NuvexaEncryptionException. A tampered or corrupt file throws NuvexaIntegrityException and stays closed. The engine does not repair it.

Store the secret in the platform keystore: SecureStorage on MAUI, Credential Manager on Windows, Keychain on Apple, Android Keystore on Android. A local demo can use a throwaway string. A shipped app keeps that string out of source, appsettings.json, logs, and crash reports.

Data Studio, the CLI, and the editors

Nuvexa Data Studio (Nuventra.NuvexaDB.Explorer) is an Avalonia workbench for one .nvx. Windows (x64 and ARM64 .msi), macOS (unsigned .pkg into /Applications), and Linux (.deb / .rpm for x64 and ARM64). Three tabs: Database Structure, Browse Data (200-row pages), and NQL. Import and export JSON or CSV. Compact, backup, restore, and change the encryption key from the Tools menu. Drag a .nvx onto the window. An encrypted file asks for the key. Recent files remember the last 12 paths and never the passphrase.

The same session backs the Visual Studio tool window and the VS Code / Cursor custom editor. Those VSIX packages bundle nuvexa under cli/.

The standalone CLI is a global dotnet tool. Extract NuvexaDB-Cli.zip and install from that folder:

dotnet tool install -g Nuventra.NuvexaDB.Cli --add-source /path/to/NuvexaDB-Cli

nuvexa covers query, browse, explain, samples, backup, and restore. Do not dotnet add package the CLI into an application.

When something looks wrong

Where NuvexaDB sits next to the other tools

Try it

# After extracting NuvexaDB-NuGet.zip from the v1.0.7 release:
dotnet new console -n Acme.Store -f net10.0
cd Acme.Store
dotnet add package Nuventra.NuvexaDB --source /path/to/unzipped-nuget

Create app.nvx, insert one document, and run the find above. Open that file in Data Studio and run the same NQL in the NQL tab.

• Release: github.com/nuvyntralabs/NuvexaDB/releases/tag/v1.0.7
• Repository: github.com/nuvyntralabs/NuvexaDB
• Product page: nuvyntralabs.github.io/nuvexadb/
• Integration guides: nuvyntralabs.github.io/nuvexadb/integration/
• NQL: nuvyntralabs.github.io/nuvexadb/docs/query/

By Niladri