# Connect (/sdks/cpp/tutorials/connect)



## Overview [#overview]

Every KubeMQ application starts the same way: open a connection to the broker and prove it actually works before building anything on top of it. This tutorial is that first lesson — create a client, give it a stable identity, and confirm connectivity with a health check, so the pattern is muscle memory before you move on to real messaging.

`ClientOptions` is populated with an address and a `client_id` — the ID tags this connection in broker logs, subscriptions, and management views, so pick something stable rather than a random string. `Client::Create()` returns a `StatusOr<unique_ptr<Client>>`, so checking `ok()` catches construction failures immediately instead of dereferencing a null client. `client->Ping()` verifies the round trip cheaply: it returns live server info (host, version, uptime) instead of just a success status, proving the client is talking to a real broker rather than silently misconfigured. `client->Close()` releases the connection explicitly, though the destructor handles it too via RAII.

**Gotchas:** a successful `Create()` doesn't always mean the broker is reachable — connection can happen lazily, so `Ping()` is the only reliable proof; reusing the same client ID across running instances causes routing confusion on the broker; and relying on the destructor instead of an explicit `Close()` in long-lived processes can delay releasing the connection longer than expected.

## Prerequisites [#prerequisites]

* KubeMQ server running on `localhost:50000`
* C++ SDK installed (vcpkg or CMake FetchContent)
* C++17 compiler (GCC 9+, Clang 9+, MSVC 2019+)

## Code [#code]

```cpp title="main.cc"
// Example: connection/connect
//
// Demonstrates how to create a basic KubeMQ client connection.
// The client connects to a KubeMQ server on localhost:50000 and verifies
// connectivity with a Ping.
//
// Channel: cpp-connection.connect
// Client ID: cpp-connection-connect-client
//
// Run with a KubeMQ server on localhost:50000
// (see https://docs.kubemq.io/deploy).

#include <kubemq/kubemq.h>

#include <iostream>

int main() {
    std::cout << "[1] Connecting to localhost:50000" << std::endl;

    // Create a KubeMQ client with basic configuration.
    kubemq::ClientOptions options;
    options.set_address("localhost", 50000);
    options.set_client_id("cpp-connection-connect-client");

    auto client_result = kubemq::Client::Create(options);
    if (!client_result.ok()) {
        std::cerr << "[ERROR] Failed to create client: " << client_result.status().message()
                  << std::endl;
        return 1;
    }
    auto& client = *client_result;

    // Verify the connection by pinging the server.
    auto ping_result = client->Ping();
    if (!ping_result.ok()) {
        std::cerr << "[ERROR] Ping failed: " << ping_result.status().message() << std::endl;
        return 1;
    }
    std::cout << "[2] Connected successfully: host=" << ping_result->host
              << " version=" << ping_result->version
              << " uptime=" << ping_result->server_up_time_seconds << "s" << std::endl;

    // Close the client explicitly.
    // Note: Client destructor would also handle cleanup (RAII)
    auto close_status = client->Close();
    if (!close_status.ok()) {
        std::cerr << "[ERROR] Close failed: " << close_status.message() << std::endl;
        return 1;
    }
    std::cout << "[3] Client closed" << std::endl;

    return 0;
}
```

## How It Works [#how-it-works]

* Creates a `ClientOptions` instance and sets the broker address and client ID.
* Calls `Client::Create()` which returns a `StatusOr<unique_ptr<Client>>` -- check `ok()` before use.
* Verifies the connection with `Ping()`, which returns server information.
* Closes the client explicitly with `Close()`. The destructor also handles cleanup (RAII).

## Related [#related]

* [C++ SDK Reference](/sdks/cpp/reference)
* [Close](/sdks/cpp/how-to/connection/close)
* [Ping](/sdks/cpp/how-to/connection/ping)