Moongate.Persistence 0.6.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.6.0
                    
NuGet\Install-Package Moongate.Persistence -Version 0.6.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.6.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Moongate.Persistence" Version="0.6.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.6.0
                    
#r "nuget: Moongate.Persistence, 0.6.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.6.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.6.0
                    
Install as a Cake Addin
#tool nuget:?package=Moongate.Persistence&version=0.6.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

  • Auth/World entity registration with automatic internal modules and PostgreSQL schemas.
  • Detached asynchronous reads, SQL-translated filtering, upserts, and deletes.
  • Grouped writes in one asynchronous transaction for a single database target.
  • Versioned SQL readiness checks, draft schema preview, and explicit development synchronization.
  • 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; } = "";
}

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 a postgres://user:password@host:5432/database connection URI 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)
         .AddPersistenceWorld<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);

AddPersistenceWorld<T>() selects the Realm database; AddPersistenceAuth<T>() selects the shared Accounts database. Moongate creates internal modules from the schema-qualified table attributes, so no module class is required. Both helpers also accept a live source and an explicit detached snapshot function. Explicit IPersistenceModule declarations remain available for plugins that need them.

Connection options accept postgres:// and postgresql:// URIs, including percent-encoded credentials, IPv6 hosts and query options such as sslmode and connect_timeout. Native Npgsql connection strings are also supported.

Normal deployments keep automatic synchronization disabled. Generate and review versioned SQL, then apply it with the separate Moongate.MigrationRunner executable. Configure PostgreSqlPersistenceOptions.MigrationCatalogFactory for migration readiness checks in a custom host; Moongate.Server wires this automatically. SynchronizeSchemaAsync remains a development-only convenience and does not record history.

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 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. FreeSql schema comparison compares the current database with current attributes. Versioned SQL and the checksum journal live in Moongate.Persistence.Migrations; the separate runner applies them atomically.

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