ZTeraDB Connection Guide

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

---

🔌 What is ZTeraDBConnection?

ZTeraDBConnection is the PHP client 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

use ZTeraDB\Connection\ZTeraDBConnection;

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

✔ Make sure you have created the same config as global object
✔ Ensure your host and port are correct for your ZTeraDB instance

---

🧪 Example: Full Working Connection

use ZTeraDB\Config\ZTeraDBConfig;
use ZTeraDB\Connection\ZTeraDBConnection;
use ZTeraDB\Query\ZTeraDBQuery;
use ZTeraDB\Config\ResponseDataTypes;
use ZTeraDB\Config\ENVS;

$config = new ZTeraDBConfig([
  'client_key' => getenv('CLIENT_KEY'),
  'access_key' => getenv('ACCESS_KEY'),
  'secret_key' => getenv('SECRET_KEY'),
  'database_id' => getenv('DATABASE_ID'),
  'env' => ENVS::dev,
  'response_data_type' => ResponseDataTypes::json
]);

$db = new ZTeraDBConnection(
  getenv("ZTERADB_HOST"),
  getenv("ZTERADB_PORT"),
  $config
);

$query = (new ZTeraDBQuery("user"))->select();

foreach ($db->run($query) as $row) {
  print_r($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();
$result = $db->run($query);

Returned value

You can iterate results like:

foreach ($result as $row) {
  print_r($row);
}

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

---

2️⃣ close()

Always close the connection when done:

$db->close();

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

---

✔ Best Practice: Put Config in .env

Example .env:

CLIENT_KEY=<Your ZTeraDB client key>
ACCESS_KEY=<Your ZTeraDB access key>
SECRET_KEY=<Your ZTeraDB secret key>
DATABASE_ID=<Your ZTeraDB database id>
ZTERADB_ENV=<dev|staging|qa|prod>
REQUEST_DATA_TYPE=json
MIN_CONNECTION=1
MAX_CONNECTION=2
ZTERADB_HOST=<Your ZTeraDB host ip / name>
ZTERADB_PORT=<Your ZTeraDB port>

Load it:

$config = new ZTeraDBConfig(
  'client_key' => getenv('CLIENT_KEY'),
  'access_key' => getenv('ACCESS_KEY'),
  'secret_key' => getenv('SECRET_KEY'),
  'database_id' => getenv('DATABASE_ID'),
  'env' => getenv('ZTERADB_ENV'),
  'response_data_type' => getenv('REQUEST_DATA_TYPE'),
  'options' => new Options([              // Optional
    'connection_pool' => new ConnectionPool(
      min: (int) getenv("MIN_CONNECTION"),
      max: (int) getenv("MAX_CONNECTION")
    )
  ])
);

⚠️ Common Mistakes

❌ Wrong host or port

✔ Check your ZTeraDB dashboard for correct host

❌ Passing wrong config fields

✔ Ensure all environment variables are set

❌ Forgetting to close the connection

✔ Always call $db->close() at the end

---

🎉 You are ready to run queries!

Continue to:
👉 zteradb-query.md