goracle

README

goracle

goracle is a package which is a database/sql/driver.Driver for connecting to Oracle DB, using Anthony Tuininga's excellent OCI wrapper, ODPI-C.

Rationale

With Go 1.9, driver-specific things are not needed, everything (I need) can be achieved with the standard database/sql library. Even calling stored procedures with OUT parameters, or sending/retrieving PL/SQL array types - just give a goracle.PlSQLArrays Option within the parameters of Exec!

Connections are pooled by default (except AS SYSOPER or AS SYSDBA).

Install

It is go get'able with go get gopkg.in/goracle.v2 iff you have ODPI-C installed.

Otherwise, after the go get failed, Install ODPI

cd $GOPATH/src/gopkg.in/goracle.v2
go generate
sudo cp -a odpi/lib/libodpic.so /usr/local/lib/
sudo ldconfig /usr/local/lib
cd ..

go install

.

Documentation

Overview

Package goracle is a database/sql/driver for Oracle DB.

The connection string for the sql.Open("goracle", connString) call can be the simple

loin/password@sid [AS SYSDBA|AS SYSOPER]

type (with sid being the sexp returned by tnsping), or in the form of

ora://login:password@sid/? \
  sysdba=0& \
  sysoper=0& \
  poolMinSessions=1& \
  poolMaxSessions=1000& \
  poolIncrement=1& \
  connectionClass=POOLED

These are the defaults. Many advocate that a static session pool (min=max, incr=0) is better, with 1-10 sessions per CPU thread. See http://docs.oracle.com/cd/E82638_01/JJUCP/optimizing-real-world-performance.htm#JJUCP-GUID-BC09F045-5D80-4AF5-93F5-FEF0531E0E1D

If you specify connectionClass, that'll reuse the same session pool without the connectionClass, but will specify it on each session acquire. Thus you can cluster the session pool with classes, or ose POOLED for DRCP.

Index

• Constants
• Variables
• func EnableDbmsOutput(ctx context.Context, conn execer) error
• func ParseConnString(connString string) (connectionParams, error)
• func ReadDbmsOutput(ctx context.Context, w io.Writer, conn preparer) error
• type Column
• type CompileError
  • func GetCompileErrors(queryer queryer, all bool) ([]CompileError, error)
  • func (ce CompileError) Error() string
• type DirectLob
  • func (dl *DirectLob) Close() error
  • func (dl *DirectLob) ReadAt(p []byte, offset int64) (int, error)
  • func (dl *DirectLob) WriteAt(p []byte, offset int64) (int, error)
• type Lob
  • func (lob *Lob) Hijack() (*DirectLob, error)
• type Number
• type Option
• type QueryColumn
  • func DescribeQuery(ctx context.Context, db execer, qry string) ([]QueryColumn, error)
• type ServerVersion
  • func GetServerVersion(db queryRower) (ServerVersion, error)

Constants

const (
	// DpiMajorVersion is the wanted major version of the underlying ODPI-C library.
	DpiMajorVersion = 2
	// DpiMinorVersion is the wanted minor version of the underlying ODPI-C library.
	DpiMinorVersion = 0

	// DriverName is set on the connection to be seen in the DB
	DriverName = "gopkg.in/rana/ora.v5 : " + Version

	// DefaultPoolMinSessions specifies the default value for minSessions for pool creation.
	DefaultPoolMinSessions = 1
	// DefaultPoolMaxSessions specifies the default value for maxSessions for pool creation.
	DefaultPoolMaxSessions = 1000
	// DefaultPoolInrement specifies the default value for increment for pool creation.
	DefaultPoolIncrement = 1
	// DefaultConnectionClass is the defailt connectionClass
	DefaultConnectionClass = "POOLED"
)

const CheckLOBWrite = true

const PlSQLArrays = Option(1)

PlSQLArrays is to signal that the slices given in arguments of Exec to be left as is - the default is to treat them as arguments for ExecMany.

const Version = "v5.0.0"

Version of this driver

Variables

var Log = func(...interface{}) error { return nil }

Log function

Functions

func EnableDbmsOutput

func EnableDbmsOutput(ctx context.Context, conn execer) error

EnableDbmsOutput enables DBMS_OUTPUT buffering on the given connection. This is required if you want to retrieve the output with ReadDbmsOutput later.

func ParseConnString

func ParseConnString(connString string) (connectionParams, error)

ParseConnString parses the given connection string into a struct.

func ReadDbmsOutput

func ReadDbmsOutput(ctx context.Context, w io.Writer, conn preparer) error

ReadDbmsOutput copies the DBMS_OUTPUT buffer into the given io.Writer.

Types

type Column

type Column struct {
	Name       string
	OracleType C.dpiOracleTypeNum
	NativeType C.dpiNativeTypeNum
	Size       C.uint32_t
	Precision  C.int16_t
	Scale      C.int8_t
	Nullable   bool
	ObjectType *C.dpiObjectType
}

Column holds the info from a column.

type CompileError

type CompileError struct {
	Owner, Name, Type    string
	Line, Position, Code int64
	Text                 string
	Warning              bool
}

CompileError represents a compile-time error as in user_errors view.

func GetCompileErrors

func GetCompileErrors(queryer queryer, all bool) ([]CompileError, error)

GetCompileErrors returns the slice of the errors in user_errors.

If all is false, only errors are returned; otherwise, warnings, too.

func (CompileError) Error

func (ce CompileError) Error() string

type DirectLob

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

func (*DirectLob) Close

func (dl *DirectLob) Close() error

func (*DirectLob) ReadAt

func (dl *DirectLob) ReadAt(p []byte, offset int64) (int, error)

func (*DirectLob) WriteAt

func (dl *DirectLob) WriteAt(p []byte, offset int64) (int, error)

type Lob

type Lob struct {
	io.Reader
	IsClob bool
}

Lob is for reading/writing a LOB.

func (*Lob) Hijack

func (lob *Lob) Hijack() (*DirectLob, error)

Hijack the underlying lob reader/writer, and return a DirectLob for reading/writing the lob directly.

After this, the Lob is unusable!

type Number

type Number string

Number as string

type Option

type Option uint8

Option for NamedArgs

type QueryColumn

type QueryColumn struct {
	Schema, Name                   string
	Type, Length, Precision, Scale int
	Nullable                       bool
	CharsetID, CharsetForm         int
}

QueryColumn is the described column.

func DescribeQuery

func DescribeQuery(ctx context.Context, db execer, qry string) ([]QueryColumn, error)

DescribeQuery describes the columns in the qry string, using DBMS_SQL.PARSE + DBMS_SQL.DESCRIBE_COLUMNS2.

This can help using unknown-at-compile-time, a.k.a. dynamic queries.

type ServerVersion

type ServerVersion struct {
	// major.maintenance.application-server.component-specific.platform-specific
	Major, Maintenance, AppServer, Component, Platform int8
}

ServerVersion data.

func GetServerVersion

func GetServerVersion(db queryRower) (ServerVersion, error)

GetServerVersion returns the Oracle product version.