Moongate.Persistence 0.5.0

Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package Moongate.Persistence --version 0.5.0
                    
NuGet\Install-Package Moongate.Persistence -Version 0.5.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Moongate.Persistence" Version="0.5.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Moongate.Persistence" Version="0.5.0" />
                    
Directory.Packages.props
<PackageReference Include="Moongate.Persistence" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Moongate.Persistence --version 0.5.0
                    
#r "nuget: Moongate.Persistence, 0.5.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Moongate.Persistence@0.5.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Moongate.Persistence&version=0.5.0
                    
Install as a Cake Addin
#tool nuget:?package=Moongate.Persistence&version=0.5.0
                    
Install as a Cake Tool

Moongate

Moongate.Persistence

Asynchronous PostgreSQL persistence for serial-identified entities, powered by FreeSql.

Installation

Moongate.Persistence requires .NET 10 and PostgreSQL. Use the Moongate version available in your configured NuGet feed.

dotnet add package Moongate.Persistence

Features

  • Explicit module ownership, PostgreSQL schemas, and Accounts or Realm database targets.
  • Detached asynchronous reads, SQL-translated filtering, upserts, and deletes.
  • Grouped writes in one asynchronous transaction for a single database target.
  • Explicit schema preview/apply APIs with automatic synchronization disabled by default.
  • Owner-controlled SaveAllAsync snapshots for application-managed live entities.

Example

Define one stable attribute mapping in Player.cs. The application assigns every nonzero Serial identity.

using FreeSql.DataAnnotations;
using Moongate.Core.Interfaces.Entities;
using Moongate.Core.Primitives;

[Table(Name = "sample_players.players")]
public sealed class Player : IMoongateEntity
{
    [Column(Name = "id", IsPrimary = true, MapType = typeof(long))]
    public Serial Id { get; set; }

    [Column(Name = "name", StringLength = 100)]
    public string Name { get; set; } = "";
}

Declare the entity's sole module owner in PlayerModule.cs.

using Moongate.Persistence.Interfaces;
using Moongate.Persistence.Types.Persistence;

public sealed class PlayerModule : IPersistenceModule
{
    public string Id => "example.players";
    public string Schema => "sample_players";
    public PersistenceDatabaseTarget DatabaseTarget => PersistenceDatabaseTarget.Realm;
    public IReadOnlyCollection<Type> EntityTypes => [typeof(Player)];
}

Program.cs resolves its connection at runtime, applies the example schema explicitly, commits two writes together, and reads a detached value asynchronously. Set MOONGATE_PERSISTENCE_DATABASE to an Npgsql key=value; connection string for an empty development database before running it.

using DryIoc;
using Moongate.Core.Primitives;
using Moongate.Persistence.Data.Config;
using Moongate.Persistence.Extensions;
using Moongate.Persistence.Interfaces;
using Moongate.Persistence.Services;
using Moongate.Persistence.Types.Persistence;

var connectionString = Environment.GetEnvironmentVariable("MOONGATE_PERSISTENCE_DATABASE")
    ?? throw new InvalidOperationException("Set MOONGATE_PERSISTENCE_DATABASE before running this example.");
var options = new PostgreSqlPersistenceOptions(
    [new PersistenceDatabaseOptions(PersistenceDatabaseTarget.Realm, connectionString)],
    autoSynchronizeSchema: true);

using var container = new Container();
container.RegisterMoongatePersistence(options)
         .AddPersistenceModule<PlayerModule>()
         .AddPersistenceEntity<Player>();

await using var persistence = container.Resolve<MoongatePersistenceService>();
await persistence.InitializeAsync();
await persistence.ExecuteInTransactionAsync(PersistenceDatabaseTarget.Realm, async transaction =>
{
    var players = transaction.GetDataAccess<Player>();
    await players.UpsertAsync(new Player { Id = new Serial(1), Name = "Mario" });
    await players.UpsertAsync(new Player { Id = new Serial(2), Name = "Luigi" });
});

var player = await container.Resolve<IDataAccess<Player>>().GetByIdAsync(new Serial(1));
Console.WriteLine(player?.Name);

Normal deployments should keep automatic schema synchronization disabled. Review PreviewSchemaAsync, then run SynchronizeSchemaAsync with a separately authorized schema connection during maintenance.

Behavior and scope

Reads return detached entities. Changing a returned instance does not persist it; call UpsertAsync or DeleteAsync. Writes are last-writer-wins and provide no optimistic concurrency token. A transaction callback covers one Accounts or Realm target and is never retried after an uncertain commit result.

SaveAllAsync captures registered live sources and commits one independent transaction per database target. Snapshot functions must deep-copy nested mutable state. An absent entity is retained; deletion is always explicit.

FreeSql can generate ordinary additive schema DDL. Use OldName for supported renames, and write explicit reviewed SQL for semantic data transformations. Downgrades are operator-managed. This package does not import the removed binary snapshot/journal format and does not create database backups.

Map every complex property explicitly with a supported column/navigation mapping or mark it for explicit omission, such as IsIgnore. Do not assume an ordinary writable object graph is serialized or cascaded automatically.

Mappings are immutable, attribute-only, and identical for a persistence CLR type everywhere. Modules select ownership and target; they do not remap types. Do not independently reconfigure these types through another raw FreeSql instance. Schema comparison has no migration history: it compares the current database with the current attributes and does not record the prior application model.

FreeSql.Provider.PostgreSQL 3.5.311 currently resolves Npgsql 5.0.18. This acknowledged provider limitation must not be hidden with a silent Npgsql major override. Upgrade the provider/driver combination only after running the PostgreSQL compatibility tests.

Further reading

See the persistence and operations guide for schema review, plugin ownership, world saves, transactions, and database backup responsibility.

License and source

Licensed under AGPL-3.0-or-later. See the source repository and license.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.21.0 94 11/3/2026
0.20.1 109 10/22/2026
0.20.0 102 10/22/2026
0.19.0 104 10/16/2026
0.18.0 115 10/16/2026
0.17.0 102 10/14/2026
0.16.0 107 10/9/2026
0.15.0 106 10/7/2026
0.14.0 108 10/4/2026
0.13.0 112 10/3/2026
0.12.0 99 10/2/2026
0.11.0 111 9/30/2026
0.10.0 113 9/30/2026
0.9.0 115 9/27/2026
0.8.0 113 9/26/2026
0.7.0 97 9/24/2026
0.6.0 117 9/21/2026
0.5.0 116 9/20/2026
0.4.1 114 9/20/2026
0.4.0 116 9/19/2026
Loading failed