Ecosyste.ms: Packages

proxy.golang.org : gopkg.in/rana/ora.v1

Package ora implements an Oracle database driver. An Oracle database may be accessed through the database/sql package or through the ora package directly. database/sql offers connection pooling, thread safety, a consistent API to multiple database technologies and a common set of Go types. The ora package offers additional features including pointers, slices, nullable types, numerics of various sizes, Oracle-specific types, Go return type configuration, and Oracle abstractions such as environment, server and session. The ora package is written with the Oracle Call Interface (OCI) C-language libraries provided by Oracle. The OCI libraries are a standard for client application communication and driver communication with Oracle databases. The ora package has been verified to work with Oracle Enterprise 12c (12.1.0.1.0) on Windows 8.1. Minimum requirements are Go 1.3 with CGO enabled, a GCC C compiler, and Oracle 12c (12.1.0.1.0) or Oracle Instant Client (12.1.0.1.0). Get the ora package from GitHub: Install Oracle 12c or Oracle Instant Client. Set the CGO_CFLAGS and CGO_LDFLAGS environment variables to locate the OCI headers and library. For example: CGO_CFLAGS identifies the location of the OCI header file. CGO_LDFLAGS identifies the location of the OCI library. These locations will vary based on whether an Oracle database is locally installed or whether the Oracle instant client libraries are locally installed. The ora package supports all built-in Oracle data types. The supported Oracle built-in data types are NUMBER, BINARY_DOUBLE, BINARY_FLOAT, FLOAT, DATE, TIMESTAMP, TIMESTAMP WITH TIME ZONE, TIMESTAMP WITH LOCAL TIME ZONE, INTERVAL YEAR TO MONTH, INTERVAL DAY TO SECOND, CHAR, NCHAR, VARCHAR, VARCHAR2, NVARCHAR2, LONG, CLOB, NCLOB, BLOB, LONG RAW, RAW, ROWID and BFILE. SYS_REFCURSOR is also supported. Oracle does not provide a built-in boolean type. Oracle provides a single-byte character type. A common practice is to define two single-byte characters which represent true and false. The ora package adopts this approach. The oracle package associates a Go bool value to a Go rune and sends and receives the rune to a CHAR(1 BYTE) column or CHAR(1 CHAR) column. The default false rune is zero '0'. The default true rune is one '1'. The bool rune association may be configured or disabled when directly using the ora package but not with the database/sql package. Within a SQL string a placeholder may be specified to indicate where a Go variable is placed. The SQL placeholder is an Oracle identifier, from 1 to 30 characters, prefixed with a colon (:). For example: Placeholders within a SQL statement are bound by position. The actual name is not used by the ora package driver e.g., placeholder names :c1, :1, or :xyz are treated equally. You may access an Oracle database through the database/sql package. The database/sql package offers a consistent API across different databases, connection pooling, thread safety and a set of common Go types. database/sql makes working with Oracle straight-forward. The ora package implements interfaces in the database/sql/driver package enabling database/sql to communicate with an Oracle database. Using database/sql ensures you never have to call the ora package directly. When using database/sql, the mapping between Go types and Oracle types is immutable. The Go-to-Oracle type mapping for database/sql is: The ora package allows programming with pointers, slices, nullable types, numerics of various sizes, Oracle-specific types, Go return type configuration, and Oracle abstractions such as environment, server and session. When working with the ora package directly, the API is slightly different than database/sql. When using the ora package directly, the mapping between Go types and Oracle types is mutable. The Go-to-Oracle type mapping for the ora package is: An example of using the ora package directly: Pointers may be used to capture out-bound values from a SQL statement such as an insert or stored procedure call. For example, a numeric pointer captures an identity value: A string pointer captures an out parameter from a stored procedure: Slices may be used to insert multiple records with a single insert statement: The ora package provides nullable Go types to support DML operations such as insert and select. The nullable Go types provided by the ora package are Int64, Int32, Int16, Int8, Uint64, Uint32, Uint16, Uint8, Float64, Float32, Time, IntervalYM, IntervalDS, String, Bool, Bytes and Bfile. For example, you may insert nullable Strings and select nullable Strings: The Statement.Prepare method is variadic accepting zero or more GoColumnType which define a Go return type for a select-list column. For example, a Prepare call can be configured to return an int64 and a nullable Int64 from the same column: Go numerics of various sizes are supported in DML operations. The ora package supports int64, int32, int16, int8, uint64, uint32, uint16, uint8, float64 and float32. For example, you may insert a uint16 and select numerics of various sizes: If a non-nullable type is defined for a nullable column returning null, the Go type's zero value is returned. GoColumnTypes defined by the ora package are: When Statement.Prepare doesn't receive a GoColumnType, or receives an incorrect GoColumnType, the default value defined in ResultSetConfig is used. There are two configuration structs, StatementConfig and ResultSetConfig. StatementConfig configures various aspects of a Statement. ResultSetConfig configures various aspects of a ResultSet, including the default mapping between a select-list column and a Go type. StatementConfig may be set in an Environment, Server, Session and Statement. ResultSetConfig may be set in a ResultSet and StatementConfig. Setting a StatementConfig on a configurable struct, such as Environment, Server, Session or Statement, cascades the StatementConfig to all current and future descendent structs. An Environment may contain multiple Servers. A Server may contain multiple Sessions. A Session may contain multiple Statements. A Statement may contain multiple ResultSets. Setting a ResultSetConfig on a StatementConfig does not cascade through descendent structs. One configuration scenario may be to set a server's select statements to return nullable Go types by default: Another scenario may be to configure the runes mapped to bool values: Oracle-specific types offered by the ora package are ResultSet, IntervalYM, IntervalDS, and Bfile. ResultSet represents an Oracle SYS_REFCURSOR. IntervalYM represents an Oracle INTERVAL YEAR TO MONTH. IntervalDS represents an Oracle INTERVAL DAY TO SECOND. And Bfile represents an Oracle BFILE. ROWID columns are returned as strings and don't have a unique Go type. ResultSet is used to obtain Go values from a SQL select statement. ResultSet has two usages. Statement.Fetch may be called to obtain a ResultSet when a SQL select statement is provided to Statement.Prepare: ResultSet may also be used with stored procedure parameters that are defined as OUT SYS_REFCURSOR. For example: Stored procedures with multiple SYS_REFCURSOR parameters enable a single Execute call to obtain multiple ResultSets: Opening and closing ResultSets is managed internally. ResultSet doesn't have an Open method or Close method. ResultSet prefetching may be controlled by StatementConfig.PrefetchRowCount and StatementConfig.PrefetchMemorySize. PrefetchRowCount works in coordination with PrefetchMemorySize. When PrefetchRowCount is set to zero only PrefetchMemorySize is used; otherwise, the minimum of PrefetchRowCount and PrefetchMemorySize is used. The default uses a PrefetchMemorySize of 134MB. IntervalYM may be be inserted and selected: IntervalDS may be be inserted and selected: Transactions on an Oracle server are supported: The Server.Ping method is available to check whether the client's connection to the Oracle server is valid. A call to Ping requires an open Session. Ping will return a nil error when the connection is fine: The Server.Version method is available to obtain the Oracle server version. A call to Version requires an open Session: Further code examples are available in the samples folder, example file and test files. Tests are available and require some setup. Setup varies depending on whether the Oracle server is configured as a container database or non-container database. It's simpler to setup a non-container database. An example for each setup is explained. Non-container test database setup steps: Container test database setup steps: Some helpful SQL maintenance statements: Run the tests. database/sql method Stmt.QueryRow is not supported. Copyright 2014 Rana Ian. All rights reserved. Use of this source code is governed by The MIT License found in the accompanying LICENSE file.

Registry - Source - Documentation - JSON
purl: pkg:golang/gopkg.in/rana/ora.v1
Keywords: database, driver, go, golang, golang-package, oracle, oracle-database, oracle-db
License: MIT
Latest release: 18 days ago
Namespace: gopkg.in/rana
Stars: 272 on GitHub
Forks: 65 on GitHub
See more repository details: repos.ecosyste.ms
Last synced: 18 days ago

• Versions 0
• Dependent Packages 0
• Maintainers 0
• Related Packages 4