From 5ce2c327323eb5c164e60f922f051df35ea08c83 Mon Sep 17 00:00:00 2001 From: Sean Corfield Date: Fri, 15 Jul 2022 16:08:26 -0700 Subject: [PATCH] fixes #199 by adding suggested text --- CHANGELOG.md | 1 + doc/tips-and-tricks.md | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index cbe3b0d..cd4a9d0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ Only accretive/fixative changes will be made from now on. * 1.2.next in progress + * Address [#199](https://github.com/seancorfield/next-jdbc/issues/199) by adding notes on UTC usage -- [@denismccarthykerry](https://github.com/denismccarthykerry). * Enhance `insert-multi!` to accept a sequence of hash maps and also to support batch execution, via PR [#206](https://github.com/seancorfield/next-jdbc/pull/206) -- [@rschmukler](https://github.com/rschmukler). * Fix HikariCP pooling example. diff --git a/doc/tips-and-tricks.md b/doc/tips-and-tricks.md index 0c25344..89c4078 100644 --- a/doc/tips-and-tricks.md +++ b/doc/tips-and-tricks.md @@ -85,6 +85,26 @@ The result of `plan` is also foldable in the [clojure.core.reducers](https://clo There is no back pressure here so if your reducing function is slow, you may end up with more of the realized result set in memory than your system can cope with. +## Times, Dates, and Timezones + +Working with dates and timezones in databases can be confusing, as you are +working at the intersection between the database, the JDBC library and the +date library that you happen to be using. A good rule of thumb is to keep +timezone-related logic as simple as possible. For example, with Postgres we +recommend always storing dates in a Postgres `TIMESTAMP` (without time zone) +column, storing all such timestamps in UTC, and applying your time zone logic +separately using application logic. The `TIMESTAMP WITH TIME ZONE` column type in +Postgres stores its date in UTC anyhow, and applications that need to deal with +time zones typically require richer functionality than simply adjusting the time +zone to wherever the database happens to be hosted. Treat time zone related +logic as an application concern, and keep stored dates in UTC. + +For example, for a developer using [`clojure.java-time`](https://github.com/dm3/clojure.java-time), saving `(java-time/instant)` +in a timestamp column (and doing any timezone adjustment elsewhere) is a good +way to minimize long term confusion. + +> Original text contributed by [Denis McCarthy](https://github.com/denismccarthykerry); in addition: I generally recommend not only using UTC everywhere but also setting your database _and your servers_ to all be in the UTC timezones, to avoid the possibly of incorrect date/time translations -- Sean Corfield. + ## MS SQL Server In MS SQL Server, the generated key from an insert comes back as `:GENERATED_KEYS`.