Use Entity Framework Core|V1.1.0|OceanBase Connector/NET|docs|OceanBase Documentations

OceanBase.EntityFrameworkCore8 is an EF Core provider for OceanBase Oracle mode, based on OceanBase Connector/NET. It allows you to use OceanBase.OracleConnection, OracleCommand, and other capabilities in EF Core to access OceanBase.

Note

Currently, this provider only supports EF Core 8.0.

Install

If you install it by using NuGet:

dotnet add package OceanBase.EntityFrameworkCore8

Connection string

Use the Oracle mode format supported by OceanBase.ManagedDataAccess. Replace the placeholders with the actual values in your environment. Do not directly copy the literals in the sample:

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

Note

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

Get started

Define entities and a DbContext:

using Microsoft.EntityFrameworkCore;
using OceanBase.EntityFrameworkCore;

public sealed class User
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Balance { get; set; }
    public DateTime CreatedTime { get; set; }
}

public sealed class AppDbContext : DbContext
{
    private readonly string _connectionString;

    public AppDbContext(string connectionString)
    {
        _connectionString = connectionString;
    }

    public DbSet<User> Users => Set<User>();

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.UseOceanBaseForOracle(_connectionString);
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<User>(entity =>
        {
            entity.ToTable("USERS");
            entity.HasKey(x => x.Id);

            entity.Property(x => x.Id)
                .HasColumnName("ID");

            entity.Property(x => x.Name)
                .HasColumnName("NAME")
                .HasMaxLength(100)
                .IsRequired();

            entity.Property(x => x.Balance)
                .HasColumnName("BALANCE")
                .HasColumnType("NUMBER(10,2)");

            entity.Property(x => x.CreatedTime)
                .HasColumnName("CREATED_TIME")
                .HasDefaultValueSql("SYSDATE");
        });
    }
}

Use dependency injection:

using Microsoft.EntityFrameworkCore;
using OceanBase.EntityFrameworkCore;

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseOceanBaseForOracle(connectionString));

Example

Query, insert, update, and delete data:

await using var db = new AppDbContext(connectionString);

var adults = await db.Users
    .Where(x => x.Balance > 100)
    .OrderBy(x => x.Name)
    .ToListAsync();

var user = new User
{
    Name = "Alice",
    Balance = 7500.50m,
    CreatedTime = DateTime.Now
};

db.Users.Add(user);
await db.SaveChangesAsync();

user.Name = "Alice Zhang";
await db.SaveChangesAsync();

db.Users.Remove(user);
await db.SaveChangesAsync();

Perform transactions:

await using var db = new AppDbContext(connectionString);
await using var tx = await db.Database.BeginTransactionAsync();

try
{
    db.Users.Add(new User { Name = "U1", Balance = 100m, CreatedTime = DateTime.Now });
    db.Users.Add(new User { Name = "U2", Balance = 200m, CreatedTime = DateTime.Now });

    await db.SaveChangesAsync();
    await tx.CommitAsync();
}
catch
{
    await tx.RollbackAsync();
    throw;
}

Execute DML statements

Execute DML statements:

var rows = await db.Database.ExecuteSqlRawAsync(
    "UPDATE USERS SET BALANCE = BALANCE + 100 WHERE ID = {0}",
    1);

Query a scalar value (the ExecuteSqlRaw method returns the number of affected rows, which is not suitable for directly reading the result of a SELECT statement):

var count = db.Database
    .SqlQuery<int>($"SELECT COUNT(*) FROM USERS WHERE NAME = {"Alice"}")
    .Single();

Notice

ExecuteSqlRaw is suitable for INSERT, UPDATE, and DELETE statements. To query a scalar value, use SqlQuery<T>() or the equivalent API for your version.

Migrations and database creation

Code First migrations:

dotnet ef migrations add InitialCreate
dotnet ef database update

EnsureCreated:

await db.Database.EnsureCreatedAsync();

Value generation

The provider supports value generation for HiLo, identity, and GUID.

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.UseOceanBaseHiLo("APP_HILO_SEQ");

    modelBuilder.Entity<User>(entity =>
    {
        entity.Property(x => x.Id)
            .UseOceanBaseIdentityColumn();
    });
}

Code First / Data type mapping

When you generate or synchronize a table schema based on an entity, the default type mapping is as follows (actual values may vary):

CLR type	Default database type
`int`	`NUMBER(10)`
`long`	`NUMBER(19)`
`short`	`NUMBER(6)`
`byte`	`NUMBER(3)`
`decimal`	`DECIMAL(29,4)` / `NUMBER(p,s)`
`double`	`FLOAT(49)` / `BINARY_DOUBLE`
`float`	`BINARY_FLOAT`
`string`	Default `VARCHAR2`; `NVARCHAR2` when Unicode is explicitly specified
`DateTime`	`DATE` / `TIMESTAMP`
`DateTimeOffset`	`TIMESTAMP WITH TIME ZONE`
`byte[]`	`BLOB` / `RAW`
`TimeSpan`	`INTERVAL DAY TO SECOND`

For fields such as amounts and decimals, we recommend that you explicitly configure HasColumnType("NUMBER(10,2)") or HasPrecision(10, 2) and ensure that the settings match the database table definition. If you have specific requirements for length, precision, or column type, explicitly configure them in the Fluent API or data annotations. Do not rely solely on the default mapping.

Considerations

1. Default string mapping

By default, strings are mapped to VARCHAR2.
Strings are mapped to NVARCHAR2 only when you explicitly configure IsUnicode(true).

2. `decimal` precision and scale

We recommend that you explicitly configure:

entity.Property(x => x.Balance)
    .HasColumnType("NUMBER(10,2)");

or:

entity.Property(x => x.Balance)
    .HasPrecision(10, 2);

3. `NOT NULL` string columns

The provider handles the issue of null values for string columns in newly added entities through the SaveChanges interceptor:

If a default value is specified, the model's default value is written first.
If no default value is specified, an empty string "" is written.

4. `ExecuteSqlRaw` and `SELECT`

The ExecuteSqlRaw method is suitable for executing INSERT, UPDATE, DELETE, and DDL statements. It is not suitable for using SELECT COUNT(*) to return a scalar value.

Correct example:

var count = db.Database
    .SqlQuery<int>($"SELECT COUNT(*) FROM USERS")
    .Single();

Summary

For EF Core 8.0 + OceanBase Oracle mode, the current provider supports the following main paths:

DbContext access
CRUD operations
Transactions
Parameterized queries
Raw SQL
Common LINQ translation
Migrations / EnsureCreated
Value generation
Scaffolding
Execution strategies

If your business requires JSON queries, more advanced LINQ translations, or EF Core 9 compatibility, verify them separately before integration.

Note

Install

Connection string

Note

Get started

Example

Execute DML statements

Notice

Migrations and database creation

Value generation

Code First / Data type mapping

Considerations

1. Default string mapping

2. decimal precision and scale

3. NOT NULL string columns

4. ExecuteSqlRaw and SELECT

Summary

2. `decimal` precision and scale

3. `NOT NULL` string columns

4. `ExecuteSqlRaw` and `SELECT`