Moongate.Persistence
0.5.0
Prefix Reserved
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
<PackageReference Include="Moongate.Persistence" Version="0.5.0" />
<PackageVersion Include="Moongate.Persistence" Version="0.5.0" />
<PackageReference Include="Moongate.Persistence" />
paket add Moongate.Persistence --version 0.5.0
#r "nuget: Moongate.Persistence, 0.5.0"
#:package Moongate.Persistence@0.5.0
#addin nuget:?package=Moongate.Persistence&version=0.5.0
#tool nuget:?package=Moongate.Persistence&version=0.5.0

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
SaveAllAsyncsnapshots 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 | Versions 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. |
-
net10.0
- FreeSql.Provider.PostgreSQL (>= 3.5.311)
- Moongate.Core (>= 0.5.0)
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 |