{"id":4669,"date":"2025-04-24T11:51:03","date_gmt":"2025-04-24T18:51:03","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/ef-core-provider-for-couchbase-general-availability\/"},"modified":"2025-04-24T11:51:03","modified_gmt":"2025-04-24T18:51:03","slug":"ef-core-provider-for-couchbase-general-availability","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/pt\/ef-core-provider-for-couchbase-general-availability\/","title":{"rendered":"Announcing the General Availability of the Couchbase EF Core Provider"},"content":{"rendered":"\n

The <\/span>Couchbase EF Core Provider<\/b> is now <\/span>generally available<\/b><\/a>. This release brings the power of Entity Framework Core to Couchbase, allowing .NET developers to work with Couchbase using familiar EF Core patterns.<\/span><\/p>\n\n\n\n

What is the Couchbase EF Core provider?<\/h2>\n\n\n\n

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.<\/span><\/p>\n\n\n\n

The <\/span>Couchbase EF Core Provider<\/b> enables developers to use Entity Framework Core with <\/span>Couchbase Server<\/b> and <\/span>Couchbase Capell<\/b>a<\/b><\/a> (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.<\/span><\/p>\n\n\n\n

Getting started<\/h2>\n\n\n\n

To install the Couchbase EF Core Provider, add the <\/span>NuGet package<\/span><\/a>:<\/span><\/p>\n\n\n

[crayon nums=”false” lang=”ps” decode=”true”]# .NET CLI
\ndotnet add package Couchbase.EntityFrameworkCore<\/p>\n

# Or using Package Manager
\nInstall-Package Couchbase.EntityFrameworkCore[\/crayon]<\/p>\n\n\n\n

Example: using EF Core with Couchbase<\/h3>\n\n\n\n

Here\u2019s a simple “shopping cart” example of how to set up and use the <\/span>Couchbase EF Core Provider<\/b> with a shopping cart model.<\/span><\/p>\n\n\n\n

Define Your Entity Models<\/h4>\n\n\n

[crayon nums=”false” wrap=”true” lang=”c#” decode=”true”]using Couchbase;
\nusing Couchbase.EntityFrameworkCore;
\nusing Couchbase.EntityFrameworkCore.Extensions;
\nusing Microsoft.EntityFrameworkCore;
\nusing Microsoft.Extensions.Logging;
\nusing NLog.Extensions.Logging;
\nusing ILoggerFactory = Microsoft.Extensions.Logging.ILoggerFactory;<\/p>\n

public class Cart
\n{
\n\u00a0\u00a0\u00a0\u00a0public string CartId { get; set; }
\n\u00a0\u00a0\u00a0\u00a0public DateTimeOffset Created { get; set; }
\n\u00a0\u00a0\u00a0\u00a0public List<Item> Items { get; set; }
\n}<\/p>\n

public class Item
\n{
\n\u00a0\u00a0\u00a0\u00a0public string ItemId { get; set; }
\n\u00a0\u00a0\u00a0\u00a0public string Name { get; set; }
\n\u00a0\u00a0\u00a0\u00a0public uint Quantity { get; set; }
\n\u00a0\u00a0\u00a0\u00a0public decimal Price { get; set; }
\n}[\/crayon]<\/p>\n\n\n\n

Create a DbContext for Couchbase<\/h4>\n\n\n

[crayon nums=”false” wrap=”true” lang=”c#” decode=”true”]public class CartContext : DbContext
\n{
\n\u00a0\u00a0\u00a0\u00a0public DbSet<Cart> Carts { get; set; }
\n\u00a0\u00a0\u00a0\u00a0public DbSet<Item> Items { get; set; }
\n\u00a0\u00a0\u00a0\u00a0private static readonly ILoggerFactory LoggerFactory = Microsoft.Extensions.Logging.LoggerFactory.Create(builder =>
\n\u00a0\u00a0\u00a0\u00a0{
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0builder.ClearProviders();
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0builder.AddNLog();
\n\u00a0\u00a0\u00a0\u00a0});
\n\u00a0\u00a0\u00a0\u00a0protected override void OnConfiguring(DbContextOptionsBuilder options)
\n\u00a0\u00a0\u00a0\u00a0{
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0options.UseCouchbase(new ClusterOptions()
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0.WithCredentials(“Administrator”, “password”)
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0.WithConnectionString(“couchbase:\/\/localhost”)
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0.WithLogging(LoggerFactory),
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0couchbaseDbContextOptions =>
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0couchbaseDbContextOptions.Bucket = “Shopping”;
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0couchbaseDbContextOptions.Scope = “Ecommerce”;
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0});
\n\u00a0\u00a0\u00a0\u00a0}<\/p>\n

\u00a0\u00a0\u00a0\u00a0protected override void OnModelCreating(ModelBuilder modelBuilder)
\n\u00a0\u00a0\u00a0\u00a0{
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0modelBuilder.Entity<Cart>().ToCouchbaseCollection(this, “Carts”);
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0modelBuilder.Entity<Item>().ToCouchbaseCollection(this, “Items”);
\n\u00a0\u00a0\u00a0\u00a0}
\n}[\/crayon]<\/p>\n\n\n\n

This arrangement assumes that you have created a bucket in Couchbase called Shopping<\/em>, which contains a scope called Ecommerce<\/em>, which contains collections Items<\/em> and Carts<\/em>.<\/span><\/p>\n\n\n\n

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.<\/span><\/p>\n\n\n\n

Insert and Query Data<\/h4>\n\n\n

[crayon nums=”false” wrap=”true” lang=”c#” decode=”true”]await using var db = new CartContext();
\nvar cart = new Cart
\n{
\n\u00a0\u00a0\u00a0\u00a0CartId = Guid.NewGuid().ToString(),
\n\u00a0\u00a0\u00a0\u00a0Created = DateTimeOffset.Now,
\n\u00a0\u00a0\u00a0\u00a0Items = new List<Item>
\n\u00a0\u00a0\u00a0\u00a0{
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0new Item { ItemId = Guid.NewGuid().ToString(), Name = “Widget”, Price = 0.99M, Quantity = 1},
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0new Item { ItemId = Guid.NewGuid().ToString(), Name = “Foo”, Price = 4.99M, Quantity = 3},
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0new Item { ItemId = Guid.NewGuid().ToString(), Name = “Baz”, Price = 99.19M, Quantity = 1}
\n\u00a0\u00a0\u00a0\u00a0}
\n};
\nawait db.AddAsync(cart);
\nawait db.SaveChangesAsync();<\/p>\n

var items = await db.Items.Where(i => i.Name == “Foo”).ToListAsync();
\nforeach (var i in items)
\n{
\n\u00a0\u00a0\u00a0\u00a0Console.WriteLine(JsonConvert.SerializeObject(i));
\n}[\/crayon]<\/p>\n\n\n\n

Here’s an example of what the documents in Couchbase will look like after insertion:<\/span><\/p>\n\n\n

[crayon nums=”false” lang=”js” decode=”true”]Key: 080c210a-34eb-45ea-b9b4-e5c6f8afa4d6
\n{
\n\u00a0\u00a0“CartId”: “080c210a-34eb-45ea-b9b4-e5c6f8afa4d6”,
\n\u00a0\u00a0“Created”: “2025-03-13T17:16:31.9904224-04:00”
\n}
\nKey acf54397-51c4-4ad7-bf34-d0a42061b662
\n{
\n\u00a0\u00a0“ItemId”: “acf54397-51c4-4ad7-bf34-d0a42061b662”,
\n\u00a0\u00a0“CartId”: “080c210a-34eb-45ea-b9b4-e5c6f8afa4d6”,
\n\u00a0\u00a0“Name”: “Foo”,
\n\u00a0\u00a0“Price”: 4.99,
\n\u00a0\u00a0“Quantity”: 3
\n}
\nKey a3f25210-97f2-4c95-ad4b-f241dde0d9c3
\n{
\n\u00a0\u00a0“ItemId”: “a3f25210-97f2-4c95-ad4b-f241dde0d9c3”,
\n\u00a0\u00a0“CartId”: “080c210a-34eb-45ea-b9b4-e5c6f8afa4d6”,
\n\u00a0\u00a0“Name”: “Widget”,
\n\u00a0\u00a0“Price”: 0.99,
\n\u00a0\u00a0“Quantity”: 1
\n}
\n\/\/ … etc …[\/crayon]<\/p>\n\n\n\n

What works in the GA release?<\/h2>\n\n\n\n

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:<\/span><\/p>\n\n\n\n

\u2705 <\/span>LINQ support<\/b> \u2013 Translates LINQ queries to <\/span>Couchbase SQL++<\/b>.
\n<\/span>\u2705 <\/span>Basic CRUD operations<\/b> \u2013 Insert, update, and delete work as expected.
\n<\/span>\u2705 <\/span>Change tracking<\/b> \u2013 Entities are tracked for efficient updates.<\/span><\/p>\n\n\n\n

Also note that using Async methods is <\/span>required<\/b>. 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<\/code>.<\/span><\/p>\n\n\n\n

Known limitations<\/h2>\n\n\n\n

While this is a significant milestone, <\/span>some features are still a work in progress<\/b>, including:<\/span><\/p>\n\n\n\n

\u274c <\/span>Denormalization<\/b> \u2013 Nesting collections inside documents (e.g., storing <\/span>Items<\/span> inside <\/span>Cart <\/span>as a single JSON document) is not yet supported.
\n<\/span>\u274c <\/span>Eager Loading<\/b> \u2013 <\/span>.Include()<\/code><\/span> statements may not work as expected.
\n<\/span>\u274c <\/span>SQL++ Function Support<\/b> \u2013 Some SQL++ functions like <\/span>META<\/span>, <\/span>RYOW<\/span>, etc., are not fully implemented.
\n<\/span>\u274c <\/span>Transactions <\/b>\u2013 Not yet supported in this release.<\/span><\/p>\n\n\n\n

Join the conversation!<\/h2>\n\n\n\n

We want your feedback! Help shape the future of the <\/span>Couchbase EF Core Provider<\/b>:<\/span><\/p>\n\n\n\n