This topic provides instructions for installing, running, and modifying the go unixodbc driver for connecting to ODBC databases through unixodbc. The driver supports Go's database/sql package.

The following software packages are required to use the go unixodbc driver.

The latest driver requires the Go language 1.20 or higher.

This driver was primarily developed with support of Debian 12, however other linux distributions may work correctly providing that unixodbc is installed.

unixodbc 2.3.11 or greater must on the system your application is running on. For debian, the following packages must be installed in order for this driver to connect:

• libssl-dev
• unixodbc-common
• unixodbc-dev
• unixodbc

The driver has been developed and tested for the following databases with the corresponding driver, but may work with other proprietary databases:

Typical connection to the database can be established by importing the go unixodbc driver and opening the connection with sql.Open. The connection string to use will be specific to the database and database driver that you are using:

package main

import (
    _ "github.com/ninthclowd/unixodbc"
    "database/sql"
)

func main(){
    db = sql.Open("unixodbc", "DSN=EXAMPLE")
}

The driver supports prepared statement caching on each connection using a LRU algorithm by connecting to the database with sql.OpenDB and supplying an unixodbc.Connector:

package main

import (
    "github.com/ninthclowd/unixodbc"
    "database/sql"
)

func main(){
    db = sql.OpenDB(&unixodbc.Connector{
        ConnectionString:   unixodbc.StaticConnStr("DSN=EXAMPLE"),
        StatementCacheSize: 5, // number of prepared statements to cache per connection
    })
}

The driver supports dynamic connection strings for use in databases that require token based authentication. This can be accomplished by implementing unixodbc.ConnectionStringFactory and connecting with sql.OpenDB:

package main

import (
	"context"
	"github.com/ninthclowd/unixodbc"
	"database/sql"
)

type GetToken struct {
}

// ConnectionString implements unixodbc.ConnectionStringFactory
func (d *GetToken) ConnectionString(ctx context.Context) (connStr string, err error) {
	var token string
	// insert code to pull token for each new connection
	// ...

	// create a dynamic connection string and return it
	connStr = "DSN=EXAMPLE;UID=User;PWD=" + token
	return
}

func main() {
	db = sql.OpenDB(&unixodbc.Connector{
		ConnectionString: &GetToken{},
	})
}

To develop this code base you will need the following components installed on your system:

• standard C headers
• the unixodbc C headers
• mockgen
• c-for-go

API wrappers and mocks for unit testing are generated through go generate ./...

An example for setting up an Ubuntu WSL environment:

apt install gcc-multilib libssl-dev unixodbc-dev
go install github.com/golang/mock/[email protected]
go install https://github.com/xlab/[email protected]

At this time, most CGO driver functionality in the internal/odbc package is validated through the acceptance tests in the test/acceptance folder using the corresponding workflow and docker-compose.yml. To run these tests, ensure Docker is installed and run make test.

You may use your preferred editor to edit the driver code. If you are adding support for a new database, please include new Acceptance Tests for the database if possible. Please make fmt to format your code and make test to validate your code before submitting.