Use FreeSql

Install FreeSql, OceanBase.ManagedDataAccess, and FreeSql.Provider.OceanBase in OceanBase Oracle mode. You can obtain IFreeSql by using OceanBaseProvider<TMark>. For more information about the connection string, see Connection string. For more information about the package and version, see Package reference and usage.

Installation

The installation method is the same as for the basic driver:

dotnet add package FreeSql
dotnet add package OceanBase.ManagedDataAccess
dotnet add package FreeSql.Provider.OceanBase

Connection string

Use the Oracle mode format supported by the driver. Replace the placeholders with the actual values from your environment, and do not directly copy the literals from the example:

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

If the session requires the GBK character set, you can append Character Set=gbk (aliases CharSet / CharacterSet):

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

Quick start

Replace the connection string with your local configuration (such as a configuration file or environment variable), then create a client and perform a connectivity check:

using FreeSql;
using FreeSql.Provider.OceanBase;

var connectionString = "<your connection string>";

using var fsql = new OceanBaseProvider<object>(
    connectionString,
    null);

fsql.Aop.CurdBefore += (_, e) => Console.WriteLine(e.Sql);

var ok = fsql.Ado.ExecuteConnectTest();
Console.WriteLine($"ConnectTest={ok}");

In a single-database scenario, it is recommended to use IFreeSql as a singleton.

Full example

Creating tables, performing CRUD operations, pagination, and other tasks are similar to standard FreeSql usage. Replace <your connection string> with your actual connection string.

using System;
using FreeSql;
using FreeSql.DataAnnotations;
using FreeSql.Provider.OceanBase;

var connectionString =
    "<your connection string>";

using var fsql = new OceanBaseProvider<object>(connectionString, null);

fsql.Aop.CurdBefore += (_, e) => Console.WriteLine(e.Sql);
fsql.Aop.CurdAfter += (_, e) => Console.WriteLine($"Rows={e.AffectedRows}");

fsql.CodeFirst.SyncStructure<DemoUser>();

var userId = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();

fsql.Insert(new DemoUser
{
    Id = userId,
    Name = "Alice",
    Age = 28,
    CreatedAt = DateTime.Now,
    LastLoginAt = DateTimeOffset.Now
}).ExecuteAffrows();

var user = fsql.Select<DemoUser>()
    .Where(x => x.Id == userId)
    .First();

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

fsql.Update<DemoUser>()
    .Set(x => x.Name, "Alice-Updated")
    .Set(x => x.Age, 29)
    .Where(x => x.Id == userId)
    .ExecuteAffrows();

var page = fsql.Select<DemoUser>()
    .OrderBy(x => x.Id)
    .Page(1, 10)
    .ToList();

Console.WriteLine($"PageCount={page.Count}");

fsql.Delete<DemoUser>()
    .Where(x => x.Id == userId)
    .ExecuteAffrows();

[Table(Name = "T_DEMO_USER")]
public class DemoUser
{
    [Column(Name = "ID", IsPrimary = true)]
    public long Id { get; set; }

    [Column(Name = "NAME", StringLength = 100)]
    public string Name { get; set; } = string.Empty;

    [Column(Name = "AGE")]
    public int? Age { get; set; }

    [Column(Name = "CREATED_AT")]
    public DateTime CreatedAt { get; set; }

    [Column(Name = "LAST_LOGIN_AT")]
    public DateTimeOffset? LastLoginAt { get; set; }
}

Read/write separation example

The OceanBaseProvider<TMark> constructor supports primary and read-only connection strings:

using var fsql = new OceanBaseProvider<object>(
    masterConnectionString,
    new[] { slaveConnectionString1, slaveConnectionString2 });

This is suitable for businesses that already have read/write separation scenarios.

Native SQL example

It is recommended to use parameterized queries. If you need to execute native SQL, you can use the Ado API:

var count = fsql.Ado.ExecuteScalar<int>(
    "select count(1) from T_DEMO_USER where AGE >= :minAge",
    new OceanBase.OracleParameter(":minAge", 18));

CodeFirst / DbFirst

The current adapter layer supports basic CodeFirst and DbFirst capabilities.

CodeFirst

Example of synchronizing table structure based on entities:

fsql.CodeFirst.SyncStructure<DemoUser>();

Default type mapping examples (actual versions may vary):

If your business has specific requirements for length, precision, or column types, it is recommended to explicitly configure column attributes on the entity rather than relying solely on default mappings.

DbFirst

var exists = fsql.DbFirst.ExistsTable("<table name>");
var table = fsql.DbFirst.GetTableByName("<table name>");
var tables = fsql.DbFirst.GetTablesByDatabase("<database or schema name consistent with the connection string>");

This is suitable for simple metadata reading, inspections, or code generation.

Recommended Integration Approach

We recommend organizing your business project as follows:

1. Create an IFreeSql instance once when the application starts.
2. Reuse it as a singleton through dependency injection (DI).
3. Continue using the original FreeSql features and CRUD writing methods.
4. Explicitly specify key metadata such as table names, column names, length, and precision.

This approach typically requires only replacing the driver and provider initialization code, with minimal changes to the business layer's CRUD operations.

Considerations

• Do not omit the database parameter in the connection string. The current provider's metadata capabilities rely on database to identify the current schema.
• When using GBK, set Character Set=gbk in the connection string and ensure the provider version is V1.1.0 or later. For details, see the "Connection string" section above.
• If some APIs that return entities after updates/deletes are unavailable, consider using affected rows APIs or querying before modifying/deleting.
• For complex scenarios involving cross-schema operations or schema-qualified table names, plan accordingly based on your business needs rather than relying solely on automatic table creation.
• Keep native SQL parameterized.

Minimum Connectivity Verification

using FreeSql.Provider.OceanBase;

var fsql = new OceanBaseProvider<object>("<your connection string>", null);
Console.WriteLine(fsql.Ado.ExecuteConnectTest());

A return value of True indicates successful connectivity.