Skip to content

CBEF-127: Throw on synchronous I/O by default; opt in with ConfigureWarnings - #188

Draft
davidkelly wants to merge 1 commit into
spec-root-causesfrom
sync-option-b
Draft

davidkelly wants to merge 1 commit into
spec-root-causesfrom
sync-option-b

Conversation

@davidkelly

@davidkelly davidkelly commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Synchronous EF calls (SaveChanges(), .ToList(), EnsureCreated(), ...) threw
NotSupportedException in Release builds and blocked in Debug builds, so an app behaved
differently in each and had no way to opt in. This makes them throw by default in every
build, with an opt-in, as Cosmos does.

Change

  • Synchronous calls raise the new CouchbaseEventId.SyncNotSupported warning, which
    UseCouchbase configures as an error. An app allows them with
    ConfigureWarnings(w => w.Ignore(CouchbaseEventId.SyncNotSupported)), or logs each one with
    w.Log(...). The #if DEBUG splits are gone.
  • Synchronous enumeration of LINQ and FromSql queries now works when enabled (it blocks on
    the async enumerator) instead of throwing NotImplementedException.
  • Docs (limitations, getting started, CRUD, queries) and CHANGELOG describe the opt-in.
  • Spec harness: the test store opts in, so EF's synchronous test variants reach their
    assertions. Deletes the sync-io row from root-causes.tsv.

Tests

  • Unit 1,213/1,213; integration 400/400, including the new SyncIoTests (throws by default,
    opt-in for query, SaveChanges and transaction, Log).
  • Spec tests, 8 classes with the most synchronous failures, local 3-node 8.0.1 cluster: no new
    failures; 1,221 baseline failures now pass. known-failures.txt is regenerated once, in CBEF-128: Generate integer keys from a Couchbase sequence by default #189,
    from a full CI run of the whole stack (CI fails only on new failures, so this PR is safe to merge
    with the current list).

Stacked on #190, so the diff here shows only this change.

Jira: CBEF-127

@emilienbev emilienbev left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice change. One behaviour in every build, with the same opt-in as Cosmos, is much easier to explain to users. One blocking issue on sync EnsureCreated(), the rest are small.

Nit. ExceptionHelper.SyncroIONotSupportedException has no callers after this change. Could we delete it?

@@ -874,11 +878,8 @@ public override void Delete()
/// </returns>
public override bool Exists()

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the opt-in, sync EnsureCreated() runs EF's relational version, not ours. It calls Exists() and then HasTables(), which returns true here. So on an existing bucket it returns without creating collections, sequences or indexes. Could we override EnsureCreated() to check once and block on EnsureCreatedAsync, and add a case to SyncIoTests?

/// <c>UseCouchbase</c>); when the application ignores or logs it, the caller then runs the
/// asynchronous operation and blocks on it.
/// </summary>
public static void SyncNotSupported<TLoggerCategory>(this IDiagnosticsLogger<TLoggerCategory> diagnostics)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Small thing. The check and the blocking call are paired by hand in about 15 places, so a few blocking paths still have no check. Two examples are CouchbaseConnection.Open(), which CreateDbCommand also calls, and CouchbaseDbDataReader.Read(). Could we add one helper that checks and then calls AsyncHelper.RunSync? If CouchbaseConnection.Open() used it, the Open override in CouchbaseRelationalConnection could go too.

{
var connLogger = _loggerFactory?.CreateLogger<CouchbaseConnection>();
return new CouchbaseConnection(_bucketProvider, _couchbaseDbContextOptionsBuilder, connLogger);
// Synchronous ADO.NET calls on this connection (BeginTransaction, Commit, Rollback,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit. BeginTransaction and Rollback don't go through this check, because neither does I/O. So the BeginTransactionAsync and RollbackAsync edits in ConnectionTests and TransactionTests aren't needed either. Could we fix the comment and keep those tests as they were?


Assert.True(result is 0 or -1, $"Expected ExecuteNonQuery to return 0 or -1 for a SELECT query, but got {result}.");
outputHelper.WriteLine($"ExecuteNonQuery result: {result}");
// Sync option B: synchronous I/O is rejected unless the context opts in

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit. "Sync option B" points to a design discussion that readers of the code won't have. Could we drop it here and in FromRawSqlTests, SyncIoTests and CouchbaseTestStore?

…arnings

The Couchbase SDK is asynchronous, so a synchronous EF call has to block
a thread on it. Synchronous calls threw NotSupportedException in Release
builds and blocked in Debug builds (#if DEBUG), so an application
behaved differently in each, and there was no way to opt in.

Synchronous calls now raise CouchbaseEventId.SyncNotSupported, a warning
that UseCouchbase configures as an error, in every build (as Cosmos
does). An application can allow blocking calls with
ConfigureWarnings(w => w.Ignore(CouchbaseEventId.SyncNotSupported)), or
log each one with w.Log(...).

Covered: SaveChanges, synchronous query enumeration (LINQ and FromSql,
now done by blocking on the async enumerator instead of throwing),
EnsureCreated/EnsureDeleted/Exists, RelationalConnection.Open, sequence
values on a synchronous Add, and Commit/Rollback/Execute* on connections
a context creates. BeginTransaction on main starts a buffered transaction
with no I/O, so it is not checked itself; it opens the connection, which
is.

SyncIoTests covers throw-by-default, opt-in (query, SaveChanges,
transaction) and Log. Tests that used synchronous ADO calls use the
async ones. Docs and CHANGELOG describe the opt-in.

Spec harness: the test store ignores SyncNotSupported, so the
synchronous variants of EF's tests reach their assertions instead of
all failing on the rejected call. ConnectionInterceptionCouchbaseTest
builds its own options for the bad-connection tests, so it ignores
the warning there too.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants