OceanBaseConnector 0.3.1

There is a newer version of this package available.
See the version list below for details.
dotnet add package OceanBaseConnector --version 0.3.1
                    
NuGet\Install-Package OceanBaseConnector -Version 0.3.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="OceanBaseConnector" Version="0.3.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="OceanBaseConnector" Version="0.3.1" />
                    
Directory.Packages.props
<PackageReference Include="OceanBaseConnector" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add OceanBaseConnector --version 0.3.1
                    
#r "nuget: OceanBaseConnector, 0.3.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package OceanBaseConnector@0.3.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=OceanBaseConnector&version=0.3.1
                    
Install as a Cake Addin
#tool nuget:?package=OceanBaseConnector&version=0.3.1
                    
Install as a Cake Tool

OceanBaseConnector

CI/CD NuGet License

A managed ADO.NET provider for OceanBase MySQL and Oracle tenant compatibility modes. One provider shares protocol infrastructure and keeps mode-specific SQL, binding, types and metadata. It does not promise complete native MySQL or Oracle driver compatibility.

The driver is experimental. Historical live evidence covers selected direct OceanBase4.4.2.2 cases on Windows with TLS disabled. Oracle server/permission/shape failures remain recorded; real TLS/mTLS, OBProxy, genuine OB20/trace/compression, other versions and full platform/load matrices remain open.

Start with the documentation index:

Core connections, commands, parameters, readers and transactions use ADO.NET APIs. Pooling, caching, batch optimizations, Oracle LOB/complex types/XA, discovery and protocol extensions have explicit options and boundaries. Sent operations with unknown outcomes are never replayed automatically. TLS defaults to VerifyFull; the local plain-transport test environments require an explicit Disabled setting.

Packages

Package Purpose
OceanBaseConnector Connections, commands, parameters, readers and transactions.
OceanBaseConnector.DependencyInjection Optional dependency injection integration.

Both packages target netstandard2.0, netstandard2.1, net8.0, net9.0 and net10.0. Data sources and batches are available on the .NET 8/9/10 assets.

Usage

This example uses Oracle mode and a server certificate trusted by the client:

using System.Data;
using OceanBaseConnector;

using var connection = new OceanBaseConnection(
    "Server=db.example;Port=2881;User ID=test_user@tenant;Password=replace-me;ExpectedMode=Oracle");
await connection.OpenAsync();

using var command = connection.CreateCommand();
command.CommandText = "select :value from dual";
var parameter = command.CreateParameter();
parameter.ParameterName = "value";
parameter.DbType = DbType.Int32;
parameter.Value = 42;
command.Parameters.Add(parameter);

var result = await command.ExecuteScalarAsync();

For the complete keyword list, defaults and validation rules see the connection string reference.

ExpectedMode validates the detected mode; it does not change the server mode. TLS defaults to VerifyFull, validating certificate trust and hostnames. Set Check Certificate Revocation=true to enable platform revocation checks. For mutual TLS, assign an application-owned certificate with a private key to OceanBaseConnection.ClientCertificate before opening. Pooling supports client certificates and isolates certificate instances and SHA-256 fingerprints; reuse a stable certificate instance for one ordinary pool. The application must keep that certificate valid through each Open.

Modern data sources offer OceanBaseDataSourceBuilder.UseClientCertificate(...). Build captures an owned copy even with pooling disabled, so the original can be disposed after Build succeeds. Source connections inherit fixed configuration. Certificate rotation uses a new data source; dispose the old source and close its borrowed connections when retiring that identity. Pooled borrow does not repeat TLS validation. See the client certificate contract for ownership and rotation limits.

For enterprise trust or certificate pinning, set OceanBaseConnection.RemoteCertificateValidationCallback before Open, or use OceanBaseDataSourceBuilder.UseRemoteCertificateValidationCallback(...). This requires TLS Mode=VerifyFull. A callback replaces the platform validation decision and must handle certificate, chain, hostname and revocation errors; null retains platform validation. Ordinary pools isolate callback instances by reference. Validation runs at physical TLS establishment, not at each pooled borrow; rebuild/dispose the data source when retiring a trust policy. See the TLS API contract.

Every Open confirms the actual OceanBase version and tenant mode. Server features are selected from the actual version and negotiated capabilities, without a JDBC 5/8 compatibility profile. In MySQL mode, signed TINYINT(1) returns bool by default (nonzero is true); set Treat Tiny As Boolean=false to read integers. UPDATE reports matched rows by default; set Use Affected Rows=true to request changed rows. See the configuration reference.

With the DI package:

using Microsoft.Extensions.DependencyInjection;

services.AddOceanBaseConnection(connectionString);

Each resolution creates a closed transient connection owned by its container scope. On .NET 8/9/10, AddOceanBaseDataSource and AddKeyedOceanBaseDataSource register singleton data sources; callers dispose the connections they create.

Features and limits

  • Synchronous and asynchronous SQL, server-prepared parameters, multiple results, streaming reads and binary uploads.
  • Text multi-statements are opt-in with Allow Multi Statements=true. Oracle named and MySQL positional inputs support numbers, strings, binary, JSON (MySQL), NChar/NVarchar2 (Oracle) and NULL, plus MySQL DATE/DATETIME/TIMESTAMP/TIME and Oracle DATE/TIMESTAMP/TIMESTAMP WITH TIME ZONE/TIMESTAMP WITH LOCAL TIME ZONE/INTERVAL YEAR TO MONTH/INTERVAL DAY TO SECOND. Oracle national inputs use ASCII Unicode literals, preserving characters outside the client charset; national result decoding requires fresh trusted state and uses the supported explicit encoding mappings. MySQL strings tolerate SQL_MODE changes but require stable parsing character sets. Binary Input streams use bounded client-literal encoding; MySQL scalar Output/InputOutput/ReturnValue positions use private user variables, with atomic publication after the script and a hidden output SELECT complete; reader close drains the active script. Script or output-query errors preserve prior parameter values but do not undo successful SQL. Stream/locator/complex outputs, Oracle script outputs, Prepare and server cursors remain unsupported. Oracle named complex input support is limited to the documented D-02d1 through D-02d3 and D-04f subsets. See compatibility for limits.
  • Server-initiated LOCAL INFILE is opt-in with Allow Local Infile=true and an application-provided LocalInfileStreamFactory; the driver never opens the server filename as a local path. Real OceanBase/OBProxy interoperability remains unverified.
  • Local transactions; .NET 8/9/10 assets also expose savepoints and sequential batches.
  • MySQL stored procedures support binary InputOutput streams through prepared SET/CALL, with caller-owned sources and outputs published after complete results. See INOUT stream evidence.
  • Opt-in client prepare fallback accepts MySQL BIT/YEAR inputs using exact numeric literals after a validated unsupported-Prepare response. See fallback evidence and deployment limits.
  • Explicit MySQL JSON inputs also support that opt-in fallback, using fresh session charset/SQL_MODE facts and ordinary string literals. JSON syntax remains server-validated; see JSON fallback evidence.
  • MySQL DATE/DATETIME/TIME inputs also support opt-in fallback, retaining exact input precision and current-session TIMESTAMP conversion. TIME cap fractions have server-specific binary/text differences; see temporal evidence and the completed/remaining checkpoint.
  • REF CURSOR readers offer opt-in forward offset FETCH through GetDataReader(fetchSize, useCursorOffset, behavior) and GetDataReaderAsync(fetchSize, useCursorOffset, behavior, cancellationToken). For declared REF CURSOR outputs, a positive parent FetchSize with UseCursorOffset=true supplies the existing reader overloads' default; explicit reader bool overloads override it, and child page size remains independent. Other calls retain ordinary FETCH. Offset readers validate every position tail, including the first page; scrolling, array offset and cursor-valued parent columns remain unsupported.
  • Oracle extensions include stored procedures, OUT parameters, REF CURSOR, LOB locators, complex types and array binding. Procedures and output parameters require Use Oracle Prepare Execute=true; locator LOBs also require Use Lob Locators=true.
  • Oracle binary InputOutput streams use the existing prepared piece upload and retain caller ownership. Outputs follow server metadata: the verified anonymous procedure wrapper returns RAW content as CHAR hex text. See Oracle INOUT stream evidence.
  • Complex LOB inputs support named BLOB bytes/CLOB text and anonymous BLOB/CLOB arrays of session-bound locator handles. Single-statement Oracle Text/StoredProcedure named locator inputs use validated constructors with hidden root LOB binds; independent scalar and specified resource outputs, batch input-only subsets, and specified mixed batch routine-barrier output combinations are supported. Complex locator InputOutput and multi-statement expansion remain unsupported; see the complex type input contract.
  • CLOB locator parameters convert inline content in a sending copy for configured client charsets (V1; V2 on authenticated OceanBase4.4.1+). Original handles and UTF-8 readers retain their bytes; see the charset contract.
  • Explicit XA, multiple server addresses, custom address resolution, logging, tracing and metrics.
  • MySQL ARRAY values use the existing String parameter/result path. Current direct acceptance covers INT nesting and single-level TINYINT/SMALLINT/BIGINT/FLOAT/DOUBLE/VARCHAR arrays. Results preserve the server representation: FLOAT array text may round values, and VARCHAR array text may contain raw control characters and incomplete JSON escaping. Do not assume lossless text rebinding or JSON parsing; see compatibility.
  • Named Oracle OBJECT/collection values support exact INTERVAL YEAR TO MONTH and DAY TO SECOND members in binary inputs/results and PL OUT/INOUT, including named client-constructor inputs. Use the existing interval provider values. Named OBJECT and nested OBJECT text results also decode exact INTERVAL members from the preloaded declaration (D-04f3; Oracle 4.4.2.2 direct, 24/24). Unknown declarations or malformed values are rejected; collection and other unsupported complex text shapes retain their guards. Canonical anonymous INTERVAL factories also support the verified ExecuteArray DML input/RETURNING subset (D-04f1); current PL outputs with unknown precision are rejected. Anonymous INTERVAL result descriptors now reuse the embedded-precision codec; explicitly declared precision-9 PL local collection OUT has initial direct evidence (D-04f2), but extended live acceptance is incomplete after endpoint handshake failures. Ordinary anonymous 0x17 binding and dedicated multi-send acceptance remain open. See D-04f in the roadmap.
  • GetSchema exposes 20 Oracle-mode / 18 MySQL-mode collections, including views, indexes, keys/constraints, foreign keys, sequences and users; Oracle also provides named types and synonyms. Restrictions describes exact bound filters; static DataTypes reports CLR/provider mappings and conditional codec support. See the Schema contract for permissions and mode limits; real directory/OBProxy validation remains open.
  • OceanBaseParameter.DecimalScale declares signed decimal scale, including Oracle NUMBER negative scales. Values requiring rounding are rejected; MySQL retains its narrower limits. See the parameter contract for precedence and mode bounds. Real-server declared-scale validation remains open.
  • Custom address resolution runs once per logical Open, including pool reuse. Ordinary pools isolate resolver instances; a fresh address snapshot retires idle sessions on removed host/port endpoints before reuse. Already borrowed sessions finish normally. With a custom resolver, the connection timeout also bounds discovery, pool waiting and prewarming.
  • CredentialProvider and modern builder UseCredentialProvider obtain one immutable credential per logical Open, including pool reuse. Higher versions retire old sessions without interrupting active borrowers; expiry, cancellation and refresh failures fail closed. Providers own caching/refresh and remain caller-owned. See the credential contract.
  • Statement Cache Size=1 enables a bounded idle prepared-statement cache per physical session (0..1024, default 0). Dispose commands to return entries; pool reset and observed schema/session context changes invalidate them. Commands still holding statements are outside the idle capacity limit.
  • Pooling=true reuses authenticated physical sessions, validates reused sessions, resets them before return, and supports Min Pool Size, Max Pool Size, Pool Wait Timeout, Connection Idle Lifetime and Connection Lifetime; Min Pool Size prewarms physical sessions before a borrow and rolls back sessions still idle after a failed warmup, preserving sessions already borrowed by concurrent Opens. Recognized user session-state and temporary-object statements discard the physical session instead of returning it to the pool. Opening inside an ambient TransactionScope enlists one local transaction through the coordinator single-resource slot. A second database resource and distributed promotion are rejected. Lost COMMIT responses report InDoubt; automatic OpenAsync initialization observes the opening cancellation token and discards an interrupted session. Cancelling that token after Open completes does not cancel the transaction. See the ambient contract.
  • OceanBaseConnection.ClearPool(connection) closes idle sessions for that identity and discards borrowed sessions when returned. ClearAllPools() clears ordinary registry pools; private data sources use source.Clear() or ClearPool with one of their connections. Active commands continue, and new Opens remain available. See the pool clearing contract.
  • Every connection confirms ob_version() and the tenant compatibility mode; MySQL-mode opens also require @@autocommit enabled, rejecting sessions whose implicit transactions this provider could not commit. Oracle opens explicitly confirm set autocommit = 1; pool return repeats it after successful reset, discarding the session on failure. See the Oracle baseline contract. Recognized version formats are accepted; versions beyond the recorded deployment and OBProxy still need real-server validation.

Use Compression=true enables standard MySQL zlib compression in either compatibility mode, including over TLS and pooled sessions. It requires server support and is off by default; combining it with Use OB20=true is currently rejected. OB20 compression, reroute and real-server compression validation remain open.

The driver does not automatically replay SQL. If OceanBaseException.IsExecutionOutcomeUnknown is true, reconcile the operation before retrying a write or commit. Batches run sequentially and need an explicit transaction for atomicity. Dispose readers, commands and connections; closing an unread reader can destroy its session.

Build and test

Requires the .NET 11 SDK and a .NET 10 runtime. Tests target and run on .NET 10. Certificate creation/import, TLS/mTLS handshakes and TLS consumer tests belong to the separate security acceptance suite, outside the main solution and CI. Real-database integration tests never run in CI or a plain dotnet test; they need an explicit opt-in and a configured environment (integration guide).

dotnet restore OceanBaseConnector.slnx
dotnet build OceanBaseConnector.slnx -c Release --no-restore
dotnet test OceanBaseConnector.slnx -c Release --no-build --no-restore
dotnet pack OceanBaseConnector.slnx -c Release --no-build --no-restore -o TestResults/packages

To check package consumption, run pwsh -File eng/Verify-Packages.ps1 -PackageDirectory TestResults/packages. This requires PowerShell 7.1+ and .NET/ASP.NET Core 8/9/10 runtimes. The script checks exact restored package hashes/assets and runs eight synthetic loopback protocol scenarios per asset/runtime profile, covering both modes, sync/async and buffered/sequential reads. Modern hosts assert the expected runtime major so major roll-forward cannot satisfy another profile. Add -VerifyNetFramework on Windows with .NET Framework 4.8 and its targeting pack to also run the Standard2.0 asset on desktop CLR. Standard2.0 transaction begin/commit and Close use synchronous APIs. These local checks require no database credentials and do not establish real-server compatibility.

CI/CD and releases

This repository and Locus share the same CI/CD conventions: pushes to the default branch and pull requests compile and test, and only a version tag publishes. Other branches (including dev) trigger nothing.

The workflow builds and tests on Windows and Linux for pull requests targeting master, pushes to master, and version tag pushes.

Event Build and test Pack and verify NuGet consumers Publish to NuGet and GitHub Releases
Pull request to master Yes No No
Push to master Yes Yes No
Version tag push Yes Yes Yes, after both operating systems pass
Other branch push No No No

Each run compiles once: tests reuse that build output and packing runs with --no-build --no-restore. Packages are built from the two projects under src/, verified on Windows, and retained as the nuget-packages workflow artifact. Tag publication downloads these same packages without checking out source, restoring, or rebuilding. Real database credentials are not required by this workflow.

To release, update the shared Version in Directory.Build.props, commit it, and push a matching tag (with or without a v prefix). A tag that mismatches Version or does not point to HEAD fails before building or publishing. A prerelease Version creates a GitHub prerelease.

Publication uses nuget.org trusted publishing, so no long-lived API key is stored: the publish job exchanges the workflow's GitHub OIDC token for a one-hour nuget.org API key immediately before pushing. Before the first tag release, sign in to nuget.org as the virtual profile that owns both package IDs and add a trusted publishing policy for repository owner cocosip, repository obconnector-dotnet, workflow file ci-cd.yml, and an empty environment. The workflow uses GITHUB_TOKEN with contents: write to create the GitHub Release.

Each release records the non-merge commits since the previous reachable version tag, a comparison link, and install commands for both packages. The first release includes the initial commit history. These notes and the verified .nupkg files are attached to the GitHub Release; each NuGet package's release notes link to it. Notes are generated from Git history, so use descriptive commit subjects. This does not replace the outstanding publication review in the verification status.

Check notes generation locally with pwsh -File eng/Test-ReleaseNotes.ps1. To preview an existing tag, check out that tag and run pwsh -File eng/New-ReleaseNotes.ps1 -Tag <tag>; the output defaults to TestResults/packages/RELEASE_NOTES.md.

Documentation

License

MIT. See third-party notices.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (4)

Showing the top 4 NuGet packages that depend on OceanBaseConnector:

Package Downloads
OceanBaseConnector.DependencyInjection

Dependency injection integration for the unified OceanBase ADO.NET provider.

SharpAbp.Abp.Dapper.OceanBase

SharpAbp Dapper OceanBase Module

SharpAbp.Abp.Data.SqlBuilder.OceanBase

SharpAbp Data SqlBuilder OceanBase Module

Sharp.OceanBase.EntityFrameworkCore

Entity Framework Core provider for OceanBase MySQL and Oracle compatibility modes.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.4.0 121 11/19/2026
0.3.1 126 11/18/2026
0.3.0 194 11/13/2026
0.2.0 152 11/9/2026
0.1.0 160 10/24/2026