OceanBaseConnector 0.2.0
See the version list below for details.
dotnet add package OceanBaseConnector --version 0.2.0
NuGet\Install-Package OceanBaseConnector -Version 0.2.0
<PackageReference Include="OceanBaseConnector" Version="0.2.0" />
<PackageVersion Include="OceanBaseConnector" Version="0.2.0" />
<PackageReference Include="OceanBaseConnector" />
paket add OceanBaseConnector --version 0.2.0
#r "nuget: OceanBaseConnector, 0.2.0"
#:package OceanBaseConnector@0.2.0
#addin nuget:?package=OceanBaseConnector&version=0.2.0
#tool nuget:?package=OceanBaseConnector&version=0.2.0
OceanBaseConnector
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:
- Feature and capability matrix: MySQL/Oracle scope and implemented subsets.
- Missing functionality and verification gaps: code limits, optional candidates and deployment blockers.
- Acceptance criteria: required behavior, complete live suites, failure/skip and cleanup rules.
- Official/Java evidence and cleanup decisions.
- Compatibility and retained TLS/environment limitations.
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();
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 INFILEis opt-in withAllow Local Infile=trueand an application-providedLocalInfileStreamFactory; 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)andGetDataReaderAsync(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 requireUse 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.
GetSchemaexposes 20 Oracle-mode / 18 MySQL-mode collections, including views, indexes, keys/constraints, foreign keys, sequences and users; Oracle also provides named types and synonyms.Restrictionsdescribes exact bound filters; staticDataTypesreports CLR/provider mappings and conditional codec support. See the Schema contract for permissions and mode limits; real directory/OBProxy validation remains open.OceanBaseParameter.DecimalScaledeclares 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.
CredentialProviderand modern builderUseCredentialProviderobtain 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=1enables 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=truereuses authenticated physical sessions, validates reused sessions, resets them before return, and supportsMin Pool Size,Max Pool Size,Pool Wait Timeout,Connection Idle LifetimeandConnection Lifetime;Min Pool Sizeprewarms 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 ambientTransactionScopeenlists one local transaction through the coordinator single-resource slot. A second database resource and distributed promotion are rejected. Lost COMMIT responses report InDoubt; automaticOpenAsyncinitialization 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 usesource.Clear()orClearPoolwith 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@@autocommitenabled, rejecting sessions whose implicit transactions this provider could not commit. Oracle opens explicitly confirmset 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
The workflow builds and tests on Windows and Linux for pull requests targeting main/master, pushes to those branches, and tag pushes.
| Event | Build and test | Pack and verify NuGet consumers | Publish to NuGet and GitHub Releases |
|---|---|---|---|
Pull request to main/master |
Yes | No | No |
Push to main/master |
Yes | Yes | No |
| Version tag push | Yes | Yes | Yes, after both operating systems pass |
| Other branch push | No | No | No |
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 rebuilding them. 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 such as v0.1.0 (or 0.1.0). A mismatched tag fails before building or publishing. Prerelease versions such as v0.2.0-rc.1 create 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 v0.1.0; the output defaults to TestResults/packages/RELEASE_NOTES.md.
Documentation
- Compatibility and known limitations
- Complete driver audit report
- Complete driver capability baseline and gap plan
- Database acceptance guide
- Opt-in controlled network outcome acceptance
- Opt-in XA coordinator process recovery acceptance
- Opt-in controlled topology acceptance
- Integration test guide
- API reference
- Credential provision and rotation
- Verification status and remaining work
- Connector/J architecture reference
License
MIT. See third-party notices.
| Product | Versions 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. |
-
.NETStandard 2.0
- BouncyCastle.Cryptography (>= 2.7.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.0)
- SharpZipLib (>= 1.4.2)
- System.Diagnostics.DiagnosticSource (>= 10.0.0)
- System.Text.Encoding.CodePages (>= 10.0.0)
-
.NETStandard 2.1
- BouncyCastle.Cryptography (>= 2.7.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.0)
- SharpZipLib (>= 1.4.2)
- System.Diagnostics.DiagnosticSource (>= 10.0.0)
- System.Text.Encoding.CodePages (>= 10.0.0)
-
net10.0
- BouncyCastle.Cryptography (>= 2.7.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.0)
- SharpZipLib (>= 1.4.2)
-
net8.0
- BouncyCastle.Cryptography (>= 2.7.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.0)
- SharpZipLib (>= 1.4.2)
-
net9.0
- BouncyCastle.Cryptography (>= 2.7.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 9.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 9.0.0)
- SharpZipLib (>= 1.4.2)
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.