Releases: Doxense/foundationdb-dotnet-client
7.0.0-preview1
TODO: add more complete releases notes ASAP!
Short version:
- This version includes the new Deferred Value Checks and Layer Caching API!
- Directory subspace API has changed (documentation is out of date!)
- Dropped support for .NET Standard 2.1 / .NET Core 3.1, replaced with .NET 5.0
6.2.0-preview1
Please do not use this release!
5.2.1-preview2
Changes
- Bumped from .NET 4.7.1 to 4.7.2, and from .NET Core 2.1 to 2.2. Still "supporting" .NET 4.6.1
- Max API bumped to API level 600 (by default)
- Reworked the Dynamic and Typed key subspaces so that all methods for generating ranges have proper names (
ToRange(item1, item2, ...)
vsPackRange(tuple)
) (7636b1b) - Added a lot of missing properties on the metrics exposed by
status json
to get in line with 5.x and 6.0 (c4c36d3) - Added the
IFdbDatabaseProvider
andIFdbDatabaseScopeProvider
to help use fdb with dependency injection framework (the norm for ASP.NET Core apps). - Steamlined the Directory API exposed on database instances (#88)
- Completely removed the
FdbDatabasePartition
type that is not needed anymore (following the change in Directory API). - Fixed
clearrange
command in FdbShell (a6a5d02) - Updated and reworked FdbTop to expose all the new metrics from 5.x and 6.x
- Deprecated TLSPlugin and other TLS options since they are also deprecated in fdb 6.0
Changes in the Directory API
The FdbDatabasePartition
type is gone, and now IFdbDatabase
looks like this:
public interface IFdbDatabase
{
// ...
IFdbDirectory Directory { get; }
}
Code that has to use the Directory layer inside a retry-loop now looks like this:
var partition = new [] { "Tests", "ACME", Environment.MachineName };
this.Db = await Fdb.OpenAsync(new FdbConnectionOptions() { PartitionPath = partition }, ct);
await this.Db.ReadWriteAsync(async tr =>
{
foreach(var dir in await this.Db.Directory.TryListAsync(tr))
{
await this.Db.Directory.RemoveAsync(tr, new [] { dir });
}
}, ct);
Another change is that most Directory Layer overloads will expect a IEnumerable<string>
anymore, but for a new struct called FdbDirectoryPath
. This struct encapsulate the concept of 'path of a subdirectory', and has mutiple implicit and explicit cast from string, string arrays, and so on. This is the first step into being able to use types other than string for the folder names (int, guid, ...).
IFdbDatabaseScopeProvider
To be able to use FoundationDB with ASP.NET Core web site that make heavy use of dependency injection, we needed additional types to make it work better.
The new IFdbDatabaseProvider
and IFdbDatabaseScopeProvider
are interfaces that can be registered with the DI framework, and can be used to obtain an IFdbDatabase
instance inside MVC controllers, for example.
The reason we are not registering an IFdbDatabase
singleton directly is that the creation of this instance is async, and it is possible that the cluster is down while the web site is starting up.
The IFdbDatabaseScopeProvider
on the other hand, only wraps the desiered connection options, and has a method GetDatabaseAsync
that returns a cached database instance asynchronously:
public interface IFdbDatabaseScopeProvider : IDisposable
{
// ... other methods
/// <summary>Return an instance of the database, once it is ready</summary>
/// <remarks>During the startup of the application, the task returned will wait until the database becomes ready. After that, the task will immediately return the database singleton.</remarks>
[ItemNotNull]
ValueTask<IFdbDatabase> GetDatabase(CancellationToken ct);
}
The expected usage of this interface is to require an IFdbDatabaseScopeProvider
in your controller's constructor, and then await provider.GetDatabase(...)
to get the IFdbDatabase
instance. While the application is still in the early startup stage, and the database connection is not yet ready, this task will block until it is ready. Once the connection has been set up, then this task will immediately return the cached instance (hence why this is a ValueTask<...>
.
To simplify the code, there is a set of extensions methods ReadAsync(...)
, ReadWriteAsync(..)
and WriteAsync(...)
on providers that are identicial to the version on a database instance, and handle all of this under the hood.
This means that in practice, MVC controllers can treat an IFdbDatabaseScopeProvider
the same way as an IFdbDatabase
.
Startup class:
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
// registers the various `IFdbDatabaseProvider` and `IFdbDatabaseScopeProvider` services with DI
services.AddFoundationDb(520, options =>
{
options.ConnectionOptions.PartitionPath = new[] { "FooBarApp", "AcmeCustomer", .... };
// other options here
});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env, IApplicationLifetime lifetime)
{
// Plug with the "start" event of the web app, so that it calls "Start()" and "Stop()" on the root provider.
app.UseFoundationDb((fdb) =>
{
// more setup possible here
});
}
}
Example controller:
public class FooController
{
public IFdbDatabaseScopeProvider Db { get; }
public FooController(IFdbDatabaseScopeProvider db, /* other services required */)
{
this.Db = db;
//...
}
[HttpGet]
public async Task<ActionResult<IEnumerable<FooModel>>> Get(CancellationToken ct)
{
return await this.Db.ReadAsync((tr) =>
{
// regular transaction code that reads a range and returns an sequence of 'FooModel'
}, ct);
}
//....
}
5.2.0-preview1
IMPORTANT: This updates introduce a few breaking changes!
- Added multi-targeting to .NET 4.6.1, .NET 4.7.1 and .NET Standard 2.0
- Added support for API version 520 (
AppendsIfFit
, offset inSetVersionStampedValue
, ...) - [BREAKING] Changed binary format of embedded tuples to match the latest specifications (#84)
- [BREAKING] Renamed ITuple to IVarTuple to fix naming conflict in .NET Framework 4.7.1 (#89)
- Added
FdbConnectionOptions
and a correspondingFdb.OpenAsync(..)
that should be used as the default starting point. - Deprecated all the other
Fdb.OpenAsync(..)
andFdb.Directory.OpenNamedPartitionAsync(...)
- Fixed a few things regarding use of Watches (187ac16)
- Optimized futures to use
TaskCreationOptions.RunContinuationsAsynchronously
instead of queueing a workitem on the thread pool (a22228c) - Added
GetRangeKeys
andGetRangeValues
helpers that attempt to reduce the other of copying data that will not be used (7c46b38). Note that this feature is emulated client-side because it is not supported by the db at this time! - [BREAKING] FdbRangeChunk has been changed from a
struct
to aclass
(0167365) - Added a few commands to FDBShell
- Made FDBTop work on smaller terminal sizes.
5.1.0-alpha2
This release aligns the encoding of embedded tuples and booleans with the new specifications.
THIS IS A BREAKING CHANGE: any data previously inserted in the database using embedded tuples or booleans will not be compatible with this new version!
- Change the encoding of embedded tuples from type 0x03 to 0x05 (#84)
- Change the encoding of booleans from integers to types 0x26 and 0x27 (#84)
- Add pre-emptive support for new handling of versionstamped keys and values in API 520 (f09709c)
- Remove redundant async/await in Fdb.OpenAsync(...) call (#86)
5.1.0-alpha1
Updated version that targets FoundationDB API v510 by default and .NET Standard 2.0
- Use API version 510 by default (#63)
- Migrated projects to target .NET Standard 2.0 (#68)
- Added initial support for VersionStamps (#72)
- Added integration with System.ValueTuple (#73)
- Updated the Tuple Encoder layer and Slice code (breaking change)
- Updated the IKeyEncoder and Subspace API (breaking change)
warning: the API is still marked as unstable and may change again in the next alpha or beta release!