From 86a9a42495ddccd65fee27c90afdbe07b23de3bc Mon Sep 17 00:00:00 2001 From: Shay Rojansky Date: Mon, 8 Nov 2021 11:04:58 +0100 Subject: [PATCH] Breaking change note on DbType.DateTime See https://github.com/npgsql/npgsql/issues/4106 --- conceptual/Npgsql/index.md | 12 +++++++----- conceptual/Npgsql/release-notes/6.0.md | 3 ++- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/conceptual/Npgsql/index.md b/conceptual/Npgsql/index.md index 9c603d9de..fbb62a710 100644 --- a/conceptual/Npgsql/index.md +++ b/conceptual/Npgsql/index.md @@ -14,9 +14,10 @@ title: Documentation The best way to use Npgsql is to install its [nuget package](https://www.nuget.org/packages/Npgsql/). Npgsql aims to be fully ADO.NET-compatible, its API should feel almost identical to other .NET database drivers. + Here's a basic code snippet to get you started. -```c# +```csharp var connString = "Host=myserver;Username=mylogin;Password=mypass;Database=mydatabase"; await using var conn = new NpgsqlConnection(connString); @@ -32,9 +33,10 @@ await using (var cmd = new NpgsqlCommand("INSERT INTO data (some_field) VALUES ( // Retrieve all rows await using (var cmd = new NpgsqlCommand("SELECT some_field FROM data", conn)) await using (var reader = await cmd.ExecuteReaderAsync()) - while (await reader.ReadAsync()) - Console.WriteLine(reader.GetString(0)); +{ +while (await reader.ReadAsync()) + Console.WriteLine(reader.GetString(0)); +} ``` -You can find more info about the ADO.NET API in the [MSDN docs](https://msdn.microsoft.com/en-us/library/h43ks021(v=vs.110).aspx) -or in many tutorials on the Internet. +You can find more info about the ADO.NET API in the [MSDN docs](https://msdn.microsoft.com/en-us/library/h43ks021(v=vs.110).aspx) or in many tutorials on the Internet. diff --git a/conceptual/Npgsql/release-notes/6.0.md b/conceptual/Npgsql/release-notes/6.0.md index c962eba92..7a44d58d2 100644 --- a/conceptual/Npgsql/release-notes/6.0.md +++ b/conceptual/Npgsql/release-notes/6.0.md @@ -119,7 +119,7 @@ In previous versions, specifying `SSL Mode=Require` made Npgsql validate the ser #### Quick summary * Most applications want to store UTC timestamps in the database. To do this, migrate your `timestamp without time zone` columns to `timestamp with time zone` ([see migration notes below](#migrating-columns-from-timestamp-to-timestamptz)), and always use DateTime with Kind=Utc when interacting with Npgsql. -* For the few cases where non-UTC timestamps are desired, add explicit configuration to your properties to be `timestamp without time zone` +* For the few cases where non-UTC timestamps are desired, add explicit configuration to your properties to be `timestamp without time zone`. * If you're using Dapper, use version 2.0.123 or above. Earlier versions will fail when trying to send a UTC DateTime. #### Detailed notes @@ -131,6 +131,7 @@ The below notes will use the PostgreSQL aliases `timestamptz` to refer to `times * It is no longer possible to write UTC DateTime as `timestamp`, or Local/Unspecified DateTime as `timestamptz`. This was previously allowed, with Npgsql performing implicit timezone conversions. * Note that if you write a UTC DateTime to a PostgreSQL `timestamp` column, PostgreSQL will implicitly convert the `timestamptz` value sent by Npgsql, performing a timezone conversion based on the `TimeZone` parameter. * `timestamptz` values are now read back as DateTime with Kind=UTC, without any conversions; these were previously returned as local DateTime, converted to the local machine's timezone. When reading `timestamptz` values as [DateTimeOffset](https://docs.microsoft.com/dotnet/api/system.datetimeoffset), UTC values (offset 0) are always returned. +* [DbType.DateTime](https://docs.microsoft.com/dotnet/api/system.data.dbtype#System_Data_DbType_DateTime) now maps to `timestamptz`, not `timestamp`. [DbType.DateTime2](https://docs.microsoft.com/dotnet/api/system.data.dbtype#System_Data_DbType_DateTime2) continues to map to `timestamp`, and [DbType.DateTimeOffset](https://docs.microsoft.com/dotnet/api/system.data.dbtype#System_Data_DbType_DateTimeOffset) continues to map to `timestamptz`, as before. Unless you're writing cross-database applications, consider using [NpgsqlDbType](https://www.npgsql.org/doc/basic-usage.html#parameter-types) instead of `DbType` to specify precise PostgreSQL types, or simply let Npgsql infer the types by not setting either. * It is no longer possible to write [DateTimeOffset](https://docs.microsoft.com/dotnet/api/system.datetimeoffset) with offsets other than 0 (UTC), since these cannot be represented in PostgreSQL. These were previously implicitly converted to UTC before sending. * It is no longer possible to read or write `timetz` as DateTime or TimeSpan, as these don't have a timezone. This was previously allowed, with the offset being stripped.