Go unixodbc driver

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.

Prerequisites

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

Go

The latest driver requires the Go language 1.20 or higher.

Operating System

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

unixodbc

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

Supported Databases and Database Drivers

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

Database	Tested Version	Database Driver
postgres	16	odbc-postgresql
Microsoft SQL Server	2022	tdsodbc
mariadb	10.9	odbc-mariadb

Configuration

Basic Connection

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")
}

Prepared Statement Caching

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
    })
}

Dynamic Connection Strings

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{},
	})
}

Development

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/mockgen@v1.6.0
go install https://github.com/xlab/c-for-go@v1.2.0

Acceptance Testing

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.

Submitting Pull Requests

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.