oracle

package module

v0.3.0 Latest Latest Go to latest Published: Nov 4, 2026 License: MIT Imports: 24 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/xo/oracle

Links

Open Source Insights

README ¶

oracle

A pure Go Oracle Database driver for database/sql.

github.com/xo/oracle is a fork of sijms/go-ora at its v3 code, kept by the xo project because fixes to the upstream driver were not being accepted. It carries the v3 code only. It does not carry the v1 or v2 code, and it does not carry the upstream tags. It is under rewrite, and docs/PLAN.md holds the plan.

usql, dbtpl and dbmeta read Oracle through this driver.

Features

Pure Go. It needs no C compiler and no Oracle client.
It implements the context form of each interface of database/sql. A context that ends breaks the call, and the connection stays usable.
It works with Oracle 11g, 18c, 19c, 21c, 23ai and 26ai, and with the Autonomous Database.
It reads and binds VECTOR, BOOLEAN, JSON, LOBs, intervals and every other Oracle type.
It binds and reads user defined types, collections and PL/SQL records through Go structs.
It holds Advanced Queuing, in the aq package.
It connects with TLS, a wallet, native network encryption, Kerberos, NTS or a token.
It logs the packets and events of each connection to a *slog.Logger.

Installation

go get github.com/xo/oracle

Requires Go 1.27.1 or later.

Quick Start

package main

import (
    "database/sql"
    "fmt"
    "log"

    _ "github.com/xo/oracle"
)

func main() {
    db, err := sql.Open("oracle", "oracle://user:pass@host/service")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    if err := db.Ping(); err != nil {
        log.Fatal(err)
    }

    fmt.Println("Connected to Oracle")
}

Connection options

A DSN is a URL whose scheme is oracle:

oracle://user:password@host:port/service/instance?key=value

The port is 1521 when the DSN names none. The path is the service name, and an instance name after it. A service name that holds a / is written as %2F. Every key is lower case. A key that the driver does not know is an error, and so is a key that appears twice, other than server. The DSN takes none of the key names of go-ora, such as SSL VERIFY or SERVICE NAME.

Key	Holds	Default
`sid`	A SID, in place of a service name	none
`descriptor`	A TNS descriptor, `(DESCRIPTION=...)`, in place of the host, the port and the path	none
`server`	One more address, `host:port`. Repeat it for more	none
`sslmode`	`disable`, `require`, `verify-ca` or `verify-full`, as in `pgx`	`disable`
`sslrootcert`, `sslcert`, `sslkey`	The PEM files of the authority, and of the certificate and key of the client	none
`sslservername`	The name to check the certificate against	the host
`wallet`, `wallet_password`	A folder with `cwallet.sso` or `ewallet.p12`, and its password	none
`timeout`, `connect_timeout`	Go durations, such as `30s`	none, and `60s`
`prefetch`	The rows that one fetch asks for. With `25`, the driver sizes each fetch by the size of its rows and their LOB values	`25`
`lob_fetch`, `lob_read`	`inline` or `stream`, and `auto` or `explicit`	`inline`, `auto`
`auth`	`password`, `os`, `kerberos` or `token`	`password`
`privilege`	`sysdba`, `sysoper`, `sysasm`, `sysbackup`, `sysdg`, `syskm` or `sysrac`	none
`token`, `token_key`	The files of a token and its private key	none
`encryption`, `checksum`	`accepted`, `rejected`, `requested` or `required`	the server decides
`language`, `territory`, `charset`	The NLS settings of the client	`AMERICAN`, `AMERICA`
`program`, `proxy_user`	The program that the session reports, and a proxy user	none
`unix_socket`	A Unix socket in place of TCP	none
`alias`, `tns_admin`	An alias of `tnsnames.ora`, in place of the host, the port and the path, and the folder of the file	none, and `$TNS_ADMIN`

A user named SYS gets no privilege by its name. Write privilege=sysdba.

The server reads a user name in upper case unless the name is quoted, as in SQL. A user created as "scott" logs on as oracle://%22scott%22:pass@host/service.

Config.Client names the program, the host, the user and the terminal that v$session shows for the session. An empty field takes the value of the process.

ParseDSN returns a Config. A caller that needs more than a DSN can say, such as a *tls.Config, a Dialer or a *slog.Logger, changes the Config and opens the database with a connector:

cfg, err := oracle.ParseDSN(dsn)
if err != nil {
    return err
}
cfg.Dialer = myDialer
c, err := oracle.NewConnector(cfg, oracle.WithSessionParam("nls_date_format", "'YYYY-MM-DD'"))
if err != nil {
    return err
}
db := sql.OpenDB(c)

Each connector holds the state of its own database: the session parameters, the registered types and the coders. Two databases in one process share none of it.

Values

A NULL scans as nil, and a nullable column scans into sql.Null[T]. The type of a column decides the Go type that a scan into *any gets:

Oracle	Go
`NUMBER` with a scale of 0 and a precision of 18 or less	`int64`
Any other `NUMBER`, such as `COUNT(*)`	`*apd.Decimal`, from `github.com/cockroachdb/apd/v3`
`BINARY_FLOAT`, `BINARY_DOUBLE`	`float64`
`INTERVAL YEAR TO MONTH`	`oracle.IntervalYM`
`INTERVAL DAY TO SECOND`	`time.Duration`
`RAW`, `LONG RAW`, `BLOB`	`[]byte`
`DATE`, `TIMESTAMP`	`time.Time` in UTC
`TIMESTAMP WITH TIME ZONE`	`time.Time` in its zone
`TIMESTAMP WITH LOCAL TIME ZONE`	`time.Time` in the zone of the database

A decimal of another package binds as a NUMBER, and scans from one with every digit, when it has the Decompose and Compose methods that database/sql uses.

A DATE and a TIMESTAMP hold no zone, so the driver returns the wall clock of the value in UTC, whatever the zone of the server. To read one as the time in a zone, such as Europe/Prague, call time.Date with the fields of the value and that zone. A time.Time binds as its wall clock, and the server reads it in the zone of the session. oracle.TimestampTZ binds with its zone.

Oracle stores a UUID as a RAW(16). A uuid.UUID of the standard library binds as one, and a RAW(16) scans into a *uuid.UUID. A scan into *any gives a []byte, because a RAW(16) can hold other things, such as a hash:

id := uuid.NewV7()
_, err := db.ExecContext(ctx, "INSERT INTO orders (id) VALUES (:1)", id)

var got uuid.UUID
err = db.QueryRowContext(ctx, "SELECT id FROM orders").Scan(&got)

A string or a []byte longer than 32,767 bytes, or 4,000 on 11g, binds as a LONG or a LONG RAW. SQL takes one only as a value to insert or set. Where SQL uses the value in an expression, as in the SELECT of a MERGE, bind oracle.CreateClob or oracle.CreateBlob in its place. In a PL/SQL block the driver binds a value that long as a temporary LOB itself.

A decimal scans into a *string, a *float64 or an *int64 too. Both interval types bind as arguments. docs/DESIGN.md, under Values, holds the whole table.

Reading a LOB in pieces

A CLOB scans into a *string and a BLOB into a *[]byte, which hold the whole value. To read a large value in pieces, fetch it as a locator with lob_fetch=stream, scan it into an oracle.Clob or an oracle.Blob, and read it with NewReader:

rows, err := db.QueryContext(ctx, `SELECT doc FROM files`, oracle.WithLobFetch(oracle.LobFetchStream))
// ...
for rows.Next() {
	var doc oracle.Clob
	if err := rows.Scan(&doc); err != nil {
		return err
	}
	if _, err := io.Copy(w, doc.NewReader(ctx)); err != nil {
		return err
	}
}

Each piece is one round trip of 1 MiB, and NewReaderSize sets another size. A CLOB reads as UTF-8. Each read watches ctx. A LOB of a row reads until its rows close, and a read after that fails with oracle.ErrRowsClosed, because the connection of the rows can serve another caller by then. An oracle.BFile reads the same way once it is open.

New Types

VECTOR (Oracle 23ai)

A VECTOR scans into the slice of its format:

Format	Go
`FLOAT32`	`[]float32`
`FLOAT64`	`[]float64`
`INT8`	`[]int8`
`BINARY`	`[]byte`, 8 dimensions in each byte
a sparse vector	`oracle.SparseVector`

A dense vector binds through oracle.CreateVector, because a slice binds as a PL/SQL array. A SparseVector binds as it is:

vec, err := oracle.CreateVector([]float32{1.5, 2.5, 3.5})
_, err = db.ExecContext(ctx, "INSERT INTO items (v) VALUES (:1)", vec)

var v []float32
err = db.QueryRowContext(ctx, "SELECT v FROM items").Scan(&v)

A scan into *any gives the slice of the format. The server converts a vector between the formats.

JSON (Oracle 21c+)

// bind any Go value, through encoding/json/v2
js, err := oracle.NewJSON(Order{ID: 7, Items: []string{"a", "b"}})
_, err = db.ExecContext(ctx, "INSERT INTO orders (doc) VALUES (:1)", js)

// scan into any type that encoding/json/v2 decodes into
var order Order
err = db.QueryRowContext(ctx, "SELECT doc FROM orders").Scan(&order)

// or as the JSON text
var text jsontext.Value
err = db.QueryRowContext(ctx, "SELECT doc FROM orders").Scan(&text)

A JSON column scans into *any as a jsontext.Value. The driver turns JSON text into OSON, the binary JSON of Oracle, and back, and encoding/json/v2 maps it to Go values, so a number keeps every digit.

BOOLEAN

A bool binds as a BOOLEAN in SQL on 23ai and later, and in PL/SQL from 12.1. In SQL before 23ai it binds as the NUMBER 1 or 0. A BOOLEAN scans into a *bool or a *sql.Null[bool]:

var ok bool
_, err := db.ExecContext(ctx, "BEGIN :1 := my_check(:2); END;", oracle.Out{Dest: &ok}, true)

Advanced Queuing

import "github.com/xo/oracle/aq"

// A queue uses one connection
conn, err := db.Conn(ctx)
queue, err := aq.CreateQueue(conn, "my_queue", aq.RAW, "")

// Enqueue
msg, _ := queue.NewMessage([]byte("hello"))
queue.Enqueue(msg)

// Dequeue
msg, err = queue.Dequeue(&aq.DequeueOptions{
    Consumer: "my_consumer",
    Mode:     aq.Browse,
    Wait:     5,
})

A message holds RAW, JSON, a user defined type (UDT) or XML. A queue enqueues and dequeues one message or an array of them, in the persistent or the buffered delivery mode. A dequeue that finds no message returns nil and no error. The options set the visibility, the navigation, the expiration and the correlation of a message.

User-Defined Types

// Register with array counterpart
err := oracle.RegisterType(db, "MY_OBJECT", "MY_ARRAY", MyStruct{})

// Register with explicit owner
err = oracle.RegisterTypeWithOwner(db, "SCHEMA", "MY_OBJECT", "MY_ARRAY", MyStruct{})

A struct maps to an object through its udt tags, and an object can hold other objects and collections, VARRAY and TABLE OF. A record of a PL/SQL package registers as PKG.TYPE, and the record of a row as TABLE%ROWTYPE. A type registers with the database of db alone. A value of the Go type that RegisterType names binds as its Oracle type, and a field of a named type, such as type Status string, binds as its kind.

A collection of a basic type registers with the name of its element type. Its Go element type can be a named type, which binds with no more help:

type Name string

err := oracle.RegisterType(db, "varchar2", "NAME_LIST", Name(""))
rows, err := db.Query("SELECT column_value FROM TABLE(:1)", []Name{"a", "b"})

With no Go type, oracle.Object names the collection at the bind. A []time.Time or a [][]byte binds as a PL/SQL array without it:

err := oracle.RegisterType(db, "date", "DATE_LIST", nil)
var out []time.Time
_, err = db.Exec("BEGIN :1 := :2; END;",
    oracle.Out{Dest: oracle.Object{Name: "DATE_LIST", Value: &out}},
    oracle.Object{Name: "DATE_LIST", Value: []time.Time{time.Now()}})

A CLOB or a BLOB attribute of an object reads into a string, a []byte, an oracle.Clob or an oracle.Blob field, and binds from any of them.

Session parameters

c, err := oracle.NewConnector(cfg,
    oracle.WithSessionParam("cursor_sharing", "force"),
    oracle.WithSessionParam("nls_language", "arabic"))

The connector sets each parameter with ALTER SESSION on each connection after its logon.

Options of one statement

An option sets one statement, as an argument or through the context, and a later one wins over the DSN:

rows, err := db.QueryContext(ctx, query, arg1, oracle.WithPrefetch(1000))

ctx = oracle.WithOptions(ctx, oracle.WithTimeout(5*time.Second))
_, err = db.ExecContext(ctx, "BEGIN slow_proc; END;")

WithTimeout ends the call after the time, and leaves the connection usable. WithPrefetch and WithLobFetch are the keys prefetch and lob_fetch for one statement. WithReadonly(true), WithParameter and WithDatabase fail with ErrNotSupported, because Oracle has no such setting for one statement.

A batch of DML binds a slice for each argument, and stops at the first row that fails. With WithBatchErrors, the batch runs every row that it can, and returns an *oracle.BatchError that holds the index and the error of each row that failed. WithRowCounts fills a slice with the count of the rows that each row of the batch changed:

var counts []int64
_, err := db.ExecContext(ctx, "UPDATE t SET n = n + 1 WHERE id = :1",
    []int64{1, 2, 3}, oracle.WithBatchErrors(), oracle.WithRowCounts(&counts))
var batchErr *oracle.BatchError
if errors.As(err, &batchErr) {
    // batchErr.Rows holds the index and the error of each row that failed
}

DBMS_OUTPUT

DBMS_OUTPUT belongs to one session, so the helpers take a *sql.Conn or a *sql.Tx:

conn, err := db.Conn(ctx)
if err != nil {
    return err
}
defer conn.Close()
if err := oracle.EnableOutput(ctx, conn, 0); err != nil {
    return err
}
if _, err := conn.ExecContext(ctx, "BEGIN my_proc; END;"); err != nil {
    return err
}
lines, err := oracle.ReadOutput(ctx, conn)

ReadOutput reads every line in one round trip, and removes them.

Logging

The driver logs nothing unless the caller sets Config.Logger:

cfg.Logger = slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelDebug}))

Each packet that a connection sends and receives goes to the logger at slog.LevelDebug as a hex dump, with each statement, bind and event of the connection. A break and a bad connection go at slog.LevelInfo. The packets of the logon carry the encrypted password, so the logger gets only their length until the logon ends.

Architecture

oracle/
├── aq/                # Advanced Queuing
├── integration/       # Integration tests, which need a server
├── internal/
│   ├── auth/          # Encryption, checksums, Kerberos, NTS, NTLM
│   ├── charset/       # The Oracle charsets, compacted
│   ├── codec/         # Type encoding and decoding, and OSON
│   ├── config/        # The configuration of a connection, and wallets
│   ├── repotest/      # Tests of the repository setup
│   ├── tns/           # TNS packets and the session
│   ├── tnstest/       # Recorded exchanges for the tests
│   ├── ttc/           # Connections, statements, rows, LOBs, types
│   └── types/         # The values of each Oracle type
├── testdata/          # Exchanges recorded against each release
├── conn.go            # The connection that database/sql uses
├── connector.go       # Connector, and the configuration of each connection
├── driver.go          # Driver registration, RegisterType
├── dsn.go             # Config and ParseDSN
├── errors.go          # The sentinel errors, ServerError and BatchError
├── options.go         # The options of one statement
├── output.go          # DBMS_OUTPUT
├── rows.go            # The rows of a query
├── stmt.go            # A prepared statement
├── tx.go              # A transaction
└── values.go          # Out, RefCursor and the other types a caller uses

Design Principles

Each Oracle type has its own coder, and a type switch chooses the coder of a Go value.
Each connector holds the registered types, the session parameters and the fast login cookies of its own database, which reach no other.
Each call takes a context. A context that ends breaks the call with an Oracle Net break, and the connection stays usable.
A connect tries each address of a descriptor in turn. After the connect, the driver retries nothing, and database/sql drops a bad connection.

Migration from go-ora

go-ora v2	oracle
`github.com/sijms/go-ora/v2`	`github.com/xo/oracle`
Types in the driver package	Types in the driver package, such as `oracle.Clob` and `oracle.Vector`
`go_ora/dbms.NewAQ`	`aq.CreateQueue`
`go_ora/dbms.NewOutput`	`oracle.EnableOutput` and `oracle.ReadOutput`
Manual UDT setup	`oracle.RegisterType` with struct tags
`go_ora.AddSessionParam` / `DelSessionParam`	`oracle.WithSessionParam` on the connector
`go_ora.NewConnector(dsn)`, `Dialer`, `WithTLSConfig`	`oracle.NewConnector(cfg)` with `Config.Dialer` and `Config.TLS`
`go_ora.AddParameterCoder`, `SetStringConverter`, `RegisterConnConfig`	Removed
`go_ora.SetNTSAuth`, `SetKerberosAuth`	`Config.NTS` and `Config.Kerberos` on the connector
`go_ora.BuildUrl`, `BuildJDBC`	`Config.DSN`
The package `go_ora`	The package `oracle`
A `DATE` in the zone of the server	A `DATE` in UTC

The DSN is not compatible. See Connection options.

usql is a universal command line client for databases, and reads Oracle through this driver.
dbtpl generates Go code from a database schema.
dbmeta reads the metadata of a database, and its dbrun starts the Oracle releases that this driver is tested against.
dburl parses database URLs, and builds the oracle URL of this driver.
dbimp holds database/sql drivers for other databases, whose design this driver follows.
tblfmt renders result sets as tables.

Contributing

Read CONTRIBUTING.md before you change anything, and AGENTS.md if you are a coding agent. Work that is known and not done is in docs/BACKLOG.md.

License

MIT. The code descends from sijms/go-ora, and LICENSE holds its notice.

Documentation ¶

Index ¶

Constants
func DisableOutput(ctx context.Context, e Execer) error
func EnableOutput(ctx context.Context, e Execer, size int) error
func NewBatch(array driver.Value) driver.Value
func ReadOutput(ctx context.Context, e Execer) ([]string, error)
func RegisterType(db *sql.DB, typeName, arrayTypeName string, typeObj any) error
func RegisterTypeWithOwner(db *sql.DB, owner, typeName, arrayTypeName string, typeObj any) error
func WithOptions(ctx context.Context, opts ...Option) context.Context
func WrapRefCursor(ctx context.Context, q Querier, cursor *RefCursor) (*sql.Rows, error)
type Auth
type BFile
- func CreateBFile(ctx context.Context, db *sql.DB, dir, name string) (*BFile, error)
type BatchError
type Blob
- func CreateBlob(ctx context.Context, db *sql.DB, input any) (*Blob, error)
type Bool
type Client
type Clob
- func CreateClob(ctx context.Context, db *sql.DB, input any, nclob bool) (*Clob, error)
type Config
- func ParseDSN(dsn string) (Config, error)
- func (cfg Config) DSN() string
type Connector
- func NewConnector(cfg Config, opts ...ConnectorOption) (*Connector, error)
- func (c *Connector) Close() error
- func (c *Connector) Connect(ctx context.Context) (driver.Conn, error)
- func (c *Connector) Driver() driver.Driver
type ConnectorOption
- func WithSessionParam(key, value string) ConnectorOption
- func WithWallet(r io.Reader) ConnectorOption
type Dialer
type Driver
- func (Driver) Open(string) (driver.Conn, error)
- func (Driver) OpenConnector(dsn string) (driver.Connector, error)
type Error
type Execer
type IntervalYM
type JSON
- func NewJSON(v any) (*JSON, error)
type Kerberos
type LobFetch
type LobRead
type LobReader
type NTS
type NVarChar
type Object
type Option
- func WithBatchErrors() Option
- func WithDatabase(name string) Option
- func WithLobFetch(f LobFetch) Option
- func WithParameter(name string, value any) Option
- func WithPrefetch(rows int) Option
- func WithReadonly(readonly bool) Option
- func WithRowCounts(counts *[]int64) Option
- func WithTimeout(d time.Duration) Option
type Out
type Privilege
type Querier
type RefCursor
type RowError
type RowID
type SSLMode
type ServerError
type ServiceLevel
type SparseVector
type TimestampTZ
type Vector
- func CreateVector(array any) (*Vector, error)

Constants ¶

View Source

const (
	// ErrScheme is a DSN whose scheme is not oracle.
	ErrScheme Error = "the scheme of the dsn is not oracle"
	// ErrUnknownKey is a key of a DSN that the driver does not know.
	ErrUnknownKey Error = "unknown key"
	// ErrRepeatedKey is a key that a DSN holds twice.
	ErrRepeatedKey Error = "repeated key"
	// ErrInvalidValue is a value that the driver cannot use.
	ErrInvalidValue = tns.ErrInvalidValue
	// ErrNotSupported is a feature that the driver or the server does not
	// have.
	ErrNotSupported = tns.ErrNotSupported
	// ErrRowsClosed is a read of a LOB of a row after its rows closed. The
	// connection of the rows can serve another caller by then.
	ErrRowsClosed = tns.ErrRowsClosed
	// ErrConnectorClosed is a Connect after Close.
	ErrConnectorClosed Error = "the connector is closed"
	// ErrAuthentication is a server that refused the credential. A
	// *ServerError with ORA-01017 matches it.
	ErrAuthentication = tns.ErrAuthentication
	// ErrCompilation is a PL/SQL unit, a view or a type that the server
	// created but could not compile. The statement returns a *ServerError
	// with ORA-24344, which matches it, and USER_ERRORS holds the errors of
	// the compilation (D32).
	ErrCompilation = tns.ErrCompilation
)

The sentinel errors.

View Source

const DefaultPieceSize = types.DefaultPieceSize

DefaultPieceSize is the size in bytes of the piece that a LobReader asks the server for, unless NewReaderSize sets another.

View Source

const DefaultPort = 1521

DefaultPort is the port of an Oracle listener when the DSN names none.

Variables ¶

This section is empty.

Functions ¶

func DisableOutput ¶

func DisableOutput(ctx context.Context, e Execer) error

DisableOutput disables DBMS_OUTPUT in the session of e, and drops the lines that it holds.

func EnableOutput ¶

func EnableOutput(ctx context.Context, e Execer, size int) error

EnableOutput enables DBMS_OUTPUT in the session of e, with a buffer of size bytes, or with no limit when size is 0.

func NewBatch ¶

func NewBatch(array driver.Value) driver.Value

NewBatch returns an argument that binds each element of array, a slice, as one row of an array bind, for a bulk insert.

func ReadOutput ¶

func ReadOutput(ctx context.Context, e Execer) ([]string, error)

ReadOutput reads and removes the lines that DBMS_OUTPUT holds in the session of e, which EnableOutput enabled. go-ora read them through dbms.NewOutput.

func RegisterType ¶

func RegisterType(db *sql.DB, typeName, arrayTypeName string, typeObj any) error

RegisterType registers the user defined type typeName, and its collection arrayTypeName when that is not empty, for the Go type of typeObj, with the database of db alone. The owner of the type is the user of the database. It reads the attributes of the type through db, so the type must exist.

func RegisterTypeWithOwner ¶

func RegisterTypeWithOwner(db *sql.DB, owner, typeName, arrayTypeName string, typeObj any) error

RegisterTypeWithOwner is RegisterType for a type that owner owns.

func WithOptions ¶

func WithOptions(ctx context.Context, opts ...Option) context.Context

WithOptions returns a context that carries opts, after the options that ctx carries. Each statement that runs with the context applies them.

func WrapRefCursor ¶

func WrapRefCursor(ctx context.Context, q Querier, cursor *RefCursor) (*sql.Rows, error)

WrapRefCursor returns the rows of cursor, read through q.

Types ¶

type Auth ¶

type Auth string

Auth is how a connection proves who it is.

const (
	// AuthPassword sends the user and the password. It is the default.
	AuthPassword Auth = "password"
	// AuthOS uses the user of the operating system, through NTS on Windows.
	AuthOS Auth = "os"
	// AuthKerberos uses Kerberos, through Config.Kerberos.
	AuthKerberos Auth = "kerberos"
	// AuthToken sends the token of Config.Token, signed with Config.TokenKey.
	AuthToken Auth = "token"
)

The ways to authenticate.

type BFile ¶

type BFile = types.BFile

BFile is a BFILE, a file that the server reads from an Oracle directory.

func CreateBFile ¶

func CreateBFile(ctx context.Context, db *sql.DB, dir, name string) (*BFile, error)

CreateBFile returns the BFILE of the file name in the Oracle directory dir.

type BatchError ¶

type BatchError = tns.BatchError

BatchError is the error of a batch of DML that ran with WithBatchErrors: the rows that failed, each with the index of the row from 0 and the error of the server. The other rows ran. errors.As finds the error of each row (D34).

type Blob ¶

type Blob = types.Blob

Blob is a BLOB.

func CreateBlob ¶

func CreateBlob(ctx context.Context, db *sql.DB, input any) (*Blob, error)

CreateBlob returns a BLOB that holds input, a []byte.

type Bool ¶

type Bool = types.Bool

Bool is a BOOLEAN of Oracle 23ai and later, or of PL/SQL.

type Client ¶

type Client struct {
	Program  string
	Host     string
	User     string
	Terminal string
}

Client is what the connect packet and the logon say about the client. An empty field takes the value of this process: the path of the program, the name of the host, and the user of the operating system. The logon sends Host as the machine and User as the user of the operating system, which v$session shows, and Terminal as its terminal, which is Host when it is empty, sijms/go-ora#584.

type Clob ¶

type Clob = types.Clob

Clob is a CLOB or an NCLOB. A column scans into it, and it binds as an argument.

func CreateClob ¶

func CreateClob(ctx context.Context, db *sql.DB, input any, nclob bool) (*Clob, error)

CreateClob returns a CLOB, or an NCLOB when nclob is true, that holds input, a string or a []byte. Its value goes to the server when it is bound to a statement.

type Config ¶

type Config struct {
	User     string
	Password string

	// Host and Port are the address of the listener. Servers are more
	// addresses, as host:port, that the driver tries in order.
	Host    string
	Port    int
	Servers []string

	// Service is the service name, Instance the instance name, and SID the
	// SID, which some old databases use in place of a service name.
	Service  string
	Instance string
	SID      string

	// Descriptor is a TNS descriptor, such as (DESCRIPTION=...), that names
	// the addresses and the service in place of the fields above.
	Descriptor string

	// Alias is an alias of tnsnames.ora, whose descriptor takes the place of
	// Descriptor. The file is in the folder TNSAdmin, or in the folder that
	// the environment variable TNS_ADMIN names when TNSAdmin is empty (D20).
	Alias    string
	TNSAdmin string

	// SSLMode and the SSL fields say whether and how the connection uses TLS.
	SSLMode       SSLMode
	SSLRootCert   string
	SSLCert       string
	SSLKey        string
	SSLServerName string

	// TLS is a TLS configuration for the connection. When it is set, it takes
	// the place of the SSL files, and the connector clones it for each dial.
	TLS *tls.Config

	// Wallet is a folder that holds cwallet.sso or ewallet.p12, and
	// WalletPassword the password of ewallet.p12.
	Wallet         string
	WalletPassword string

	// Timeout is the deadline of each round trip, and ConnectTimeout the limit
	// on the dial, the TLS handshake and the logon. Zero means no timeout and
	// 60 seconds.
	Timeout        time.Duration
	ConnectTimeout time.Duration

	// Prefetch is the number of rows that one fetch asks for. Zero means 25.
	Prefetch int

	LobFetch LobFetch
	LobRead  LobRead

	Auth      Auth
	Privilege Privilege

	// Token and TokenKey are the files of a token and of its private key.
	Token    string
	TokenKey string

	// Encryption and Checksum are the levels of the native encryption and
	// checksums of Oracle Net.
	Encryption ServiceLevel
	Checksum   ServiceLevel

	// Language, Territory and Charset are the NLS settings of the client.
	Language  string
	Territory string
	Charset   string

	// Program is the program name that the session reports, and ProxyUser
	// the user of a proxy session.
	Program   string
	ProxyUser string

	// UnixSocket is a Unix socket to dial in place of TCP.
	UnixSocket string

	// Client is what the connect packet says about the client.
	Client Client

	// Dialer opens each network connection. Nil uses a net.Dialer.
	Dialer Dialer

	// Kerberos returns the ticket when Auth is AuthKerberos.
	Kerberos Kerberos

	// NTS makes the messages of NTS when Auth is AuthOS and the server asks
	// for it. Nil uses the NTLM of the driver.
	NTS NTS

	// Logger receives the packets and events of each connection. Nil logs
	// nothing (D14).
	Logger *slog.Logger
}

Config is the configuration of one database. ParseDSN fills it from a DSN, and a caller can change it or build one, and pass it to NewConnector. The zero value of a field is its default.

func ParseDSN ¶

func ParseDSN(dsn string) (Config, error)

ParseDSN parses a DSN of the form

oracle://user:password@host:port/service/instance?key=value

The scheme must be oracle. The port is 1521 when the DSN names none. The path is the service name, and an instance name after it. A service name that holds a / is written with %2F. A key that ParseDSN does not know, and a key that appears twice, other than server, are errors. An error never holds the DSN, which can hold a password.

func (Config) DSN ¶

func (cfg Config) DSN() string

DSN returns cfg as a DSN that ParseDSN reads back to the same Config. It writes no field that a DSN cannot hold, such as TLS, Dialer or Logger.

type Connector ¶

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

Connector opens connections to one Oracle database. It holds everything that belongs to that database: the configuration, the session parameters, the registered types and the type coders (D9). Pass it to sql.OpenDB.

func NewConnector ¶

func NewConnector(cfg Config, opts ...ConnectorOption) (*Connector, error)

NewConnector returns a Connector for cfg. It reads the files that cfg names, such as a wallet or a certificate, and it does not connect.

func (*Connector) Close ¶

func (c *Connector) Close() error

Close makes each later Connect fail. sql.DB.Close calls it. It closes no connection, because database/sql closes those.

func (*Connector) Connect ¶

func (c *Connector) Connect(ctx context.Context) (driver.Conn, error)

Connect opens a connection, logs on, and sets the session parameters.

func (*Connector) Driver ¶

func (c *Connector) Driver() driver.Driver

Driver returns a Driver that points at c.

type ConnectorOption ¶

type ConnectorOption func(*Connector) error

ConnectorOption changes a Connector as NewConnector makes it.

func WithSessionParam ¶

func WithSessionParam(key, value string) ConnectorOption

WithSessionParam sets the session parameter key to value, with ALTER SESSION, on each connection after its logon. The value is written as it is, so a string value needs its quotes, as in WithSessionParam("nls_date_format", "'YYYY-MM-DD'").

func WithWallet ¶

func WithWallet(r io.Reader) ConnectorOption

WithWallet reads a wallet, a cwallet.sso file, from r. It takes the place of the folder that Config.Wallet names.

type Dialer ¶

type Dialer interface {
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

Dialer opens the network connection to a listener. A caller sets it to reach the server through a proxy or a tunnel.

type Driver ¶

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

Driver is the oracle driver. The value that init registers holds nothing. Each Connector returns a Driver that points back at it, so that RegisterType reaches the types of one database through its *sql.DB.

func (Driver) Open ¶

func (Driver) Open(string) (driver.Conn, error)

Open fails, because it has no context. database/sql does not call it, because Driver implements driver.DriverContext, and sql.Open works.

func (Driver) OpenConnector ¶

func (Driver) OpenConnector(dsn string) (driver.Connector, error)

OpenConnector parses dsn with ParseDSN and returns a Connector for it. It does not connect.

type Error ¶

type Error = tns.Error

Error is the type of the sentinel errors of the driver. Compare an error with a sentinel with errors.Is.

type Execer ¶

type Execer interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
}

Execer runs a statement. *sql.Conn and *sql.Tx are each one, and each holds one session, which DBMS_OUTPUT belongs to. A *sql.DB is one too, but each call can take another session from its pool, so it reads no output.

type IntervalYM ¶

type IntervalYM = types.IntervalYM

IntervalYM is an INTERVAL YEAR TO MONTH. An INTERVAL DAY TO SECOND is a time.Duration.

type JSON ¶

type JSON = types.JSON

JSON is a JSON value of Oracle 21c and later. A JSON column scans as a jsontext.Value, and into any destination that encoding/json/v2 decodes into. NewJSON makes one to bind.

func NewJSON ¶

func NewJSON(v any) (*JSON, error)

NewJSON returns the JSON of v. A string, a []byte and a jsontext.Value are JSON text already, and any other value goes through json.Marshal of encoding/json/v2.

type Kerberos ¶

type Kerberos interface {
	Authenticate(server, service string) ([]byte, error)
}

Kerberos returns the Kerberos ticket for a service.

type LobFetch ¶

type LobFetch string

LobFetch says how a query returns a LOB column.

const (
	// LobFetchInline returns the whole value in the row.
	LobFetchInline LobFetch = "inline"
	// LobStream returns a locator, and the driver reads the value with more
	// round trips.
	LobFetchStream LobFetch = "stream"
)

The ways to fetch a LOB.

type LobRead ¶

type LobRead string

LobRead says whether the driver reads the value of a LOB locator for the caller.

const (
	// LobReadAuto reads the value when the row is scanned.
	LobReadAuto LobRead = "auto"
	// LobReadExplicit leaves the locator for the caller to read.
	LobReadExplicit LobRead = "explicit"
)

The ways to read a LOB.

type LobReader ¶

type LobReader = types.LobReader

LobReader reads the value of a Clob, a Blob or a BFile in pieces, through their NewReader. A LOB of a row reads until its rows close, and a read after that fails with ErrRowsClosed (D22).

type NTS ¶

type NTS = config.NTSAuthenticator

NTS makes the NTLM messages of NTS, the Windows authentication of Oracle Net, for Config.NTS.

type NVarChar ¶

type NVarChar = types.NVarChar

NVarChar is a string that binds as NVARCHAR2, in the national character set of the database. A string binds as VARCHAR2. A []NVarChar binds as a PL/SQL array of NVARCHAR2, and sql.Null[NVarChar] as a NULL one.

type Object ¶

type Object = types.Object

Object names the user defined type of a bind, as RegisterType registered it. Most values need none, because the Go type that RegisterType names binds as its type. A collection of a basic type, such as a TABLE OF DATE, needs one, since a []time.Time binds as a PL/SQL array. Value is the value, or a pointer to the destination in an Out.

type Option ¶

type Option = ttc.Option

Option sets one option of one statement (D109). An option comes from the DSN, then from the context through WithOptions, then from an argument of the statement, and a later one wins:

rows, err := db.QueryContext(ctx, query, oracle.WithPrefetch(1000))

func WithBatchErrors ¶

func WithBatchErrors() Option

WithBatchErrors runs a batch of DML past the rows that fail. The batch returns a *BatchError, which holds the index and the error of each row that failed, and the other rows run. A statement that is not DML fails with ErrNotSupported (D34).

func WithDatabase ¶

func WithDatabase(name string) Option

WithDatabase names the database of one statement. A connection of Oracle reaches one database, so a name fails the statement with ErrNotSupported.

func WithLobFetch ¶

func WithLobFetch(f LobFetch) Option

WithLobFetch sets how a query returns a LOB, as the key lob_fetch does.

func WithParameter ¶

func WithParameter(name string, value any) Option

WithParameter sets a setting of the server by its name, for a setting that the driver has no option for. Oracle has none for one statement, so it fails the statement with ErrNotSupported. ALTER SESSION, or WithSessionParam on the connector, sets a setting of the session.

func WithPrefetch ¶

func WithPrefetch(rows int) Option

WithPrefetch sets the number of rows that one fetch asks for, as the key prefetch does.

func WithReadonly ¶

func WithReadonly(readonly bool) Option

WithReadonly asks that the server refuse a write. Oracle has it for a transaction, through sql.TxOptions, and not for one statement, so true fails the statement with ErrNotSupported.

func WithRowCounts ¶

func WithRowCounts(counts *[]int64) Option

WithRowCounts fills counts with the count of the rows that each row of a batch of DML changed, or with the count of the one row of a statement that is not a batch. A statement that is not DML fails with ErrNotSupported (D34).

func WithTimeout ¶

func WithTimeout(d time.Duration) Option

WithTimeout ends the call of a statement after d, through the break of Oracle Net, which leaves the connection usable. Zero asks for nothing. It bounds the call that runs the statement, and not the fetches of its rows after it.

type Out ¶

type Out = ttc.Out

Out is an OUT or IN OUT argument of a PL/SQL call. Dest receives the value, Size is the largest size in bytes that the value can have, and In sends the value of Dest too.

type Privilege ¶

type Privilege string

Privilege is an administrative privilege that a session asks for.

const (
	PrivilegeSYSDBA    Privilege = "sysdba"
	PrivilegeSYSOPER   Privilege = "sysoper"
	PrivilegeSYSASM    Privilege = "sysasm"
	PrivilegeSYSBACKUP Privilege = "sysbackup"
	PrivilegeSYSDG     Privilege = "sysdg"
	PrivilegeSYSKM     Privilege = "syskm"
	PrivilegeSYSRAC    Privilege = "sysrac"
)

The administrative privileges.

type Querier ¶

type Querier = ttc.Querier

Querier runs a query, as *sql.DB, *sql.Conn and *sql.Tx do.

type RefCursor ¶

type RefCursor = ttc.RefCursor

RefCursor is a REF CURSOR that a PL/SQL call returns. WrapRefCursor reads its rows as *sql.Rows.

type RowError ¶

type RowError = tns.RowError

RowError is the error of one row of a BatchError.

type RowID ¶

type RowID = types.RowID

RowID is a ROWID. A column of the type ROWID scans into it.

type SSLMode ¶

type SSLMode string

SSLMode says whether a connection uses TLS, and what it checks. The values are the ones of the sslmode key of pgx and lib/pq (D11).

const (
	// SSLDisable speaks TCP with no TLS.
	SSLDisable SSLMode = "disable"
	// SSLRequire speaks TLS and checks no certificate.
	SSLRequire SSLMode = "require"
	// SSLVerifyCA speaks TLS and checks that a known authority signed the
	// certificate of the server, and not its name.
	SSLVerifyCA SSLMode = "verify-ca"
	// SSLVerifyFull speaks TLS and checks the authority and the name.
	SSLVerifyFull SSLMode = "verify-full"
)

The modes. An Oracle listener speaks TCP or TCPS on one port, never both, so the allow and prefer modes of pgx do not exist here.

type ServerError ¶

type ServerError = tns.OracleError

ServerError is an error that the server returned, with its ORA code in ErrCode. Its method AuthenticationRefused reports whether the server refused the credential, as usql asks an error, and matches errors.Is(err, ErrAuthentication).

type ServiceLevel ¶

type ServiceLevel string

ServiceLevel is how much the client wants an Oracle Net service, such as encryption or checksums. The server compares it with its own level.

const (
	ServiceAccepted  ServiceLevel = "accepted"
	ServiceRejected  ServiceLevel = "rejected"
	ServiceRequested ServiceLevel = "requested"
	ServiceRequired  ServiceLevel = "required"
)

The service levels of Oracle Net.

type SparseVector ¶

type SparseVector = types.SparseVector

SparseVector is a sparse VECTOR: the number of its dimensions, and the indices and values of the elements that are not zero.

type TimestampTZ ¶

type TimestampTZ = types.TimestampTZ

TimestampTZ is a time that binds as TIMESTAMP WITH TIME ZONE, where a time.Time binds as TIMESTAMP. A nullable one is sql.Null[TimestampTZ].

type Vector ¶

type Vector = types.Vector

Vector is a VECTOR of Oracle 23ai and later.

func CreateVector ¶

func CreateVector(array any) (*Vector, error)

CreateVector returns a VECTOR that holds array: a []float32, a []float64, a []int8, a []byte of the BINARY format, which holds 8 dimensions in each byte, or a SparseVector. A VECTOR column scans into a *Vector, or into a pointer to the type of its elements.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
aq
internal
auth
auth/ntlmssp Package ntlmssp provides NTLM/Negotiate authentication over HTTP	Package ntlmssp provides NTLM/Negotiate authentication over HTTP
auth/ntlmssp/md4 Package md4 implements the MD4 hash algorithm as defined in RFC 1320.	Package md4 implements the MD4 hash algorithm as defined in RFC 1320.
auth/security
charset
codec
codec/oson
config
tns
tnstest Package tnstest records the TNS packets that the driver and a server exchange, and plays them back to the driver with no server.	Package tnstest records the TNS packets that the driver and a server exchange, and plays them back to the driver with no server.
ttc
types

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

oracle

Features

Installation

Quick Start

Connection options

Values

Reading a LOB in pieces

New Types

VECTOR (Oracle 23ai)

JSON (Oracle 21c+)

BOOLEAN

Advanced Queuing

User-Defined Types

Session parameters

Options of one statement

DBMS_OUTPUT

Logging

Architecture

Design Principles

Migration from go-ora

Related Projects

Contributing

License

Documentation ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

func DisableOutput ¶

func EnableOutput ¶

func NewBatch ¶

func ReadOutput ¶

func RegisterType ¶

func RegisterTypeWithOwner ¶

func WithOptions ¶

func WrapRefCursor ¶

Types ¶

type Auth ¶

type BFile ¶

func CreateBFile ¶

type BatchError ¶

type Blob ¶

func CreateBlob ¶

type Bool ¶

type Client ¶

type Clob ¶

func CreateClob ¶

type Config ¶

func ParseDSN ¶

func (Config) DSN ¶

type Connector ¶

func NewConnector ¶

func (*Connector) Close ¶

func (*Connector) Connect ¶

func (*Connector) Driver ¶

type ConnectorOption ¶

func WithSessionParam ¶

func WithWallet ¶

type Dialer ¶

type Driver ¶

func (Driver) Open ¶

func (Driver) OpenConnector ¶

type Error ¶

type Execer ¶

type IntervalYM ¶

type JSON ¶

func NewJSON ¶

type Kerberos ¶

type LobFetch ¶

type LobRead ¶

type LobReader ¶

type NTS ¶

type NVarChar ¶

type Object ¶

type Option ¶

func WithBatchErrors ¶

func WithDatabase ¶

func WithLobFetch ¶

func WithParameter ¶