Documentation
¶
Overview ¶
Package godror is a database/sql/driver for Oracle DB.
The connection string for the sql.Open("godror", dataSourceName) call can be the simple
user="login" password="password" connectString="host:port/service_name" sysdba=true
with additional params (here with the defaults):
sysdba=0 sysoper=0 poolMinSessions=1 poolMaxSessions=1000 poolMaxSessionsPerShard= poolPingInterval= poolIncrement=1 connectionClass= standaloneConnection=0 enableEvents=0 heterogeneousPool=0 externalAuth=0 prelim=0 poolWaitTimeout=5m poolSessionMaxLifetime=1h poolSessionTimeout=30s timezone= noTimezoneCheck= newPassword= onInit="ALTER SESSION SET current_schema=my_schema" configDir= libDir= stmtCacheSize=
These are the defaults. For external authentication, user and password should be empty with default value(0) for heterogeneousPool parameter. heterogeneousPool(valid for standaloneConnection=0) and externalAuth parameters are internally set. For Proxy support , sessionuser is enclosed in brackets [sessionuser].
To use a heterogeneous Pool with Proxy Support ,user and password parameters should be non-empty and parameter heterogeneousPool should be 1. If user,password are empty and heterogeneousPool is set to 1, different user and password can be passed in subsequent queries.
Many advocate that a static session pool (min=max, incr=0) is better, with 1-10 sessions per CPU thread. See https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-7DFBA826-7CC0-4D16-B19C-31D168069B54 You may also use ConnectionParams to configure a connection.
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.
For connectionClass usage, see https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-CE6E4DCC-92DF-4946-92B8-2BDD9845DA35
If you specify server_type as POOLED in sid, DRCP is used. For what can be used as "sid", see https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-E5358DEA-D619-4B7B-A799-3D2F802500F1
Generated by generate_tznames.go. DO NOT EDIT
Index ¶
- Constants
- Variables
- func CallbackSubscr(ctx unsafe.Pointer, message *C.dpiSubscrMessage)
- func ContextWithLog(ctx context.Context, logF func(...interface{}) error) context.Context
- func ContextWithParams(ctx context.Context, commonParams dsn.CommonParams, connParams dsn.ConnParams) context.Context
- func ContextWithTraceTag(ctx context.Context, tt TraceTag) context.Context
- func ContextWithUserPassw(ctx context.Context, user, password, connClass string) context.Context
- func EnableDbmsOutput(ctx context.Context, conn Execer) error
- func IsBadConn(err error) bool
- func MapToSlice(qry string, metParam func(string) interface{}) (string, []interface{})
- func NamedToOrdered(qry string, namedParams map[string]interface{}) (string, []interface{})
- func NewConnector(params dsn.ConnectionParams) driver.Connector
- func NewDriver() *drv
- func NewLogfmtLog(w io.Writer) func(...interface{}) error
- func NewSessionIniter(m map[string]string) func(context.Context, driver.ConnPrepareContext) error
- func Raw(ctx context.Context, ex Execer, f func(driverConn Conn) error) error
- func ReadDbmsOutput(ctx context.Context, w io.Writer, conn preparer) error
- func Timezone(ctx context.Context, ex Execer) (loc *time.Location, err error)
- func WithDeqOptions(o DeqOptions) queueOption
- func WithEnqOptions(o EnqOptions) queueOption
- func WrapRows(ctx context.Context, q Querier, rset driver.Rows) (*sql.Rows, error)
- type Column
- type CommonParams
- type CompileError
- type Conn
- type ConnParams
- type ConnectionParams
- type Data
- func (d *Data) Get() interface{}
- func (d *Data) GetBool() bool
- func (d *Data) GetBytes() []byte
- func (d *Data) GetFloat32() float32
- func (d *Data) GetFloat64() float64
- func (d *Data) GetInt64() int64
- func (d *Data) GetIntervalDS() time.Duration
- func (d *Data) GetIntervalYM() IntervalYM
- func (d *Data) GetLob() *Lob
- func (d *Data) GetObject() *Object
- func (d *Data) GetStmt() driver.Stmt
- func (d *Data) GetTime() time.Time
- func (d *Data) GetTimeIn(serverTZ *time.Location) time.Time
- func (d *Data) GetUint64() uint64
- func (d *Data) IsNull() bool
- func (d *Data) IsObject() bool
- func (d *Data) Set(v interface{}) error
- func (d *Data) SetBool(b bool)
- func (d *Data) SetBytes(b []byte)
- func (d *Data) SetFloat32(f float32)
- func (d *Data) SetFloat64(f float64)
- func (d *Data) SetInt64(i int64)
- func (d *Data) SetIntervalDS(dur time.Duration)
- func (d *Data) SetIntervalYM(ym IntervalYM)
- func (d *Data) SetLob(lob *DirectLob)
- func (d *Data) SetNull()
- func (d *Data) SetObject(o *Object)
- func (d *Data) SetStmt(s *statement)
- func (d *Data) SetTime(t time.Time)
- func (d *Data) SetUint64(u uint64)
- type DeliveryMode
- type DeqMode
- type DeqNavigation
- type DeqOptions
- type DirectLob
- func (dl *DirectLob) Close() error
- func (dl *DirectLob) GetFileName() (dir, file string, err error)
- func (dl *DirectLob) ReadAt(p []byte, offset int64) (int, error)
- func (dl *DirectLob) Set(p []byte) error
- func (dl *DirectLob) Size() (int64, error)
- func (dl *DirectLob) Trim(size int64) error
- func (dl *DirectLob) WriteAt(p []byte, offset int64) (int, error)
- type EnqOptions
- type Event
- type EventType
- type Execer
- type IntervalYM
- type Lob
- type Message
- type MessageState
- type NullTime
- type Number
- func (N *Number) Compose(form byte, negative bool, coefficient []byte, exponent int32) error
- func (N Number) Decompose(buf []byte) (form byte, negative bool, coefficient []byte, exponent int32)
- func (n Number) MarshalJSON() ([]byte, error)
- func (n Number) MarshalText() ([]byte, error)
- func (n *Number) Scan(v interface{}) error
- func (n Number) String() string
- func (n *Number) UnmarshalJSON(p []byte) error
- func (n *Number) UnmarshalText(p []byte) error
- func (n Number) Value() (driver.Value, error)
- type Object
- func (O *Object) Close() error
- func (O *Object) Collection() ObjectCollection
- func (O *Object) Get(name string) (interface{}, error)
- func (O *Object) GetAttribute(data *Data, name string) error
- func (O *Object) ObjectRef() *Object
- func (O *Object) ResetAttributes() error
- func (O *Object) Set(name string, v interface{}) error
- func (O *Object) SetAttribute(name string, data *Data) error
- type ObjectAttribute
- type ObjectCollection
- func (O ObjectCollection) Append(v interface{}) error
- func (O ObjectCollection) AppendData(data *Data) error
- func (O ObjectCollection) AppendObject(obj *Object) error
- func (O ObjectCollection) AsSlice(dest interface{}) (interface{}, error)
- func (O ObjectCollection) Delete(i int) error
- func (O ObjectCollection) First() (int, error)
- func (O ObjectCollection) Get(i int) (interface{}, error)
- func (O ObjectCollection) GetItem(data *Data, i int) error
- func (O ObjectCollection) Last() (int, error)
- func (O ObjectCollection) Len() (int, error)
- func (O ObjectCollection) Next(i int) (int, error)
- func (O ObjectCollection) Set(i int, v interface{}) error
- func (O ObjectCollection) SetItem(i int, data *Data) error
- func (O ObjectCollection) Trim(n int) error
- type ObjectScanner
- type ObjectType
- func (t *ObjectType) Close() error
- func (t *ObjectType) FullName() string
- func (t *ObjectType) NewCollection() (ObjectCollection, error)
- func (t *ObjectType) NewData(baseType interface{}, sliceLen, bufSize int) ([]*Data, error)
- func (t *ObjectType) NewObject() (*Object, error)
- func (t *ObjectType) String() string
- type ObjectWriter
- type Operation
- type Option
- func ArraySize(arraySize int) Option
- func BoolToString(trueVal, falseVal string) Option
- func CallTimeout(d time.Duration) Option
- func ClobAsString() Optiondeprecated
- func DeleteFromCache() Option
- func FetchArraySize(rowCount int) Option
- func FetchRowCount(rowCount int) Option
- func LobAsReader() Option
- func NullDateAsZeroTime() Option
- func ParseOnly() Option
- func PrefetchCount(rowCount int) Option
- type OraErr
- func (oe *OraErr) Action() string
- func (oe *OraErr) Code() int
- func (oe *OraErr) Error() string
- func (oe *OraErr) FunName() string
- func (oe *OraErr) IsWarning() bool
- func (oe *OraErr) Message() string
- func (oe *OraErr) Offset() int
- func (oe *OraErr) Recoverable() bool
- func (oe *OraErr) SQLState() string
- type Password
- type PoolParams
- type PoolStats
- type Querier
- type QueryColumn
- type QueryEvent
- type Queue
- func (Q *Queue) Close() error
- func (Q *Queue) DeqOptions() (DeqOptions, error)
- func (Q *Queue) Dequeue(messages []Message) (int, error)
- func (Q *Queue) EnqOptions() (EnqOptions, error)
- func (Q *Queue) Enqueue(messages []Message) error
- func (Q *Queue) Name() string
- func (Q *Queue) SetDeqCorrelation(correlation string) error
- func (Q *Queue) SetDeqOptions(D DeqOptions) error
- func (Q *Queue) SetEnqOptions(E EnqOptions) error
- type RowEvent
- type ShutdownMode
- type StartupMode
- type Subscription
- type SubscriptionOption
- type TableEvent
- type TraceTag
- type UserPasswdConnClassTag
- type VersionInfo
- type Visibility
Examples ¶
Constants ¶
const ( // StartupDefault is the default mode for startup which permits database access to all users. StartupDefault = StartupMode(C.DPI_MODE_STARTUP_DEFAULT) // StartupForce shuts down a running instance (using ABORT) before starting a new one. This mode should only be used in unusual circumstances. StartupForce = StartupMode(C.DPI_MODE_STARTUP_FORCE) // StartupRestrict only allows database access to users with both the CREATE SESSION and RESTRICTED SESSION privileges (normally the DBA). StartupRestrict = StartupMode(C.DPI_MODE_STARTUP_RESTRICT) )
const ( // ShutdownDefault - further connections to the database are prohibited. Wait for users to disconnect from the database. ShutdownDefault = ShutdownMode(C.DPI_MODE_SHUTDOWN_DEFAULT) // ShutdownTransactional - further connections to the database are prohibited and no new transactions are allowed to be started. Wait for active transactions to complete. ShutdownTransactional = ShutdownMode(C.DPI_MODE_SHUTDOWN_TRANSACTIONAL) // ShutdownTransactionalLocal - behaves the same way as ShutdownTransactional but only waits for local transactions to complete. ShutdownTransactionalLocal = ShutdownMode(C.DPI_MODE_SHUTDOWN_TRANSACTIONAL_LOCAL) // ShutdownImmediate - all uncommitted transactions are terminated and rolled back and all connections to the database are closed immediately. ShutdownImmediate = ShutdownMode(C.DPI_MODE_SHUTDOWN_IMMEDIATE) // ShutdownAbort - all uncommitted transactions are terminated and are not rolled back. This is the fastest way to shut down the database but the next database startup may require instance recovery. ShutdownAbort = ShutdownMode(C.DPI_MODE_SHUTDOWN_ABORT) // ShutdownFinal shuts down the database. This mode should only be used in the second call to dpiConn_shutdownDatabase(). ShutdownFinal = ShutdownMode(C.DPI_MODE_SHUTDOWN_FINAL) )
const ( // DefaultFetchArraySize is the fetch array size by default (if not changed through FetchArraySize statement option). DefaultFetchArraySize = C.DPI_DEFAULT_FETCH_ARRAY_SIZE // DefaultPrefetchCountis the number of prefetched rows by default (if not changed through PrefetchCount statement option). DefaultPrefetchCount = DefaultFetchArraySize // DefaultArraySize is the length of the maximum PL/SQL array by default (if not changed through ArraySize statement option). DefaultArraySize = 1 << 10 )
const ( // DpiMajorVersion is the wanted major version of the underlying ODPI-C library. DpiMajorVersion = C.DPI_MAJOR_VERSION // DpiMinorVersion is the wanted minor version of the underlying ODPI-C library. DpiMinorVersion = C.DPI_MINOR_VERSION // DpiPatchLevel is the patch level version of the underlying ODPI-C library DpiPatchLevel = C.DPI_PATCH_LEVEL // DpiVersionNumber is the underlying ODPI-C version as one number (Major * 10000 + Minor * 100 + Patch) DpiVersionNumber = C.DPI_VERSION_NUMBER // DriverName is set on the connection to be seen in the DB // // It cannot be longer than 30 bytes ! DriverName = "godror : " + Version // DefaultPoolMinSessions specifies the default value for minSessions for pool creation. DefaultPoolMinSessions = dsn.DefaultPoolMinSessions // DefaultPoolMaxSessions specifies the default value for maxSessions for pool creation. DefaultPoolMaxSessions = dsn.DefaultPoolMaxSessions // DefaultSessionIncrement specifies the default value for increment for pool creation. DefaultSessionIncrement = dsn.DefaultSessionIncrement // DefaultPoolIncrement is a deprecated name for DefaultSessionIncrement. DefaultPoolIncrement = DefaultSessionIncrement // DefaultConnectionClass is empty, which allows to use the poolMinSessions created as part of session pool creation for non-DRCP. For DRCP, connectionClass needs to be explicitly mentioned. DefaultConnectionClass = dsn.DefaultConnectionClass // NoConnectionPoolingConnectionClass is a special connection class name to indicate no connection pooling. // It is the same as setting standaloneConnection=1 NoConnectionPoolingConnectionClass = dsn.NoConnectionPoolingConnectionClass // DefaultSessionTimeout is the seconds before idle pool sessions get evicted DefaultSessionTimeout = dsn.DefaultSessionTimeout // DefaultWaitTimeout is the milliseconds to wait for a session to become available DefaultWaitTimeout = dsn.DefaultWaitTimeout // DefaultMaxLifeTime is the maximum time in seconds till a pooled session may exist DefaultMaxLifeTime = dsn.DefaultMaxLifeTime //DefaultStandaloneConnection holds the default for standaloneConnection. DefaultStandaloneConnection = dsn.DefaultStandaloneConnection )
const ( // MsgStateReady says that "The message is ready to be processed". MsgStateReady = MessageState(C.DPI_MSG_STATE_READY) // MsgStateWaiting says that "The message is waiting for the delay time to expire". MsgStateWaiting = MessageState(C.DPI_MSG_STATE_WAITING) // MsgStateProcessed says that "The message has already been processed and is retained". MsgStateProcessed = MessageState(C.DPI_MSG_STATE_PROCESSED) // MsgStateExpired says that "The message has been moved to the exception queue". MsgStateExpired = MessageState(C.DPI_MSG_STATE_EXPIRED) )
const ( // DeliverPersistent is to Dequeue only persistent messages from the queue. This is the default mode. DeliverPersistent = DeliveryMode(C.DPI_MODE_MSG_PERSISTENT) // DeliverBuffered is to Dequeue only buffered messages from the queue. DeliverBuffered = DeliveryMode(C.DPI_MODE_MSG_BUFFERED) // DeliverPersistentOrBuffered is to Dequeue both persistent and buffered messages from the queue. DeliverPersistentOrBuffered = DeliveryMode(C.DPI_MODE_MSG_PERSISTENT_OR_BUFFERED) )
const ( // VisibleImmediate means that "The message is not part of the current transaction but constitutes a transaction of its own". VisibleImmediate = Visibility(C.DPI_VISIBILITY_IMMEDIATE) // VisibleOnCommit means that "The message is part of the current transaction. This is the default value". VisibleOnCommit = Visibility(C.DPI_VISIBILITY_ON_COMMIT) )
const ( // DeqRemove reads the message and updates or deletes it. This is the default mode. Note that the message may be retained in the queue table based on retention properties. DeqRemove = DeqMode(C.DPI_MODE_DEQ_REMOVE) // DeqBrows reads the message without acquiring a lock on the message (equivalent to a SELECT statement). DeqBrowse = DeqMode(C.DPI_MODE_DEQ_BROWSE) // DeqLocked reads the message and obtain a write lock on the message (equivalent to a SELECT FOR UPDATE statement). DeqLocked = DeqMode(C.DPI_MODE_DEQ_LOCKED) // DeqPeek confirms receipt of the message but does not deliver the actual message content. DeqPeek = DeqMode(C.DPI_MODE_DEQ_REMOVE_NO_DATA) )
const ( DeqNavigation(C.DPI_DEQ_NAV_FIRST_MSG) NavNextTran = DeqNavigation(C.DPI_DEQ_NAV_NEXT_TRANSACTION) NavNext = DeqNavigation(C.DPI_DEQ_NAV_NEXT_MSG) )NavFirst =
const ( EvtStartup = EventType(C.DPI_EVENT_STARTUP) EvtShutdown = EventType(C.DPI_EVENT_SHUTDOWN) EvtShutdownAny = EventType(C.DPI_EVENT_SHUTDOWN_ANY) EvtDereg = EventType(C.DPI_EVENT_DEREG) EvtObjChange = EventType(C.DPI_EVENT_OBJCHANGE) EvtQueryChange = EventType(C.DPI_EVENT_QUERYCHANGE) EvtAQ = EventType(C.DPI_EVENT_AQ) )
Events that can be watched.
const ( // OpAll Indicates that notifications should be sent for all operations on the table or query. OpAll = Operation(C.DPI_OPCODE_ALL_OPS) // OpAllRows 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) // OpInsert Indicates that an insert operation has taken place in the table or query. OpInsert = Operation(C.DPI_OPCODE_INSERT) // OpUpdate Indicates that an update operation has taken place in the table or query. OpUpdate = Operation(C.DPI_OPCODE_UPDATE) // OpDelete Indicates that a delete operation has taken place in the table or query. OpDelete = Operation(C.DPI_OPCODE_DELETE) // OpAlter Indicates that the registered table or query has been altered. OpAlter = Operation(C.DPI_OPCODE_ALTER) // OpDrop Indicates that the registered table or query has been dropped. OpDrop = Operation(C.DPI_OPCODE_DROP) // OpUnknown An unknown operation has taken place. OpUnknown = Operation(C.DPI_OPCODE_UNKNOWN) )
const MsgIDLength = 16
const Version = "v0.25.5"
Version of this driver
Variables ¶
var ( // Int64 for converting to-from int64. Int64 = intType{} // Float64 for converting to-from float64. Float64 = floatType{} // Num for converting to-from Number (string) Num = numType{} )
var DefaultDeqOptions = DeqOptions{ Mode: DeqRemove, DeliveryMode: DeliverPersistent, Navigation: NavNext, Visibility: VisibleOnCommit, Wait: 0, }
DefaultDeqOptions is the default set for NewQueue.
var DefaultEnqOptions = EnqOptions{ Visibility: VisibleOnCommit, DeliveryMode: DeliverPersistent, }
DefaultEnqOptions is the default set for NewQueue.
var ErrNoSuchKey = errors.New("no such key")
ErrNoSuchKey is the error for missing key in lookup.
var ErrNotCollection = errors.New("not collection")
ErrNotCollection is returned when the Object is not a collection.
var ErrNotExist = errors.New("not exist")
ErrNotExist is returned when the collection's requested element does not exist.
var ErrNotSupported = errors.New("not supported")
var Log func(...interface{}) error
Log function. By default, it's nil, and thus logs nothing. If you want to change this, change it to a github.com/go-kit/kit/log.Swapper.Log or analog to be race-free.
Functions ¶
func CallbackSubscr ¶
func CallbackSubscr(ctx unsafe.Pointer, message *C.dpiSubscrMessage)
CallbackSubscr is the callback for C code on subscription event.
func ContextWithLog ¶
ContextWithLog returns a context with the given log function.
func ContextWithParams ¶
func ContextWithParams(ctx context.Context, commonParams dsn.CommonParams, connParams dsn.ConnParams) context.Context
ContextWithParams returns a context with the specified parameters. These parameters are used to modify the session acquired from the pool.
WARNING: set ALL the parameters you don't want as default (Timezone, for example), as it won't inherit the pool's params! Start from an already parsed ConnectionParams for example.
If a standalone connection is being used this will have no effect.
Also, you should disable the Go connection pool with DB.SetMaxIdleConns(0).
func ContextWithTraceTag ¶
ContextWithTraceTag returns a context with the specified TraceTag, which will be set on the session used.
func ContextWithUserPassw ¶
ContextWithUserPassw returns a context with the specified user and password, to be used with heterogeneous pools.
WARNING: this will NOT set other elements of the parameter hierarchy, they will be inherited.
If a standalone connection is being used this will have no effect.
Also, you should disable the Go connection pool with DB.SetMaxIdleConns(0).
func EnableDbmsOutput ¶
EnableDbmsOutput enables DBMS_OUTPUT buffering on the given connection. This is required if you want to retrieve the output with ReadDbmsOutput later.
Warning! EnableDbmsOutput, the code that uses DBMS_OUTPUT and ReadDbmsOutput must all execute on the same session - for example by using the same *sql.Tx, or *sql.Conn. A *sql.DB connection pool won't work!
func MapToSlice ¶
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 ¶
NamedToOrdered converts the query from named params (:paramname) to :%d placeholders + slice of params, copying the params verbatim.
func NewConnector ¶
func NewConnector(params dsn.ConnectionParams) driver.Connector
NewConnector returns a driver.Connector to be used with sql.OpenDB, (for the default Driver registered with godror)
ConnectionParams must be complete, so start with what ParseDSN returns!
func NewLogfmtLog ¶
NewLogfmtLog returns a function that can be used as the Log variable, and that logs using logfmt, to the given io.Writer.
func NewSessionIniter ¶
NewSessionIniter returns a function suitable for use in NewConnector as onInit,
Deprecated. Use ParseDSN + ConnectionParams.SetSessionParamOnInit and NewConnector. which calls "ALTER SESSION SET <key>='<value>'" for each element of the given map.
func ReadDbmsOutput ¶
ReadDbmsOutput copies the DBMS_OUTPUT buffer into the given io.Writer.
Be sure that you enable it beforehand (either with EnableDbmsOutput or with DBMS_OUTPUT.enable(NULL))
Warning! EnableDbmsOutput, the code that uses DBMS_OUTPUT and ReadDbmsOutput must all execute on the same session - for example by using the same *sql.Tx, or *sql.Conn. A *sql.DB connection pool won't work!
func WithDeqOptions ¶
func WithDeqOptions(o DeqOptions) queueOption
WithDeqOptions returns a queueOption usable in NewQueue, applying the given DeqOptions.
func WithEnqOptions ¶
func WithEnqOptions(o EnqOptions) queueOption
WithEnqOptions returns a queueOption usable in NewQueue, applying the given EnqOptions.
Types ¶
type Column ¶
type Column struct { ObjectType *C.dpiObjectType Name string OracleType C.dpiOracleTypeNum NativeType C.dpiNativeTypeNum Size, SizeInChars, DBSize C.uint32_t Precision C.int16_t Scale C.int8_t Nullable bool }
Column holds the info from a column.
type CommonParams ¶
type CommonParams = dsn.CommonParams
dsn is separated out for fuzzing, but keep it as "internal"
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 ¶
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 Conn ¶
type Conn interface { driver.Conn driver.ConnBeginTx driver.ConnPrepareContext driver.Pinger Break() error Commit() error Rollback() error ClientVersion() (VersionInfo, error) ServerVersion() (VersionInfo, error) GetObjectType(name string) (*ObjectType, error) NewSubscription(string, func(Event), ...SubscriptionOption) (*Subscription, error) Startup(StartupMode) error Shutdown(ShutdownMode) error NewData(baseType interface{}, SliceLen, BufSize int) ([]*Data, error) Timezone() *time.Location GetPoolStats() (PoolStats, error) }
Conn is the interface for a connection, to be returned by DriverConn.
type ConnParams ¶
type ConnParams = dsn.ConnParams
dsn is separated out for fuzzing, but keep it as "internal"
type ConnectionParams ¶
type ConnectionParams = dsn.ConnectionParams
dsn is separated out for fuzzing, but keep it as "internal"
func ParseConnString ¶
func ParseConnString(s string) (ConnectionParams, error)
ParseConnString is deprecated, use ParseDSN.
func ParseDSN ¶
func ParseDSN(dataSourceName string) (P ConnectionParams, err error)
ParseDSN parses the given dataSourceName and returns a ConnectionParams structure for use in sql.OpenDB(godror.NewConnector(P)).
type Data ¶
type Data struct { ObjectType *ObjectType NativeTypeNum C.dpiNativeTypeNum // contains filtered or unexported fields }
Data holds the data to/from Oracle.
func NewData ¶
NewData creates a new Data structure for the given type, populated with the given type.
func (*Data) GetFloat32 ¶
GetFloat32 gets float32 from the data.
func (*Data) GetFloat64 ¶
GetFloat64 gets float64 from the data.
func (*Data) GetIntervalDS ¶
GetIntervalDS gets duration as interval date-seconds from data.
func (*Data) GetIntervalYM ¶
func (d *Data) GetIntervalYM() IntervalYM
GetIntervalYM gets IntervalYM from the data.
func (*Data) GetObject ¶
GetObject gets Object from data.
As with all Objects, you MUST call Close on it when not needed anymore!
func (*Data) GetTimeIn ¶
GetTimeIn gets Time from data using the given Location (use the server's for correct value).
func (*Data) SetIntervalDS ¶
SetIntervalDS sets the duration as interval date-seconds to data.
func (*Data) SetIntervalYM ¶
func (d *Data) SetIntervalYM(ym IntervalYM)
SetIntervalYM sets IntervalYM to the data.
type DeqOptions ¶
type DeqOptions struct {
Condition, Consumer, Correlation string
MsgID, Transformation string
Mode DeqMode
DeliveryMode DeliveryMode
Visibility Visibility
Wait time.Duration
}
DeqOptions are the options used to dequeue a message.
type DirectLob ¶
type DirectLob struct {
// contains filtered or unexported fields
}
DirectLob holds a Lob and allows direct (Read/WriteAt, not streaming Read/Write) operations on it.
func (*DirectLob) GetFileName ¶
GetFileName Return directory alias and file name for a BFILE type LOB.
func (*DirectLob) Set ¶
Set the contents of the LOB to the given byte slice. The LOB is cleared first.
func (*DirectLob) Size ¶
Size returns the size of the LOB.
WARNING: for historical reasons, Oracle stores CLOBs and NCLOBs using the UTF-16 encoding, regardless of what encoding is otherwise in use by the database. The number of characters, however, is defined by the number of UCS-2 codepoints. For this reason, if a character requires more than one UCS-2 codepoint, the size returned will be inaccurate and care must be taken to account for the difference!
type EnqOptions ¶
type EnqOptions struct { Transformation string Visibility Visibility DeliveryMode DeliveryMode }
EnqOptions are the options used to enqueue a message.
type Event ¶
type Event struct { Err error DB string Tables []TableEvent Queries []QueryEvent Type EventType }
Event for a subscription.
type IntervalYM ¶
type IntervalYM struct {
Years, Months int
}
IntervalYM holds Years and Months as interval.
type Lob ¶
Lob is for reading/writing a LOB.
func (*Lob) Hijack ¶
Hijack the underlying lob reader/writer, and return a DirectLob for reading/writing the lob directly.
After this, the Lob is unusable!
func (*Lob) NewBufferedReader ¶
NewBufferedReader returns a new bufio.Reader with the given size (or 1M if 0).
type Message ¶
type Message struct { Enqueued time.Time Object *Object Correlation, ExceptionQ string Raw []byte Delay, Expiration time.Duration DeliveryMode DeliveryMode State MessageState Priority, NumAttempts int32 MsgID, OriginalMsgID [16]byte }
Message is a message - either received or being sent.
type Number ¶
type Number string
Number as string
func (*Number) Compose ¶
Compose sets the internal decimal value from parts. If the value cannot be represented then an error should be returned.
func (Number) Decompose ¶
func (N Number) Decompose(buf []byte) (form byte, negative bool, coefficient []byte, exponent int32)
Decompose returns the internal decimal state in parts. If the provided buf has sufficient capacity, buf may be returned as the coefficient with the value set and length set as appropriate.
func (Number) MarshalJSON ¶
MarshalJSON marshals a Number into a JSON string.
func (Number) MarshalText ¶
MarshalText marshals a Number to text.
func (*Number) UnmarshalJSON ¶
UnmarshalJSON parses a JSON string into the Number.
func (*Number) UnmarshalText ¶
UnmarshalText parses text into a Number.
type Object ¶
type Object struct { *ObjectType // contains filtered or unexported fields }
Object represents a dpiObject.
func (*Object) Collection ¶
func (O *Object) Collection() ObjectCollection
Collection returns &ObjectCollection{Object: O} iff the Object is a collection. Otherwise it returns nil.
func (*Object) GetAttribute ¶
GetAttribute gets the i-th attribute into data.
func (*Object) ResetAttributes ¶
ResetAttributes prepare all attributes for use the object as IN parameter
type ObjectAttribute ¶
type ObjectAttribute struct { *ObjectType Name string // contains filtered or unexported fields }
ObjectAttribute is an attribute of an Object.
type ObjectCollection ¶
type ObjectCollection struct {
*Object
}
ObjectCollection represents a Collection of Objects - itself an Object, too.
func (ObjectCollection) Append ¶
func (O ObjectCollection) Append(v interface{}) error
Append v to the collection.
func (ObjectCollection) AppendData ¶
func (O ObjectCollection) AppendData(data *Data) error
AppendData to the collection.
func (ObjectCollection) AppendObject ¶
func (O ObjectCollection) AppendObject(obj *Object) error
AppendObject adds an Object to the collection.
func (ObjectCollection) AsSlice ¶
func (O ObjectCollection) AsSlice(dest interface{}) (interface{}, error)
AsSlice retrieves the collection into a slice.
func (ObjectCollection) Delete ¶
func (O ObjectCollection) Delete(i int) error
Delete i-th element of the collection.
func (ObjectCollection) First ¶
func (O ObjectCollection) First() (int, error)
First returns the first element's index of the collection.
func (ObjectCollection) Get ¶
func (O ObjectCollection) Get(i int) (interface{}, error)
Get the i-th element of the collection.
func (ObjectCollection) GetItem ¶
func (O ObjectCollection) GetItem(data *Data, i int) error
GetItem gets the i-th element of the collection into data.
func (ObjectCollection) Last ¶
func (O ObjectCollection) Last() (int, error)
Last returns the index of the last element.
func (ObjectCollection) Len ¶
func (O ObjectCollection) Len() (int, error)
Len returns the length of the collection.
func (ObjectCollection) Next ¶
func (O ObjectCollection) Next(i int) (int, error)
Next returns the succeeding index of i.
func (ObjectCollection) Set ¶
func (O ObjectCollection) Set(i int, v interface{}) error
Set the i-th element of the collection with value.
func (ObjectCollection) SetItem ¶
func (O ObjectCollection) SetItem(i int, data *Data) error
SetItem sets the i-th element of the collection with data.
func (ObjectCollection) Trim ¶
func (O ObjectCollection) Trim(n int) error
Trim the collection to n.
type ObjectScanner ¶
ObjectScanner assigns a value from a database object
type ObjectType ¶
type ObjectType struct { CollectionOf *ObjectType Attributes map[string]ObjectAttribute Schema, Name string DBSize, ClientSizeInBytes, CharSize int OracleTypeNum C.dpiOracleTypeNum NativeTypeNum C.dpiNativeTypeNum Precision int16 Scale int8 FsPrecision uint8 // contains filtered or unexported fields }
ObjectType holds type info of an Object.
func GetObjectType ¶
GetObjectType returns the ObjectType for the name.
func (*ObjectType) Close ¶
func (t *ObjectType) Close() error
Close releases a reference to the object type.
func (*ObjectType) FullName ¶
func (t *ObjectType) FullName() string
FullName returns the object's name with the schame prepended.
func (*ObjectType) NewCollection ¶
func (t *ObjectType) NewCollection() (ObjectCollection, error)
NewCollection returns a new Collection object with ObjectType type. If the ObjectType is not a Collection, it returns ErrNotCollection error.
func (*ObjectType) NewData ¶
func (t *ObjectType) NewData(baseType interface{}, sliceLen, bufSize int) ([]*Data, error)
NewData returns Data for input parameters on Object/ObjectCollection.
func (*ObjectType) NewObject ¶
func (t *ObjectType) NewObject() (*Object, error)
NewObject returns a new Object with ObjectType type.
As with all Objects, you MUST call Close on it when not needed anymore!
func (*ObjectType) String ¶
func (t *ObjectType) String() string
type ObjectWriter ¶
type ObjectWriter interface { WriteObject() error // contains filtered or unexported methods }
ObjectWriter update database object before binding
type Option ¶
type Option func(*stmtOptions)
Option holds statement options.
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.
func ArraySize ¶
ArraySize returns an option to set the array size to be used, overriding DefaultArraySize.
func BoolToString ¶
BoolToString is an option that governs convertsion from bool to string in the database. This is for converting from bool to string, from outside of the database (which does not have a BOOL(EAN) column (SQL) type, only a BOOLEAN PL/SQL type).
This will be used only with DML statements and when the PlSQLArrays Option is not used.
For the other way around, use an sql.Scanner that converts from string to bool. For example:
type Booler bool var _ sql.Scanner = Booler{} func (b Booler) Scan(src interface{}) error { switch src := src.(type) { case int: *b = x == 1 case string: *b = x == "Y" || x == "T" // or any string your database model treats as truth value default: return fmt.Errorf("unknown scanner source %T", src) } return nil }
Such a type cannot be included in this package till we can inject the truth strings into the scanner method.
func CallTimeout ¶
CallTimeout sets the round-trip timeout (OCI_ATTR_CALL_TIMEOUT).
func ClobAsString
deprecated
func ClobAsString() Option
ClobAsString returns an option to force fetching CLOB columns as strings.
Deprecated: CLOBs are returned as string by default - for CLOB, use LobAsReader. EXCEPT for Object attributes, those are returned as-is - as lobReader.
func DeleteFromCache ¶
func DeleteFromCache() Option
DeleteFromCache is an option to delete the statement from the statement cache.
func FetchArraySize ¶
FetchArraySize returns an option to set the rows to be fetched, overriding DefaultFetchRowCount.
For choosing FetchArraySize and PrefetchCount, see https://cx-oracle.readthedocs.io/en/latest/user_guide/tuning.html#choosing-values-for-arraysize-and-prefetchrows
func FetchRowCount ¶
FetchRowCount is DEPRECATED, use FetchArraySize.
It returns an option to set the rows to be fetched, overriding DefaultFetchRowCount.
func LobAsReader ¶
func LobAsReader() Option
LobAsReader is an option to set query columns of CLOB/BLOB to be returned as a Lob.
LOB as a reader and writer is not the most performant at all. Yes, OCI and ODPI-C provide a way to retrieve this data directly. Effectively, all you need to do is tell ODPI-C that you want a "long string" or "long raw" returned. You can do that by telling ODPI-C you want a variable with oracleTypeNum=DPI_ORACLE_TYPE_LONG_VARCHAR or DPI_ORACLE_TYPE_LONG_RAW and nativeTypeNum=DPI_NATIVE_TYPE_BYTES. ODPI-C will handle all of the dynamic fetching and allocation that is required. :-) You can also use DPI_ORACLE_TYPE_VARCHAR and DPI_ORACLE_TYPE_RAW as long as you set the size > 32767 -- whichever way you wish to use.
With the use of LOBs, there is one round-trip to get the LOB locators, then a round-trip for each read() that is performed. If you request the length there is another round-trip required. So if you fetch 100 rows with 2 CLOB columns, that means you get 401 round-trips. Using string/[]bytes directly means only one round trip. So you can see that if your database is remote with high latency you can have a significant performance penalty!
EXCEPT for Object attributes, those are returned as-is - as lobReader.
func NullDateAsZeroTime ¶
func NullDateAsZeroTime() Option
NullDateAsZeroTime is an option to return NULL DATE columns as time.Time{} instead of nil. If you must Scan into time.Time (cannot use sql.NullTime), this may help.
func ParseOnly ¶
func ParseOnly() Option
ParseOnly returns an option to set the ExecMode to only Parse.
func PrefetchCount ¶
PrefetchCount returns an option to set the rows to be fetched, overriding DefaultPrefetchCount.
For choosing FetchArraySize and PrefetchCount, see https://cx-oracle.readthedocs.io/en/latest/user_guide/tuning.html#choosing-values-for-arraysize-and-prefetchrows
WARNING: If you will take a REF CURSOR, the driver will start prefetching, so if you give that cursor to a stored procedure, that won't see the prefetched rows!
type OraErr ¶
type OraErr struct {
// contains filtered or unexported fields
}
OraErr is an error holding the ORA-01234 code and the message.
func (*OraErr) Action ¶
Action returns the internal action that was being performed when the error took place. This is a null-terminated ASCII string.
func (*OraErr) FunName ¶
FunName returns the public ODPI-C function name which was called in which the error took place. This is a null-terminated ASCII string.
func (*OraErr) Offset ¶
Offset returns the parse error offset (in bytes) when executing a statement or the row offset when performing bulk operations or fetching batch error information. If neither of these cases are true, the value is 0.
func (*OraErr) Recoverable ¶
Recoverable indicates if the error is recoverable. This is always false unless both client and server are at release 12.1 or higher.
type PoolParams ¶
type PoolParams = dsn.PoolParams
dsn is separated out for fuzzing, but keep it as "internal"
type QueryColumn ¶
QueryColumn is the described column.
func DescribeQuery ¶
DescribeQuery describes the columns in the qry.
This can help using unknown-at-compile-time, a.k.a. dynamic queries.
type QueryEvent ¶
type QueryEvent struct { Tables []TableEvent ID uint64 Operation }
QueryEvent is an event of a Query.
type Queue ¶
type Queue struct { PayloadObjectType *ObjectType // contains filtered or unexported fields }
Queue represents an Oracle Advanced Queue.
func NewQueue ¶
func NewQueue(ctx context.Context, execer Execer, name string, payloadObjectTypeName string, options ...queueOption) (*Queue, error)
NewQueue creates a new Queue.
WARNING: the connection given to it must not be closed before the Queue is closed! So use an sql.Conn for it.
func (*Queue) DeqOptions ¶
func (Q *Queue) DeqOptions() (DeqOptions, error)
DeqOptions returns the queue's dequeue options in effect.
func (*Queue) Dequeue ¶
Dequeues messages into the given slice. Returns the number of messages filled in the given slice.
func (*Queue) EnqOptions ¶
func (Q *Queue) EnqOptions() (EnqOptions, error)
EnqOptions returns the queue's enqueue options in effect.
func (*Queue) Enqueue ¶
Enqueue all the messages given.
WARNING: calling this function in parallel on different connections acquired from the same pool may fail due to Oracle bug 29928074. Ensure that this function is not run in parallel, use standalone connections or connections from different pools, or make multiple calls to Queue.enqOne() instead. The function Queue.Dequeue() call is not affected.
func (*Queue) SetDeqCorrelation ¶
SetDeqCorrelation is a convenience function setting the Correlation DeqOption
func (*Queue) SetDeqOptions ¶
func (Q *Queue) SetDeqOptions(D DeqOptions) error
SetDeqOptions sets all the dequeue options
func (*Queue) SetEnqOptions ¶
func (Q *Queue) SetEnqOptions(E EnqOptions) error
SetEnqOptions sets all the enqueue options
type ShutdownMode ¶
type ShutdownMode C.dpiShutdownMode
ShutdownMode for the database.
Example ¶
ExampleShutdownMode is an example of how to shut down a database.
package main import ( "context" "database/sql" "fmt" "log" godror "github.com/Seakia/godror" ) func main() { dsn := "oracle://?sysdba=1" // equivalent to "/ as sysdba" db, err := sql.Open("godror", dsn) if err != nil { log.Fatal(fmt.Errorf("%s: %w", dsn, err)) } defer db.Close() if err = exampleShutdown(db, godror.ShutdownTransactionalLocal); err != nil { log.Fatal(err) } } func exampleShutdown(db *sql.DB, shutdownMode godror.ShutdownMode) error { ctx, cancel := context.WithCancel(context.Background()) defer cancel() err := godror.Raw(ctx, db, func(oraDB godror.Conn) error { log.Printf("Beginning shutdown %v", shutdownMode) return oraDB.Shutdown(shutdownMode) }) if err != nil { return err } if shutdownMode == godror.ShutdownAbort { return nil } log.Println("Closing database") if _, err = db.Exec("alter database close normal"); err != nil { return err } log.Println("Unmounting database") if _, err = db.Exec("alter database dismount"); err != nil { return err } log.Println("Finishing shutdown") return godror.Raw(ctx, db, func(oraDB godror.Conn) error { return oraDB.Shutdown(godror.ShutdownFinal) }) }
Output:
type StartupMode ¶
type StartupMode C.dpiStartupMode
StartupMode for the database.
Example ¶
ExampleStartupMode calls exampleStartup to start a database.
package main import ( "context" "database/sql" "fmt" "log" godror "github.com/Seakia/godror" ) func main() { if err := exampleStartup(godror.StartupDefault); err != nil { log.Fatal(err) } } func exampleStartup(startupMode godror.StartupMode) error { ctx, cancel := context.WithCancel(context.Background()) defer cancel() dsn := "oracle://?sysdba=1&prelim=1" db, err := sql.Open("godror", dsn) if err != nil { log.Fatal(fmt.Errorf("%s: %w", dsn, err)) } defer db.Close() err = godror.Raw(ctx, db, func(oraDB godror.Conn) error { log.Println("Starting database") if err = oraDB.Startup(startupMode); err != nil { return err } return nil }) db2, err := sql.Open("godror", "oracle://?sysdba=1") if err != nil { return err } defer db2.Close() log.Println("Mounting database") if _, err = db2.Exec("alter database mount"); err != nil { return err } log.Println("Opening database") if _, err = db2.Exec("alter database open"); err != nil { return err } return nil }
Output:
type Subscription ¶
type Subscription struct { ID uint64 // contains filtered or unexported fields }
Subscription for events in the DB.
func (*Subscription) Close ¶
func (s *Subscription) Close() error
Close the subscription.
This code is EXPERIMENTAL yet!
func (*Subscription) Register ¶
func (s *Subscription) Register(qry string, params ...interface{}) error
Register a query for Change Notification.
This code is EXPERIMENTAL yet!
type SubscriptionOption ¶
type SubscriptionOption func(*subscriptionParams)
SubscriptionOption is for setting various parameters of the Subscription.
func SubscrClientInitiated ¶
func SubscrClientInitiated(b bool) SubscriptionOption
SubscrClientInitiated sets whether the subscription is client-initated.
func SubscrHostPort ¶
func SubscrHostPort(address string, port uint32) SubscriptionOption
SubscrHostPort is a SubscriptionOption that sets tha IPAddress and Port to the specified values.
The address is on which the subscription listens to receive notifications, for a server-initiated connection.
The address can be an IPv4 address in dotted decimal format such as 192.1.2.34 or an IPv6 address in hexadecimal format such as 2001:0db8:0000:0000:0217:f2ff:fe4b:4ced.
By default (address is the empty string), an IP address will be selected by the Oracle client.
The port number on which to receive notifications, for a server-initiated connection.
The default value of 0 means that a port number will be selected by the Oracle client.
type TableEvent ¶
TableEvent is for a Table-related event.
type TraceTag ¶
type TraceTag struct { // ClientIdentifier - specifies an end user based on the logon ID, such as HR.HR ClientIdentifier string // ClientInfo - client-specific info ClientInfo string // DbOp - database operation DbOp string // Module - specifies a functional block, such as Accounts Receivable or General Ledger, of an application Module string // Action - specifies an action, such as an INSERT or UPDATE operation, in a module Action string }
TraceTag holds tracing information for the session. It can be set on the session with ContextWithTraceTag.
type UserPasswdConnClassTag ¶
UserPasswdConnClassTag consists of Username, Password and ConnectionClass values that can be set with ContextWithUserPassw
type VersionInfo ¶
type VersionInfo struct { ServerRelease string Version, Release, Update, PortRelease, PortUpdate, Full uint8 }
VersionInfo holds version info returned by Oracle DB.
func ClientVersion ¶
func ClientVersion(ctx context.Context, ex Execer) (vi VersionInfo, err error)
ClientVersion returns the VersionInfo from the DB.
func ServerVersion ¶
func ServerVersion(ctx context.Context, ex Execer) (vi VersionInfo, err error)
ServerVersion returns the VersionInfo of the client.
func (*VersionInfo) String ¶
func (V *VersionInfo) String() string