godror

Contents

Go DRiver for ORacle User Guide

Godror Connection Handling

Connect to Oracle Database using sql.Open("godror", dataSourceName) where dataSourceName contains options such as the user credentials, the database connection string, and other configuration settings. It should be a logfmt-encoded parameter list. For example:

db, err := sql.Open("godror", `user="scott" password="tiger" connectString="dbhost:1521/orclpdb1"
    poolSessionTimeout=42s configDir="/tmp/admin"
    heterogeneousPool=false standaloneConnection=false`)

Other connection and driver options can also be used:

db, err := sql.Open("godror", `user="scott" password="tiger"
    connectString="dbhost:1521/orclpdb1?connect_timeout=2"
    poolSessionTimeout=42s configDir="/opt/oracle/configdir"
    heterogeneousPool=false standaloneConnection=false
    timezone="Europe/Berlin"`)

[!TIP] On MacOS, when setting (DY)_LD_LIBRARY_PATH for the Oracle Instant Client lib files does not work (Variables LD_LIBRARY_PATH / DYLD_LIBRARY_PATH are not passed to the environment of a child process on macOS if System Integrity Protect (SIP) is enabled.), you can put that into the connection string’s libDir parameter.

See this issue.

All godror parameters should also be logfmt-ted.

You can provide all possible options with ConnectionParams:

var P godror.ConnectionParams
P.Username, P.Password = "scott", godror.NewPassword("tiger")
P.ConnectString = "dbhost:1521/orclpdb1?connect_timeout=2"
P.SessionTimeout = 42 * time.Second
P.SetSessionParamOnInit("NLS_NUMERIC_CHARACTERS", ",.")
P.SetSessionParamOnInit("NLS_LANGUAGE", "FRENCH")
P.Timezone = time.Local
fmt.Println(P.StringWithPassword())
db := sql.OpenDB(godror.NewConnector(P))

Or if you really want to build it “by hand”, use connstr.AppendLogfmt:

var buf strings.Builder
connstr.AppendLogfmt(&buf, "user", "scott")
connstr.AppendLogfmt(&buf, "password", "tiger")
connstr.AppendLogfmt(&buf, "connectString", "dbhost:1521/orclpdb1?connect_timeout=2")
connstr.AppendLogfmt(&buf, "timezone", "Europe/Berlin")
fmt.Println(buf.String())

Note ConnectionParams.String() redacts the password (for security, to avoid logging it - see https://github.com/go-goracle/goracle/issues/79). If you need the password, then use ConnectionParams.StringWithPassword().

Connection Strings

The sql.Open() data source name connectString parameter or ConnectionParams field ConnectString can be one of:

Optional Oracle Net Configuration Files

Optional Oracle Net configuration files are used by the Oracle Client libraries during the first call to sql.Open. The directory containing the files can be specified in the sql.Open() data source name with the configDir option.

The common files are:

The files should be in a directory accessible to godror, not on the database server host.

If the configDir connection option is not used, then a search heuristic is used to find the directory containing the files. The search includes:

Oracle Autonomous DataBase (ADB)

See https://blogs.oracle.com/opal/how-connect-to-oracle-autonomous-cloud-databases for ADB-specific guide.

Oracle Session Pooling

Set standaloneConnection=0 - this is the default. The old advice of setting db.SetMaxIdleConns(0) are obsolete with Go 1.14.6. It does no harm, but the revised connection pooling (synchronous ResetSession before pooling the connection) eliminates the need for it.

To use heterogeneous pools, set heterogeneousPool=1 and provide the username and password through godror.ContextWithUserPassw or godror.ContextWithParams.

WARNING if you cannot use Go 1.14.6 or newer, then either set standaloneConnection=1 or disable Go connection pooling by db.SetMaxIdleConns(0) - they do not work well together, resulting in stalls!

Backward compatibility

For backward compatibility, you can still provide ANYTHING as the dataSourceName, if it is one line, and is not logfmt-encoded, then it will be treated as a connectString. So

works, too.

This site is open source. Improve this page.