README.md

FSharp.CosmosDb 🌍

This project is a wrapper around the Cosmos DB v4 .NET SDK to make it a bit more friendly to the F# language.

Install

Install via NuGet:

dotnet add package FSharp.CosmosDb

Or using Paket:

dotnet paket add FSharp.CosmosDb

Usage

All operations will return an AsyncSeq via FSharp.Control.AsyncSeq that contains the data fetched, data inserted or data updated.

Insert

open FSharp.CosmosDb

let connStr = "..."

let insertUsers data =
    connStr
    |> Cosmos.fromConnectionString
    |> Cosmos.database "UserDb"
    |> Cosmos.container "UserContainer"
    |> Cosmos.insertMany<User> data
    |> Cosmos.execAsync

Upsert

open FSharp.CosmosDb

let connStr = "..."

let insertUsers data =
    connStr
    |> Cosmos.fromConnectionString
    |> Cosmos.database "UserDb"
    |> Cosmos.container "UserContainer"
    |> Cosmos.upsertMany<User> data
    |> Cosmos.execAsync

Update

open FSharp.CosmosDb

let connStr = "..."

let updateUser id partitionKey =
    connStr
    |> Cosmos.fromConnectionString
    |> Cosmos.database "UserDb"
    |> Cosmos.container "UserContainer"
    |> Cosmos.update<User> id partitionKey (fun user -> { user with IsRegistered = true })
    |> Cosmos.execAsync

Query

open FSharp.CosmosDb

let host = "https://..."
let key = "..."
let findUsers() =
    host
    |> Cosmos.host
    |> Cosmos.connect key
    |> Cosmos.database "UserDb"
    |> Cosmos.container "UserContainer"
    |> Cosmos.query "SELECT u.FirstName, u.LastName FROM u WHERE u.LastName = @name"
    |> Cosmos.parameters [ "@name", box "Powell" ]
    |> Cosmos.execAsync<User>

[<EntryPoint>]
let main argv =
    async {
        let users = findUsers()
        do! users
        |> AsyncSeq.iter (fun u -> printfn "%s %s" u.FirstName u.LastName)

        return 0
    } |> Async.RunSynchronously

DeleteItem

open FSharp.CosmosDb

let connStr = "..."

let updateUser id partitionKey =
    connStr
    |> Cosmos.fromConnectionString
    |> Cosmos.database "UserDb"
    |> Cosmos.container "UserContainer"
    |> Cosmos.deleteItem id partitionKey
    |> Cosmos.execAsync

DeleteContainer

open FSharp.CosmosDb

let connStr = "..."

connStr
|> Cosmos.container "ContainerName"
|> Cosmos.deleteContainer
|> Cosmos.execAsync
|> Async.Ignore

FSharp.CosmosDb.Analyzer 💡

Also part of this repo is a F# Analyzer for use from the CLI or in Ionide.

Features

• Validation of database name against databases in Cosmos
  • Quick fix provided with list of possible db names
• Validation of container name against containers in the database
  • Quick fix provided with list of possible container names
• Detection of unused parameters in the query
  • Quick fix provided with list of defined parameters (if any)
• Detection of supplied but unused parameters
  • Quick fix provided with list of declared parameters
• Detection of missing @ for parameter name
  • Quick fix provided to add it in

Analyzer Usage

1. Provide connection information

Connection information can be provided as either environment variables or using an appsettings.json/appsettings.Development.json file.

Environment Variables

The analyzer will look for the following environment variables:

• FSHARP_COSMOS_CONNSTR -> A full connection string to Cosmos DB
• FSHARP_COSMOS_HOST & FSHARP_COSMOS_KEY -> The URI endpoint and access key

The FSHARP_COSMOS_CONNSTR will take precedence if both sets of environment variables are provided

App Settings

The analyzer will look for a file matching appsettings.json or appsettings.Development.json in either the workspace root of the VS Code instance or relative to the file being parsed. The file is expected to have the following JSON structure in it:

{
  "CosmosConnection": {
    "ConnectionString": "",
    "Host": "",
    "Key": ""
  }
}

If CosmosConnection.ConnectionString exists, it will be used, otherwise it will use the CosmosConnection.Host and CosmosConnection.Key to connect.

2. Install the Analyzer from paket

paket add FSharp.CosmosDb.Analyzer --group Analyzers

3. Enable Analyzers in Ionide

Add the following settings (globally or in the workspace):

{
  "FSharp.enableAnalyzers": true,
  "FSharp.analyzersPath": ["./packages/analyzers"]
}

License

MIT

Thank You

• Zaid Ajaj for the Npgsql Analyzer. Without this I wouldn't have been able to work out how to do it (and there's some code lifted from there)
• Krzysztof Cieślak for the amazing Ionide plugin
• Isaac Abraham for helping fix the parser