Skip to main content

ZTeraDB Connection Guide

This guide explains how to create and manage a connection to ZTeraDB Server using the ZTeraDBConnection.

🚀 What is ZTeraDBConnection?

ZTeraDBConnection is the class responsible for:

  • Opening a secure connection to ZTeraDB Server
  • Authenticating with your keys
  • Executing ZQL queries
  • Streaming results efficiently
  • Managing connection pooling
  • Handling network communication
  • Closing the connection safely

It works together with ZTeraDBConfig.

You don’t need to manage sockets or databases yourself — ZTeraDB does all the heavy lifting.

🧠 How Connection Works (Simple Diagram)

Your App
   ↓
ZTeraDBConnection
   ↓
ZTeraDB Server / Your Hosted ZTeraDB Server
   ↓
Your Actual Databases

📦 Creating a Connection

import { ZTeraDBConnection } from "zteradb";

const config = JSON.parse(process.env.ZTERADB_CONFIG);

const connection = new ZTeraDBConnection(
  config,            // ZTeraDBConfig object
  "db.zteradb.com",  // Host
  7777               // Port
);

✔ Make sure you passed the same config from your .env file
✔ Ensure your host and port are correct for your ZTeraDB instance

🧪 Example: Full Working Connection

import { ZTeraDBConnection, ZTeraDBQuery } from "zteradb";

const config = JSON.parse(process.env.ZTERADB_CONFIG);

const db = new ZTeraDBConnection(config, "db1.zteradb.com", 7777);

const query = new ZTeraDBQuery("user").select();

const result = await db.run(query);

for await (const row of result) {
  console.log(row);
}

db.close();

🔑 Constructor Parameters

⚙️ config​

An instance of ZTeraDBConfig.

config = new ZTeraDBConfig([...]);

🏠 host​

The ZTeraDB endpoint assigned to your database.
Example:

"db1.zteradb.com"

🔌 port​

ZTeraDB communication port (TCP).
Default for most clusters: 7777

📌 Methods of ZTeraDBConnection

1️⃣ run(query)​

Use the run() method to execute queries created with ZTeraDBQuery.

query = new ZTeraDBQuery("user")->select();
const result = await connection.run(query);

Returned value → Async Generator​

This means you can iterate results like:

for await (const row of result) {
  console.log(row);
}

Returns an async iterable stream
Efficient for large data sets
Avoids loading all rows into memory

2️⃣ close()​

Closes all active TCP connections.

connection.close();

Always close after finishing your queries — especially in serverless environments.

✔ Best Practice: Put Config in .env

Example .env:

ZTERADB_CONFIG={
  "clientKey": "<Your ZTeraDB client key>",
  "accessKey": "<Your ZTeraDB access key>",
  "secretKey": "<Your ZTeraDB secret key>",
  "databaseID": "<Your ZTeraDB database id>",
  "env": "<dev|staging|qa|prod>",
  "responseDataType": "json"
}

Load it:

const config = JSON.parse(process.env.ZTERADB_CONFIG);

⚠️ Common Errors & Fixes

❌ Wrong host or port​

✔ Check your ZTeraDB dashboard for correct host

❌ Passing wrong config fields​

✔ Ensure all environment variables are set

❌ JSON parse error​

✔ Ensure .env contains valid JSON

❌ Connection closed early​

✔ Call await db.close() only after all queries

🎉 You’re ready to run queries!

Continue to:
👉 zteradb-query.md