36 lines
3.2 KiB
Markdown
36 lines
3.2 KiB
Markdown
# Upgrade from v3 to v4
|
|
|
|
## The Quick Version
|
|
|
|
- Add `BitBadger.Documents.[Postgres|Sqlite].Compat` to your list of `using` (C#) or `open` (F#) statements. This namespace has deprecated versions of the methods/functions that were removed in v4. These generate warnings, rather than the "I don't know what this is" compiler errors.
|
|
- If your code referenced `Query.[Action].[ById|ByField|etc]`, the sides of the query on each side of the `WHERE` clause are now separate. A query to patch a document by its ID would go from `Query.Patch.ById(tableName)` to `Query.ById(Query.Patch(tableName))`. These functions may also require more parameters; keep reading for details on that.
|
|
- Custom queries had to be used when querying more than one field, or when the results in the database needed to be ordered. v4 provides solutions for both of these within the library itself.
|
|
|
|
## `ByField` to `ByFields` and PostgreSQL Numbers
|
|
|
|
All methods/functions that ended with `ByField` now end with `ByFields`, and take a `FieldMatch` case (`Any` equates to `OR`, `All` equates to `AND`) and sequence of `Field` objects. These `Field`s need to have their values as well, because the PostgreSQL library will now cast the field from the document to numeric and bind the parameter as-is.
|
|
|
|
That is an action-packed paragraph; these changes have several ripple effects throughout the library:
|
|
- Queries like `Query.Find.ByField` would need the full collection of fields to generate the SQL. Instead, `Query.ByFields` takes a "first-half" statement as its first parameter, then the field match and parameters as its next two.
|
|
- `Field` instances in version 3 needed to have a parameter name, which was specified externally to the object itself. In version 4, `ParameterName` is an optional member of the `Field` object, and the library will generate parameter names if it is missing. In both C# and F#, the `.WithParameterName(string)` method can be chained to the `Field.[OP]` call to specify a name, and F# users can also use the language's `with` keyword (`{ Field.EQ "TheField" "value" with ParameterName = Some "@theField" }`).
|
|
|
|
## `Op` Type Removal
|
|
|
|
The `Op` type has been replaced with a `Comparison` type which captures both the type of comparison and the object of the comparison in one type. This is considered an internal implementation detail, as that type was not intended for use outside the library; however, it was `public`, so its removal warrants at least a mention.
|
|
|
|
Additionally, the addition of `In` and `InArray` field comparisons drove a change to the `Field` type's static creation functions. These now have the comparison spelled out, as opposed to the two-to-three character abbreviations. (These abbreviated functions still exists as aliases, so this change will not result in compile errors.) The functions to create fields are:
|
|
|
|
| Old | New |
|
|
|:-----:|-----------------------|
|
|
| `EQ` | `Equal` |
|
|
| `GT` | `Greater` |
|
|
| `GE` | `GreaterOrEqual` |
|
|
| `LT` | `Less` |
|
|
| `LE` | `LessOrEqual` |
|
|
| `NE` | `NotEqual` |
|
|
| `BT` | `Between` |
|
|
| `IN` | `In` _(since v4 rc1)_ |
|
|
| -- | `InArray` _(v4 rc4)_ |
|
|
| `EX` | `Exists` |
|
|
| `NEX` | `NotExists` |
|