The Couchbase EF Core Provider is now generally available. This release brings the power of Entity Framework Core to Couchbase, allowing .NET developers to work with Couchbase using familiar EF Core patterns.
What is the Couchbase EF Core provider?
Entity Framework Core (EF Core) is a popular O/RM that simplifies database access for .NET applications. It allows developers to work with data using C# objects and LINQ queries instead of writing raw database queries. EF Core enables integration with various databases, providing automatic change tracking, transactions, and a familiar DbContext API. It’s a familiar interface that developers can use to save time and integrate with many frameworks and database-adjacent libraries.
The Couchbase EF Core Provider enables developers to use Entity Framework Core with Couchbase Server and Couchbase Capella (now available with a perpetual free tier). With this provider, you can work with Couchbase documents as if they were relational entities, using Linq queries, DbContext, and change tracking.
Getting started
To install the Couchbase EF Core Provider, add the NuGet package:
|
1 2 3 4 5 |
# .NET CLI dotnet add package Couchbase.EntityFrameworkCore # Or using Package Manager Install-Package Couchbase.EntityFrameworkCore |
Example: using EF Core with Couchbase
Here’s a simple “shopping cart” example of how to set up and use the Couchbase EF Core Provider with a shopping cart model.
Define Your Entity Models
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
using Couchbase; using Couchbase.EntityFrameworkCore; using Couchbase.EntityFrameworkCore.Extensions; using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Logging; using NLog.Extensions.Logging; using ILoggerFactory = Microsoft.Extensions.Logging.ILoggerFactory; public class Cart { public string CartId { get; set; } public DateTimeOffset Created { get; set; } public List<Item> Items { get; set; } } public class Item { public string ItemId { get; set; } public string Name { get; set; } public uint Quantity { get; set; } public decimal Price { get; set; } } |
Create a DbContext for Couchbase
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
public class CartContext : DbContext { public DbSet<Cart> Carts { get; set; } public DbSet<Item> Items { get; set; } private static readonly ILoggerFactory LoggerFactory = Microsoft.Extensions.Logging.LoggerFactory.Create(builder => { builder.ClearProviders(); builder.AddNLog(); }); protected override void OnConfiguring(DbContextOptionsBuilder options) { options.UseCouchbase(new ClusterOptions() .WithCredentials("Administrator", "password") .WithConnectionString("couchbase://localhost") .WithLogging(LoggerFactory), couchbaseDbContextOptions => { couchbaseDbContextOptions.Bucket = "Shopping"; couchbaseDbContextOptions.Scope = "Ecommerce"; }); } protected override void OnModelCreating(ModelBuilder modelBuilder) { modelBuilder.Entity<Cart>().ToCouchbaseCollection(this, "Carts"); modelBuilder.Entity<Item>().ToCouchbaseCollection(this, "Items"); } } |
This arrangement assumes that you have created a bucket in Couchbase called Shopping, which contains a scope called Ecommerce, which contains collections Items and Carts.
Also, note that logging is optional, but it’s a good idea to turn it on to help identify any issues that may come up.
Insert and Query Data
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
await using var db = new CartContext(); var cart = new Cart { CartId = Guid.NewGuid().ToString(), Created = DateTimeOffset.Now, Items = new List<Item> { new Item { ItemId = Guid.NewGuid().ToString(), Name = "Widget", Price = 0.99M, Quantity = 1}, new Item { ItemId = Guid.NewGuid().ToString(), Name = "Foo", Price = 4.99M, Quantity = 3}, new Item { ItemId = Guid.NewGuid().ToString(), Name = "Baz", Price = 99.19M, Quantity = 1} } }; await db.AddAsync(cart); await db.SaveChangesAsync(); var items = await db.Items.Where(i => i.Name == "Foo").ToListAsync(); foreach (var i in items) { Console.WriteLine(JsonConvert.SerializeObject(i)); } |
Here’s an example of what the documents in Couchbase will look like after insertion:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
Key: 080c210a-34eb-45ea-b9b4-e5c6f8afa4d6 { "CartId": "080c210a-34eb-45ea-b9b4-e5c6f8afa4d6", "Created": "2025-03-13T17:16:31.9904224-04:00" } Key acf54397-51c4-4ad7-bf34-d0a42061b662 { "ItemId": "acf54397-51c4-4ad7-bf34-d0a42061b662", "CartId": "080c210a-34eb-45ea-b9b4-e5c6f8afa4d6", "Name": "Foo", "Price": 4.99, "Quantity": 3 } Key a3f25210-97f2-4c95-ad4b-f241dde0d9c3 { "ItemId": "a3f25210-97f2-4c95-ad4b-f241dde0d9c3", "CartId": "080c210a-34eb-45ea-b9b4-e5c6f8afa4d6", "Name": "Widget", "Price": 0.99, "Quantity": 1 } // ... etc ... |
What works in the GA release?
The entire functionality of EF Core is very, very large. Being able to handle every possible Linq statement, for instance, is nearly impossible, even for mature EF Core providers like SQL Server. However, this release supports many core EF Core capabilities, including:
✅ LINQ support – Translates LINQ queries to Couchbase SQL++.
✅ Basic CRUD operations – Insert, update, and delete work as expected.
✅ Change tracking – Entities are tracked for efficient updates.
Also note that using Async methods is required. Couchbase’s .NET SDK is completely asynchronous. If you try to use a non-async method, you will get a runtime error along the lines of Couchbase EF Core Database Provider does not support synchronous I/O.
Known limitations
While this is a significant milestone, some features are still a work in progress, including:
❌ Denormalization – Nesting collections inside documents (e.g., storing Items inside Cart as a single JSON document) is not yet supported.
❌ Eager Loading – .Include() statements may not work as expected.
❌ SQL++ Function Support – Some SQL++ functions like META, RYOW, etc., are not fully implemented.
❌ Transactions – Not yet supported in this release.
Join the conversation!
We want your feedback! Help shape the future of the Couchbase EF Core Provider:
-
- Ask questions and share experiences in the Couchbase .NET forums.
- Chat with us on Discord – Join our community.
- Report issues and contribute on GitHub.
What’s next?
This release is just the beginning! We’re actively working on building out this EF Core implementation. Your feedback will help to prioritize functionality.
Try it out today and let us know what you think. Happy coding!
