go-ora

go-ora is a native Go implementation of Oracle’s TNS wire protocol, giving Go applications a way to talk to Oracle Database (10.2 and newer) without linking against Oracle Instant Client, OCI, or any C libraries. It registers itself as a standard database/sql driver under the name oracle, so existing code that already uses Go’s database/sql package can query, execute DDL/DML, and call PL/SQL blocks with familiar Query, Exec, and QueryRow calls.

Beyond basic CRUD, the driver reimplements a substantial slice of Oracle’s client-side behavior in pure Go: bulk insert/update/merge via array binding, LOB (CLOB/BLOB/NCLOB) streaming, REF CURSOR output parameters, user-defined object types, Oracle wallet-based authentication, TLS/SSL and TCPS connections, and struct-tag-driven parameter binding. Its own connection-string builders (BuildUrl, BuildJDBC) cover the option surface DBAs expect: timeouts, failover, SYSDBA/SYSOPER privileges, custom string converters for non-UTF8 client charsets, and packet-level trace logging for debugging.

Because it has zero third-party dependencies and compiles to a single static binary, it’s a common choice for containerized Go services, CLI tools, and CI pipelines that need to reach an Oracle database without the deployment overhead of Oracle’s official client libraries.

What You Get

• A database/sql-compatible driver registered under the name oracle, usable with the standard sql.Open, Query, Exec, and transaction APIs
• Connection-string builders (BuildUrl, BuildJDBC) covering SSL/TLS, Oracle wallet paths, failover, DBA privileges, and session tracing options
• Support for advanced data types: CLOB/BLOB/NCLOB streaming, REF CURSOR, ROWID/UROWID, TIMESTAMP WITH TIME ZONE, BFILE, and user-defined object types
• Bulk operations (batch insert, update, and merge) via array parameter binding for high-throughput writes
• Struct-tag-based parameter mapping (db:"NAME,type") for binding Go structs directly to PL/SQL IN/OUT parameters
• Zero external dependencies and no CGO requirement, producing fully static, cross-compilable binaries

Common Use Cases

• Connecting a Go backend service to an existing Oracle database without deploying Oracle Instant Client alongside it
• Running Go-based CLI tools or migration scripts against Oracle from minimal container images (scratch/distroless)
• Calling PL/SQL stored procedures and packages with typed IN/OUT parameters from Go application code
• Bulk-loading or bulk-updating large datasets into Oracle tables via array binding instead of row-by-row inserts
• Streaming large CLOB/BLOB columns (documents, binary payloads) into and out of Oracle without loading them fully into memory

Under The Hood

Architecture The codebase is layered around the standard database/sql/driver contract: driver.go registers an OracleDriver with Go’s sql.Register, connection.go owns TCP session lifecycle and Oracle Net (TNS) handshake/negotiation, and command.go handles statement execution, parameter binding, and PL/SQL block execution. Beneath that, the network/ package implements the wire-level TNS packet types (connect, accept, data packets) and advanced_nego/ implements Oracle’s advanced negotiation services for authentication and data-integrity/encryption, while converters/ and configurations/ isolate Oracle-specific number/date encoding and connection-string parsing respectively. This gives a clean top-to-bottom path — public driver API, session/connection management, protocol framing, data marshaling — with no single package owning more than one concern, though a change to the TNS negotiation layer in advanced_nego/ would ripple through both connection.go and command.go since both depend on an established, authenticated session.

Tech Stack Written in Go (module targets Go 1.18+) with zero runtime dependencies declared in go.mod — the entire Oracle Net protocol, authentication negotiation, and data type marshaling are implemented from scratch rather than wrapping Oracle’s official OCI/Instant Client libraries. It builds with the standard Go toolchain (go build), integrates with database/sql as its only external-facing API surface, and ships CI via GitHub Actions running go fmt, go build, go test, and golangci-lint across two Go version targets.

Code Quality The repository has a focused set of test files (connection_test.go, command_test.go, bulkcopy_test.go, parameter_encode_test.go, urowid_test.go, utils_test.go) covering connection handling, bulk-copy operations, and type encoding, plus a dedicated TestIssues directory for regression cases tied to specific bug reports. Error handling follows idiomatic Go conventions with explicit error returns rather than panics for recoverable failures, comment density in core files like connection.go and command.go is comparatively high for a systems-level driver, and CI enforces go fmt and golangci-lint on every pull request. No table-driven test coverage summary is published, so overall test depth relative to the protocol surface is not independently verifiable from the repo alone.

What Makes It Unique Most Go Oracle clients historically required CGO bindings to Oracle’s Instant Client / OCI libraries, which complicates cross-compilation and forces larger, non-static container images. go-ora’s distinguishing choice is reimplementing Oracle’s proprietary TNS wire protocol — including its advanced negotiation, authentication, and encryption handshake — entirely in pure Go, producing a dependency-free, statically-linked driver that behaves like any other native Go database driver while still supporting comparatively advanced Oracle-specific features like wallet auth, object types, and array-bind bulk operations.