libovsdb

An OVSDB client library written in Go.

What is OVSDB?

OVSDB is the Open vSwitch Database Protocol, defined in RFC 7047. It is used primarily to manage the configuration of Open vSwitch and OVN.

Quick Start

1. Define a Model

Models are tagged Go structs that map to OVSDB tables:

type MyLogicalSwitch struct {
    UUID   string            `ovsdb:"_uuid"` // required
    Name   string            `ovsdb:"name"`
    Ports  []string          `ovsdb:"ports"`
    Config map[string]string `ovsdb:"other_config"`
}

OVSDB types map to Go types as follows:

OVSDB type	Go type
Set (min 0, max unlimited)	Slice
Set (min 0, max 1)	Pointer to scalar
Set (min 0, max N)	Array of N
Enum	Type-aliased string
Map	Map
Scalar	Equivalent Go scalar

2. Create a Database Model

dbModel, err := model.NewClientDBModel("OVN_Northbound", map[string]model.Model{
    "Logical_Switch": &MyLogicalSwitch{},
})

3. Connect

ovs, err := client.NewOVSDBClient(dbModel, client.WithEndpoint("tcp:172.18.0.4:6641"))
if err != nil { ... }

err = ovs.Connect(context.Background())
err = ovs.MonitorAll(context.Background()) // required for cache-based operations

4. Interact with the Database

// List all rows
var switches []MyLogicalSwitch
err = ovs.List(context.Background(), &switches)

// Create
ops, err := ovs.Create(&MyLogicalSwitch{Name: "foo"})
_, err = ovs.Transact(context.Background(), ops...)

// Get by index
ls := &MyLogicalSwitch{Name: "foo"}
err = ovs.Get(context.Background(), ls)

// Update
ls.Config["key"] = "value"
ops, err = ovs.Where(ls).Update(ls)
_, err = ovs.Transact(context.Background(), ops...)

// Delete
ops, err = ovs.Where(ls).Delete()
_, err = ovs.Transact(context.Background(), ops...)

For the full API — conditional queries (Where, WhereAny, WhereAll, WhereCache), client-defined indexes, Select, and cache event handlers — see the API guide.

Code Generation

modelgen generates Go model types from an OVSDB schema file, so you don't have to write them by hand. See the modelgen guide.

Package Documentation

API reference for each sub-package is available on pkg.go.dev:

Package	Description
client	OVSDB client and API
cache	Model-based cache
model	Model and database model
ovsdb	Low-level OVSDB types
mapper	Tagged struct ↔ OVSDB mapping
modelgen	Code-generator library
server	In-process test server
database	Database types and interfaces
updates	Model update helpers

Testing

Unit Tests

make test

Integration Tests

Integration tests require Docker with a running OVS container:

make integration-test

To test against a specific OVS version:

OVS_VERSION=v3.4.0 make integration-test

Contributing

See CONTRIBUTING.md.

Contact

The libovsdb community is part of ovn-kubernetes. Find us in the #libovsdb channel on the CNCF Slack server.