Notions de base

Notions de base du protocole natif

La référence du protocole client est en cours.

La plupart des exemples sont uniquement en Go.

Ce document décrit le protocole binaire pour les clients TCP de ClickHouse.

​

Varint

Pour les longueurs, les codes de paquets et dans d’autres cas, l’encodage varint non signé est utilisé. Utilisez binary.PutUvarint et binary.ReadUvarint.

Le varint signé n’est pas utilisé.

​

String

Les chaînes de longueur variable sont encodées sous la forme (length, value), où length est un varint et value une chaîne UTF-8.

Vérifiez la longueur pour éviter une OOM :

0 ≤ len < MAX

Encodage

s := "Hello, world!"

// Écriture de la longueur de la chaîne en uvarint.
buf := make([]byte, binary.MaxVarintLen64)
n := binary.PutUvarint(buf, uint64(len(s)))
buf = buf[:n]

// Écriture de la valeur de la chaîne.
buf = append(buf, s...)

Décodage

r := bytes.NewReader([]byte{
    0xd, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x2c,
    0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x21,
})

// Lecture de la longueur.
n, err := binary.ReadUvarint(r)
if err != nil {
        panic(err)
}

// Vérifiez n pour éviter une OOM ou une exception d'exécution dans make().
const maxSize = 1024 * 1024 * 10 // 10 MB
if n > maxSize || n < 0 {
    panic("invalid n")
}

buf := make([]byte, n)
if _, err := io.ReadFull(r, buf); err != nil {
        panic(err)
}

fmt.Println(string(buf))
// Hello, world!

Dump hexadécimal

00000000  0d 48 65 6c 6c 6f 2c 20  77 6f 72 6c 64 21        |.Hello, world!|

Base64

DUhlbGxvLCB3b3JsZCE

Go

data := []byte{
    0xd, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x2c,
    0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x21,
}

​

Entiers

ClickHouse utilise Little Endian pour les entiers à taille fixe.

​

Int32

v := int32(1000)

// Encode.
buf := make([]byte, 8)
binary.LittleEndian.PutUint32(buf, uint32(v))

// Decode.
d := int32(binary.LittleEndian.Uint32(buf))
fmt.Println(d) // 1000

Dump hexadécimal

00000000  e8 03 00 00 00 00 00 00                           |........|

Base64

6AMAAAAAAAA

​

Booléen

Les booléens sont représentés par un octet unique : 1 correspond à true et 0 à false.