ZeroZ DB

https://github.com/zeroz4j/zerozdb
Admin
ZeroZ DB is a zero-impedance pure-Java database over EclipseStore that provides serialized atomic...
Tokens:13,353
Snippets:206
Trust Score:2.1
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Server Configuration Properties

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Example configuration file for the ZeroZDb standalone server.

```properties
port = 5150
bindAddress = 127.0.0.1
secret = change-me
schemaId = myapp-v3
durability = SYNC
store.shop.dir  = /data/shop
store.shop.root = com.example.ShopRoot
console.port = 8090
console.password = ops
```

--------------------------------

### Configure server properties

Source: https://github.com/zeroz4j/zerozdb/blob/main/README.md

Example configuration file defining port, schema, durability, and store locations.

```properties
port = 5150
schemaId = myapp-v3
durability = SYNC
store.shop.dir  = /data/shop
store.shop.root = com.example.ShopRoot
```

--------------------------------

### Build ZeroZ DB from Source

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Clone the repository and install the project locally using Maven.

```bash
git clone https://github.com/ZeroZ4j/zerozdb.git
cd zerozdb && mvn install
```

--------------------------------

### Run ZeroZDb standalone server

Source: https://github.com/zeroz4j/zerozdb/blob/main/README.md

Command to start the ZeroZDb server daemon using the provided JAR and configuration file.

```bash
java -cp zerozdb.jar:my-domain.jar com.zeroz4j.db.server.ZeroZDbServerMain server.properties
```

--------------------------------

### Initialize Operations Console

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Start the operations console server to browse the object graph and execute registered queries.

```java
ConsoleServer console = ConsoleServer.builder()
        .store("shop", db)
        .model(ShopRoot.class, Product.class)
        .schemaBaseline(Path.of("src/test/resources/schema-baseline.txt"))
        .queries("shop", new QueryCatalog()
                .register("by-sku", "Find a product by SKU", List.of("sku"),
                        p -> new FindBySku(p.get("sku"))))
        .password("ops")
        .port(8090)
        .start();
```

--------------------------------

### Perform a read operation

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Uses a shared lock to ensure consistent reads. Avoid returning live collections or starting writes within this block.

```java
List<Product> hot = db.read(() ->
        root.products.values().stream().filter(Product::isHot).toList());
```

--------------------------------

### Initialize ZeroZDbNode and Execute Commands

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Opens a database node and executes commands or queries. The node automatically handles ownership and client roles.

```java
ZeroZDbNode node = ZeroZDbNode.open(Path.of("data/shop"), ShopRoot::new);
long id = node.execute(new AddProduct("SKU-1"));   // DbCommand, runs on the owner
int n = node.query(new ProductCount());            // DbQuery, runs on the owner
```

--------------------------------

### Configure ZeroZDb Client-Server Mode

Source: https://github.com/zeroz4j/zerozdb/blob/main/README.md

Initializes a server instance to own store files and connects a client to execute commands and queries.

```java
// Server JVM
ZeroZDb db = ZeroZDb.open(new ShopRoot(), Path.of("data/shop"));
ZeroZDbServer server = ZeroZDbServer.builder()
        .store("shop", db).schemaId("v1").port(5150).start();

// Client JVM — commands run on the server, inside one atomic durable write-block
ZeroZDbClient client = ZeroZDbClient.connect("127.0.0.1", 5150, "v1");
long id = client.execute("shop", new AddProduct("SKU-1", "Laptop stand"));
int count = client.query("shop", new ProductCount());
```

--------------------------------

### Build and Test Commands

Source: https://github.com/zeroz4j/zerozdb/blob/main/AGENTS.md

Standard Maven commands for building the project, running tests, and generating API documentation.

```bash
mvn install          # build and install locally
mvn test             # 107 tests, about two minutes
mvn javadoc:javadoc  # API docs into target/reports/apidocs
```

--------------------------------

### Initialize and Use ZeroZ DB

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Define a root object, open the database, and perform transactional writes and reads.

```java
public class ShopRoot {
    public final Map<String, Product> products = new HashMap<>();
    public long nextId = 1;
}

ZeroZDb db = ZeroZDb.open(new ShopRoot(), Path.of("data/shop"));
ShopRoot root = db.root();

db.write(ctx -> {
    long id = root.nextId++;
    root.products.put("SKU-1", new Product(id, "Laptop stand"));
    ctx.store(root);            // the counter changed
    ctx.store(root.products);   // the map changed - storing root does NOT cover it
});

List<Product> all = db.read(() -> List.copyOf(root.products.values()));
db.close();
```

--------------------------------

### Initialize ZeroZDb Node

Source: https://github.com/zeroz4j/zerozdb/blob/main/README.md

Every JVM uses the same initialization code to either become the store owner or a client.

```java
// Every JVM runs exactly this. The first one owns the store and serves it;
// the rest discover it and become clients. Same code, same API, either role.
ZeroZDbNode node = ZeroZDbNode.open(Path.of("data/shop"), ShopRoot::new);

long id = node.execute(new AddProduct("SKU-1", "Laptop stand"));
int count = node.query(new ProductCount());
```

--------------------------------

### Initialize and Use ZeroZDb API

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Feasibility-And-Design.md

Demonstrates opening a database instance and performing concurrent reads or atomic, durable writes.

```java
Esdb db = ZeroZDb.open(storageManager);           // wraps an existing EmbeddedStorageManager
// or ZeroZDb.open(root, path) to own the manager

// Reads: concurrent, cheap, consistent (no torn state possible while a block holds the read lock)
List<Prospect> hot = db.read(() ->
    root.prospects().values().stream()
        .filter(p -> p.getStatus() == HOT)
        .toList());

// Writes: serialized, atomic, durable
db.write(ctx -> {
    prospect.setPhone("555-1234");             // plain POJO mutation — the ES way
    prospect.setCity("Berlin");
    ctx.store(prospect);                       // explicit touch: enlist + mark for flush
});
```

--------------------------------

### Initialize ZeroZDb nodes in different modes

Source: https://github.com/zeroz4j/zerozdb/blob/main/README.md

Demonstrates creating nodes for embedded, shared, and client-only operation using the ZeroZDbNode API.

```java
// Private to this JVM: no socket, one copy of the graph, full transactions.
ZeroZDbNode tenant = ZeroZDbNode.embedded(Path.of("data/tenant-42"), TenantRoot::new);

// Shared: owns and serves it if free, joins the owner if not.
ZeroZDbNode shared = ZeroZDbNode.open(Path.of("data/root"), RootSegment::new);

// Never owns data — for app JVMs in front of a dedicated server.
ZeroZDbNode app = ZeroZDbNode.builder(Path.of("data/root"), RootSegment::new)
        .mode(ZeroZDbNode.Mode.CLIENT_ONLY).build();
```

--------------------------------

### Run Tests

Source: https://github.com/zeroz4j/zerozdb/blob/main/README.md

Command to execute the project test suite.

```bash
mvn test
```

--------------------------------

### Deploy project to Maven Central

Source: https://github.com/zeroz4j/zerozdb/blob/main/RELEASING.md

Executes a clean build and deployment using the release profile. This command attaches source and javadoc jars, signs artifacts, and uploads them to the portal.

```bash
mvn clean deploy -Prelease
```

--------------------------------

### Configure LeaseFileArbiter for ZeroZDb

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Feasibility-And-Design.md

Configures the node to use LeaseFileArbiter for ownership management and opens the store in unguarded mode to avoid internal lock collisions.

```java
ZeroZDbNode.builder(...).arbiter(new LeaseFileArbiter()).ownerId("pod-7")
```

```java
ZeroZDb.openUnguarded(...)
```

--------------------------------

### Initialize and interact with ZeroZ DB

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/index.md

Opens a database instance and performs atomic write and concurrent read operations on the root object.

```java
ZeroZDb db = ZeroZDb.open(new ShopRoot(), Path.of("data/shop"));
ShopRoot root = db.root();

db.write(ctx -> {                          // atomic, and on disk when this returns
    root.products.put("SKU-1", new Product("Laptop stand"));
    ctx.store(root.products);
});

List<Product> all = db.read(() ->          // concurrent, never sees a half-applied write
        List.copyOf(root.products.values()));
```

--------------------------------

### Run Stress Application

Source: https://github.com/zeroz4j/zerozdb/blob/main/README.md

Executes the stress harness to test engine performance with virtual-thread clients.

```bash
mvn -q test-compile dependency:build-classpath -Dmdep.outputFile=target/cp.txt && java -cp "target/classes;target/test-classes;$(cat target/cp.txt)" com.zeroz4j.db.stress.StressHarness 128 120 SYNC
```

--------------------------------

### Configure cross-host ownership with LeaseFileArbiter

Source: https://github.com/zeroz4j/zerozdb/blob/main/README.md

Uses a lease-based arbiter instead of default OS file locks for reliable ownership in containerized or network-mounted environments.

```java
ZeroZDbNode.builder(dir, Root::new)
        .arbiter(new LeaseFileArbiter())      // instead of the default OS file lock
        .ownerId("pod-7")
        .build();
```

--------------------------------

### Create and Query a Maintained Index

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Feasibility-And-Design.md

Demonstrates creating a secondary index on a class field and performing an O(1) lookup. This avoids full graph scans for hot lookups.

```java
Index<String, Prospect> byCity = db.index(Prospect.class, Prospect::getCity);
Collection<Prospect> berlin = byCity.get("Berlin");   // O(1), no scan
```

--------------------------------

### Generate and Publish GPG Signing Keys

Source: https://github.com/zeroz4j/zerozdb/blob/main/RELEASING.md

Commands to generate a new GPG key pair, identify the key ID, and publish the public key to common keyservers.

```bash
# Generate. Choose RSA 4096, no expiry or a long one, and your published email address.
gpg --full-generate-key

# Find the key id (the long hex string after 'sec   rsa4096/')
gpg --list-secret-keys --keyid-format=long

# Publish the public key so Central can verify signatures
gpg --keyserver keyserver.ubuntu.com --send-keys YOUR_KEY_ID
gpg --keyserver keys.openpgp.org --send-keys YOUR_KEY_ID
```

--------------------------------

### Define database root and data models

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/start/quickstart.md

Create plain Java classes to represent the database root and data entities. No annotations or interfaces are required.

```java
public class ShopRoot {
    public final Map<String, Product> products = new HashMap<>();
    public long nextId = 1;
}

public class Product {
    public long id;
    public String sku;
    public String name;

    public Product() { }
    public Product(long id, String sku, String name) {
        this.id = id; this.sku = sku; this.name = name;
    }
}
```

--------------------------------

### Configure database durability

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Set the durability level during database opening to balance performance and data safety. OS_BUFFERED is faster but less resilient to power loss.

```java
ZeroZDb db = ZeroZDb.open(root, dir, Durability.OS_BUFFERED);
```

--------------------------------

### Configure Maven Server Credentials

Source: https://github.com/zeroz4j/zerozdb/blob/main/RELEASING.md

Add the generated publishing token credentials to your local Maven settings file. The server ID must be set to 'central'.

```xml
<settings>
  <servers>
    <server>
      <id>central</id>
      <username>THE_TOKEN_USERNAME</username>
      <password>THE_TOKEN_PASSWORD</password>
    </server>
  </servers>
</settings>
```

--------------------------------

### Implement DbCommand for Remote Execution

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Defines a command object for remote execution. Must be a plain class with public fields and a no-arg constructor; do not use records.

```java
public class AddProduct implements DbCommand<Long> {
    public String sku;                       // public fields, no-arg constructor

    public AddProduct() { }
    public AddProduct(String sku) { this.sku = sku; }

    public Long execute(WriteContext ctx, Object root) {
        ShopRoot shop = (ShopRoot) root;
        ctx.edit(shop); ctx.edit(shop.products);
        long id = shop.nextId++;
        shop.products.put(sku, new Product(id, sku));
        return id;
    }
}
```

--------------------------------

### Run Multi-Process Stress Test

Source: https://github.com/zeroz4j/zerozdb/blob/main/README.md

Executes the multi-process stress test across real JVM instances over TCP.

```bash
mvn -q test-compile dependency:build-classpath -Dmdep.outputFile=target/cp.txt && java -cp "target/classes;target/test-classes;$(cat target/cp.txt)" com.zeroz4j.db.stress.MultiJvmStress 6 16 30 SYNC
```

--------------------------------

### Perform database operations

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/start/quickstart.md

Open the database, perform atomic writes using the context, and execute read operations. Ensure objects are enlisted before mutation.

```java
try (ZeroZDb db = ZeroZDb.open(new ShopRoot(), Path.of("data/shop"))) {
    ShopRoot root = db.root();

    long id = db.writeResult(ctx -> {
        ctx.edit(root);                  // enlist BEFORE mutating
        ctx.edit(root.products);
        long newId = root.nextId++;
        root.products.put("SKU-1", new Product(newId, "SKU-1", "Laptop stand"));
        return newId;
    });

    int count = db.read(() -> root.products.size());
    System.out.println("stored " + count + " product(s), first id " + id);
}
```

--------------------------------

### Verify Rollback Compatibility

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Ensure schema changes remain compatible with previous versions by checking against a baseline file.

```java
@Test
void schemaStaysRollbackCompatible() {
    SchemaCompatibility.check(Path.of("src/test/resources/schema-baseline.txt"),
            List.of(ShopRoot.class, Product.class));
}
```

--------------------------------

### Configure GPG Signing in Maven

Source: https://github.com/zeroz4j/zerozdb/blob/main/RELEASING.md

Add the GPG key ID and passphrase to the release profile in your Maven settings file.

```xml
<profiles>
  <profile>
    <id>release</id>
    <properties>
      <gpg.keyname>YOUR_KEY_ID</gpg.keyname>
      <gpg.passphrase>YOUR_PASSPHRASE</gpg.passphrase>
    </properties>
  </profile>
</profiles>
```

--------------------------------

### Register indexes and constraints

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Indexes are maintained automatically after registration. Unique constraints trigger a rollback if violated during a write.

```java
Index<String, Product> byCategory =
        db.index("byCategory", Product.class, () -> root.products, p -> p.category);
UniqueIndex<String, Product> bySku =
        db.uniqueIndex("bySku", Product.class, () -> root.products, p -> p.sku);

List<Product> office = byCategory.get("office");   // O(1), no scan
Product one = bySku.get("SKU-1");
```

--------------------------------

### Configure Schema Evolution Renames

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Use strict schema evolution to map renamed fields during database opening.

```java
ZeroZDb.open(root, dir, Durability.SYNC,
        SchemaEvolution.strict().rename("com.x.Product#sku", "com.x.Product#code"));
```

--------------------------------

### Perform Local Reads on Client

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Executes high-speed reads on a client node. Reads occur at heap speed.

```java
try (var local = node.localReads()) {
    int count = local.read(root -> ((ShopRoot) root).products.size());  // ~130 ns
}
```

--------------------------------

### Add ZeroZ DB dependency

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/start/quickstart.md

Include the ZeroZ DB library in your Maven project configuration.

```xml
<dependency>
    <groupId>com.zeroz4j</groupId>
    <artifactId>zerozdb</artifactId>
    <version>0.1.0</version>
</dependency>
```

--------------------------------

### Perform Local Reads

Source: https://github.com/zeroz4j/zerozdb/blob/main/README.md

Access data at heap speed using local replicas, avoiding network round trips.

```java
try (var local = node.localReads()) {              // live graph if owner, replica if client
    int hot = local.read(root -> root.prospects().size());   // 130 ns, no round trip
}
```

--------------------------------

### Perform Atomic Cross-Store Writes

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Executes operations across multiple stores atomically. All participants must be owned by the local JVM.

```java
CrossStoreWrite.run(ctx -> {
    ctx.on(registry).edit(registryRoot.tenants);
    registryRoot.tenants.put(id, tenant);
    ctx.on(tenantStore).edit(tenantRoot.settings);
    tenantRoot.settings.put("locale", "de");
}, registry, tenantStore);
```

--------------------------------

### Configure Schema Evolution Strict Mode

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Feasibility-And-Design.md

Enables strict schema evolution to prevent silent data corruption, with support for explicit field renaming.

```java
SchemaEvolution.strict()
```

```java
SchemaEvolution.strict().rename("com.x.Product#sku",
  "com.x.Product#productCode")
```

```java
SchemaEvolution.lenient()
```

--------------------------------

### Manage transactions across method calls

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Use try-with-resources with WriteTransaction to ensure transactions are properly committed or rolled back. Nested transactions join the outer transaction.

```java
try (WriteTransaction tx = db.beginWrite()) {
    prospect.setPhone("555");
    tx.context().store(prospect);
    tx.commit();
}
```

--------------------------------

### Implement optimistic concurrency

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Uses baseline tracking to prevent lost updates. Throws StaleObjectException if the object was modified since the baseline was captured.

```java
long baseline = db.baseline(prospect);      // when the edit begins
...
db.write(ctx -> {
    ctx.edit(prospect);
    prospect.setPhone("555");
    ctx.storeChecked(prospect, baseline);   // throws StaleObjectException if it moved
});
```

--------------------------------

### Correcting Object Enlistment

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/guides/troubleshooting.md

Ensure that nested objects are explicitly enlisted in the context rather than just the root object to persist changes correctly.

```java
db.write(ctx -> {
    root.products.put("SKU-1", product);
    ctx.store(root);              // WRONG: the map changed, not the root
});

db.write(ctx -> {
    root.products.put("SKU-1", product);
    ctx.store(root.products);     // right
});
```

--------------------------------

### Perform atomic write blocks

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/Guide.md

Use write blocks to ensure all operations within the block are committed atomically. The block returns nothing or a value depending on the method used.

```java
db.write(ctx -> { ... });                       // returns nothing
long id = db.writeResult(ctx -> { ... ; return newId; });   // returns a value
```

--------------------------------

### Declare a field rename for schema evolution

Source: https://github.com/zeroz4j/zerozdb/blob/main/docs/guides/troubleshooting.md

Use this to explicitly map a renamed field during schema evolution to avoid data loss or unset fields.

```java
SchemaEvolution.strict().rename("com.x.Product#sku", "com.x.Product#code")
```
Tokens:
Raw