ZTeraDB Connection Guide

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

---

🔌 What is ZTeraDBConnectionAsync?

ZTeraDBConnectionAsync is the Python client class responsible for:

• Opening a secure connection to ZTeraDB Server
• Authenticating with your keys
• Executing ZQL queries asynchronously
• 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 (async)
   ↓
ZTeraDBConnectionAsync
   ↓
ZTeraDB Server / Your Hosted ZTeraDB Server
   ↓
Your Actual Databases

---

📦 Creating a Connection

from zteradb.zteradb_connection import ZTeraDBConnectionAsync

connection = ZTeraDBConnectionAsync(
    config=config,          # ZTeraDBConfig object
    host="db.zteradb.com",  # Host
    port=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

import asyncio
from zteradb.zteradb_config import ZTeraDBConfig, Options, ENVS, ResponseDataTypes
from zteradb.zteradb_connection import ZTeraDBConnectionAsync
from zteradb.zteradb_query import ZTeraDBQuery

async def main():
    config = ZTeraDBConfig(
        client_key="ABC123",
        access_key="XYZ789",
        secret_key="LONG_SECRET_VALUE",
        database_id="7K3WHGOJKJJEJ3PFJM407QO25F",
        env=ENVS("dev"),
        response_data_type=ResponseDataTypes("json"),
        options=Options(connection_pool=dict(min=1, max=5))
    )

    conn = ZTeraDBConnectionAsync(
        host="YOUR_ZTERADB_HOST",
        port=7777,
        config=config
    )

    try:
        query = ZTeraDBQuery("user").select().limit(0, 10)
        result = await conn.run(query)  # returns parsed JSON or stream depending on response_data_type
        # result may be an iterator or a list depending on client behavior; check examples
        print(result)
    finally:
        await conn.close()

if __name__ == "__main__":
    asyncio.run(main())

---

🔑 Constructor Parameters

⚙️ config

An instance of ZTeraDBConfig.

config = 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 ZTeraDBConnectionAsync

1️⃣ run(query)

Execute queries created with ZTeraDBQuery.

query = ZTeraDBQuery("user").select()
result = await conn.run(query)

Returned value

You can iterate results like:

async for row in result:
    print_r(row);

---

2️⃣ close()

Always close the connection when done:

await conn.close()

Ensure closure in finally blocks or async with contexts (if supported).

---

✔ 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 in Python (example with os.getenv):

import os
from zteradb.zteradb_config import ZTeraDBConfig, Options, ENVS, ResponseDataTypes

config = ZTeraDBConfig(
    client_key=os.getenv("CLIENT_KEY"),
    access_key=os.getenv("ACCESS_KEY"),
    secret_key=os.getenv("SECRET_KEY"),
    database_id=os.getenv("DATABASE_ID"),
    env=ENVS(os.getenv("ZTERADB_ENV", "dev")),
    response_data_type=ResponseDataTypes(os.getenv("REQUEST_DATA_TYPE", "json")),
    options=Options(connection_pool=dict(
        min=int(os.getenv("MIN_CONNECTION", 1)),
        max=int(os.getenv("MAX_CONNECTION", 2))
    ))
)

⚠️ 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 await conn.close() in finally blocks

---

🎉 You are ready to run queries!

Continue to:
👉 zteradb-query.md