goracle

package module
v2.1.3+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 1, 2017 License: Apache-2.0 Imports: 18 Imported by: 0

README

Build Status GoDoc

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.

At least Go 1.9 is required!

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

Speed

Correctness and simplicity is more important than speed, but the underlying ODPI-C library helps a lot with the lower levels, so the performance is not bad.

Queries are prefetched (128 rows), but you can speed up INSERT/UPDATE/DELETE statements by providing all the subsequent parameters at once, by putting each param's subsequent elements in a separate slice:

Instead of

db.Exec("INSERT INTO table (a, b) VALUES (:1, :2)", 1, "a")
db.Exec("INSERT INTO table (a, b) VALUES (:1, :2)", 2, "b")

do

db.Exec("INSERT INTO table (a, b) VALUES (:1, :2)", []int{1, 2}, []string{"a", "b"})

.

Logging

Goracle uses github.com/go-kit/kit/log's concept of a Log function. Either set goracle.Log to a logging function globally, or (better) set the logger in the Context of ExecContext or QueryContext:

db.QueryContext(context.WithValue(ctx, goracle.LogCtxKey, logger.Log), qry)

Install

Just

go get gopkg.in/goracle.v2

and you're ready to go!

Contribute

Just as with other Go projects, you don't want to change the import paths, but you can hack on the library in place, just set up different remotes:

cd $GOPATH.src/gopkg.in/goracle.v2
git remote add upstream https://github.com/go-goracle/goracle.git
git fetch upstream
git checkout -b master upstream/master

git checkout -f master
git pull upstream master
git remote add fork git@github.com:mygithubacc/goracle
git checkout -b newfeature upstream/master

Change, experiment as you wish, then

git commit -m 'my great changes' *.go
git push fork newfeature

and you're ready to send a GitHub Pull Request from github.com/mygithubacc/goracle, newfeature branch.

As the ODPI-C sources are included as git submodule, don't forget to

git submodule update --init
# or
go generate

to update ODPI-C, too. If you want to refresh ODPI-C, you can:

cd odpi
git pull
cd ..
git add odpi
git commit -m 'upgrade odpi to <git commit hash of odpi>' odpi

Third-party

  • oracall generates a server for calling stored procedures. The "goracall" branch uses this library as the underying driver.

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

View Source 
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/goracle.v2 : " + 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 = "GORACLE"
)
View Source 
const (
	EvtStartup     = EventType(C.DPI_EVENT_STARTUP)
	EvtShutdown    = EventType(C.DPI_EVENT_SHUTDOWN)
	EvtShutdownAny = EventType(C.DPI_EVENT_SHUTDOWN_ANY)
	EvtDropDB      = EventType(C.DPI_EVENT_DROP_DB)
	EvtDereg       = EventType(C.DPI_EVENT_DEREG)
	EvtObjChange   = EventType(C.DPI_EVENT_OBJCHANGE)
	EvtQueryChange = EventType(C.DPI_EVENT_QUERYCHANGE)
)
View Source 
const (
	// 	Indicates that notifications should be sent for all operations on the table or query.
	OpAll = Operation(C.DPI_OPCODE_ALL_OPS)
	// 	Indicates that all rows have been changed in the table or query (or too many rows were changed or row information was not requested).
	OpAllRows = Operation(C.DPI_OPCODE_ALL_ROWS)
	// 	Indicates that an insert operation has taken place in the table or query.
	OpInsert = Operation(C.DPI_OPCODE_INSERT)
	// 	Indicates that an update operation has taken place in the table or query.
	OpUpdate = Operation(C.DPI_OPCODE_UPDATE)
	// 	Indicates that a delete operation has taken place in the table or query.
	OpDelete = Operation(C.DPI_OPCODE_DELETE)
	// 	Indicates that the registered table or query has been altered.
	OpAlter = Operation(C.DPI_OPCODE_ALTER)
	// 	Indicates that the registered table or query has been dropped.
	OpDrop = Operation(C.DPI_OPCODE_DROP)
	// 	An unknown operation has taken place.
	OpUnknown = Operation(C.DPI_OPCODE_UNKNOWN)
)
View Source 
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.

View Source 
const Version = "v5.0.3"

Version of this driver

Variables

View Source 
var (
	Int64   = intType{}
	Float64 = floatType{}
	Num     = numType{}
)
View Source 
var ErrNotCollection = errors.New("not collection")
View Source 
var ErrNotExist = errors.New("not exist")
View Source 
var Log = func(...interface{}) error { return nil }

Log function

Functions

func CallbackSubscr 

func CallbackSubscr(ctx unsafe.Pointer, message *C.dpiSubscrMessage)

func ContextWithLog 

func ContextWithLog(ctx context.Context, logF func(...interface{}) error) context.Context

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 MapToSlice 

func MapToSlice(qry string, metParam func(string) interface{}) (string, []interface{})

MapToSlice modifies query for map (:paramname) to :%d placeholders + slice of params.

Calls metParam for each parameter met, and returns the slice of their results.

func NamedToOrdered 

func NamedToOrdered(qry string, namedParams map[string]interface{}) (string, []interface{})

NamedToOrdered converts the query from named params (:paramname) to :%d placeholders + slice of params, copying the params verbatim.

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 Data 

type Data struct {
	NativeTypeNum C.dpiNativeTypeNum
	// contains filtered or unexported fields
}

func (*Data) Get 

func (d *Data) Get() interface{}

func (*Data) GetBool 

func (d *Data) GetBool() bool

func (*Data) GetBytes 

func (d *Data) GetBytes() []byte

func (*Data) GetFloat32 

func (d *Data) GetFloat32() float32

func (*Data) GetFloat64 

func (d *Data) GetFloat64() float64

func (*Data) GetInt64 

func (d *Data) GetInt64() int64

func (*Data) GetIntervalDS 

func (d *Data) GetIntervalDS() time.Duration

func (*Data) GetIntervalYM 

func (d *Data) GetIntervalYM() IntervalYM

func (*Data) GetLob 

func (d *Data) GetLob() *Lob

func (*Data) GetObject 

func (d *Data) GetObject() *Object

func (*Data) GetStmt 

func (d *Data) GetStmt() *statement

func (*Data) GetTime 

func (d *Data) GetTime() time.Time

func (*Data) GetUint64 

func (d *Data) GetUint64() uint64

func (*Data) IsNull 

func (d *Data) IsNull() bool

func (*Data) SetBool 

func (d *Data) SetBool(b bool)

func (*Data) SetBytes 

func (d *Data) SetBytes(b []byte)

func (*Data) SetFloat32 

func (d *Data) SetFloat32(f float32)

func (*Data) SetFloat64 

func (d *Data) SetFloat64(f float64)

func (*Data) SetInt64 

func (d *Data) SetInt64(i int64)

func (*Data) SetIntervalDS 

func (d *Data) SetIntervalDS(dur time.Duration)

func (*Data) SetIntervalYM 

func (d *Data) SetIntervalYM(ym IntervalYM)

func (*Data) SetObject 

func (d *Data) SetObject(o *Object)

func (*Data) SetStmt 

func (d *Data) SetStmt(s *statement)

func (*Data) SetTime 

func (d *Data) SetTime(t time.Time)

func (*Data) SetUint64 

func (d *Data) SetUint64(u uint64)

type DataTypeInfo 

type DataTypeInfo struct {
	OracleTypeNum                       C.dpiOracleTypeNum
	NativeTypeNum                       C.dpiNativeTypeNum
	ObjectType                          *ObjectType
	DBSize, ClientSizeInBytes, CharSize int
	Precision                           int16
	Scale                               int8
	FsPrecision                         uint8
}

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 Event 

type Event struct {
	Err     error
	Type    EventType
	DB      string
	Tables  []TableEvent
	Queries []QueryEvent
}

type EventType 

type EventType C.dpiEventType

type IntervalYM 

type IntervalYM struct {
	Years, Months int
}

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

func (*Number) Scan 

func (n *Number) Scan(v interface{}) error

func (Number) String 

func (n Number) String() string

func (Number) Value 

func (n Number) Value() (driver.Value, error)

type Object 

type Object struct {
	*ObjectType
	// contains filtered or unexported fields
}

func (Object) ClientVersion 

func (d Object) ClientVersion() (VersionInfo, error)

func (*Object) GetAttribute 

func (O *Object) GetAttribute(data *Data, i int) error

func (Object) Open 

func (d Object) Open(connString string) (driver.Conn, error)

Open returns a new connection to the database. The name is a string in a driver-specific format.

func (*Object) SetAttribute 

func (O *Object) SetAttribute(i int, data *Data) error

type ObjectAttribute 

type ObjectAttribute struct {
	Name string
	DataTypeInfo
	// contains filtered or unexported fields
}

func (ObjectAttribute) ClientVersion 

func (d ObjectAttribute) ClientVersion() (VersionInfo, error)

func (ObjectAttribute) Close 

func (A ObjectAttribute) Close() error

func (ObjectAttribute) Open 

func (d ObjectAttribute) Open(connString string) (driver.Conn, error)

Open returns a new connection to the database. The name is a string in a driver-specific format.

type ObjectCollection 

type ObjectCollection struct {
	Object
}

func (*ObjectCollection) Append 

func (O *ObjectCollection) Append(data *Data) error

func (ObjectCollection) ClientVersion 

func (d ObjectCollection) ClientVersion() (VersionInfo, error)

func (*ObjectCollection) Delete 

func (O *ObjectCollection) Delete(i int) error

func (*ObjectCollection) First 

func (O *ObjectCollection) First() (int, error)

func (*ObjectCollection) Get 

func (O *ObjectCollection) Get(data *Data, i int) error

func (*ObjectCollection) Last 

func (O *ObjectCollection) Last() (int, error)

func (*ObjectCollection) Len 

func (O *ObjectCollection) Len() (int, error)

func (*ObjectCollection) Next 

func (O *ObjectCollection) Next(i int) (int, error)

func (ObjectCollection) Open 

func (d ObjectCollection) Open(connString string) (driver.Conn, error)

Open returns a new connection to the database. The name is a string in a driver-specific format.

func (*ObjectCollection) Set 

func (O *ObjectCollection) Set(i int, data *Data) error

func (*ObjectCollection) Trim 

func (O *ObjectCollection) Trim(n int) error

type ObjectCollectionInfo 

type ObjectCollectionInfo interface {
	OracleTypeNum() C.dpiOracleTypeNum
	NativeTypeNum() C.dpiNativeTypeNum
	ObjectType() *ObjectType
}

type ObjectInfo 

type ObjectInfo interface {
	Schema() string
	Name() string
	NumAttributes() int
	IsCollection() bool
}

type ObjectType 

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

func GetObjectType 

func GetObjectType(ex execer, typeName string) (*ObjectType, error)

func (*ObjectType) Attributes 

func (t *ObjectType) Attributes() ([]ObjectAttribute, error)

func (ObjectType) ClientVersion 

func (d ObjectType) ClientVersion() (VersionInfo, error)

func (*ObjectType) Info 

func (t *ObjectType) Info() (ObjectInfo, error)

func (*ObjectType) NewObject 

func (t *ObjectType) NewObject() (*Object, error)

func (ObjectType) Open 

func (d ObjectType) Open(connString string) (driver.Conn, error)

Open returns a new connection to the database. The name is a string in a driver-specific format.

type Operation 

type Operation C.dpiOpCode

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 QueryEvent 

type QueryEvent struct {
	Operation
	ID     uint64
	Tables []TableEvent
}

type RowEvent 

type RowEvent struct {
	Operation
	Rowid string
}

type Subscription 

type Subscription struct {
	ID C.uint64_t
	// contains filtered or unexported fields
}

func (Subscription) Begin deprecated 

func (c Subscription) Begin() (driver.Tx, error)

Begin starts and returns a new transaction.

Deprecated: Drivers should implement ConnBeginTx instead (or additionally).

func (Subscription) BeginTx 

func (c Subscription) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error)

BeginTx starts and returns a new transaction. If the context is canceled by the user the sql package will call Tx.Rollback before discarding and closing the connection.

This must check opts.Isolation to determine if there is a set isolation level. If the driver does not support a non-default level and one is set or if there is a non-default isolation level that is not supported, an error must be returned.

This must also check opts.ReadOnly to determine if the read-only value is true to either set the read-only transaction property if supported or return an error if it is not supported.

func (Subscription) Break 

func (c Subscription) Break() error

func (*Subscription) Close 

func (s *Subscription) Close() error

func (Subscription) Commit 

func (c Subscription) Commit() error

func (Subscription) GetObjectType 

func (c Subscription) GetObjectType(name string) (*ObjectType, error)

func (Subscription) NewSubscription 

func (c Subscription) NewSubscription(events chan<- Event, name string) (*Subscription, error)

func (Subscription) Ping 

func (c Subscription) Ping(ctx context.Context) error

func (Subscription) Prepare 

func (c Subscription) Prepare(query string) (driver.Stmt, error)

Prepare returns a prepared statement, bound to this connection.

func (Subscription) PrepareContext 

func (c Subscription) PrepareContext(ctx context.Context, query string) (driver.Stmt, error)

PrepareContext returns a prepared statement, bound to this connection. context is for the preparation of the statement, it must not store the context within the statement itself.

func (*Subscription) Register 

func (s *Subscription) Register(qry string, params ...interface{}) error

func (Subscription) Rollback 

func (c Subscription) Rollback() error

func (Subscription) ServerVersion 

func (c Subscription) ServerVersion() (VersionInfo, error)

type TableEvent 

type TableEvent struct {
	Operation
	Name string
	Rows []RowEvent
}

type VersionInfo 

type VersionInfo struct {
	Version, Release, Update, PortRelease, PortUpdate, Full int
	ServerRelease                                           string
}

func ClientVersion 

func ClientVersion(ex execer) (VersionInfo, error)

func ServerVersion 

func ServerVersion(ex execer) (VersionInfo, error)

func (VersionInfo) String 

func (V VersionInfo) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.