BitBadger.Documents.Postgres 4.0.0-rc3

This is a prerelease version of BitBadger.Documents.Postgres.
There is a newer version of this package available.
See the version list below for details.
dotnet add package BitBadger.Documents.Postgres --version 4.0.0-rc3                
NuGet\Install-Package BitBadger.Documents.Postgres -Version 4.0.0-rc3                
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="BitBadger.Documents.Postgres" Version="4.0.0-rc3" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add BitBadger.Documents.Postgres --version 4.0.0-rc3                
#r "nuget: BitBadger.Documents.Postgres, 4.0.0-rc3"                
#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.
// Install BitBadger.Documents.Postgres as a Cake Addin
#addin nuget:?package=BitBadger.Documents.Postgres&version=4.0.0-rc3&prerelease

// Install BitBadger.Documents.Postgres as a Cake Tool
#tool nuget:?package=BitBadger.Documents.Postgres&version=4.0.0-rc3&prerelease                

BitBadger.Documents.Postgres

This package provides a lightweight document library backed by PostgreSQL. It also provides streamlined functions for traditional ADO.NET functionality where relational data is required. Both C# and F# have first-class implementations.

Features

  • Select, insert, update, save (upsert), delete, count, and check existence of documents, and create tables and indexes for these documents
  • Address documents via ID, via comparison on any field, via equality on any property (using JSON containment, on a likely indexed field), or via condition on any property (using JSON Path queries)
  • Access documents as your domain models (<abbr title="Plain Old CLR Objects">POCO</abbr>s)
  • Use Task-based async for all data access functions
  • Use building blocks for more complex queries

Getting Started

Once the package is installed, the library needs a data source. Construct an NpgsqlDataSource instance, and provide it to the library:

// C#
using BitBadger.Documents.Postgres;

//...
// Do not use "using" here; the library will handle disposing this instance
var data = new NpgsqlDataSourceBuilder("connection-string").Build();
Postgres.Configuration.UseDataSource(data);
// F#
open BitBadger.Documents.Postgres

// ...
// Do not use "use" here; the library will handle disposing this instance
let dataSource = // same as above ....

Configuration.useDataSource dataSource
// ...

By default, the library uses a System.Text.Json-based serializer configured to use the FSharp.SystemTextJson converter. To provide a different serializer (different options, more converters, etc.), construct it to implement IDocumentSerializer and provide it via Configuration.useSerializer. If custom serialization makes the serialized Id field not be Id, that will also need to be configured.

Using

Retrieve all customers:

// C#; parameter is table name
// Find.All type signature is Func<string, Task<List<TDoc>>>
var customers = await Find.All<Customer>("customer");
// F#
// Find.all type signature is string -> Task<'TDoc list>
let! customers = Find.all<Customer> "customer"

Select a customer by ID:

// C#; parameters are table name and ID
// Find.ById type signature is Func<string, TKey, Task<TDoc?>>
var customer = await Find.ById<string, Customer>("customer", "123");
// F#
// Find.byId type signature is string -> 'TKey -> Task<'TDoc option>
let! customer = Find.byId<string, Customer> "customer" "123"

(keys are treated as strings in the database)

Count customers in Atlanta (using JSON containment):

// C#; parameters are table name and object for containment query
// Count.ByContains type signature is Func<string, TCriteria, int>
var customerCount = await Count.ByContains("customer", new { City = "Atlanta" });
// F#
// Count.byContains type signature is string -> 'TCriteria -> Task<int>
let! customerCount = Count.byContains "customer" {| City = "Atlanta" |}

Delete customers in Chicago: (no offense, Second City; just an example...)

// C#; parameters are table name and JSON Path expression
// Delete.ByJsonPath type signature is Func<string, string, Task>
await Delete.ByJsonPath("customer", "$.City ? (@ == \"Chicago\")");
// F#
// Delete.byJsonPath type signature is string -> string -> Task<unit>
do! Delete.byJsonPath "customer" """$.City ? (@ == "Chicago")"""

More Information

The project site has full details on how to use this library.

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.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
4.0.0 77 12/18/2024
4.0.0-rc5 100 9/18/2024
4.0.0-rc4 95 9/17/2024
4.0.0-rc3 110 8/23/2024
4.0.0-rc2 121 8/22/2024
4.0.0-rc1 114 8/19/2024
3.1.0 137 6/6/2024
3.0.0 126 4/21/2024
3.0.0-rc-2 231 1/24/2024
3.0.0-rc-1 154 12/31/2023

From rc2: preserve additional ORDER BY qualifiers. From rc1: add case-insensitive ordering. From v3.1: Change ByField to ByFields; support dot-access to nested document fields; add Find*Ordered functions/methods; see project site for breaking changes and compatibility