Connect-ZrStore

Opens a session-wide connection to a Zaris store and remembers it for the rest of the session, so subsequent Zr data cmdlets can run without repeating the store name or endpoints. Only one store may be connected at a time.

Syntax

Connect-ZrStore -ConnectionString <string>
    [-Credential <PSCredential>] [-ManagementUrl <string>]
    [-TlsCaCert <string>] [-TlsInsecureSkipVerify] [-TimeoutSec <int>] [-Force]

Connect-ZrStore [-StoreName] <string> [-Endpoints] <string[]> [-Token <string>]
    [-Tls] [-TlsCaCert <string>] [-TlsInsecureSkipVerify] [-TimeoutSec <int>] [-Force]

Connect-ZrStore [-StoreName] <string> [-Endpoints] <string[]>
    -Credential <PSCredential> -ManagementUrl <string>
    [-Tls] [-TlsCaCert <string>] [-TlsInsecureSkipVerify] [-TimeoutSec <int>] [-Force]

Description

Connect-ZrStore establishes the ambient data-plane connection that other ClientShell cmdlets reuse. It seeds the connection from the supplied endpoints (the first endpoint is parsed as the seed node for cluster discovery) and stores the connection context in the current session.

The connection can be described in two equivalent ways, selected by parameter set:

• ConnectionString set: pass a single -ConnectionString that carries everything — zaris://host1,host2/store for plaintext or zariss://… for TLS, with the store name in the path, comma-separated seed/failover hosts, and options such as ?token=env:VAR (or file:/path/a literal), ?ca=file:/path/ca.pem, and ?tlsInsecure=true.
• StoreName/Endpoints sets: supply -StoreName and -Endpoints with the discrete -Token/-Tls/-TlsCaCert switches. Both forms remain fully supported.

Authentication is optional:

• Connect anonymously (no ?token= / no -Token) when the store has no authentication.
• Pass a fixed bearer token (JWT) — in the string with ?token= (prefer env:/file: to keep the secret out of the string), or with -Token — when the store has token-based security enabled.
• Pass -Credential and -ManagementUrl to sign in against the Management Service and obtain a self-renewing token; the password is used only for login and is not retained. -Credential/-ManagementUrl can be combined with -ConnectionString (move the seeds/store/TLS into the string and let the credential sign-in supply the token).

Transport security is enabled by the zariss:// scheme (or -Tls). When TLS is on without a CA (no ?ca= and no -TlsCaCert), the CA is auto-fetched and cached from the Management Service (this requires -ManagementUrl); otherwise supply ?ca=file:…/-TlsCaCert to pin a known CA, or ?tlsInsecure=true/-TlsInsecureSkipVerify to bypass verification for testing.

If a store is already connected, the command fails unless -Force is specified.

Parameters

Parameter	Type	Required	Description
-ConnectionString	String	Yes (ConnectionString set)	A Zaris connection string that carries the store, seeds, and options in one value, e.g. zaris://host1,host2:7861/OrdersStore (plaintext) or zariss://host:7861/OrdersStore?token=env:ZARIS_TOKEN&ca=file:/etc/zaris/ca.pem (TLS). The store name is the URI path; comma-separated hosts are seed/failover; zariss:// enables TLS; ?token=, ?ca=, and ?tlsInsecure=true supply auth and trust. An alternative to -StoreName + -Endpoints.
-StoreName	String	Yes (StoreName sets)	Name of the store to connect to. Position 0.
-Endpoints	String[]	Yes	One or more seed node endpoints in host:port form. Position 1. The first endpoint is used as the seed for discovery; the rest are retained.
-Token	String	No	Bearer token (JWT) presented at each connection's Hello when the store has token-based security enabled. Belongs to the Token parameter set. Omit when security is disabled.
-Credential	PSCredential	Yes (Credential set)	Username/password exchanged for a self-renewing token against the Management Service at -ManagementUrl. Belongs to the Credential parameter set; the password is not retained.
-ManagementUrl	String	Yes (Credential set)	Management Service base URL to sign in against, e.g. http://mgr-01:7801. Belongs to the Credential parameter set. Also used to auto-fetch the cluster CA when -Tls is set without -TlsCaCert.
-Tls	SwitchParameter	No	Uses TLS for the data-plane connection, validating each node's certificate against the cluster CA.
-TlsCaCert	String	No	Cluster CA trust anchor: a path to cluster-ca.crt or its PEM contents. When omitted with -Tls, the CA is auto-fetched and cached from the Management Service.
-TlsInsecureSkipVerify	SwitchParameter	No	DEV ONLY. Accepts any server certificate without validation; never use against a real cluster.
-TimeoutSec	Int32	No	Connection timeout in seconds. Range 1–120. Default 5.
-Force	SwitchParameter	No	Replaces an existing connection instead of failing when a store is already connected.

The command returns an object with StoreName, Endpoints, ConnectedAtUtc, LogFile, Success, and Error. A client log is written under %LOCALAPPDATA%\Clustron\ZarisClient (for example zaris-OrdersStore-20260308.log).

Examples

Connect to a store using two seed endpoints, with security disabled:

Connect-ZrStore -ConnectionString "zaris://10.0.0.11:7861,10.0.0.12:7861/OrdersStore"

The equivalent discrete form (-StoreName/-Endpoints) remains valid:

Connect-ZrStore -StoreName OrdersStore -Endpoints "10.0.0.11:7861","10.0.0.12:7861"

Connect with a fixed bearer token to a store that has token-based security enabled (prefer token=env:VAR to keep the secret out of the string):

Connect-ZrStore -ConnectionString "zaris://10.0.0.11:7861/OrdersStore?token=$jwt"

Sign in with a credential over TLS, letting the CA be auto-fetched from the Management Service:

Connect-ZrStore -ConnectionString "zariss://10.0.0.11:7861/OrdersStore" `
    -Credential (Get-Credential) -ManagementUrl "http://mgr-01:7801"

Replace an existing session connection:

Connect-ZrStore -ConnectionString "zaris://10.0.0.11:7861/OrdersStore" -Force

Related

• Disconnect-ZrStore
• Get-ZrConnection
• Test-ZrConnection
• ClientShell Overview