A 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.
A Couchbase EF Core Provider enables developers to use Entity Framework Core with Couchbase Server e 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.
Começar
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 |
usando Couchbase; usando Couchbase.EntityFrameworkCore; usando Couchbase.EntityFrameworkCore.Extensions; usando Microsoft.EntityFrameworkCore; usando Microsoft.Extensions.Registro; usando NLog.Extensions.Registro; usando ILoggerFactory = Microsoft.Extensions.Registro.ILoggerFactory; público class Cart { público string CartId { obter; definir; } público DateTimeOffset Created { obter; definir; } público Lista<Item> Items { obter; definir; } } público class Item { público string ItemId { obter; definir; } público string Nome { obter; definir; } público uint Quantity { obter; definir; } público decimal Preço { obter; definir; } } |
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 |
público class CartContext : DbContext { público DbSet<Cart> Carts { obter; definir; } público DbSet<Item> Items { obter; definir; } private static readonly ILoggerFactory LoggerFactory = Microsoft.Extensions.Registro.LoggerFactory.Create(builder => { builder.ClearProviders(); builder.AddNLog(); }); protected override vazio OnConfiguring(DbContextOptionsBuilder Opções) { Opções.UseCouchbase(novo OpçõesDeCluster() .WithCredentials(“Administrador”, “senha”) .WithConnectionString(“couchbase://localhost”) .WithLogging(LoggerFactory), couchbaseDbContextOptions => { couchbaseDbContextOptions.Balde = “Shopping”; couchbaseDbContextOptions.Escopo = “Ecommerce”; }); } protected override vazio 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 e 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 |
aguarde usando variável db = novo CartContext(); variável cart = novo Cart { CartId = Guid.NewGuid().ToString(), Created = DateTimeOffset.Now, Items = novo Lista<Item> { novo Item { ItemId = Guid.NewGuid().ToString(), Nome = “Widget”, Preço = 0.99M, Quantity = 1}, novo Item { ItemId = Guid.NewGuid().ToString(), Nome = “Foo”, Preço = 4.99M, Quantity = 3}, novo Item { ItemId = Guid.NewGuid().ToString(), Nome = “Baz”, Preço = 99.19M, Quantity = 1} } }; aguarde db.AddAsync(cart); aguarde db.SaveChangesAsync(); variável items = aguarde db.Items.Where(i => i.Nome == “Foo”).ToListAsync(); foreach (variável i em 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.
❌ Transações – 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 no Couchbase .NET forums.
- Chat with us on Discord – Join our community.
- Report issues and contribute ligado 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!
Deixe um comentário
Você precisa fazer o login para publicar um comentário.