From a0b461808357e618f3d3cbe4ce36dcb9d0b8f6eb Mon Sep 17 00:00:00 2001 From: Sean Corfield Date: Wed, 4 Sep 2019 19:19:32 -0700 Subject: [PATCH] Doc updates for PostgreSQL = ANY(?) trick --- CHANGELOG.md | 2 +- doc/friendly-sql-functions.md | 16 ++++++++++++++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f2c3416..15b5a8a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ Only accretive/fixative changes will be made from now on. The following changes have been committed to the **master** branch since the 1.0.6 release: -* Added test for using `any(?)` and arrays in PostgreSQL for `IN (?,,,?)` style queries. Documentation to follow once I figure out where that belongs! +* Added test for using `any(?)` and arrays in PostgreSQL for `IN (?,,,?)` style queries. Added a **Tips & Tricks** section to **Friendly SQL Functions** with database-specific suggestions, that starts with this one. ## Stable Builds diff --git a/doc/friendly-sql-functions.md b/doc/friendly-sql-functions.md index fd936d6..c1af72b 100644 --- a/doc/friendly-sql-functions.md +++ b/doc/friendly-sql-functions.md @@ -161,4 +161,20 @@ These quoting functions can be provided to any of the friendly SQL functions abo Note that the entity naming function is passed a string, the result of calling `name` on the keyword passed in. Also note that the default quoting functions do not handle schema-qualified names, such as `dbo.table_name` -- `sql-server` would produce `[dbo.table_name]` from that. Use the `schema` function to wrap the quoting function if you need that behavior, e.g,. `{:table-fn (schema sql-server)}` which would produce `[dbo].[table_name]`. +## Tips & Tricks + +This section will accrue various tips and tricks that make it easier to use `next.jdbc` with a variety of databases. It will be organized by database. + +## MySQL + +MySQL generally stores tables as files so they are case-sensitive if your O/S is (Linux) or case-insensitive if your O/S is not (Mac, Windows) but the column names are generally case-insensitive. This can matter when if you use `next.jdbc.result-set/as-lower-maps` because that will lower-case the table names (as well as the column names) so if you are round-tripping based on the keys you get back, you may produce an incorrect table name in terms of case. You'll also need to be careful about `:table-fn`/`:column-fn` because of this. + +It's also worth noting that column comparisons are case-insensitive so `WHERE foo = 'BAR'` will match `"bar"` or `"BAR"` etc. + +### PostgreSQL + +If you have a query where you want to select where a column is `IN` a sequence of values, you can use `col = ANY(?)` with a native array of the values instead of `IN (?,?,?,,,?)` and a sequence of values. + +What does this mean for your use of `next.jdbc`? In `plan`, `execute!`, and `execute-one!`, you can use `col = ANY(?)` in the SQL string and a single primitive array parameter, such as `(int-array [1 2 3 4])`. That means that in `next.jdbc.sql`'s functions that take a where clause (`find-by-keys`, `update!`, and `delete!`) you can specify `["col = ANY(?)" (int-array data)]` for what would be a `col IN (?,?,?,,,?)` where clause for other databases and require multiple values. + [<: Getting Started](/doc/getting-started.md) | [Result Set Builders :>](/doc/result-set-builders.md)