OceanBase logo

OceanBase

A unified distributed database ready for your transactional, analytical, and AI workloads.

Product Overview
DEPLOY YOUR WAY

OceanBase Cloud

The best way to deploy and scale OceanBase

OceanBase Enterprise

Run and manage OceanBase on your infra

TRY OPEN SOURCE

OceanBase Community Edition

The free, open-source distributed database

OceanBase seekdb

Open source AI native search database

Customer Stories

Real-world success stories from enterprises across diverse industries.

View All
BY USE CASES

Mission-Critical Transactions

Global & Multicloud Application

Elastic Scaling for Peak Traffic

Real-time Analytics

Active Geo-redundancy

Database Consolidation

Resources

Comprehensive knowledge hub for OceanBase.

Blog

Live Demos

Training & Certification

Documentation

Official technical guides, tutorials, API references, and manuals for all OceanBase products.

View All
PRODUCTS

OceanBase Cloud

OceanBase Database

Tools

Connectors and Middleware

QUICK START

OceanBase Cloud

OceanBase Database

BEST PRACTICES

Practical guides for utilizing OceanBase more effectively and conveniently

Company

Learn more about OceanBase – our company, partnerships, and trust and security initiatives.

About OceanBase

Partner

Trust Center

Contact Us

International - English
中国站 - 简体中文
日本 - 日本語
Sign In
Start on Cloud

OceanBase

A unified distributed database ready for your transactional, analytical, and AI workloads.

Product Overview
DEPLOY YOUR WAY

OceanBase Cloud

The best way to deploy and scale OceanBase

OceanBase Enterprise

Run and manage OceanBase on your infra

TRY OPEN SOURCE

OceanBase Community Edition

The free, open-source distributed database

OceanBase seekdb

Open source AI native search database

Customer Stories

Real-world success stories from enterprises across diverse industries.

View All
BY USE CASES

Mission-Critical Transactions

Global & Multicloud Application

Elastic Scaling for Peak Traffic

Real-time Analytics

Active Geo-redundancy

Database Consolidation

Comprehensive knowledge hub for OceanBase.

Blog

Live Demos

Training & Certification

Documentation

Official technical guides, tutorials, API references, and manuals for all OceanBase products.

View All
PRODUCTS
OceanBase CloudOceanBase Database
ToolsConnectors and Middleware
QUICK START
OceanBase CloudOceanBase Database
BEST PRACTICES

Practical guides for utilizing OceanBase more effectively and conveniently

Learn more about OceanBase – our company, partnerships, and trust and security initiatives.

About OceanBase

Partner

Trust Center

Contact Us

Start on Cloud
编组
All Products
    • Databases
    • iconOceanBase Database
    • iconOceanBase Cloud
    • iconOceanBase Tugraph
    • iconInteractive Tutorials
    • iconOceanBase Best Practices
    • Tools
    • iconOceanBase Cloud Platform
    • iconOceanBase Migration Service
    • iconOceanBase Developer Center
    • iconOceanBase Migration Assessment
    • iconOceanBase Admin Tool
    • iconOceanBase Loader and Dumper
    • iconOceanBase Deployer
    • iconKubernetes operator for OceanBase
    • iconOceanBase Diagnostic Tool
    • iconOceanBase Binlog Service
    • Connectors and Middleware
    • iconOceanBase Database Proxy
    • iconEmbedded SQL in C for OceanBase
    • iconOceanBase Call Interface
    • iconOceanBase Connector/C
    • iconOceanBase Connector/J
    • iconOceanBase Connector/ODBC
    • iconOceanBase Connector/NET
icon

OceanBase Connector/NET

V1.1.0

  • What Is OceanBase Connector/NET
    • Introduction
  • Install and Connect
    • Installation process
    • Test the connection
    • Package reference and usage
    • Compatibility impact
  • User Guide
    • Quick Start
      • Complete example
    • Connection Strings and Data Source
      • Connection strings
    • Data Types
      • Overview of data types
    • Command and Parameter
      • Overview
    • Result Set
      • Supported result set types
    • ORM and Frameworks
      • Use Entity Framework Core
      • Use SqlSugar
      • Use FreeSql
  • Reference Information
    • Common Interfaces
      • Overview of commonly used interfaces
  • Version Release Records
    • OceanBase Connector/NET V1.0.0
    • OceanBase Connector/NET V1.1.0

Download PDF

Introduction Installation process Test the connection Package reference and usage Compatibility impact Complete example Connection strings Overview of data types Overview Supported result set types Use Entity Framework Core Use SqlSugar Use FreeSql Overview of commonly used interfaces OceanBase Connector/NET V1.0.0 OceanBase Connector/NET V1.1.0
OceanBase logo

The Unified Distributed Database for the AI Era.

Follow Us
Products
OceanBase CloudOceanBase EnterpriseOceanBase Community EditionOceanBase seekdb
Resources
DocsBlogLive DemosTraining & Certification
Company
About OceanBaseTrust CenterLegalPartnerContact Us
Follow Us

© OceanBase 2026. All rights reserved

Cloud Service AgreementPrivacy PolicySecurity
Contact Us
Document Feedback
  1. Documentation Center
  2. OceanBase Connector/NET
  3. V1.1.0
iconOceanBase Connector/NET
V 1.1.0
  • V 1.1.0
  • V 1.0.0

Use SqlSugar

Last Updated:2026-04-28 03:38:03  Updated
share
What is on this page
Installation
Connection string
Access method
Method A (Recommended): DbType.Custom + InstanceFactory
Method B: DbType.OceanBaseForOracle + CustomDllName
Startup encapsulation (SqlSugarOceanBaseBootstrap)
Initialize SqlSugarScope
Complete example
ADO and parameterized queries
CodeFirst / DbFirst
CodeFirst
DbFirst/Metadata reading
Recommended usage
Current limitations and considerations
1. DbType can be set to DbType.Custom or DbType.OceanBaseForOracle
2. BulkCopy / FastBuilder are not yet implemented
3. It is recommended to continue using parameterized SQL
4. Native types are provided by the OceanBase driver
Minimal working example

folded

share

The underlying connection driver of SqlSugarCore.Oceanbase is OceanBase.ManagedDataAccess, which allows SqlSugar to access OceanBase Database in Oracle mode through the dotnet driver.

Installation

The installation method is the same as the basic driver. For more information, see Package reference and usage.

You also need to reference SqlSugarCore.OceanBase (which usually includes SqlSugarCore and other dependencies):

<ItemGroup>
  <PackageReference Include="SqlSugarCore.OceanBase" />
</ItemGroup>

Connection string

Use the Oracle mode format supported by OceanBase.ManagedDataAccess, and replace the placeholders with actual values from your environment. Do not directly copy the literal values from the example:

server=<host or IP>;port=<port>;user id=<OceanBase Oracle account>;password=<password>;database=<schema name>;

Note

  • user id specifies the OceanBase Oracle account.
  • database is recommended to be specified. The metadata capabilities of the current provider rely on it to identify the current schema.
  • The default port is usually 2881.

Access method

InstanceFactory.CustomDllName and similar are static global configurations. We recommend setting them only once during application startup to avoid loading errors caused by multiple overwrites.

Method ConnectionConfig.DbType Description
Method A (Recommended) DbType.Custom Explicitly set CustomDllName, CustomNamespace, and CustomDbName. This method does not depend on whether SqlSugarCore includes DbType.OceanBaseForOracle.
Method B DbType.OceanBaseForOracle Requires that SqlSugarCore includes this enumeration and sets CustomDllName to load the adapter assembly.

Method A (Recommended): DbType.Custom + InstanceFactory

using SqlSugar;
using SqlSugar.OceanBaseForOracle

InstanceFactory.CustomDllName = "SqlSugarCore.OceanBase";
InstanceFactory.CustomNamespace = "SqlSugarCore.OceanBase";
InstanceFactory.CustomDbName = "OceanBaseForOracle";
InstanceFactory.CustomAssemblies = new[] { typeof(OceanBaseForOracleProvider).Assembly };

var db = new SqlSugarClient(new ConnectionConfig
{
    ConnectionString = "server=127.0.0.1;port=2881;user id=...;password=...;database=...;",
    DbType = DbType.Custom,
    InitKeyType = InitKeyType.Attribute,
    IsAutoCloseConnection = true,
    MoreSettings = new ConnMoreSettings { IsAutoToUpper = false }
});

Method B: DbType.OceanBaseForOracle + CustomDllName

This method is closer to the built-in plugin enumeration of SqlSugar. It requires that the used SqlSugarCore includes DbType.OceanBaseForOracle (otherwise, the code cannot be compiled).

using SqlSugar;
using SqlSugar.OceanBaseForOracle;
InstanceFactory.CustomDllName = "SqlSugarCore.OceanBase";
InstanceFactory.CustomAssemblies = new[] { typeof(OceanBaseForOracleProvider).Assembly };

var db = new SqlSugarClient(new ConnectionConfig
{
    ConnectionString = "server=127.0.0.1;port=2881;user id=...;password=...;database=...;",
    DbType = DbType.OceanBaseForOracle,
    InitKeyType = InitKeyType.Attribute,
    IsAutoCloseConnection = true,
    MoreSettings = new ConnMoreSettings { IsAutoToUpper = false }
});

Some versions of SqlSugar automatically set InstanceFactory.CustomDllName when initializing DbType.OceanBaseForOracle. We still recommend explicitly setting it once during startup to reduce troubleshooting costs caused by version differences.

Startup encapsulation (SqlSugarOceanBaseBootstrap)

If you want to share the same startup code for both methods:

using SqlSugar;
using SqlSugar.OceanBaseForOracle;
public static class SqlSugarOceanBaseBootstrap
{
    private static bool s_registered;

    /// <param name="useCustomDbType">true = Method A (DbType.Custom); false = Method B (DbType.OceanBaseForOracle)</param>
    public static void Register(bool useCustomDbType = true)
    {
        if (s_registered)
            return;

        InstanceFactory.CustomDllName = "SqlSugarCore.OceanBase";
        InstanceFactory.CustomAssemblies = new[] { typeof(OceanBaseForOracleProvider).Assembly };

        if (useCustomDbType)
        {
            InstanceFactory.CustomNamespace = "SqlSugarCore.OceanBase";
            InstanceFactory.CustomDbName = "OceanBaseForOracle";
        }

        s_registered = true;
    }
}

Initialize SqlSugarScope

We recommend using SqlSugarScope in web or multi-threaded scenarios. First, call SqlSugarOceanBaseBootstrap.Register(...) (or manually set InstanceFactory), and then create ConnectionConfig.

Method A example:

using SqlSugar;

SqlSugarOceanBaseBootstrap.Register(useCustomDbType: true);

var connectionString = "server=127.0.0.1;port=2881;user id=demo_user@test_tenant#oboracle;password=123456;database=DEMO;";

var db = new SqlSugarScope(new ConnectionConfig
{
    ConfigId = "default",
    DbType = DbType.Custom,
    ConnectionString = connectionString,
    InitKeyType = InitKeyType.Attribute,
    IsAutoCloseConnection = true,
    MoreSettings = new ConnMoreSettings { IsAutoToUpper = false }
},
sqlSugarClient =>
{
    sqlSugarClient.Aop.OnLogExecuting = (sql, parameters) => { Console.WriteLine(sql); };
    sqlSugarClient.Aop.OnError = ex => { Console.WriteLine(ex.Message); };
});

Method B example: Set Register(useCustomDbType: false) and set DbType = DbType.OceanBaseForOracle. The rest is similar to Method A.

You can also directly use SqlSugarClient in console applications with the same configuration.

Complete example

The following example demonstrates table creation, data insertion, query, update, pagination, deletion, and transactions (default using Method A):

using SqlSugar;
using SqlSugar.OceanBaseForOracle;
SqlSugarOceanBaseBootstrap.Register(useCustomDbType: true);

var db = new SqlSugarScope(new ConnectionConfig
{
    ConfigId = "default",
    DbType = DbType.Custom,
    ConnectionString = "server=127.0.0.1;port=2881;user id=demo_user@test_tenant#oboracle;password=123456;database=DEMO;",
    InitKeyType = InitKeyType.Attribute,
    IsAutoCloseConnection = true,
    MoreSettings = new ConnMoreSettings { IsAutoToUpper = false }
});

if (!db.Ado.IsValidConnection())
    throw new Exception("OceanBase connection failed.");

db.CodeFirst.InitTables<DemoUser>();

var userId = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();

db.Insertable(new DemoUser
{
    Id = userId,
    Name = "Alice",
    Age = 28,
    CreatedAt = DateTime.Now
}).ExecuteCommand();

var user = db.Queryable<DemoUser>()
    .Where(x => x.Id == userId)
    .Single();

Console.WriteLine($"{user.Id} {user.Name} {user.Age}");

db.Updateable<DemoUser>()
    .SetColumns(x => new DemoUser { Name = "Alice-Updated", Age = 29 })
    .Where(x => x.Id == userId)
    .ExecuteCommand();

var page = db.Queryable<DemoUser>()
    .OrderBy(x => x.Id)
    .ToPageList(1, 10, out var totalCount);

Console.WriteLine($"TotalCount={totalCount}");

db.Ado.BeginTran();
try
{
    db.Deleteable<DemoUser>()
        .Where(x => x.Id == userId)
        .ExecuteCommand();

    db.Ado.CommitTran();
}
catch
{
    db.Ado.RollbackTran();
    throw;
}

[SugarTable("T_DEMO_USER")]
public class DemoUser
{
    [SugarColumn(ColumnName = "ID", IsPrimaryKey = true)]
    public long Id { get; set; }

    [SugarColumn(ColumnName = "NAME", Length = 100)]
    public string Name { get; set; } = string.Empty;

    [SugarColumn(ColumnName = "AGE", IsNullable = true)]
    public int? Age { get; set; }

    [SugarColumn(ColumnName = "CREATED_AT")]
    public DateTime CreatedAt { get; set; }
}

If you use Method B, set Register(useCustomDbType: false) and change DbType to DbType.OceanBaseForOracle.

ADO and parameterized queries

In SQL, @parameter name will be processed in Oracle style. We recommend using parameterized queries:

var user = db.Ado.SqlQuerySingle<DemoUser>(
    "select ID, NAME, AGE, CREATED_AT from T_DEMO_USER where ID=@id",
    new SugarParameter("@id", 1001));
var users = db.Ado.SqlQuery<DemoUser>(
    "select ID, NAME, AGE, CREATED_AT from T_DEMO_USER where AGE >= @minAge",
    new SugarParameter("@minAge", 18));

CodeFirst / DbFirst

CodeFirst

You can directly initialize tables based on entities:

db.CodeFirst.InitTables<DemoUser>();

Common combination methods (modify the table names as needed):

if (db.DbMaintenance.IsAnyTable("T_DEMO_USER", false))
{
    db.DbMaintenance.DropTable("T_DEMO_USER");
}

db.CodeFirst.InitTables<DemoUser>();

DbFirst/Metadata reading

var tables = db.DbMaintenance.GetTableInfoList();
var columns = db.DbMaintenance.GetColumnInfosByTableName("T_DEMO_USER");

If you want to perform simple library and table inspections or code generation, you can directly reuse this capability.

Recommended usage

In a business project, it is recommended to organize as follows:

  1. Call SqlSugarOceanBaseBootstrap.Register(...) (or equivalent InstanceFactory configuration) once when the application starts.
  2. Uniformly encapsulate SqlSugarScope as a singleton or managed by DI.
  3. Continue to use the original SqlSugar characteristics and writing methods for entities.
  4. The original Queryable, Insertable, Updateable, and Deleteable methods generally do not need to be modified.

This approach allows the business layer to only replace the driver and register the provider, while keeping the rest of the SqlSugar code unchanged.

Current limitations and considerations

1. DbType can be set to DbType.Custom or DbType.OceanBaseForOracle

  • Option A: DbType.Custom with CustomNamespace and CustomDbName (as described above).
  • Option B: DbType.OceanBaseForOracle, which requires the SqlSugarCore to provide this enum and setting CustomDllName to load the extension assembly.

If DbType.OceanBaseForOracle is not available (e.g., in older versions of SqlSugarCore), use Option A.

2. BulkCopy / FastBuilder are not yet implemented

The OceanBaseForOracleFastBuilder in the adapter layer will currently throw an exception, so do not rely on BulkCopy capabilities.

3. It is recommended to continue using parameterized SQL

Although the adapter layer supports automatic conversion from @name to :name, it is still recommended to use parameterized queries and avoid SQL string concatenation.

4. Native types are provided by the OceanBase driver

If you need to manually specify Oracle types, you can use types from the underlying driver, for example:

using OceanBase;

var p = new SugarParameter("@p_name", "Alice")
{
    CustomDbType = OracleDbType.NVarchar2
};

Minimal working example

Option A:

using SqlSugar;
using SqlSugar.OceanBaseForOracle;
SqlSugarOceanBaseBootstrap.Register(useCustomDbType: true);

var db = new SqlSugarClient(new ConnectionConfig
{
    DbType = DbType.Custom,
    ConnectionString = "<your connection string>",
    InitKeyType = InitKeyType.Attribute,
    IsAutoCloseConnection = true
});

Console.WriteLine(db.Ado.IsValidConnection());

Option B: Set Register(useCustomDbType: false) and DbType = DbType.OceanBaseForOracle.

An output of True indicates that SqlSugar + OceanBase.ManagedDataAccess + OceanBase Oracle mode is successfully integrated.

Previous topic

Use Entity Framework Core
Last

Next topic

Use FreeSql
Next
What is on this page
Installation
Connection string
Access method
Method A (Recommended): DbType.Custom + InstanceFactory
Method B: DbType.OceanBaseForOracle + CustomDllName
Startup encapsulation (SqlSugarOceanBaseBootstrap)
Initialize SqlSugarScope
Complete example
ADO and parameterized queries
CodeFirst / DbFirst
CodeFirst
DbFirst/Metadata reading
Recommended usage
Current limitations and considerations
1. DbType can be set to DbType.Custom or DbType.OceanBaseForOracle
2. BulkCopy / FastBuilder are not yet implemented
3. It is recommended to continue using parameterized SQL
4. Native types are provided by the OceanBase driver
Minimal working example