BitBadger.Npgsql.Documents
View Source Repo

BitBadger.Npgsql.Documents provides a lightweight document-style interface over PostgreSQL's excellent JSONB storage capabilities for C# and F# programs. (It is developed by the community; it is not official software from PostgreSQL or the Npgsql project.)

What It Provides

Document databases (usually) utilize JSON storage to provide a schemaless persistence of data. MongoDB was the pioneer and is the leader in this space, but there are several who provide their own take on it, and their own programming API to come along with it. They also usually have some sort of clustering, replication, and sharding solution that allows them to be scaled out (horizontally) to handle a large amount of traffic.

As a mature relational database, PostgreSQL has a long history of robust data access from the .NET environment; Npgsql is actively developed, and provides both ADO.NET and EF Core APIs. PostgreSQL also has well-established, battle-tested horizontal scaling options. Additionally, the Npgsql.FSharp project provides a functional API over Npgsql's ADO.NET data access. These three factors make PostgreSQL an excellent choice for document storage, and its relational nature can help in areas where traditional document databases become more complex.

For straight document access, the functions provided by this library make that access dead-simple. For more complex queries, it also provides the building blocks to construct these with minimal code.

Installing

BitBadger.Npgsql.Documents is best for C# use
BitBadger.Npgsql.FSharp.Documents is best for F# use

dotnet add package BitBadger.Npgsql[.FSharp].Documents

If your application currently uses v1, check out the migration guide to v2

Using

• Setting Up details providing a data source to the library, and ensuring required tables and indexes exist.
• Basic Usage details document-level retrieval, persistence, and deletion.
• Advanced Usage demonstrates how to use the building blocks provided by this library to write slightly-more complex queries.

Why Not [something else]?

We are blessed to live in a time where there are a lot of good data storage options that are more than efficient enough for the majority of use cases. Rather than speaking ill of other projects, here is the vision of the benefits PostgreSQL and this library provide:

• Quality - PostgreSQL's reputation is one of a rock-solid, well-maintained, and continually evolving database.
• Availability - Nearly every cloud database provider offers PostgreSQL, and for custom servers, it is a package install away from being up and running.
• Efficiency - PostgreSQL is very efficient, and its indexing of JSONB allows for quick access via any field in a document.
• Maintainability - The terms “separation of concerns” and “locality of behavior” often compete within a code base, and separation of concerns often wins out; cluttering your logic with SQL can be less than optimal. Using this library, though, it may separate the concerns enough that the calls can be placed directly in the regular logic, providing one fewer place that must be looked up when tracing through the code.
• Simplicity - SQL is a familiar language; even when writing manual queries against the data store created by this library, everything one knows about SQL applies, with a few operators added.
• Reliability - Both the C# and F# libraries have a full suite of tests, run against every supported PostgreSQL version, to ensure the functionality provided is what is advertised.

Support

Issues can be filed on the project's GitHub repository.