Create a store

A store is the primary unit in Clustron Zaris: a distributed key-value database made up of one or more nodes. You define a store with New-ZrStore, which computes a node layout from the replication factor and per-node partition count and creates it on every manager in the active workspace. Creating a store does not start it — the nodes are defined but not yet running.

Activate a workspace first (see Connect to a cluster); New-ZrStore targets the managers in the active workspace, or the managers you pass with -Managers.

Create the store

New-ZrStore derives the node topology from the replication factor, the partitions per node, and the two starting ports.

New-ZrStore `
  -Name <StoreName> `
  -ReplicationFactor <Count> `
  -BaseClusterPort <Port> `
  -BaseClientPort <Port> `
  [-PartitionsPerNode <Count>]

Parameter	Description	Default
-Name	Name of the store. Required.	—
-ReplicationFactor	Number of copies of each partition (primary + replicas). Required. For production it must be no greater than the number of servers, so each replica lands on a different machine.	—
-BaseClusterPort	First cluster (node-to-node) port on each server. Required. Incremented per node process.	—
-BaseClientPort	First client (application) port on each server. Required. Incremented per node process.	—
-PartitionsPerNode	Target partitions per server. 1 matches production topology; raise it to observe partition-aware behavior on a single machine.	1

New-ZrStore also accepts -ReplicationMode (Async or Sync), -WriteQuorumPolicy, -AllowReplicaReads, and -Tracing. See the New-ZrStore reference for those advanced options.

Nodes are named automatically as <serverHost>-n<index>, numbered from 0 — for example, the server 10.0.0.11 produces 10.0.0.11-n0, 10.0.0.11-n1, and so on. There is no name-prefix parameter.

note

New-ZrStore creates and forks the node processes itself — the supervisor model. It cannot be used against an attach-mode manager, where an orchestrator runs the nodes; there you adopt an externally-run store with Register-ZrStore instead. See the Deployment overview.

How the layout is computed

Two numbers determine how many node processes each server runs and how they are numbered.

• Each server runs PartitionsPerNode × ReplicationFactor node processes. With the default -PartitionsPerNode 1 and -ReplicationFactor 2, that is two processes per server — one preferred primary and one replica.
• The total node count is the number of servers in the workspace multiplied by that per-server process count.

So the workspace membership, not a per-server count parameter, decides the total size — -PartitionsPerNode is recomputed against live membership on every change and never freezes a total.

How ports are assigned

Ports start at the values you provide and increment for each additional node process on the same server. Every process gets a unique cluster port and client port.

For example, with -BaseClusterPort 7811 -BaseClientPort 7861 and two processes on a server:

<host>-n0 → BaseClusterPort 7811, BaseClientPort 7861
<host>-n1 → BaseClusterPort 7812, BaseClientPort 7862

On a multi-server cluster with one process each, every server reuses the same base ports (each server has its own address). The cluster and client port ranges must not overlap — New-ZrStore rejects base ports whose derived ranges would collide.

Example: single server, partition-aware testing

This creates a store with four partitions per node on the local machine — a common development setup for observing partition routing without extra machines.

New-ZrStore `
  -Name TestStore `
  -PartitionsPerNode 4 `
  -ReplicationFactor 2 `
  -BaseClusterPort 7811 `
  -BaseClientPort 7861

On a single machine with fewer servers than the replication factor, New-ZrStore warns that replicas share a machine — acceptable for testing, but with no fault tolerance.

Example: multi-server, production topology

Activate a workspace over all managers, then create the store once. With the default -PartitionsPerNode 1, each server receives one primary plus its share of replicas.

New-ZrWorkspace prod @('10.0.0.11:7801','10.0.0.12:7801','10.0.0.13:7801') -Activate

New-ZrStore `
  -Name TestStore `
  -ReplicationFactor 2 `
  -BaseClusterPort 7811 `
  -BaseClientPort 7861

A successful run prints one SUCCESS row per manager:

Manager                Action                         Result  Message
---------------------------------------------------------------------
10.0.0.11:7801         CreateStore                    SUCCESS Created
10.0.0.12:7801         CreateStore                    SUCCESS Created
10.0.0.13:7801         CreateStore                    SUCCESS Created

After you create the store

The store configuration is registered on every manager, and the node topology exists — but nothing is running yet. Start the store with Start-ZrStore before any client connects.

warning

Choose port ranges that do not overlap with other stores or applications on the same server. Overlapping ranges, or a -PartitionsPerNode high enough that the incrementing ports collide, cause the store to fail when you start it.

Troubleshoot creation failures

Symptom	Cause	Fix
"No active Zaris manager connection"	No workspace is active	Activate a workspace, or pass -Managers
"cannot be created here — this is an attach-mode manager"	The manager runs in attach mode	Adopt the externally-run store with Register-ZrStore instead
Error on one manager, success on others	That manager is unreachable	Confirm every manager is running and reachable, then re-create
Cluster and client port ranges overlap	The base ports are too close for the per-server process count	Widen the gap between -BaseClusterPort and -BaseClientPort
Store starts, then a node fails to launch	Chosen ports are already in use	Pick free -BaseClusterPort / -BaseClientPort ranges; see Ports and networking

Next steps

• Start and stop stores — activate the store you just created.
• Multi-node configuration — plan single-server versus multi-server topologies.
• New-ZrStore reference — full topology-generation details.