gdbc

README

GDBC - Golang JDBC Driver Wrapper

Load and use JDBC Java database drivers from go. Without Java.

IMPORTANT NOTES:

• This is VERY MUCH WIP - it 'works' but has barely been tested/benchmarked. PRs/bug reports/feature requests gratefully received.
• This repository will change. Do not rely on it yet. Compatibility is not guaranteed.
• Very likely the drivers will be split into their own modules or repos.

Supported Drivers

More may be supported, but these are the ones we package, test, and distribute.

• Microsoft SQL Server (mssql)
  • com.microsoft.sqlserver:mssql-jdbc:7.3.0.jre8-preview
• Oracle DB (oracle)
  • com.oracle:ojdbc6:12.1.0.1 (NOT distributed, as license appears to prohibit it)
• PostgreSQL (postgresql)
  • org.postgresql:postgresql:42.2.5.jre6

Building

For oracle, or if you want to build the native libraries yourself...

On osx run ./build-all.sh to build for both mac and linux.

On linux, run individual scripts e.g. ./wrapper/scripts/wrap-oracle.sh

Usage

Import oracle, mssql, or postgresql driver.

import _ "github.com/identitii/gdbc/oracle"

Use gdbc-(oracle|mssql|postgresql) as the driver name, and pass in the JDBC connection string (which is passed straight through to the driver)

pool, err = sql.Open("gdbc-oracle", "jdbc:oracle:thin:user/password@host:1521:sid")

When starting your application, it will look for the compiled driver shared library in the current directory (@executable_path) e.g. libgdbc-postgresql.dylib on mac, or libgdbc-postgresql.so on linux.

So either put the file in the current directory, or tell it where to find it like this...

DYLD_LIBRARY_PATH="path/to/the/shared/library" go run main.go

Benchmarks

The one tiny benchmark so far has these GDBC drivers about 30% faster than the pure go drivers on mac, and about 30% slower than the pure go drivers on linux.

How is this done?

GraalVM to package the java driver as a native library, then CGO to communicate with it.

Why is this done?

Because there are some databases that don't have or have incomplete or unsupported go drivers.

Initially started in order to get a fully featured oracle driver.

Also because it is fun.

TODO

• Find trusted maven repositories to download drivers
• Transaction isolation level config via driver
• Distribute binary drivers (.dylib and .so, and .dll?) via separate repositories
• Cut down the binary size from 120mb to something slightly more reasonable. (done: now 30mb)
  • Get rid of -H:IncludeResources=".*"
• Extend test suite, find existing suite?
• Test memory usage/leaking
• Linux builds
• Windows builds (waiting on graalvm support)
• CI/CD
• Implement further interfaces
  • sql/driver.Pinger
  • sql/driver.RowsColumnTypeDatabaseTypeName
  • sql/driver.RowsColumnTypeLength
  • sql/driver.RowsColumnTypeNullable
  • sql/driver.RowsColumnTypePrecisionScale
  • sql/driver.NamedValueChecker
• Allow driver specific extensions
  • Oracle continuous query notification - https://docs.oracle.com/database/121/JJDBC/dbchgnf.htm#JJDBC28815

Drivers

• sqlite? ("org.sqlite.JDBC" "jdbc:sqlite::memory:" "SELECT 1;")

Who Created This

We're a fintech startup based in Sydney, Australia.

Find this project interesting? Why not come work with us.

https://identitii.com/careers/

Thanks

https://github.com/japettyjohn/go-jdbc, which itself is partly based on https://github.com/xoba/goutil

gopher logo by Mario Furmanczyk (mfurmanc on fiverr)

Documentation

Index

• Variables
• func ParseJDBCURL(url string) (user, password, u string, err error)
• type Conn
  • func NewConn(jdbcConn JDBCConnection) Conn
• type JDBCConnection
• type JDBCDriver
• type Rows
• type Stmt
  • func (s *Stmt) Close() error
  • func (s *Stmt) Exec(args []driver.Value) (driver.Result, error)
  • func (s *Stmt) ID() int
  • func (s *Stmt) NumInput() int
  • func (s *Stmt) Query(args []driver.Value) (driver.Rows, error)
• type TransactionIsolation

Variables

var UnsupportedJDBCURL = errors.New("unsupported jdbc url")

UnsupportedJDBCURL means that no jdbc driver has been registered that accepts the url provided

Functions

func ParseJDBCURL

func ParseJDBCURL(url string) (user, password, u string, err error)

Types

type Conn

type Conn interface {
	driver.Conn
	driver.Pinger
	// contains filtered or unexported methods
}

func NewConn

func NewConn(jdbcConn JDBCConnection) Conn

type JDBCConnection

type JDBCConnection interface {
	Close(keepIsolate bool) error
	Begin() error
	Commit() error
	Rollback() error
	IsValid(timeout int) (valid bool, err error)

	Prepare(sql string) (statement int, err error)
	CloseStatement(statement int) (err error)
	NumInput(statement int) (inputs int, err error)
	Execute(statement int) (updated int, err error)
	Query(statement int) (hasResults bool, err error)
	Columns(statement int) (columnNames []string, columnTypes []string, err error)
	Next(statement int) (hasNext bool, err error)
	GetMoreResults(statement int) bool
	NextResultSet(statement int) bool

	SetByte(statement int, index int, value byte) error
	GetByte(statement int, index int) (byte, error)
	SetShort(statement int, index int, value int8) error
	GetShort(statement int, index int) (int8, error)
	SetInt(statement int, index int, value int32) error
	GetInt(statement int, index int) (value int32, err error)
	SetLong(statement int, index int, value int64) error
	GetLong(statement int, index int) (int64, error)
	SetFloat(statement int, index int, value float32) error
	GetFloat(statement int, index int) (float32, error)
	SetDouble(statement int, index int, value float64) error
	GetDouble(statement int, index int) (float64, error)
	GetBigDecimal(statement int, index int) (float64, error)
	SetString(statement int, index int, value string) error
	GetString(statement int, index int) (value string, err error)
	SetTimestamp(statement int, index int, value time.Time) error
	GetTimestamp(statement int, index int) (time.Time, error)
	SetNull(statement int, index int) error

	TestQueryJSON(query string) (result string, err error)
}

type JDBCDriver

type JDBCDriver interface {
	EnableTracing(enable bool)
	Open(url, user, password string, txIsolation TransactionIsolation) (JDBCConnection, error)
}

type Rows

type Rows interface {
	driver.RowsColumnTypeDatabaseTypeName
}

type Stmt

type Stmt struct {
	// contains filtered or unexported fields
}

func (*Stmt) Close

func (s *Stmt) Close() error

func (*Stmt) Exec

func (s *Stmt) Exec(args []driver.Value) (driver.Result, error)

func (*Stmt) ID

func (s *Stmt) ID() int

func (*Stmt) NumInput

func (s *Stmt) NumInput() int

func (*Stmt) Query

func (s *Stmt) Query(args []driver.Value) (driver.Rows, error)

type TransactionIsolation

type TransactionIsolation int

TransactionIsolation is passed through to java.sql.Connection.setTransactionIsolation method ( For more information see java.sql.Connection.TRANSACTION_READ_UNCOMMITTED etc.

const (
	TRANSACTION_NONE             TransactionIsolation = 0
	TRANSACTION_READ_UNCOMMITTED TransactionIsolation = 1
	TRANSACTION_READ_COMMITTED   TransactionIsolation = 2
	TRANSACTION_REPEATABLE_READ  TransactionIsolation = 4
	TRANSACTION_SERIALIZABLE     TransactionIsolation = 8
)