Skip to main content

🔌 Connection

This guide explains how to establish, manage, and close connections to the ZTeraDB Server using the core ZTeraDBConnection client engine.

🔌 What is ZTeraDBConnection?​

The ZTeraDBConnection class serves as the primary network broker for your application. It abstracts low-level socket management and handles:

  • 🔐 Secure Handshakes: Opens and manages TCP/TLS streams directly to the server.
  • 🎫 Session Auth: Handles initial token validations using your configuration keys.
  • 🚀 High-Throughput Streaming: Executes ZQL payloads and delivers efficient buffer streams.
  • 🔄 Socket Reuse: Integrates directly with client-side connection pooling layers.

🧠 Architectural Overview​

ZTeraDB decouples your application from the underlying target systems by acting as a single database proxy router:

📦 Initializing a Connection​

The connection constructor accepts your target infrastructure endpoints along with your initialized configuration layout.

use ZTeraDB\Connection\ZTeraDBConnection;

// Signature format: ZTeraDBConnection(string $host, int $port, ZTeraDBConfig $config)
$db = new ZTeraDBConnection(
    "db.zteradb.com", 
    7777, 
    $config
);

🔑 Constructor Parameters​

ParameterTypeRequiredDescription
$hoststringYesThe remote endpoint or network IP address allocated to your cluster runtime. (e.g., "db1.zteradb.com")
$portintYesThe active TCP entry port assigned to your instance. Defaults universally to 7777.
$configZTeraDBConfigYesAn initialized, valid configuration matrix containing your authentication profile.

🎛 Client Methods​

1. run(ZTeraDBQuery $query): iterable​

Submits an abstracted ZQL query framework directly to the cluster infrastructure socket.

$query  = (new ZTeraDBQuery("user"))->select();
$result = $db->run($query);
  • Memory Optimization: This method yields an iterable data stream. Rows are parsed as they arrive over the wire rather than loading the entire payload block into memory at once. It is highly recommended to loop through datasets via foreach().

2. close(): void​

Closes active streaming connections and frees up network socket descriptors on the host device.

$db->close();

💡 Serverless Tip: Always explicitly invoke close() at the conclusion of your script, especially inside ephemeral microservice architectures (like AWS Lambda or Bref) to prevent connection leaks.

🧪 Complete Implementation Blueprint​

<?php

require_once "vendor/autoload.php";

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

// 1. Structural configuration extraction
$config = new ZTeraDBConfig([
    'client_key'         => getenv('ZTERADB_CLIENT_KEY'),
    'access_key'         => getenv('ZTERADB_ACCESS_KEY'),
    'secret_key'         => getenv('ZTERADB_SECRET_KEY'),
    'database_id'        => getenv('ZTERADB_DATABASE_ID'),
    'env'                => ENVS::dev,
    'response_data_type' => ResponseDataTypes::json
]);

// 2. Establishing the network channel
$db = new ZTeraDBConnection(
    getenv("ZTERADB_HOST"),
    (int)getenv("ZTERADB_PORT"),
    $config
);

try {
    // 3. Execution Pipeline
    $query = (new ZTeraDBQuery("user"))->select();
    $rows  = $db->run($query);

    foreach ($rows as $row) {
        print_r($row);
    }
} finally {
    // 4. Resource Cleanup
    $db->close();
}

⚠️ Troubleshooting Connection Failures​

  • ❌ Socket Exception / Timeout Errors: Usually points to incorrect network routing or network access controls blocking access.

    • Fix: Double-check your host endpoint address and make sure outbound connections on port 7777 are permitted by your firewall.

  • ❌ Authentication Rejections: The client can reach the server but your security handshake fails.

    • Fix: Ensure all required keys (client_key, access_key, secret_key, and database_id) are mapped properly through your .env loader.

  • ❌ Resource Leakage Warning: PHP warning notifications or high system socket metrics.

    • Fix: Wrap execution processes inside a structural try...finally block to make sure $db->close() runs regardless of execution errors.

🎉 Next Step​

Now that your connection pipeline is established, learn how to build complex data lookups: 👉 ZTeraDB Query Guide