Skip to content

Commit bfa248b

Browse files
committed
HAVING OR fix, Math.Round(col, n) support, apostrophe-escape fix, transactions docs update
1 parent 5beb2a2 commit bfa248b

9 files changed

Lines changed: 127 additions & 8 deletions

File tree

‎docs/content/content/DBPLRlP.png‎

67.3 KB
Loading

‎docs/content/core/async.fsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ is to release the business logics thread while the database is doing its job.
2929
This can lead to a huge performance difference in a heavy traffic environment
3030
(basically, will your business logics server / web-server crash or not).
3131
32-
![](https://i.imgur.com/DBPLRlP.png)
32+
![Business logic server has a red wait block while DB is doing queries](../content/DBPLRlP.png)
3333
3434
In the picture, we talk about the red block, which can be released to serve other customers.
3535
As usual with async operations, there will be more thread context switching,

‎docs/content/core/crud.fsx‎

Lines changed: 63 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,69 @@ ctx.SubmitUpdates() // no record is added
180180

181181
(**
182182
183-
Inside SubmitUpdate the transaction is created by default TransactionOption, which is Required: Shares a transaction, if one exists, and creates a new transaction if necessary. So, if you have query-operation before SubmitUpdates, you should create your own transaction to wrap these into the same transaction.
183+
### Transactions and isolation level
184+
185+
`SubmitUpdates` / `SubmitUpdatesAsync` wrap the write in a `TransactionScope` created with
186+
`TransactionScopeOption.Required`: it *joins* an ambient transaction if one already exists, otherwise
187+
it starts a new one. Only the submit is wrapped — your queries/reads are **not** put in a
188+
transaction, so reads carry no locking overhead.
189+
190+
Because of `Required`, the way to make a *read-then-write* atomic (read some rows, decide, then write)
191+
is to open your **own** transaction around both the reads and the `SubmitUpdates`, and that scope's
192+
isolation level is the one that applies:
193+
194+
```fsharp
195+
open System.Transactions
196+
197+
use scope =
198+
new TransactionScope(
199+
TransactionScopeOption.Required,
200+
TransactionOptions(IsolationLevel = IsolationLevel.ReadCommitted),
201+
TransactionScopeAsyncFlowOption.Enabled) // needed if you await inside the scope
202+
203+
// Open a FRESH data context *inside* the scope for this unit of work (see note below):
204+
let ctx = sql.GetDataContext connstr
205+
206+
// ... your queries (reads) ...
207+
// ... your Create()/mutations ...
208+
ctx.SubmitUpdates()
209+
scope.Complete()
210+
```
211+
212+
**Create a fresh context per transaction — don't reuse a shared/long-lived one.** A data context
213+
accumulates *all* pending changes (every `Create()`, `Delete()`, and column edit) until `SubmitUpdates()`
214+
flushes them to the database together. If you'd reuse a long-lived or shared context, a `SubmitUpdates()`
215+
inside your transaction could commit unrelated pending changes that another request or user left sitting on
216+
that context. Opening a new context inside the scope keeps each transaction small and self-contained, and
217+
guarantees the tracked changes are exactly what this transaction should write — and it keeps the
218+
context's connection enlisted in this transaction.
219+
220+
**Reads are different — a shared context is fine (and fastest).** The "fresh context per unit of work"
221+
rule above is about *writes*. If you use `.GetReadOnlyDataContext connstr` you can enforce read-only:
222+
it has no pending-change nor transaction concerns. For read-only operations you can safely **share/cache one**
223+
database context across requests, which is actually the fastest way to read (no per-call context setup).
224+
The one thing to add is *resilience*: if the connection dies for reasons outside SQLProvider (driver/network/timeout),
225+
you need logic to rebuild the shared context — e.g. hold it in a mutable `Lazy` and recreate
226+
it when the value is null or a call throws a connection error.
227+
228+
**Isolation level gotcha:** SQLProvider's `TransactionOptions.Default` — used *only* when
229+
`SubmitUpdates` has to create a standalone write transaction (no ambient scope) — inherits the
230+
.NET default, which is **`Serializable`**, not `ReadCommitted`. A bare `new TransactionScope()` is the
231+
same: it also defaults to `Serializable`. So if you want `ReadCommitted` (usually the right choice to
232+
avoid over-locking on a larger system), pass it explicitly through `TransactionOptions`, as above. Choosing the isolation
233+
level for a unit of work is intentionally the caller's job, not SQLProvider's (see
234+
[issue #238](https://github.com/fsprojects/SQLProvider/issues/238) for one real-world use-case solution).
235+
236+
If your transaction spans an `await` / async continuation, remember `TransactionScopeAsyncFlowOption.Enabled`
237+
(otherwise the ambient transaction won't flow to the continuation thread — see the [async](async.html)
238+
page for a full example).
239+
240+
**Read vs write contexts:** SQLProvider can generate a read-only data context via
241+
`GetReadOnlyDataContext()` alongside the writable `GetDataContext()`, giving you compile-time separation
242+
of read and write code paths (the read-only context can't accidentally mutate/submit). They are type-level
243+
different. If you have a method parameter and you want to share a read-only query with a read
244+
that *must* run inside a write transaction, call `.AsReadOnly()` on the writable context to reuse its
245+
connection.
184246
185247
SQLProvider also supports async database operations:
186248

‎docs/content/core/querying.fsx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,8 @@ Math.Pow(x,y) | POWER(x,y) | POWER(x,y) | POWER(x,y) | POWER(x,y) | | x^y
326326
(/) | / | / | / | / | / | / | / | |
327327
(%) | % | % | % | % | % | % | % | |
328328
329+
SQL Engine operations may differ from .NET ones, for example `Math.Round` in .NET (banker's rounding).
330+
329331
Microsoft SQL Server doesn't have Greatest and Least functions, so that will be done via nested SQL clause: (select max(v) from (values (x), (y)) as value(v))
330332
It might also not be standard ODBC, but it should work e.g. on Amazon Redshift.
331333

‎src/SQLProvider.Common/SqlRuntime.Common.fs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1021,9 +1021,9 @@ module CommonTasks =
10211021
| Condition.And(curr, tail) ->
10221022
let converted = curr |> List.map (fun (alias,c,op,i) -> replaceAlias alias, replaceEmptyKey c, op, i)
10231023
Condition.And(converted, tail |> Option.map parseFilters)
1024-
| Condition.Or(curr,tail) ->
1024+
| Condition.Or(curr,tail) ->
10251025
let converted = curr |> List.map (fun (alias,c,op,i) -> replaceAlias alias, replaceEmptyKey c, op, i)
1026-
Condition.Or(curr, tail |> Option.map parseFilters)
1026+
Condition.Or(converted, tail |> Option.map parseFilters)
10271027
| x -> x)
10281028
parseFilters conditionList
10291029

‎src/SQLProvider.Common/SqlRuntime.Patterns.fs‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -584,7 +584,6 @@ let rec (|SqlColumnGet|_|) (ex:Expression) =
584584
| "Ceil", [_] -> Some(alias, CanonicalOperation(CanonicalOp.Ceil, col), typ)
585585
| "Floor", [_] -> Some(alias, CanonicalOperation(CanonicalOp.Floor, col), typ)
586586
| "Round", [_] -> Some(alias, CanonicalOperation(CanonicalOp.Round, col), typ)
587-
| "Round", [_; Int decCount] -> Some(alias, CanonicalOperation(CanonicalOp.RoundDecimals(decCount), col), typ)
588587
| "Sqrt", [_] -> Some(alias, CanonicalOperation(CanonicalOp.Sqrt, col), typ)
589588
| "Sin", [_] -> Some(alias, CanonicalOperation(CanonicalOp.Sin, col), typ)
590589
| "Cos", [_] -> Some(alias, CanonicalOperation(CanonicalOp.Cos, col), typ)
@@ -595,8 +594,13 @@ let rec (|SqlColumnGet|_|) (ex:Expression) =
595594
| "Truncate", [_] -> Some(alias, CanonicalOperation(CanonicalOp.Truncate, col), typ)
596595
| _ -> failwith "Shouldn't hit"
597596

597+
// Math.Round(col, decimals): a 2-arg call the single-arg numerical pattern above can't match.
598+
| _, OptionalFSharpOptionValue(MethodCallOrFSharpWrap(None, meth, [OptionalFSharpOptionValue(OptionalConvertOrTypeAs(SqlColumnGet(alias, col, typ)) as pe); Int decCount]))
599+
when (meth.Name = "Round" && (decimalTypes |> Array.exists(fun t -> Type.(=)(pe.Type, t)))) ->
600+
Some(alias, CanonicalOperation(CanonicalOp.RoundDecimals(decCount), col), typ)
601+
598602
| _, OptionalFSharpOptionValue(MethodCall(None, meth, ([OptionalFSharpOptionValue(OptionalConvertOrTypeAs(SqlColumnGet(alias, col, typ)) as p1); par])))
599-
when (meth.Name = "Max" || meth.Name = "Min" || meth.Name = "Pow") ->
603+
when (meth.Name = "Max" || meth.Name = "Min" || meth.Name = "Pow") ->
600604
match meth.Name, par with
601605
| "Max", (OptionalConvertOrTypeAs(SqlColumnGet(al2,col2,typ2)) as pe) when Type.(=)(pe.Type, p1.Type) -> Some(alias, CanonicalOperation(CanonicalOp.Greatest(SqlCol(al2,col2)), col), typ)
602606
| "Min", (OptionalConvertOrTypeAs(SqlColumnGet(al2,col2,typ2)) as pe) when Type.(=)(pe.Type, p1.Type) -> Some(alias, CanonicalOperation(CanonicalOp.Least(SqlCol(al2,col2)), col), typ)

‎src/SQLProvider.Common/SqlRuntime.Transactions.fs‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,44 @@ namespace FSharp.Data.Sql.Transactions
22

33
open System
44

5+
// SQLProvider's transaction model, in one place so it isn't misread:
6+
// * A TransactionScope is created ONLY on the write path - each provider's
7+
// ProcessUpdates/ProcessUpdatesAsync (i.e. SubmitUpdates/SubmitUpdatesAsync).
8+
// Query/read execution is intentionally NOT wrapped in a transaction (no overhead).
9+
// * The scope uses TransactionScopeOption.Required (see ensureTransaction), so if the
10+
// caller has opened their own ambient System.Transactions scope, SubmitUpdates JOINS it
11+
// and the caller's isolation level wins - TransactionOptions here are then irrelevant.
12+
// * The isolation level below only takes effect for a STANDALONE write batch (when there is
13+
// no ambient transaction). Choosing isolation for a read-then-write unit of work is the
14+
// caller's job: wrap the reads and the SubmitUpdates in one ambient transaction yourself.
15+
// (SQLProvider even exposes separate read/write data-context types to help structure this.)
16+
// So TransactionOptions.Default = Serializable is NOT a global "everything runs Serializable",
17+
// it is the fallback isolation for an unscoped write batch only.
18+
//
19+
// Recommended usage:
20+
// * Pure reads: use a read-only data context (GetReadOnlyDataContext()) - no transaction, no locking overhead.
21+
// * Writes / read-then-write: open your OWN ambient scope with the isolation you want, e.g.
22+
// use scope = new System.Transactions.TransactionScope(
23+
// System.Transactions.TransactionScopeOption.Required,
24+
// System.Transactions.TransactionOptions(IsolationLevel = <your level>),
25+
// System.Transactions.TransactionScopeAsyncFlowOption.Enabled)
26+
// do your reads + SubmitUpdates() inside it (SubmitUpdates enlists via Required), then scope.Complete().
27+
// A bare `new TransactionScope(AsyncFlowOption.Enabled)` roots a SERIALIZABLE transaction (the .NET default) -
28+
// pass explicit TransactionOptions if you want ReadCommitted etc.
29+
// * A read that must run inside a write transaction: call .AsReadOnly() on the writable context to reuse its connection.
30+
531
/// Transaction isolation level for database operations.
632
/// Corresponds to the System.Transactions.IsolationLevel but provides SQL provider specific functionality.
33+
/// Only applied when SubmitUpdates creates its own (standalone) write transaction; if you wrap your
34+
/// own ambient System.Transactions scope, that scope's isolation level is used instead.
735
type IsolationLevel =
836
/// Highest isolation level - transactions are completely isolated from each other
937
| Serializable = 0
1038
/// Prevents dirty reads and non-repeatable reads, but phantom reads can occur
1139
| RepeatableRead = 1
12-
/// Prevents dirty reads but allows non-repeatable reads and phantom reads (default for most databases)
40+
/// Prevents dirty reads but allows non-repeatable reads and phantom reads.
41+
/// (This describes the default isolation of most DB *engines* - it is NOT SQLProvider's default;
42+
/// TransactionOptions.Default is Serializable, inherited from System.Transactions.)
1343
| ReadCommitted = 2
1444
/// Allows dirty reads, non-repeatable reads, and phantom reads (fastest but least safe)
1545
| ReadUncommitted = 3
@@ -71,6 +101,12 @@ module TransactionUtils =
71101
| System.Transactions.IsolationLevel.Unspecified -> IsolationLevel.Unspecified
72102
| _ -> failwithf "Unhandled System.Transactions.IsolationLevel value: %A." isolationLevel
73103

104+
/// Creates the TransactionScope that wraps a SubmitUpdates write batch. Called ONLY from the
105+
/// providers' ProcessUpdates/ProcessUpdatesAsync - reads are never wrapped. Uses
106+
/// TransactionScopeOption.Required: if the caller already opened an ambient transaction this
107+
/// enlists in it (and the caller's isolation level applies, not the one passed here); otherwise
108+
/// it starts a fresh standalone transaction using transactionOptions. Pass
109+
/// IsolationLevel.DontCreateTransaction to skip creating a scope entirely.
74110
let ensureTransaction (transactionOptions : TransactionOptions) =
75111
if transactionOptions.IsolationLevel = IsolationLevel.DontCreateTransaction then
76112
Unchecked.defaultof<Transactions.TransactionScope>
@@ -94,6 +130,10 @@ module TransactionUtils =
94130
new Transactions.TransactionScope(transactionScopeOption, transactionOptions, System.Transactions.TransactionScopeAsyncFlowOption.Enabled)
95131

96132
type TransactionOptions with
133+
/// Inherits System.Transactions' defaults: Timeout = 1 minute and IsolationLevel = Serializable.
134+
/// The Serializable level only applies to a standalone SubmitUpdates write batch (no ambient
135+
/// transaction); wrap your read-then-write work in your own scope to control isolation. See the
136+
/// note on the IsolationLevel type above.
97137
static member Default =
98138
let sysTranOpt = System.Transactions.TransactionOptions()
99139
{

‎src/SQLProvider.Common/Utils.fs‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -290,12 +290,20 @@ module Utilities =
290290
| CanonicalOperation(op, c) -> $"c{abs(op.GetHashCode())}c{getBaseColumnName c}"
291291
| GroupColumn(op, c) -> $"g{abs(op.GetHashCode())}g{getBaseColumnName c}"
292292

293+
/// Renders an inline SQL *value literal* (used where a provider - chiefly ODBC - can't bind a
294+
/// parameter). String/Guid/DateTime literals are ALWAYS single-quoted (the delimiter is fixed
295+
/// here, it is NOT OdbcQuoteCharacter - that setting only controls *identifier* quoting:
296+
/// ` ` / [ ] / " " / 'x'). Because the delimiter is a single quote, the escape must be the
297+
/// matching single quote doubled ('') - and ONLY the single quote is doubled; every other
298+
/// character (including ") passes through verbatim. So `O'Brien` -> 'O''Brien' and
299+
/// `say "hi"` -> 'say "hi"'. The '' escape is SQL-standard and universal across backends.
300+
/// (If the literal delimiter were ever made configurable, the escaped char would have to track it.)
293301
let fieldConstant (value:obj) =
294302
//Can we create named parameters in ODBC, and how?
295303
match value with
296304
| :? Guid
297305
| :? DateTime
298-
| :? String -> sprintf "'%s'" (value.ToString().Replace("'", ""))
306+
| :? String -> sprintf "'%s'" (value.ToString().Replace("'", "''"))
299307
| _ -> value.ToString()
300308

301309

‎src/SQLProvider.Runtime/Providers.Postgresql.fs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1047,6 +1047,9 @@ type internal PostgresqlProvider(resolutionPath, contextSchemaPath, owner, refer
10471047
| DateDiffSecs(SqlConstant x) -> sprintf "EXTRACT(EPOCH FROM (%s::timestamp - %s::timestamp))" column (fieldParam x)
10481048
// Math functions
10491049
| Truncate -> sprintf "TRUNC(%s)" column
1050+
// Postgres has ROUND(double precision) but NOT ROUND(double precision, int) -
1051+
// only ROUND(numeric, int). Cast so 2-arg rounding works for float/real columns too.
1052+
| RoundDecimals n -> sprintf "ROUND(%s::numeric, %d)" column n
10501053
| BasicMathOfColumns(o, a, c) when o = "/" -> sprintf "(%s %s (1.0*%s))" column o (fieldNotation a c)
10511054
| BasicMathOfColumns(o, a, c) -> sprintf "(%s %s %s)" column o (fieldNotation a c)
10521055
| BasicMath(o, par) when (par :? String || par :? Char) -> sprintf "(%s %s %s)" column o (fieldParam par)

0 commit comments

Comments
 (0)