fle-go

name	fle-go
summary	Field-Level Encryption with the Couchbase Go SDK — CryptoManager setup, encrypting and decrypting document fields
description	Field-Level Encryption with the Couchbase Go SDK — CryptoManager setup, encrypting and decrypting document fields
compatibility	Go SDK 2.x. gocbencryption package required.
metadata	{"last_verified":"2026-05","min_server_version":"6.0","handoff":[{"condition":"user asks about FLE concepts or supported SDKs","skill":"fle"},{"condition":"user asks about connection setup","skill":"server-connection-go"}]}

Field-Level Encryption — Go

Setup

go get github.com/couchbase/gocbencryption/v2

Configure CryptoManager

import (
    "github.com/couchbase/gocb/v2"
    "github.com/couchbase/gocbencryption/v2"
)

keyBytes := make([]byte, 64) // 64-byte key for AES-256
keyring := gocbencryption.NewInsecureKeyring()
keyring.Add(gocbencryption.Key{ID: "my-key-id", Bytes: keyBytes})

provider := gocbencryption.NewAeadAes256CbcHmacSha512Provider(keyring)
cryptoMgr := gocbencryption.NewDefaultCryptoManager(nil)
cryptoMgr.RegisterEncrypter("my-encrypter", provider.EncrypterForKey("my-key-id"))
cryptoMgr.RegisterDecrypter(provider.Decrypter())

cluster, _ := gocb.Connect("couchbase://localhost", gocb.ClusterOptions{
    Username: "username",
    Password: "Password!123",
    CryptoManager: cryptoMgr,
})
collection := cluster.Bucket("myapp").DefaultCollection()

Encrypting Fields on Write

type UserDoc struct {
    Name       string `json:"name"`
    SSN        string `json:"ssn"`
    CreditCard string `json:"credit_card"`
}

doc := UserDoc{Name: "Alice", SSN: "123-45-6789", CreditCard: "4111111111111111"}

_, err := collection.Upsert("user::alice", doc, &gocb.UpsertOptions{
    Transcoder: gocbencryption.NewEncryptingTranscoder(
        gocb.NewJSONTranscoder(),
        cryptoMgr,
        []gocbencryption.EncryptedField{
            {Name: "ssn",         EncrypterAlias: "my-encrypter"},
            {Name: "credit_card", EncrypterAlias: "my-encrypter"},
        },
    ),
})

Decrypting Fields on Read

var result UserDoc
getResult, _ := collection.Get("user::alice", &gocb.GetOptions{
    Transcoder: gocbencryption.NewEncryptingTranscoder(
        gocb.NewJSONTranscoder(),
        cryptoMgr,
        []gocbencryption.EncryptedField{
            {Name: "ssn"},
            {Name: "credit_card"},
        },
    ),
})
getResult.Content(&result)
fmt.Println(result.SSN) // "123-45-6789"

Limitations

• Encrypted fields cannot be indexed or queried with SQL++
• Adds ~30% overhead to encrypted field size
• See fle for full concept reference