DotRocks.EntityFrameworkCore.Design 1.0.1

DotRocks

DotRocks for StarRocks — a native .NET driver, Entity Framework Core provider, and Roslyn analyzer suite built specifically for StarRocks.

DotRocks is an independent open-source project. It is not an official StarRocks project and does not imply StarRocks endorsement.

Packages

Status

DotRocks 1.0.0. The ADO.NET driver (DotRocks.Data), EF Core provider (DotRocks.EntityFrameworkCore), and analyzer suite (DotRocks.Analyzers) are released and validated against live StarRocks (4.0.7 and 3.3.5) in CI. The supported surface is exactly what this README documents: features are described as working only where they are built and covered by tests, and everything outside the documented surface is an explicit, deliberate boundary rather than an unfinished gap.

DotRocks implements its own managed StarRocks client protocol. It takes no runtime dependency on MySqlConnector, Oracle MySQL Connector/NET, Pomelo, or any other MySQL driver, and it is not a general-purpose MySQL driver.

Requirements

• .NET 10 SDK (pinned via global.json)
• C# 14

ADO.NET usage

Create connections directly when you need a short-lived provider object:

await using var connection = new DotRocksConnection(
    "Server=127.0.0.1;Port=9030;User ID=root"
);
await connection.OpenAsync();

await using var command = connection.CreateCommand();
command.CommandText = "SELECT 1";
object? value = await command.ExecuteScalarAsync();

DotRocksCommand.Prepare() / PrepareAsync() currently perform conservative client-side preparation for text commands: named placeholders and parameter metadata are validated up front, and execution still sends StarRocks text SQL with safely formatted current parameter values. The driver does not use the MySQL binary prepared-statement protocol yet.

Use DotRocksDataSource when one normalized configuration should create many logical connections and participate in DotRocks pooling:

await using var dataSource = new DotRocksDataSource(
    "Server=127.0.0.1;Port=9030;User ID=root;Pooling=true"
);

await using DbConnection connection = await dataSource.OpenConnectionAsync();

Provider-agnostic ADO.NET code can use DotRocksFactory:

DbProviderFactory factory = DotRocksFactory.Instance;

using DbConnectionStringBuilder builder = factory.CreateConnectionStringBuilder()!;
builder.ConnectionString = "Server=127.0.0.1;Port=9030;User ID=root";

await using DbDataSource dataSource = factory.CreateDataSource(builder.ConnectionString);
await using DbConnection connection = await dataSource.OpenConnectionAsync();

For SQL protocol TLS, set Ssl Mode=Required. Ssl Mode defaults to Disabled, which sends credentials without transport encryption — set Required for any non-local server. DotRocks uses platform certificate validation (chain and host name) by default and checks revocation in offline mode to avoid a blocking OCSP/CRL fetch during the handshake; Trust Server Certificate=true disables validation and is intended only for controlled local test environments with self-signed certificates.

DotRocks gates version-specific behavior on the StarRocks version, which it reads with SELECT current_version() (the MySQL-protocol handshake only reports a compatibility version such as 8.0.33). Set Server Compatibility Level to pin that version — for example Server Compatibility Level=4.0 — when detection is unavailable or you want to force a specific capability set. When unset, DotRocks detects the version per connection.

Entity Framework Core

DotRocks.EntityFrameworkCore provides the current EF Core provider surface for StarRocks: UseStarRocks, EF-managed relational connections, raw SQL commands, FromSqlRaw, and a deliberately small LINQ query subset verified against StarRocks.

using Microsoft.EntityFrameworkCore;

DbContextOptions<AppDbContext> options = new DbContextOptionsBuilder<AppDbContext>()
    .UseStarRocks("Server=127.0.0.1;Port=9030;User ID=root")
    .Options;

await using var context = new AppDbContext(options);

int count = await context.Widgets
    .Where(widget => widget.IsActive && widget.Name.StartsWith("prod"))
    .CountAsync();

Supported EF Core query surface:

• Database.ExecuteSqlRawAsync for raw SQL commands.
• DbSet<TEntity>.FromSqlRaw("SELECT ...") materialization.
• LINQ Where, comparison operators, boolean && / ||, nullable comparisons.
• Captured scalar LINQ parameters render as @... placeholders with values carried in DbParameters, including strings, decimals, nullable values, bools, and DotRocksDecimal.
• OrderBy, ThenBy, OrderByDescending, Skip, Take, Distinct.
• Contains over constant/parameter collections for IN (...).
• StartsWith, EndsWith, and Contains for strings using StarRocks LIKE (wildcards are backslash-escaped; StarRocks does not accept an ESCAPE clause and is not emitted one).
• FirstOrDefaultAsync, SingleAsync, ToListAsync, CountAsync, AnyAsync.
• Aggregate basics: Min, Max, Sum, Average.
• Projection into anonymous objects and simple DTOs.
• SaveChangesAsync for a constrained single-table write model: explicit primary key, scalar properties only, single-column keys, ValueGeneratedNever(), no navigations, no generated values, and no concurrency tokens. Supported DML is parameterized INSERT, UPDATE ... WHERE pk = @p, and DELETE ... WHERE pk = @p. Save one row per SaveChanges: StarRocks rejects a second DML against a table already written in the same transaction (error 5303), so a multi-row SaveChanges to one table fails — use one row per call, or Stream Load for bulk. SaveChanges inside a user transaction works; StarRocks has no SAVEPOINT, so EF savepoints are disabled. DotRocks does not model OLTP-style affected-row concurrency checks.
• Minimal migrations can create StarRocks databases from EnsureSchema as CREATE DATABASE IF NOT EXISTS, create and drop StarRocks tables, and create the EF migrations history table. CREATE TABLE defaults to DUPLICATE KEY, hash distribution by the key columns, one bucket, and replication_num = 1. Configure table shape with HasStarRocksDuplicateKey(...), HasStarRocksPrimaryKey(...), HasStarRocksUniqueKey(...), HasStarRocksHashDistribution(...), and HasStarRocksReplicationNum(...). The design-time package is DotRocks.EntityFrameworkCore.Design. Down migrations are limited to the same conservative DDL boundary; table rollback through DropTable is supported, while DROP DATABASE and schema mutations remain explicit failures.

Unsupported EF Core behavior is explicit:

• ExecuteUpdate, and ExecuteDelete.
• EnsureCreated and schema deletion.
• migration schema mutations beyond conservative database creation and table creation/drop, including DROP DATABASE, add/drop/alter/rename column, rename table, indexes, add/drop primary key, foreign keys, defaults, and computed columns.
• idempotent migration scripts.
• composite-key writes, and multi-row SaveChanges to a single table (StarRocks error 5303).
• SAVEPOINT (unsupported by StarRocks; EF savepoints are disabled).
• joins, Include, navigation materialization, and GroupBy.
• binary/varbinary EF mapping until byte-array query translation and materialization are broader than the verified ADO.NET reader path.

These constraints are enforced at model validation (when the model is first built), not only at SaveChanges. DotRocks requires the whole mapped model to be write-safe: any keyed entity with a navigation, complex property, composite key, concurrency token, generated/default/computed value, or binary property is rejected up front, even for a query-only DbContext. Configure mapped properties accordingly (for example ValueGeneratedNever() on keys) regardless of whether you intend to write.

A compilable EF Core sample lives at samples/DotRocks.Samples.EntityFrameworkCore. It demonstrates UseStarRocks, ValueGeneratedNever(), SaveChangesAsync insert/update/delete, and a minimal hand-authored migration.

StarRocks transaction behavior is characterized by live tests. COMMIT WORK makes EF SaveChangesAsync rows visible. Some StarRocks builds accept ROLLBACK WORK for DML but still expose inserted rows; DotRocks keeps rollback tests as characterization tests and does not claim OLTP rollback semantics beyond the behavior verified by the target StarRocks server.

EF Core type mapping:

Projecting high-precision StarRocks decimals to decimal can throw DotRocksPrecisionLossException; use DotRocksDecimal for lossless values. ADO.NET verifies VARBINARY / BLOB result values as byte[], including GetBytes(...); EF Core byte-array mapping remains unsupported until the EF query surface is verified end to end.

Analyzers

DotRocks.Analyzers ships Roslyn diagnostics for source-visible DotRocks security and provider-compatibility issues. DotRocks.Analyzers.CodeFixes ships optional IDE code fixes for diagnostics where the correction is mechanical. Reference these as development-time analyzer packages; they do not add runtime assemblies to application output.

Package consumption:

<PackageReference Include="DotRocks.Data" Version="1.0.0" />
<PackageReference Include="DotRocks.EntityFrameworkCore" Version="1.0.0" />
<PackageReference Include="DotRocks.EntityFrameworkCore.Design" Version="1.0.0" PrivateAssets="all" />
<PackageReference Include="DotRocks.Analyzers" Version="1.0.0" PrivateAssets="all" />
<PackageReference Include="DotRocks.Analyzers.CodeFixes" Version="1.0.0" PrivateAssets="all" />

The test suite validates these packages through a local NuGet-source consumer project and verifies analyzer diagnostics fire from package consumption, not only project references.

Current diagnostics:

Analyzer limits: diagnostics currently inspect source-visible constants, local string assignments, DotRocksConnectionStringBuilder initializers, and local method bodies. They do not perform interprocedural data-flow analysis, inspect runtime-built connection strings, prove transaction state across method boundaries, or prove whether a range change contains only one entity at runtime.

Stream Load

Use DotRocksStreamLoadClient for StarRocks HTTP Stream Load. The client uses the same connection string credentials and reads payloads from the supplied stream.

using DotRocks.Data.Loading;

using var client = new DotRocksStreamLoadClient(
    "Server=starrocks.example.com;Port=9030;User ID=loader;Password=secret;Stream Load Endpoint=https://starrocks.example.com:8030"
);

await using Stream csv = File.OpenRead("events.csv");
DotRocksStreamLoadResult result = await client.LoadCsvAsync(
    "warehouse",
    "events",
    csv,
    new DotRocksStreamLoadOptions
    {
        Label = "events_20260619",
        Columns = "id,name,created_at",
        ColumnSeparator = ",",
        RowDelimiter = "\\n",
    }
);

Transactional Stream Load uses the StarRocks begin/load/prepare/commit HTTP flow. The transaction object is single-use; after commit, rollback, or a failed remote call it rejects further operations.

using DotRocks.Data.Loading;

using var client = new DotRocksStreamLoadClient(
    "Server=starrocks.example.com;Port=9030;User ID=loader;Password=secret;Stream Load Endpoint=https://starrocks.example.com:8030"
);

DotRocksStreamLoadTransaction transaction = await client.BeginTransactionAsync(
    "warehouse",
    "events",
    new DotRocksStreamLoadTransactionOptions { Label = "events_tx_20260619" }
);

await using Stream csv = File.OpenRead("events.csv");
await transaction.LoadCsvAsync(
    csv,
    new DotRocksStreamLoadOptions
    {
        Columns = "id,name,created_at",
        ColumnSeparator = ",",
        RowDelimiter = "\\n",
    }
);

await transaction.PrepareAsync();
await transaction.CommitAsync();

// To abandon an active or prepared transaction before commit:
// await transaction.RollbackAsync();

HTTP Stream Load endpoints send Basic authentication without transport encryption and are rejected by default. For trusted local test environments such as the pinned Docker container, set Allow Insecure Stream Load=true explicitly.

The payload is streamed to StarRocks without buffering the whole input. One limitation: StarRocks redirects the load from the FE to a BE/CN, and replaying the request after a redirect requires rewinding the body. DotRocks rewinds seekable streams automatically, but a non-seekable payload (a pipe, network, or compression stream) cannot be replayed and fails explicitly after a redirect rather than being silently buffered. For non-seekable sources, use a seekable stream (for example buffer to a MemoryStream or file) or send directly to a BE/CN endpoint that does not redirect.

Observability

DotRocks emits OpenTelemetry-compatible tracing and metrics. Subscribe by name via DotRocksTelemetry.ActivitySourceName and DotRocksTelemetry.MeterName (both "DotRocks.Data"):

• Activities: dotrocks.connection.open, dotrocks.command.execute.
• Metrics: dotrocks.connections.opened, dotrocks.commands.executed, and the dotrocks.command.duration histogram (ms).

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource(DotRocksTelemetry.ActivitySourceName))
    .WithMetrics(m => m.AddMeter(DotRocksTelemetry.MeterName));

Pooled connections are liveness-checked on lease, so a connection the server closed while idle is discarded rather than handed out.

Connection pooling is process-global, keyed by the normalized connection configuration, and is not owned by any single DotRocksConnection or DotRocksDataSource. Disposing a DotRocksDataSource stops it from opening new connections but does not evict that configuration's idle physical connections from the shared pools. To release all idle pooled connections process-wide, call DotRocksConnection.ClearAllPools().

Build and test

Common tasks are exposed via just (see justfile):

just            # list recipes
just ci         # restore, format check, build, test
just build
just test
just pack

The equivalent raw commands:

dotnet tool restore
dotnet restore --locked-mode
dotnet csharpier check .
dotnet build --configuration Release --no-restore
dotnet test --configuration Release --no-build
dotnet pack --configuration Release --no-build

Run the BenchmarkDotNet suite with performance budgets when changing protocol hot paths:

dotnet run --project benchmarks/DotRocks.Benchmarks --configuration Release -- --filter '*'

Benchmark results fail the process if a measured benchmark exceeds its configured mean time or allocation budget, or if a new benchmark is added without a budget entry.

Integration tests run against a real StarRocks server and are documented separately; the commands above cover the server-free unit and protocol tests. CI keeps unit/build checks, package validation, StarRocks live integration, and release publishing in separate workflows so package artifacts and live-server gates are visible independently.

Verified robustness

DotRocks has focused regression coverage for malformed protocol packets, including length-encoded integer/string edge cases, truncated result metadata, invalid OK/ERR packets, oversized result counts, oversized row value claims, and trailing text-row bytes. Secret-hygiene tests cover connection-string redaction, connection/open failures, Stream Load HTTP failures, Stream Load result failures, and debug-display surfaces. Cancellation tests verify open cancellation, command timeout, user cancellation, DbCommand.Cancel(), active-reader cancellation, and broken pooled connection discard. SQL protocol TLS is covered by fake-server tests for SSL-request negotiation, certificate validation failure handling, and successful TLS upgrade with an explicit local trust override.

StarRocks compatibility harness (Docker)

just starrocks-up      # start a pinned StarRocks container, wait until query-ready
just harness           # probe the handshake and write a sanitized report
just starrocks-down    # stop and clean up

The harness reads the initial handshake through the DotRocks framing and handshake layers and writes a sanitized JSON report (authentication challenge bytes are never recorded).

License

Licensed under the MIT License.