v3 RC1 (#1)
This encompasses: - New behavior for SQLite - Migrated behavior for PostrgeSQL (from BitBadger.Npgsql.FSharp.Documents) - New "byField" behavior for PostgreSQL - A unification of C# and F# centric implementations
This commit was merged in pull request #1.
This commit is contained in:
GitHub
23
src/Postgres/BitBadger.Documents.Postgres.fsproj
Normal file
23
src/Postgres/BitBadger.Documents.Postgres.fsproj
Normal file
@@ -0,0 +1,23 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<PropertyGroup>
|
||||
<PackageReleaseNotes>Initial release; migrated from BitBadger.Npgsql.Documents, with field and extension additions (RC 1)</PackageReleaseNotes>
|
||||
<PackageTags>JSON Document PostgreSQL Npgsql</PackageTags>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<Compile Include="Library.fs" />
|
||||
<Compile Include="Extensions.fs" />
|
||||
<None Include="README.md" Pack="true" PackagePath="\" />
|
||||
<None Include="..\icon.png" Pack="true" PackagePath="\" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<PackageReference Include="Npgsql.FSharp" Version="5.7.0" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\Common\BitBadger.Documents.Common.fsproj" />
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
333
src/Postgres/Extensions.fs
Normal file
333
src/Postgres/Extensions.fs
Normal file
@@ -0,0 +1,333 @@
|
||||
namespace BitBadger.Documents.Postgres
|
||||
|
||||
open Npgsql
|
||||
open Npgsql.FSharp
|
||||
|
||||
/// F# Extensions for the NpgsqlConnection type
|
||||
[<AutoOpen>]
|
||||
module Extensions =
|
||||
|
||||
type NpgsqlConnection with
|
||||
|
||||
/// Execute a query that returns a list of results
|
||||
member conn.customList<'TDoc> query parameters (mapFunc: RowReader -> 'TDoc) =
|
||||
WithProps.Custom.list<'TDoc> query parameters mapFunc (Sql.existingConnection conn)
|
||||
|
||||
/// Execute a query that returns one or no results; returns None if not found
|
||||
member conn.customSingle<'TDoc> query parameters (mapFunc: RowReader -> 'TDoc) =
|
||||
WithProps.Custom.single<'TDoc> query parameters mapFunc (Sql.existingConnection conn)
|
||||
|
||||
/// Execute a query that returns no results
|
||||
member conn.customNonQuery query parameters =
|
||||
WithProps.Custom.nonQuery query parameters (Sql.existingConnection conn)
|
||||
|
||||
/// Execute a query that returns a scalar value
|
||||
member conn.customScalar<'T when 'T: struct> query parameters (mapFunc: RowReader -> 'T) =
|
||||
WithProps.Custom.scalar query parameters mapFunc (Sql.existingConnection conn)
|
||||
|
||||
/// Create a document table
|
||||
member conn.ensureTable name =
|
||||
WithProps.Definition.ensureTable name (Sql.existingConnection conn)
|
||||
|
||||
/// Create an index on documents in the specified table
|
||||
member conn.ensureDocumentIndex name idxType =
|
||||
WithProps.Definition.ensureDocumentIndex name idxType (Sql.existingConnection conn)
|
||||
|
||||
/// Create an index on field(s) within documents in the specified table
|
||||
member conn.ensureFieldIndex tableName indexName fields =
|
||||
WithProps.Definition.ensureFieldIndex tableName indexName fields (Sql.existingConnection conn)
|
||||
|
||||
/// Insert a new document
|
||||
member conn.insert<'TDoc> tableName (document: 'TDoc) =
|
||||
WithProps.Document.insert<'TDoc> tableName document (Sql.existingConnection conn)
|
||||
|
||||
/// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
|
||||
member conn.save<'TDoc> tableName (document: 'TDoc) =
|
||||
WithProps.Document.save<'TDoc> tableName document (Sql.existingConnection conn)
|
||||
|
||||
/// Count all documents in a table
|
||||
member conn.countAll tableName =
|
||||
WithProps.Count.all tableName (Sql.existingConnection conn)
|
||||
|
||||
/// Count matching documents using a JSON field comparison query (->> =)
|
||||
member conn.countByField tableName fieldName op (value: obj) =
|
||||
WithProps.Count.byField tableName fieldName op value (Sql.existingConnection conn)
|
||||
|
||||
/// Count matching documents using a JSON containment query (@>)
|
||||
member conn.countByContains tableName criteria =
|
||||
WithProps.Count.byContains tableName criteria (Sql.existingConnection conn)
|
||||
|
||||
/// Count matching documents using a JSON Path match query (@?)
|
||||
member conn.countByJsonPath tableName jsonPath =
|
||||
WithProps.Count.byJsonPath tableName jsonPath (Sql.existingConnection conn)
|
||||
|
||||
/// Determine if a document exists for the given ID
|
||||
member conn.existsById tableName docId =
|
||||
WithProps.Exists.byId tableName docId (Sql.existingConnection conn)
|
||||
|
||||
/// Determine if documents exist using a JSON field comparison query (->> =)
|
||||
member conn.existsByField tableName fieldName op (value: obj) =
|
||||
WithProps.Exists.byField tableName fieldName op value (Sql.existingConnection conn)
|
||||
|
||||
/// Determine if documents exist using a JSON containment query (@>)
|
||||
member conn.existsByContains tableName criteria =
|
||||
WithProps.Exists.byContains tableName criteria (Sql.existingConnection conn)
|
||||
|
||||
/// Determine if documents exist using a JSON Path match query (@?)
|
||||
member conn.existsByJsonPath tableName jsonPath =
|
||||
WithProps.Exists.byJsonPath tableName jsonPath (Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve all documents in the given table
|
||||
member conn.findAll<'TDoc> tableName =
|
||||
WithProps.Find.all<'TDoc> tableName (Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve a document by its ID; returns None if not found
|
||||
member conn.findById<'TKey, 'TDoc> tableName docId =
|
||||
WithProps.Find.byId<'TKey, 'TDoc> tableName docId (Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve documents matching a JSON field comparison query (->> =)
|
||||
member conn.findByField<'TDoc> tableName fieldName op (value: obj) =
|
||||
WithProps.Find.byField<'TDoc> tableName fieldName op value (Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve documents matching a JSON containment query (@>)
|
||||
member conn.findByContains<'TDoc> tableName (criteria: obj) =
|
||||
WithProps.Find.byContains<'TDoc> tableName criteria (Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve documents matching a JSON Path match query (@?)
|
||||
member conn.findByJsonPath<'TDoc> tableName jsonPath =
|
||||
WithProps.Find.byJsonPath<'TDoc> tableName jsonPath (Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve the first document matching a JSON field comparison query (->> =); returns None if not found
|
||||
member conn.findFirstByField<'TDoc> tableName fieldName op (value: obj) =
|
||||
WithProps.Find.firstByField<'TDoc> tableName fieldName op value (Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve the first document matching a JSON containment query (@>); returns None if not found
|
||||
member conn.findFirstByContains<'TDoc> tableName (criteria: obj) =
|
||||
WithProps.Find.firstByContains<'TDoc> tableName criteria (Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve the first document matching a JSON Path match query (@?); returns None if not found
|
||||
member conn.findFirstByJsonPath<'TDoc> tableName jsonPath =
|
||||
WithProps.Find.firstByJsonPath<'TDoc> tableName jsonPath (Sql.existingConnection conn)
|
||||
|
||||
/// Update an entire document by its ID
|
||||
member conn.updateById tableName (docId: 'TKey) (document: 'TDoc) =
|
||||
WithProps.Update.byId tableName docId document (Sql.existingConnection conn)
|
||||
|
||||
/// Update an entire document by its ID, using the provided function to obtain the ID from the document
|
||||
member conn.updateByFunc tableName (idFunc: 'TDoc -> 'TKey) (document: 'TDoc) =
|
||||
WithProps.Update.byFunc tableName idFunc document (Sql.existingConnection conn)
|
||||
|
||||
/// Patch a document by its ID
|
||||
member conn.patchById tableName (docId: 'TKey) (patch: 'TPatch) =
|
||||
WithProps.Patch.byId tableName docId patch (Sql.existingConnection conn)
|
||||
|
||||
/// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
|
||||
member conn.patchByField tableName fieldName op (value: obj) (patch: 'TPatch) =
|
||||
WithProps.Patch.byField tableName fieldName op value patch (Sql.existingConnection conn)
|
||||
|
||||
/// Patch documents using a JSON containment query in the WHERE clause (@>)
|
||||
member conn.patchByContains tableName (criteria: 'TCriteria) (patch: 'TPatch) =
|
||||
WithProps.Patch.byContains tableName criteria patch (Sql.existingConnection conn)
|
||||
|
||||
/// Patch documents using a JSON Path match query in the WHERE clause (@?)
|
||||
member conn.patchByJsonPath tableName jsonPath (patch: 'TPatch) =
|
||||
WithProps.Patch.byJsonPath tableName jsonPath patch (Sql.existingConnection conn)
|
||||
|
||||
/// Delete a document by its ID
|
||||
member conn.deleteById tableName (docId: 'TKey) =
|
||||
WithProps.Delete.byId tableName docId (Sql.existingConnection conn)
|
||||
|
||||
/// Delete documents by matching a JSON field comparison query (->> =)
|
||||
member conn.deleteByField tableName fieldName op (value: obj) =
|
||||
WithProps.Delete.byField tableName fieldName op value (Sql.existingConnection conn)
|
||||
|
||||
/// Delete documents by matching a JSON containment query (@>)
|
||||
member conn.deleteByContains tableName (criteria: 'TContains) =
|
||||
WithProps.Delete.byContains tableName criteria (Sql.existingConnection conn)
|
||||
|
||||
/// Delete documents by matching a JSON Path match query (@?)
|
||||
member conn.deleteByJsonPath tableName path =
|
||||
WithProps.Delete.byJsonPath tableName path (Sql.existingConnection conn)
|
||||
|
||||
|
||||
open System.Runtime.CompilerServices
|
||||
|
||||
/// C# extensions on the NpgsqlConnection type
|
||||
type NpgsqlConnectionCSharpExtensions =
|
||||
|
||||
/// Execute a query that returns a list of results
|
||||
[<Extension>]
|
||||
static member inline CustomList<'TDoc>(conn, query, parameters, mapFunc: System.Func<RowReader, 'TDoc>) =
|
||||
WithProps.Custom.List<'TDoc>(query, parameters, mapFunc, Sql.existingConnection conn)
|
||||
|
||||
/// Execute a query that returns one or no results; returns None if not found
|
||||
[<Extension>]
|
||||
static member inline CustomSingle<'TDoc when 'TDoc: null>(
|
||||
conn, query, parameters, mapFunc: System.Func<RowReader, 'TDoc>) =
|
||||
WithProps.Custom.Single<'TDoc>(query, parameters, mapFunc, Sql.existingConnection conn)
|
||||
|
||||
/// Execute a query that returns no results
|
||||
[<Extension>]
|
||||
static member inline CustomNonQuery(conn, query, parameters) =
|
||||
WithProps.Custom.nonQuery query parameters (Sql.existingConnection conn)
|
||||
|
||||
/// Execute a query that returns a scalar value
|
||||
[<Extension>]
|
||||
static member inline CustomScalar<'T when 'T: struct>(
|
||||
conn, query, parameters, mapFunc: System.Func<RowReader, 'T>) =
|
||||
WithProps.Custom.Scalar(query, parameters, mapFunc, Sql.existingConnection conn)
|
||||
|
||||
/// Create a document table
|
||||
[<Extension>]
|
||||
static member inline EnsureTable(conn, name) =
|
||||
WithProps.Definition.ensureTable name (Sql.existingConnection conn)
|
||||
|
||||
/// Create an index on documents in the specified table
|
||||
[<Extension>]
|
||||
static member inline EnsureDocumentIndex(conn, name, idxType) =
|
||||
WithProps.Definition.ensureDocumentIndex name idxType (Sql.existingConnection conn)
|
||||
|
||||
/// Create an index on field(s) within documents in the specified table
|
||||
[<Extension>]
|
||||
static member inline EnsureFieldIndex(conn, tableName, indexName, fields) =
|
||||
WithProps.Definition.ensureFieldIndex tableName indexName fields (Sql.existingConnection conn)
|
||||
|
||||
/// Insert a new document
|
||||
[<Extension>]
|
||||
static member inline Insert<'TDoc>(conn, tableName, document: 'TDoc) =
|
||||
WithProps.Document.insert<'TDoc> tableName document (Sql.existingConnection conn)
|
||||
|
||||
/// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
|
||||
[<Extension>]
|
||||
static member inline Save<'TDoc>(conn, tableName, document: 'TDoc) =
|
||||
WithProps.Document.save<'TDoc> tableName document (Sql.existingConnection conn)
|
||||
|
||||
/// Count all documents in a table
|
||||
[<Extension>]
|
||||
static member inline CountAll(conn, tableName) =
|
||||
WithProps.Count.all tableName (Sql.existingConnection conn)
|
||||
|
||||
/// Count matching documents using a JSON field comparison query (->> =)
|
||||
[<Extension>]
|
||||
static member inline CountByField(conn, tableName, fieldName, op, value: obj) =
|
||||
WithProps.Count.byField tableName fieldName op value (Sql.existingConnection conn)
|
||||
|
||||
/// Count matching documents using a JSON containment query (@>)
|
||||
[<Extension>]
|
||||
static member inline CountByContains(conn, tableName, criteria: 'TCriteria) =
|
||||
WithProps.Count.byContains tableName criteria (Sql.existingConnection conn)
|
||||
|
||||
/// Count matching documents using a JSON Path match query (@?)
|
||||
[<Extension>]
|
||||
static member inline CountByJsonPath(conn, tableName, jsonPath) =
|
||||
WithProps.Count.byJsonPath tableName jsonPath (Sql.existingConnection conn)
|
||||
|
||||
/// Determine if a document exists for the given ID
|
||||
[<Extension>]
|
||||
static member inline ExistsById(conn, tableName, docId) =
|
||||
WithProps.Exists.byId tableName docId (Sql.existingConnection conn)
|
||||
|
||||
/// Determine if documents exist using a JSON field comparison query (->> =)
|
||||
[<Extension>]
|
||||
static member inline ExistsByField(conn, tableName, fieldName, op, value: obj) =
|
||||
WithProps.Exists.byField tableName fieldName op value (Sql.existingConnection conn)
|
||||
|
||||
/// Determine if documents exist using a JSON containment query (@>)
|
||||
[<Extension>]
|
||||
static member inline ExistsByContains(conn, tableName, criteria: 'TCriteria) =
|
||||
WithProps.Exists.byContains tableName criteria (Sql.existingConnection conn)
|
||||
|
||||
/// Determine if documents exist using a JSON Path match query (@?)
|
||||
[<Extension>]
|
||||
static member inline ExistsByJsonPath(conn, tableName, jsonPath) =
|
||||
WithProps.Exists.byJsonPath tableName jsonPath (Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve all documents in the given table
|
||||
[<Extension>]
|
||||
static member inline FindAll<'TDoc>(conn, tableName) =
|
||||
WithProps.Find.All<'TDoc>(tableName, Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve a document by its ID; returns None if not found
|
||||
[<Extension>]
|
||||
static member inline FindById<'TKey, 'TDoc when 'TDoc: null>(conn, tableName, docId: 'TKey) =
|
||||
WithProps.Find.ById<'TKey, 'TDoc>(tableName, docId, Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve documents matching a JSON field comparison query (->> =)
|
||||
[<Extension>]
|
||||
static member inline FindByField<'TDoc>(conn, tableName, fieldName, op, value: obj) =
|
||||
WithProps.Find.ByField<'TDoc>(tableName, fieldName, op, value, Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve documents matching a JSON containment query (@>)
|
||||
[<Extension>]
|
||||
static member inline FindByContains<'TDoc>(conn, tableName, criteria: obj) =
|
||||
WithProps.Find.ByContains<'TDoc>(tableName, criteria, Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve documents matching a JSON Path match query (@?)
|
||||
[<Extension>]
|
||||
static member inline FindByJsonPath<'TDoc>(conn, tableName, jsonPath) =
|
||||
WithProps.Find.ByJsonPath<'TDoc>(tableName, jsonPath, Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve the first document matching a JSON field comparison query (->> =); returns None if not found
|
||||
[<Extension>]
|
||||
static member inline FindFirstByField<'TDoc when 'TDoc: null>(conn, tableName, fieldName, op, value: obj) =
|
||||
WithProps.Find.FirstByField<'TDoc>(tableName, fieldName, op, value, Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve the first document matching a JSON containment query (@>); returns None if not found
|
||||
[<Extension>]
|
||||
static member inline FindFirstByContains<'TDoc when 'TDoc: null>(conn, tableName, criteria: obj) =
|
||||
WithProps.Find.FirstByContains<'TDoc>(tableName, criteria, Sql.existingConnection conn)
|
||||
|
||||
/// Retrieve the first document matching a JSON Path match query (@?); returns None if not found
|
||||
[<Extension>]
|
||||
static member inline FindFirstByJsonPath<'TDoc when 'TDoc: null>(conn, tableName, jsonPath) =
|
||||
WithProps.Find.FirstByJsonPath<'TDoc>(tableName, jsonPath, Sql.existingConnection conn)
|
||||
|
||||
/// Update an entire document by its ID
|
||||
[<Extension>]
|
||||
static member inline UpdateById(conn, tableName, docId: 'TKey, document: 'TDoc) =
|
||||
WithProps.Update.byId tableName docId document (Sql.existingConnection conn)
|
||||
|
||||
/// Update an entire document by its ID, using the provided function to obtain the ID from the document
|
||||
[<Extension>]
|
||||
static member inline UpdateByFunc(conn, tableName, idFunc: System.Func<'TDoc, 'TKey>, document: 'TDoc) =
|
||||
WithProps.Update.ByFunc(tableName, idFunc, document, Sql.existingConnection conn)
|
||||
|
||||
/// Patch a document by its ID
|
||||
[<Extension>]
|
||||
static member inline PatchById(conn, tableName, docId: 'TKey, patch: 'TPatch) =
|
||||
WithProps.Patch.byId tableName docId patch (Sql.existingConnection conn)
|
||||
|
||||
/// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
|
||||
[<Extension>]
|
||||
static member inline PatchByField(conn, tableName, fieldName, op, value: obj, patch: 'TPatch) =
|
||||
WithProps.Patch.byField tableName fieldName op value patch (Sql.existingConnection conn)
|
||||
|
||||
/// Patch documents using a JSON containment query in the WHERE clause (@>)
|
||||
[<Extension>]
|
||||
static member inline PatchByContains(conn, tableName, criteria: 'TCriteria, patch: 'TPatch) =
|
||||
WithProps.Patch.byContains tableName criteria patch (Sql.existingConnection conn)
|
||||
|
||||
/// Patch documents using a JSON Path match query in the WHERE clause (@?)
|
||||
[<Extension>]
|
||||
static member inline PatchByJsonPath(conn, tableName, jsonPath, patch: 'TPatch) =
|
||||
WithProps.Patch.byJsonPath tableName jsonPath patch (Sql.existingConnection conn)
|
||||
|
||||
/// Delete a document by its ID
|
||||
[<Extension>]
|
||||
static member inline DeleteById(conn, tableName, docId: 'TKey) =
|
||||
WithProps.Delete.byId tableName docId (Sql.existingConnection conn)
|
||||
|
||||
/// Delete documents by matching a JSON field comparison query (->> =)
|
||||
[<Extension>]
|
||||
static member inline DeleteByField(conn, tableName, fieldName, op, value: obj) =
|
||||
WithProps.Delete.byField tableName fieldName op value (Sql.existingConnection conn)
|
||||
|
||||
/// Delete documents by matching a JSON containment query (@>)
|
||||
[<Extension>]
|
||||
static member inline DeleteByContains(conn, tableName, criteria: 'TContains) =
|
||||
WithProps.Delete.byContains tableName criteria (Sql.existingConnection conn)
|
||||
|
||||
/// Delete documents by matching a JSON Path match query (@?)
|
||||
[<Extension>]
|
||||
static member inline DeleteByJsonPath(conn, tableName, path) =
|
||||
WithProps.Delete.byJsonPath tableName path (Sql.existingConnection conn)
|
||||
770
src/Postgres/Library.fs
Normal file
770
src/Postgres/Library.fs
Normal file
@@ -0,0 +1,770 @@
|
||||
namespace BitBadger.Documents.Postgres
|
||||
|
||||
/// The type of index to generate for the document
|
||||
[<Struct>]
|
||||
type DocumentIndex =
|
||||
/// A GIN index with standard operations (all operators supported)
|
||||
| Full
|
||||
/// A GIN index with JSONPath operations (optimized for @>, @?, @@ operators)
|
||||
| Optimized
|
||||
|
||||
|
||||
open Npgsql
|
||||
|
||||
/// Configuration for document handling
|
||||
module Configuration =
|
||||
|
||||
/// The data source to use for query execution
|
||||
let mutable private dataSourceValue : NpgsqlDataSource option = None
|
||||
|
||||
/// Register a data source to use for query execution (disposes the current one if it exists)
|
||||
[<CompiledName "UseDataSource">]
|
||||
let useDataSource source =
|
||||
if Option.isSome dataSourceValue then dataSourceValue.Value.Dispose()
|
||||
dataSourceValue <- Some source
|
||||
|
||||
/// Retrieve the currently configured data source
|
||||
[<CompiledName "DataSource">]
|
||||
let dataSource () =
|
||||
match dataSourceValue with
|
||||
| Some source -> source
|
||||
| None -> invalidOp "Please provide a data source before attempting data access"
|
||||
|
||||
|
||||
open Npgsql.FSharp
|
||||
|
||||
/// Helper functions
|
||||
[<AutoOpen>]
|
||||
module private Helpers =
|
||||
/// Shorthand to retrieve the data source as SqlProps
|
||||
let internal fromDataSource () =
|
||||
Configuration.dataSource () |> Sql.fromDataSource
|
||||
|
||||
/// Execute a task and ignore the result
|
||||
let internal ignoreTask<'T> (it : System.Threading.Tasks.Task<'T>) = backgroundTask {
|
||||
let! _ = it
|
||||
()
|
||||
}
|
||||
|
||||
|
||||
open BitBadger.Documents
|
||||
|
||||
/// Functions for creating parameters
|
||||
[<AutoOpen>]
|
||||
module Parameters =
|
||||
|
||||
/// Create an ID parameter (name "@id", key will be treated as a string)
|
||||
[<CompiledName "Id">]
|
||||
let idParam (key: 'TKey) =
|
||||
"@id", Sql.string (string key)
|
||||
|
||||
/// Create a parameter with a JSON value
|
||||
[<CompiledName "Json">]
|
||||
let jsonParam (name: string) (it: 'TJson) =
|
||||
name, Sql.jsonb (Configuration.serializer().Serialize it)
|
||||
|
||||
/// Create a JSON field parameter (name "@field")
|
||||
[<CompiledName "Field">]
|
||||
let fieldParam (value: obj) =
|
||||
"@field", Sql.parameter (NpgsqlParameter("@field", value))
|
||||
|
||||
/// An empty parameter sequence
|
||||
[<CompiledName "None">]
|
||||
let noParams =
|
||||
Seq.empty<string * SqlValue>
|
||||
|
||||
|
||||
/// Query construction functions
|
||||
[<RequireQualifiedAccess>]
|
||||
module Query =
|
||||
|
||||
/// Table and index definition queries
|
||||
module Definition =
|
||||
|
||||
/// SQL statement to create a document table
|
||||
[<CompiledName "EnsureTable">]
|
||||
let ensureTable name =
|
||||
Query.Definition.ensureTableFor name "JSONB"
|
||||
|
||||
/// SQL statement to create an index on JSON documents in the specified table
|
||||
[<CompiledName "EnsureDocumentIndex">]
|
||||
let ensureDocumentIndex (name: string) idxType =
|
||||
let extraOps = match idxType with Full -> "" | Optimized -> " jsonb_path_ops"
|
||||
let tableName = name.Split '.' |> Array.last
|
||||
$"CREATE INDEX IF NOT EXISTS idx_{tableName}_document ON {name} USING GIN (data{extraOps})"
|
||||
|
||||
/// Create a WHERE clause fragment to implement a @> (JSON contains) condition
|
||||
[<CompiledName "WhereDataContains">]
|
||||
let whereDataContains paramName =
|
||||
$"data @> %s{paramName}"
|
||||
|
||||
/// Create a WHERE clause fragment to implement a @? (JSON Path match) condition
|
||||
[<CompiledName "WhereJsonPathMatches">]
|
||||
let whereJsonPathMatches paramName =
|
||||
$"data @? %s{paramName}::jsonpath"
|
||||
|
||||
/// Queries for counting documents
|
||||
module Count =
|
||||
|
||||
/// Query to count matching documents using a JSON containment query (@>)
|
||||
[<CompiledName "ByContains">]
|
||||
let byContains tableName =
|
||||
$"""SELECT COUNT(*) AS it FROM %s{tableName} WHERE {whereDataContains "@criteria"}"""
|
||||
|
||||
/// Query to count matching documents using a JSON Path match (@?)
|
||||
[<CompiledName "ByJsonPath">]
|
||||
let byJsonPath tableName =
|
||||
$"""SELECT COUNT(*) AS it FROM %s{tableName} WHERE {whereJsonPathMatches "@path"}"""
|
||||
|
||||
/// Queries for determining document existence
|
||||
module Exists =
|
||||
|
||||
/// Query to determine if documents exist using a JSON containment query (@>)
|
||||
[<CompiledName "ByContains">]
|
||||
let byContains tableName =
|
||||
$"""SELECT EXISTS (SELECT 1 FROM %s{tableName} WHERE {whereDataContains "@criteria"}) AS it"""
|
||||
|
||||
/// Query to determine if documents exist using a JSON Path match (@?)
|
||||
[<CompiledName "ByJsonPath">]
|
||||
let byJsonPath tableName =
|
||||
$"""SELECT EXISTS (SELECT 1 FROM %s{tableName} WHERE {whereJsonPathMatches "@path"}) AS it"""
|
||||
|
||||
/// Queries for retrieving documents
|
||||
module Find =
|
||||
|
||||
/// Query to retrieve documents using a JSON containment query (@>)
|
||||
[<CompiledName "ByContains">]
|
||||
let byContains tableName =
|
||||
$"""{Query.selectFromTable tableName} WHERE {whereDataContains "@criteria"}"""
|
||||
|
||||
/// Query to retrieve documents using a JSON Path match (@?)
|
||||
[<CompiledName "ByJsonPath">]
|
||||
let byJsonPath tableName =
|
||||
$"""{Query.selectFromTable tableName} WHERE {whereJsonPathMatches "@path"}"""
|
||||
|
||||
/// Queries to patch (partially update) documents
|
||||
module Patch =
|
||||
|
||||
/// Query to patch a document by its ID
|
||||
[<CompiledName "ById">]
|
||||
let byId tableName =
|
||||
$"""UPDATE %s{tableName} SET data = data || @data WHERE {Query.whereById "@id"}"""
|
||||
|
||||
/// Query to patch documents match a JSON field comparison (->> =)
|
||||
[<CompiledName "ByField">]
|
||||
let byField tableName fieldName op =
|
||||
$"""UPDATE %s{tableName} SET data = data || @data WHERE {Query.whereByField fieldName op "@field"}"""
|
||||
|
||||
/// Query to patch documents matching a JSON containment query (@>)
|
||||
[<CompiledName "ByContains">]
|
||||
let byContains tableName =
|
||||
$"""UPDATE %s{tableName} SET data = data || @data WHERE {whereDataContains "@criteria"}"""
|
||||
|
||||
/// Query to patch documents matching a JSON containment query (@>)
|
||||
[<CompiledName "ByJsonPath">]
|
||||
let byJsonPath tableName =
|
||||
$"""UPDATE %s{tableName} SET data = data || @data WHERE {whereJsonPathMatches "@path"}"""
|
||||
|
||||
/// Queries to delete documents
|
||||
module Delete =
|
||||
|
||||
/// Query to delete documents using a JSON containment query (@>)
|
||||
[<CompiledName "ByContains">]
|
||||
let byContains tableName =
|
||||
$"""DELETE FROM %s{tableName} WHERE {whereDataContains "@criteria"}"""
|
||||
|
||||
/// Query to delete documents using a JSON Path match (@?)
|
||||
[<CompiledName "ByJsonPath">]
|
||||
let byJsonPath tableName =
|
||||
$"""DELETE FROM %s{tableName} WHERE {whereJsonPathMatches "@path"}"""
|
||||
|
||||
|
||||
/// Functions for dealing with results
|
||||
[<AutoOpen>]
|
||||
module Results =
|
||||
|
||||
/// Create a domain item from a document, specifying the field in which the document is found
|
||||
[<CompiledName "FromDocument">]
|
||||
let fromDocument<'T> field (row: RowReader) : 'T =
|
||||
Configuration.serializer().Deserialize<'T>(row.string field)
|
||||
|
||||
/// Create a domain item from a document
|
||||
[<CompiledName "FromData">]
|
||||
let fromData<'T> row : 'T =
|
||||
fromDocument "data" row
|
||||
|
||||
/// Extract a count from the column "it"
|
||||
[<CompiledName "ToCount">]
|
||||
let toCount (row: RowReader) =
|
||||
row.int "it"
|
||||
|
||||
/// Extract a true/false value from the column "it"
|
||||
[<CompiledName "ToExists">]
|
||||
let toExists (row: RowReader) =
|
||||
row.bool "it"
|
||||
|
||||
|
||||
/// Versions of queries that accept SqlProps as the last parameter
|
||||
module WithProps =
|
||||
|
||||
/// Commands to execute custom SQL queries
|
||||
[<RequireQualifiedAccess>]
|
||||
module Custom =
|
||||
|
||||
/// Execute a query that returns a list of results
|
||||
[<CompiledName "FSharpList">]
|
||||
let list<'TDoc> query parameters (mapFunc: RowReader -> 'TDoc) sqlProps =
|
||||
Sql.query query sqlProps
|
||||
|> Sql.parameters parameters
|
||||
|> Sql.executeAsync mapFunc
|
||||
|
||||
/// Execute a query that returns a list of results
|
||||
let List<'TDoc>(query, parameters, mapFunc: System.Func<RowReader, 'TDoc>, sqlProps) = backgroundTask {
|
||||
let! results = list<'TDoc> query (List.ofSeq parameters) mapFunc.Invoke sqlProps
|
||||
return ResizeArray results
|
||||
}
|
||||
|
||||
/// Execute a query that returns one or no results; returns None if not found
|
||||
[<CompiledName "FSharpSingle">]
|
||||
let single<'TDoc> query parameters mapFunc sqlProps = backgroundTask {
|
||||
let! results = list<'TDoc> query parameters mapFunc sqlProps
|
||||
return FSharp.Collections.List.tryHead results
|
||||
}
|
||||
|
||||
/// Execute a query that returns one or no results; returns null if not found
|
||||
let Single<'TDoc when 'TDoc: null>(
|
||||
query, parameters, mapFunc: System.Func<RowReader, 'TDoc>, sqlProps) = backgroundTask {
|
||||
let! result = single<'TDoc> query (FSharp.Collections.List.ofSeq parameters) mapFunc.Invoke sqlProps
|
||||
return Option.toObj result
|
||||
}
|
||||
|
||||
/// Execute a query that returns no results
|
||||
[<CompiledName "NonQuery">]
|
||||
let nonQuery query parameters sqlProps =
|
||||
Sql.query query sqlProps
|
||||
|> Sql.parameters (FSharp.Collections.List.ofSeq parameters)
|
||||
|> Sql.executeNonQueryAsync
|
||||
|> ignoreTask
|
||||
|
||||
/// Execute a query that returns a scalar value
|
||||
[<CompiledName "FSharpScalar">]
|
||||
let scalar<'T when 'T: struct> query parameters (mapFunc: RowReader -> 'T) sqlProps =
|
||||
Sql.query query sqlProps
|
||||
|> Sql.parameters parameters
|
||||
|> Sql.executeRowAsync mapFunc
|
||||
|
||||
/// Execute a query that returns a scalar value
|
||||
let Scalar<'T when 'T: struct>(query, parameters, mapFunc: System.Func<RowReader, 'T>, sqlProps) =
|
||||
scalar<'T> query (FSharp.Collections.List.ofSeq parameters) mapFunc.Invoke sqlProps
|
||||
|
||||
/// Table and index definition commands
|
||||
module Definition =
|
||||
|
||||
/// Create a document table
|
||||
[<CompiledName "EnsureTable">]
|
||||
let ensureTable name sqlProps = backgroundTask {
|
||||
do! Custom.nonQuery (Query.Definition.ensureTable name) [] sqlProps
|
||||
do! Custom.nonQuery (Query.Definition.ensureKey name) [] sqlProps
|
||||
}
|
||||
|
||||
/// Create an index on documents in the specified table
|
||||
[<CompiledName "EnsureDocumentIndex">]
|
||||
let ensureDocumentIndex name idxType sqlProps =
|
||||
Custom.nonQuery (Query.Definition.ensureDocumentIndex name idxType) [] sqlProps
|
||||
|
||||
/// Create an index on field(s) within documents in the specified table
|
||||
[<CompiledName "EnsureFieldIndex">]
|
||||
let ensureFieldIndex tableName indexName fields sqlProps =
|
||||
Custom.nonQuery (Query.Definition.ensureIndexOn tableName indexName fields) [] sqlProps
|
||||
|
||||
/// Commands to add documents
|
||||
[<AutoOpen>]
|
||||
module Document =
|
||||
|
||||
/// Insert a new document
|
||||
[<CompiledName "Insert">]
|
||||
let insert<'TDoc> tableName (document: 'TDoc) sqlProps =
|
||||
Custom.nonQuery (Query.insert tableName) [ jsonParam "@data" document ] sqlProps
|
||||
|
||||
/// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
|
||||
[<CompiledName "Save">]
|
||||
let save<'TDoc> tableName (document: 'TDoc) sqlProps =
|
||||
Custom.nonQuery (Query.save tableName) [ jsonParam "@data" document ] sqlProps
|
||||
|
||||
/// Commands to count documents
|
||||
[<RequireQualifiedAccess>]
|
||||
module Count =
|
||||
|
||||
/// Count all documents in a table
|
||||
[<CompiledName "All">]
|
||||
let all tableName sqlProps =
|
||||
Custom.scalar (Query.Count.all tableName) [] toCount sqlProps
|
||||
|
||||
/// Count matching documents using a JSON field comparison (->> =)
|
||||
[<CompiledName "ByField">]
|
||||
let byField tableName fieldName op (value: obj) sqlProps =
|
||||
Custom.scalar (Query.Count.byField tableName fieldName op) [ fieldParam value ] toCount sqlProps
|
||||
|
||||
/// Count matching documents using a JSON containment query (@>)
|
||||
[<CompiledName "ByContains">]
|
||||
let byContains tableName (criteria: 'TContains) sqlProps =
|
||||
Custom.scalar (Query.Count.byContains tableName) [ jsonParam "@criteria" criteria ] toCount sqlProps
|
||||
|
||||
/// Count matching documents using a JSON Path match query (@?)
|
||||
[<CompiledName "ByJsonPath">]
|
||||
let byJsonPath tableName jsonPath sqlProps =
|
||||
Custom.scalar (Query.Count.byJsonPath tableName) [ "@path", Sql.string jsonPath ] toCount sqlProps
|
||||
|
||||
/// Commands to determine if documents exist
|
||||
[<RequireQualifiedAccess>]
|
||||
module Exists =
|
||||
|
||||
/// Determine if a document exists for the given ID
|
||||
[<CompiledName "ById">]
|
||||
let byId tableName (docId: 'TKey) sqlProps =
|
||||
Custom.scalar (Query.Exists.byId tableName) [ idParam docId ] toExists sqlProps
|
||||
|
||||
/// Determine if a document exists using a JSON field comparison (->> =)
|
||||
[<CompiledName "ByField">]
|
||||
let byField tableName fieldName op (value: obj) sqlProps =
|
||||
Custom.scalar (Query.Exists.byField tableName fieldName op) [ fieldParam value ] toExists sqlProps
|
||||
|
||||
/// Determine if a document exists using a JSON containment query (@>)
|
||||
[<CompiledName "ByContains">]
|
||||
let byContains tableName (criteria: 'TContains) sqlProps =
|
||||
Custom.scalar (Query.Exists.byContains tableName) [ jsonParam "@criteria" criteria ] toExists sqlProps
|
||||
|
||||
/// Determine if a document exists using a JSON Path match query (@?)
|
||||
[<CompiledName "ByJsonPath">]
|
||||
let byJsonPath tableName jsonPath sqlProps =
|
||||
Custom.scalar (Query.Exists.byJsonPath tableName) [ "@path", Sql.string jsonPath ] toExists sqlProps
|
||||
|
||||
/// Commands to determine if documents exist
|
||||
[<RequireQualifiedAccess>]
|
||||
module Find =
|
||||
|
||||
/// Retrieve all documents in the given table
|
||||
[<CompiledName "FSharpAll">]
|
||||
let all<'TDoc> tableName sqlProps =
|
||||
Custom.list<'TDoc> (Query.selectFromTable tableName) [] fromData<'TDoc> sqlProps
|
||||
|
||||
/// Retrieve all documents in the given table
|
||||
let All<'TDoc>(tableName, sqlProps) =
|
||||
Custom.List<'TDoc>(Query.selectFromTable tableName, [], fromData<'TDoc>, sqlProps)
|
||||
|
||||
/// Retrieve a document by its ID (returns None if not found)
|
||||
[<CompiledName "FSharpById">]
|
||||
let byId<'TKey, 'TDoc> tableName (docId: 'TKey) sqlProps =
|
||||
Custom.single (Query.Find.byId tableName) [ idParam docId ] fromData<'TDoc> sqlProps
|
||||
|
||||
/// Retrieve a document by its ID (returns null if not found)
|
||||
let ById<'TKey, 'TDoc when 'TDoc: null>(tableName, docId: 'TKey, sqlProps) =
|
||||
Custom.Single<'TDoc>(Query.Find.byId tableName, [ idParam docId ], fromData<'TDoc>, sqlProps)
|
||||
|
||||
/// Retrieve documents matching a JSON field comparison (->> =)
|
||||
[<CompiledName "FSharpByField">]
|
||||
let byField<'TDoc> tableName fieldName op (value: obj) sqlProps =
|
||||
Custom.list<'TDoc> (Query.Find.byField tableName fieldName op) [ fieldParam value ] fromData<'TDoc> sqlProps
|
||||
|
||||
/// Retrieve documents matching a JSON field comparison (->> =)
|
||||
let ByField<'TDoc>(tableName, fieldName, op, value: obj, sqlProps) =
|
||||
Custom.List<'TDoc>(
|
||||
Query.Find.byField tableName fieldName op, [ fieldParam value ], fromData<'TDoc>, sqlProps)
|
||||
|
||||
/// Retrieve documents matching a JSON containment query (@>)
|
||||
[<CompiledName "FSharpByContains">]
|
||||
let byContains<'TDoc> tableName (criteria: obj) sqlProps =
|
||||
Custom.list<'TDoc>
|
||||
(Query.Find.byContains tableName) [ jsonParam "@criteria" criteria ] fromData<'TDoc> sqlProps
|
||||
|
||||
/// Retrieve documents matching a JSON containment query (@>)
|
||||
let ByContains<'TDoc>(tableName, criteria: obj, sqlProps) =
|
||||
Custom.List<'TDoc>(
|
||||
Query.Find.byContains tableName, [ jsonParam "@criteria" criteria ], fromData<'TDoc>, sqlProps)
|
||||
|
||||
/// Retrieve documents matching a JSON Path match query (@?)
|
||||
[<CompiledName "FSharpByJsonPath">]
|
||||
let byJsonPath<'TDoc> tableName jsonPath sqlProps =
|
||||
Custom.list<'TDoc>
|
||||
(Query.Find.byJsonPath tableName) [ "@path", Sql.string jsonPath ] fromData<'TDoc> sqlProps
|
||||
|
||||
/// Retrieve documents matching a JSON Path match query (@?)
|
||||
let ByJsonPath<'TDoc>(tableName, jsonPath, sqlProps) =
|
||||
Custom.List<'TDoc>(
|
||||
Query.Find.byJsonPath tableName, [ "@path", Sql.string jsonPath ], fromData<'TDoc>, sqlProps)
|
||||
|
||||
/// Retrieve the first document matching a JSON field comparison (->> =); returns None if not found
|
||||
[<CompiledName "FSharpFirstByField">]
|
||||
let firstByField<'TDoc> tableName fieldName op (value: obj) sqlProps =
|
||||
Custom.single<'TDoc>
|
||||
$"{Query.Find.byField tableName fieldName op} LIMIT 1" [ fieldParam value ] fromData<'TDoc> sqlProps
|
||||
|
||||
/// Retrieve the first document matching a JSON field comparison (->> =); returns null if not found
|
||||
let FirstByField<'TDoc when 'TDoc: null>(tableName, fieldName, op, value: obj, sqlProps) =
|
||||
Custom.Single<'TDoc>(
|
||||
$"{Query.Find.byField tableName fieldName op} LIMIT 1", [ fieldParam value ], fromData<'TDoc>, sqlProps)
|
||||
|
||||
/// Retrieve the first document matching a JSON containment query (@>); returns None if not found
|
||||
[<CompiledName "FSharpFirstByContains">]
|
||||
let firstByContains<'TDoc> tableName (criteria: obj) sqlProps =
|
||||
Custom.single<'TDoc>
|
||||
$"{Query.Find.byContains tableName} LIMIT 1" [ jsonParam "@criteria" criteria ] fromData<'TDoc> sqlProps
|
||||
|
||||
/// Retrieve the first document matching a JSON containment query (@>); returns null if not found
|
||||
let FirstByContains<'TDoc when 'TDoc: null>(tableName, criteria: obj, sqlProps) =
|
||||
Custom.Single<'TDoc>(
|
||||
$"{Query.Find.byContains tableName} LIMIT 1",
|
||||
[ jsonParam "@criteria" criteria ],
|
||||
fromData<'TDoc>,
|
||||
sqlProps)
|
||||
|
||||
/// Retrieve the first document matching a JSON Path match query (@?); returns None if not found
|
||||
[<CompiledName "FSharpFirstByJsonPath">]
|
||||
let firstByJsonPath<'TDoc> tableName jsonPath sqlProps =
|
||||
Custom.single<'TDoc>
|
||||
$"{Query.Find.byJsonPath tableName} LIMIT 1" [ "@path", Sql.string jsonPath ] fromData<'TDoc> sqlProps
|
||||
|
||||
/// Retrieve the first document matching a JSON Path match query (@?); returns null if not found
|
||||
let FirstByJsonPath<'TDoc when 'TDoc: null>(tableName, jsonPath, sqlProps) =
|
||||
Custom.Single<'TDoc>(
|
||||
$"{Query.Find.byJsonPath tableName} LIMIT 1",
|
||||
[ "@path", Sql.string jsonPath ],
|
||||
fromData<'TDoc>,
|
||||
sqlProps)
|
||||
|
||||
/// Commands to update documents
|
||||
[<RequireQualifiedAccess>]
|
||||
module Update =
|
||||
|
||||
/// Update an entire document by its ID
|
||||
[<CompiledName "ById">]
|
||||
let byId tableName (docId: 'TKey) (document: 'TDoc) sqlProps =
|
||||
Custom.nonQuery (Query.update tableName) [ idParam docId; jsonParam "@data" document ] sqlProps
|
||||
|
||||
/// Update an entire document by its ID, using the provided function to obtain the ID from the document
|
||||
[<CompiledName "FSharpByFunc">]
|
||||
let byFunc tableName (idFunc: 'TDoc -> 'TKey) (document: 'TDoc) sqlProps =
|
||||
byId tableName (idFunc document) document sqlProps
|
||||
|
||||
/// Update an entire document by its ID, using the provided function to obtain the ID from the document
|
||||
let ByFunc(tableName, idFunc: System.Func<'TDoc, 'TKey>, document: 'TDoc, sqlProps) =
|
||||
byFunc tableName idFunc.Invoke document sqlProps
|
||||
|
||||
/// Commands to patch (partially update) documents
|
||||
[<RequireQualifiedAccess>]
|
||||
module Patch =
|
||||
|
||||
/// Patch a document by its ID
|
||||
[<CompiledName "ById">]
|
||||
let byId tableName (docId: 'TKey) (patch: 'TPatch) sqlProps =
|
||||
Custom.nonQuery (Query.Patch.byId tableName) [ idParam docId; jsonParam "@data" patch ] sqlProps
|
||||
|
||||
/// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
|
||||
[<CompiledName "ByField">]
|
||||
let byField tableName fieldName op (value: obj) (patch: 'TPatch) sqlProps =
|
||||
Custom.nonQuery
|
||||
(Query.Patch.byField tableName fieldName op) [ jsonParam "@data" patch; fieldParam value ] sqlProps
|
||||
|
||||
/// Patch documents using a JSON containment query in the WHERE clause (@>)
|
||||
[<CompiledName "ByContains">]
|
||||
let byContains tableName (criteria: 'TContains) (patch: 'TPatch) sqlProps =
|
||||
Custom.nonQuery
|
||||
(Query.Patch.byContains tableName) [ jsonParam "@data" patch; jsonParam "@criteria" criteria ] sqlProps
|
||||
|
||||
/// Patch documents using a JSON Path match query in the WHERE clause (@?)
|
||||
[<CompiledName "ByJsonPath">]
|
||||
let byJsonPath tableName jsonPath (patch: 'TPatch) sqlProps =
|
||||
Custom.nonQuery
|
||||
(Query.Patch.byJsonPath tableName) [ jsonParam "@data" patch; "@path", Sql.string jsonPath ] sqlProps
|
||||
|
||||
/// Commands to delete documents
|
||||
[<RequireQualifiedAccess>]
|
||||
module Delete =
|
||||
|
||||
/// Delete a document by its ID
|
||||
[<CompiledName "ById">]
|
||||
let byId tableName (docId: 'TKey) sqlProps =
|
||||
Custom.nonQuery (Query.Delete.byId tableName) [ idParam docId ] sqlProps
|
||||
|
||||
/// Delete documents by matching a JSON field comparison query (->> =)
|
||||
[<CompiledName "ByField">]
|
||||
let byField tableName fieldName op (value: obj) sqlProps =
|
||||
Custom.nonQuery (Query.Delete.byField tableName fieldName op) [ fieldParam value ] sqlProps
|
||||
|
||||
/// Delete documents by matching a JSON contains query (@>)
|
||||
[<CompiledName "ByContains">]
|
||||
let byContains tableName (criteria: 'TCriteria) sqlProps =
|
||||
Custom.nonQuery (Query.Delete.byContains tableName) [ jsonParam "@criteria" criteria ] sqlProps
|
||||
|
||||
/// Delete documents by matching a JSON Path match query (@?)
|
||||
[<CompiledName "ByJsonPath">]
|
||||
let byJsonPath tableName path sqlProps =
|
||||
Custom.nonQuery (Query.Delete.byJsonPath tableName) [ "@path", Sql.string path ] sqlProps
|
||||
|
||||
|
||||
/// Commands to execute custom SQL queries
|
||||
[<RequireQualifiedAccess>]
|
||||
module Custom =
|
||||
|
||||
/// Execute a query that returns a list of results
|
||||
[<CompiledName "FSharpList">]
|
||||
let list<'TDoc> query parameters (mapFunc: RowReader -> 'TDoc) =
|
||||
WithProps.Custom.list<'TDoc> query parameters mapFunc (fromDataSource ())
|
||||
|
||||
/// Execute a query that returns a list of results
|
||||
let List<'TDoc>(query, parameters, mapFunc: System.Func<RowReader, 'TDoc>) =
|
||||
WithProps.Custom.List<'TDoc>(query, parameters, mapFunc, fromDataSource ())
|
||||
|
||||
/// Execute a query that returns one or no results; returns None if not found
|
||||
[<CompiledName "FSharpSingle">]
|
||||
let single<'TDoc> query parameters (mapFunc: RowReader -> 'TDoc) =
|
||||
WithProps.Custom.single<'TDoc> query parameters mapFunc (fromDataSource ())
|
||||
|
||||
/// Execute a query that returns one or no results; returns null if not found
|
||||
let Single<'TDoc when 'TDoc: null>(query, parameters, mapFunc: System.Func<RowReader, 'TDoc>) =
|
||||
WithProps.Custom.Single<'TDoc>(query, parameters, mapFunc, fromDataSource ())
|
||||
|
||||
/// Execute a query that returns no results
|
||||
[<CompiledName "NonQuery">]
|
||||
let nonQuery query parameters =
|
||||
WithProps.Custom.nonQuery query parameters (fromDataSource ())
|
||||
|
||||
/// Execute a query that returns a scalar value
|
||||
[<CompiledName "FSharpScalar">]
|
||||
let scalar<'T when 'T: struct> query parameters (mapFunc: RowReader -> 'T) =
|
||||
WithProps.Custom.scalar query parameters mapFunc (fromDataSource ())
|
||||
|
||||
/// Execute a query that returns a scalar value
|
||||
let Scalar<'T when 'T: struct>(query, parameters, mapFunc: System.Func<RowReader, 'T>) =
|
||||
WithProps.Custom.Scalar<'T>(query, parameters, mapFunc, fromDataSource ())
|
||||
|
||||
|
||||
/// Table and index definition commands
|
||||
[<RequireQualifiedAccess>]
|
||||
module Definition =
|
||||
|
||||
/// Create a document table
|
||||
[<CompiledName "EnsureTable">]
|
||||
let ensureTable name =
|
||||
WithProps.Definition.ensureTable name (fromDataSource ())
|
||||
|
||||
/// Create an index on documents in the specified table
|
||||
[<CompiledName "EnsureDocumentIndex">]
|
||||
let ensureDocumentIndex name idxType =
|
||||
WithProps.Definition.ensureDocumentIndex name idxType (fromDataSource ())
|
||||
|
||||
/// Create an index on field(s) within documents in the specified table
|
||||
[<CompiledName "EnsureFieldIndex">]
|
||||
let ensureFieldIndex tableName indexName fields =
|
||||
WithProps.Definition.ensureFieldIndex tableName indexName fields (fromDataSource ())
|
||||
|
||||
|
||||
/// Document writing functions
|
||||
[<AutoOpen>]
|
||||
module Document =
|
||||
|
||||
/// Insert a new document
|
||||
[<CompiledName "Insert">]
|
||||
let insert<'TDoc> tableName (document: 'TDoc) =
|
||||
WithProps.Document.insert<'TDoc> tableName document (fromDataSource ())
|
||||
|
||||
/// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
|
||||
[<CompiledName "Save">]
|
||||
let save<'TDoc> tableName (document: 'TDoc) =
|
||||
WithProps.Document.save<'TDoc> tableName document (fromDataSource ())
|
||||
|
||||
|
||||
/// Queries to count documents
|
||||
[<RequireQualifiedAccess>]
|
||||
module Count =
|
||||
|
||||
/// Count all documents in a table
|
||||
[<CompiledName "All">]
|
||||
let all tableName =
|
||||
WithProps.Count.all tableName (fromDataSource ())
|
||||
|
||||
/// Count matching documents using a JSON field comparison query (->> =)
|
||||
[<CompiledName "ByField">]
|
||||
let byField tableName fieldName op (value: obj) =
|
||||
WithProps.Count.byField tableName fieldName op value (fromDataSource ())
|
||||
|
||||
/// Count matching documents using a JSON containment query (@>)
|
||||
[<CompiledName "ByContains">]
|
||||
let byContains tableName criteria =
|
||||
WithProps.Count.byContains tableName criteria (fromDataSource ())
|
||||
|
||||
/// Count matching documents using a JSON Path match query (@?)
|
||||
[<CompiledName "ByJsonPath">]
|
||||
let byJsonPath tableName jsonPath =
|
||||
WithProps.Count.byJsonPath tableName jsonPath (fromDataSource ())
|
||||
|
||||
|
||||
/// Queries to determine if documents exist
|
||||
[<RequireQualifiedAccess>]
|
||||
module Exists =
|
||||
|
||||
/// Determine if a document exists for the given ID
|
||||
[<CompiledName "ById">]
|
||||
let byId tableName docId =
|
||||
WithProps.Exists.byId tableName docId (fromDataSource ())
|
||||
|
||||
/// Determine if documents exist using a JSON field comparison query (->> =)
|
||||
[<CompiledName "ByField">]
|
||||
let byField tableName fieldName op (value: obj) =
|
||||
WithProps.Exists.byField tableName fieldName op value (fromDataSource ())
|
||||
|
||||
/// Determine if documents exist using a JSON containment query (@>)
|
||||
[<CompiledName "ByContains">]
|
||||
let byContains tableName criteria =
|
||||
WithProps.Exists.byContains tableName criteria (fromDataSource ())
|
||||
|
||||
/// Determine if documents exist using a JSON Path match query (@?)
|
||||
[<CompiledName "ByJsonPath">]
|
||||
let byJsonPath tableName jsonPath =
|
||||
WithProps.Exists.byJsonPath tableName jsonPath (fromDataSource ())
|
||||
|
||||
|
||||
/// Commands to retrieve documents
|
||||
[<RequireQualifiedAccess>]
|
||||
module Find =
|
||||
|
||||
/// Retrieve all documents in the given table
|
||||
[<CompiledName "FSharpAll">]
|
||||
let all<'TDoc> tableName =
|
||||
WithProps.Find.all<'TDoc> tableName (fromDataSource ())
|
||||
|
||||
/// Retrieve all documents in the given table
|
||||
let All<'TDoc> tableName =
|
||||
WithProps.Find.All<'TDoc>(tableName, fromDataSource ())
|
||||
|
||||
/// Retrieve a document by its ID; returns None if not found
|
||||
[<CompiledName "FSharpById">]
|
||||
let byId<'TKey, 'TDoc> tableName docId =
|
||||
WithProps.Find.byId<'TKey, 'TDoc> tableName docId (fromDataSource ())
|
||||
|
||||
/// Retrieve a document by its ID; returns null if not found
|
||||
let ById<'TKey, 'TDoc when 'TDoc: null>(tableName, docId: 'TKey) =
|
||||
WithProps.Find.ById<'TKey, 'TDoc>(tableName, docId, fromDataSource ())
|
||||
|
||||
/// Retrieve documents matching a JSON field comparison query (->> =)
|
||||
[<CompiledName "FSharpByField">]
|
||||
let byField<'TDoc> tableName fieldName op (value: obj) =
|
||||
WithProps.Find.byField<'TDoc> tableName fieldName op value (fromDataSource ())
|
||||
|
||||
/// Retrieve documents matching a JSON field comparison query (->> =)
|
||||
let ByField<'TDoc>(tableName, fieldName, op, value: obj) =
|
||||
WithProps.Find.ByField<'TDoc>(tableName, fieldName, op, value, fromDataSource ())
|
||||
|
||||
/// Retrieve documents matching a JSON containment query (@>)
|
||||
[<CompiledName "FSharpByContains">]
|
||||
let byContains<'TDoc> tableName (criteria: obj) =
|
||||
WithProps.Find.byContains<'TDoc> tableName criteria (fromDataSource ())
|
||||
|
||||
/// Retrieve documents matching a JSON containment query (@>)
|
||||
let ByContains<'TDoc>(tableName, criteria: obj) =
|
||||
WithProps.Find.ByContains<'TDoc>(tableName, criteria, fromDataSource ())
|
||||
|
||||
/// Retrieve documents matching a JSON Path match query (@?)
|
||||
[<CompiledName "FSharpByJsonPath">]
|
||||
let byJsonPath<'TDoc> tableName jsonPath =
|
||||
WithProps.Find.byJsonPath<'TDoc> tableName jsonPath (fromDataSource ())
|
||||
|
||||
/// Retrieve documents matching a JSON Path match query (@?)
|
||||
let ByJsonPath<'TDoc>(tableName, jsonPath) =
|
||||
WithProps.Find.ByJsonPath<'TDoc>(tableName, jsonPath, fromDataSource ())
|
||||
|
||||
/// Retrieve the first document matching a JSON field comparison query (->> =); returns None if not found
|
||||
[<CompiledName "FSharpFirstByField">]
|
||||
let firstByField<'TDoc> tableName fieldName op (value: obj) =
|
||||
WithProps.Find.firstByField<'TDoc> tableName fieldName op value (fromDataSource ())
|
||||
|
||||
/// Retrieve the first document matching a JSON field comparison query (->> =); returns null if not found
|
||||
let FirstByField<'TDoc when 'TDoc: null>(tableName, fieldName, op, value: obj) =
|
||||
WithProps.Find.FirstByField<'TDoc>(tableName, fieldName, op, value, fromDataSource ())
|
||||
|
||||
/// Retrieve the first document matching a JSON containment query (@>); returns None if not found
|
||||
[<CompiledName "FSharpFirstByContains">]
|
||||
let firstByContains<'TDoc> tableName (criteria: obj) =
|
||||
WithProps.Find.firstByContains<'TDoc> tableName criteria (fromDataSource ())
|
||||
|
||||
/// Retrieve the first document matching a JSON containment query (@>); returns null if not found
|
||||
let FirstByContains<'TDoc when 'TDoc: null>(tableName, criteria: obj) =
|
||||
WithProps.Find.FirstByContains<'TDoc>(tableName, criteria, fromDataSource ())
|
||||
|
||||
/// Retrieve the first document matching a JSON Path match query (@?); returns None if not found
|
||||
[<CompiledName "FSharpFirstByJsonPath">]
|
||||
let firstByJsonPath<'TDoc> tableName jsonPath =
|
||||
WithProps.Find.firstByJsonPath<'TDoc> tableName jsonPath (fromDataSource ())
|
||||
|
||||
/// Retrieve the first document matching a JSON Path match query (@?); returns null if not found
|
||||
let FirstByJsonPath<'TDoc when 'TDoc: null>(tableName, jsonPath) =
|
||||
WithProps.Find.FirstByJsonPath<'TDoc>(tableName, jsonPath, fromDataSource ())
|
||||
|
||||
|
||||
/// Commands to update documents
|
||||
[<RequireQualifiedAccess>]
|
||||
module Update =
|
||||
|
||||
/// Update an entire document by its ID
|
||||
[<CompiledName "ById">]
|
||||
let byId tableName (docId: 'TKey) (document: 'TDoc) =
|
||||
WithProps.Update.byId tableName docId document (fromDataSource ())
|
||||
|
||||
/// Update an entire document by its ID, using the provided function to obtain the ID from the document
|
||||
[<CompiledName "FSharpFullFunc">]
|
||||
let byFunc tableName (idFunc: 'TDoc -> 'TKey) (document: 'TDoc) =
|
||||
WithProps.Update.byFunc tableName idFunc document (fromDataSource ())
|
||||
|
||||
/// Update an entire document by its ID, using the provided function to obtain the ID from the document
|
||||
let ByFunc(tableName, idFunc: System.Func<'TDoc, 'TKey>, document: 'TDoc) =
|
||||
WithProps.Update.ByFunc(tableName, idFunc, document, fromDataSource ())
|
||||
|
||||
|
||||
/// Commands to patch (partially update) documents
|
||||
[<RequireQualifiedAccess>]
|
||||
module Patch =
|
||||
|
||||
/// Patch a document by its ID
|
||||
[<CompiledName "ById">]
|
||||
let byId tableName (docId: 'TKey) (patch: 'TPatch) =
|
||||
WithProps.Patch.byId tableName docId patch (fromDataSource ())
|
||||
|
||||
/// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
|
||||
[<CompiledName "ByField">]
|
||||
let byField tableName fieldName op (value: obj) (patch: 'TPatch) =
|
||||
WithProps.Patch.byField tableName fieldName op value patch (fromDataSource ())
|
||||
|
||||
/// Patch documents using a JSON containment query in the WHERE clause (@>)
|
||||
[<CompiledName "ByContains">]
|
||||
let byContains tableName (criteria: 'TCriteria) (patch: 'TPatch) =
|
||||
WithProps.Patch.byContains tableName criteria patch (fromDataSource ())
|
||||
|
||||
/// Patch documents using a JSON Path match query in the WHERE clause (@?)
|
||||
[<CompiledName "ByJsonPath">]
|
||||
let byJsonPath tableName jsonPath (patch: 'TPatch) =
|
||||
WithProps.Patch.byJsonPath tableName jsonPath patch (fromDataSource ())
|
||||
|
||||
|
||||
/// Commands to delete documents
|
||||
[<RequireQualifiedAccess>]
|
||||
module Delete =
|
||||
|
||||
/// Delete a document by its ID
|
||||
[<CompiledName "ById">]
|
||||
let byId tableName (docId: 'TKey) =
|
||||
WithProps.Delete.byId tableName docId (fromDataSource ())
|
||||
|
||||
/// Delete documents by matching a JSON field comparison query (->> =)
|
||||
[<CompiledName "ByField">]
|
||||
let byField tableName fieldName op (value: obj) =
|
||||
WithProps.Delete.byField tableName fieldName op value (fromDataSource ())
|
||||
|
||||
/// Delete documents by matching a JSON containment query (@>)
|
||||
[<CompiledName "ByContains">]
|
||||
let byContains tableName (criteria: 'TContains) =
|
||||
WithProps.Delete.byContains tableName criteria (fromDataSource ())
|
||||
|
||||
/// Delete documents by matching a JSON Path match query (@?)
|
||||
[<CompiledName "ByJsonPath">]
|
||||
let byJsonPath tableName path =
|
||||
WithProps.Delete.byJsonPath tableName path (fromDataSource ())
|
||||
101
src/Postgres/README.md
Normal file
101
src/Postgres/README.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# BitBadger.Documents.Postgres
|
||||
|
||||
This package provides a lightweight document library backed by [PostgreSQL](https://www.postgresql.org). 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:
|
||||
|
||||
```csharp
|
||||
// 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);
|
||||
```
|
||||
|
||||
```fsharp
|
||||
// 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:
|
||||
|
||||
```csharp
|
||||
// C#; parameter is table name
|
||||
// Find.All type signature is Func<string, Task<List<TDoc>>>
|
||||
var customers = await Find.All("customer");
|
||||
```
|
||||
|
||||
```fsharp
|
||||
// F#
|
||||
// Find.all type signature is string -> Task<'TDoc list>
|
||||
let! customers = Find.all<Customer> "customer"
|
||||
```
|
||||
|
||||
Select a customer by ID:
|
||||
|
||||
```csharp
|
||||
// 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");
|
||||
```
|
||||
```fsharp
|
||||
// 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):
|
||||
|
||||
```csharp
|
||||
// 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" });
|
||||
```
|
||||
|
||||
```fsharp
|
||||
// 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...)_
|
||||
|
||||
```csharp
|
||||
// C#; parameters are table name and JSON Path expression
|
||||
// Delete.ByJsonPath type signature is Func<string, string, Task>
|
||||
await Delete.ByJsonPath("customer", "$.City ? (@ == \"Chicago\")");
|
||||
```
|
||||
|
||||
```fsharp
|
||||
// F#
|
||||
// Delete.byJsonPath type signature is string -> string -> Task<unit>
|
||||
do! Delete.byJsonPath "customer" """$.City ? (@ == "Chicago")"""
|
||||
```
|
||||
|
||||
## More Information
|
||||
|
||||
The [project site](https://bitbadger.solutions/open-source/relational-documents/) has full details on how to use this library.
|
||||
Reference in New Issue
Block a user