# Connect (/sdks/go/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.

`kubemq.NewClient` dials the broker over gRPC using an address and a `ClientId` — the ID tags this connection in broker logs, subscriptions, and management views, so pick something stable rather than a random string. `client.Ping` verifies the round trip cheaply: it returns live server info (host, version, uptime) instead of just "no error," proving the client is talking to a real broker rather than silently misconfigured. `defer client.Close()` releases the gRPC connection — skip it and you leak a transport handle per client.

**Gotchas:** a successful `NewClient` call 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 forgetting to close the client in quick scripts is a common source of leaked connections under load.

## Prerequisites [#prerequisites]

* KubeMQ server running on `localhost:50000`
* Go SDK installed (`go get github.com/kubemq-io/kubemq-go/v2`)

## Code [#code]

```go title="main.go"
// 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: go-connection.connect
// Client ID: go-connection-connect-client
//
// Run with a KubeMQ server on localhost:50000
// (see https://docs.kubemq.io/deploy).
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/kubemq-io/kubemq-go/v2"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	// Create a KubeMQ client with basic configuration.
	client, err := kubemq.NewClient(ctx,
		kubemq.WithAddress("localhost", 50000), // TODO: Replace with your KubeMQ server address
		kubemq.WithClientId("go-connection-connect-client"),
	)
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}
	defer client.Close()

	// Verify the connection by pinging the server.
	info, err := client.Ping(ctx)
	if err != nil {
		log.Fatalf("Ping failed: %v", err)
	}
	fmt.Printf("Connected successfully: host=%s version=%s uptime=%ds\n",
		info.Host, info.Version, info.ServerUpTimeSeconds)
}

// Expected output:
// Connected successfully: host=<host> version=<version> uptime=<uptime>s

```

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

1. `kubemq.NewClient(ctx, opts...)` dials the broker over gRPC and returns a connected `*Client`. The `ctx` deadline bounds the initial connection attempt only; subsequent operations use their own contexts.
2. `kubemq.WithAddress("localhost", 50000)` sets the target host and gRPC port. Replace these with your server address in production.
3. `client.Ping(ctx)` performs a lightweight health check and returns `*ServerInfo` with `Host`, `Version`, and `ServerUpTimeSeconds` from the broker.
4. `defer client.Close()` drains in-flight operations and closes the underlying gRPC connection; always call it to release transport resources.

## Related [#related]

* [Go SDK Reference](/sdks/go/reference)
* [Close](/sdks/go/how-to/connection/close)
* [Ping](/sdks/go/how-to/connection/ping)