teradata

go-sql-teradata

Pure Go Teradata driver for database/sql.

I started creating this driver while working on another Go project and wanted to be able to connect to Teradata. The project is still in a very early phase and likely contains issues. If anyone out there is interested in using it and find any issues please let me know.

Install

go get github.com/atl3/go-sql-teradata

Basic Usage

Approach 1 - Using NewConnector

package main

import (
	"database/sql"
	"log"

	teradata "github.com/atl3/go-sql-teradata"
)

func main() {
	config := teradata.NewConfig()
	config.Host = "..."
	config.User = "..."
	config.Password = "..."

	cnctr, err := teradata.NewConnector(config)
	if err != nil {
		log.Fatal(err)
	}

	db := sql.OpenDB(cnctr)
	defer db.Close()
	//...
}

Approach 2 - Using DSN/Connection String

package main

import (
	"database/sql"
	"log"

	_ "github.com/atl3/go-sql-teradata"
)

func main() {
	db, err := sql.Open("teradata", "user:pass@host?COP=OFF&...")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()
    // ...
}

Config Options

URL Param names should follow the official JDBC driver names and values. Reference the JDBC documentation for detail descriptions of the values.

To date the connection options implemented are:

Base Options:

TLS Options:

LOB Options:

FastLoad Options:

TLS

By default the driver using SSLMode=Prefer and port 443. This means it will first attempt to connect with TLS on port 443 but won't enforce any certificate or hostname validations. Additionally it will fallback to the non-TLS port (1025 by default) if unable to establish a TLS connection.

• Setting SSLMode=REQUIRE will disable the fallback
• Setting SSLMode=VERIFY-CA will additionally enforce certification validations using one or more of the SSLCA/Base64 params
• Setting SSLMode=VERIFY-FULL will additionally enforce hostname validations.

LOB Support

LOB support is enabled by default. If its not-needed you can reduce some overhead by disabling it using LOBSupport=false config option.

By default LOBs won't be pre-fetched. Small LOBs will be inline from the server and available immediatly but large LOBs will require additional IO with the server to retreive. Example non-prefetched LOB usage (supressing err checks):

import (
	"database/sql"
	"github.com/atl3/go-sql-teradata"
)

func main() {
    ...
    var (
        id int64
        clob teradata.TeradataClob
        blob teradata.TeradataBlob
    )
    for rows.Next() {
        err := rows.Scan(&id, &clob, &blob)
        clobVal, err := clob.GetString()
        blobVal, err := blob.GetBytes()
        ...
    }
    ...
}

If you are working with small LOBs and want to avoid using TeradataClob/TeradataBlob you can enable LOB Prefetch and read directly to string/byte:

func main() {
    ...
    var (
        id int64
        clob sql.NullString
        blob []byte
    )
    for rows.Next() {
        err := rows.Scan(&id, &clob, &blob)
        ...
    }
    ...
}

FastLoad

Example:

import (
	"context"
	"fmt"
	"log"
	"time"

	teradata "github.com/atl3/go-sql-teradata"
)

func fastLoadDemo() {
	cfg := &teradata.Config{
		Host:     "...",
		User:     "...",
		Password: "...",
	}
	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
	defer cancel()

	// Create Connection
	fcon, err := teradata.NewFastLoadConnection(cfg)
	if err != nil {
		log.Fatal(err)
	}
	defer fcon.Close()

	// Begin Load
	tx, err := fcon.BeginFastLoad(ctx, "DATABASE_NAME", "TABLE_NAME", "COL1", "COL2") // ...
	if err != nil {
		log.Fatal(err)
	}
	defer tx.Close()

	// Load
	for i := range 10000 {
		_, err = tx.AddRow(ctx, i+500, fmt.Sprintf("FastLoad Demo %d", i))
		if err != nil {
			tx.Abort(ctx)
			log.Fatal(err)
		}
	}

	// End
	results, err := tx.End(ctx)
	fmt.Printf("RowsSent=%d, RowsAccepted=%d, UniqueViolations=%d\n", results.RowsSent, results.RowsAccepted, results.UniqueViolations)
	if len(results.Errors) > 0 {
		fmt.Println("Errors:")
		for _, e := range results.Errors {
			fmt.Printf(" - FastLoad Error: RowNumber=%d, Column=%s, ErrorCode=%d\n", e.RowNumber, e.Column, e.ErrorCode)
		}
	}
}

Logging

By default the driver won't log anything but you can enable trace logging as follows:

import (
	"log/slog"
	"github.com/atl3/go-sql-teradata"
)

func main() {
    handler := slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.Level(-8),
    })
    logger := slog.New(handler)

    cfg := &teradata.Config{
        ....,
        Logger: logger,
    }
    connector, err := teradata.NewConnector(cfg)
    ...
}

Not Yet Implemented / TODOs

• XML Data Type
• Stored procedure support
• ARRAY / structured UDT data types
• Query Banding

NOTE:

Teradata is a registered trademark of Teradata Corporation. This project is an independent open-source driver and is not affiliated with, endorsed by, or sponsored by Teradata Corporation.