Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

add some documentation about date/time config settings 

and also add some links
This commit is contained in:
Gavin King 2024-11-21 13:59:06 +01:00
parent 21095565bc
commit ca9b058d4e
1 changed files with 35 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
documentation/src/main/asciidoc/introduction/Configuration.adoc
View File

@ -481,10 +481,10 @@ The following properties are very useful for minimizing the amount of informatio
|===
| Configuration property name | Purpose
| `hibernate.default_schema` | A default schema name for entities which do not explicitly declare one
| `hibernate.default_catalog` | A default catalog name for entities which do not explicitly declare one
| `hibernate.physical_naming_strategy` | A `PhysicalNamingStrategy` implementing your database naming standards
| `hibernate.implicit_naming_strategy` | An `ImplicitNamingStrategy` which specifies how "logical" names of relational objects should be inferred when no name is specified in annotations
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#DEFAULT_SCHEMA[`hibernate.default_schema`] | A default schema name for entities which do not explicitly declare one
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#DEFAULT_CATALOG[`hibernate.default_catalog`] | A default catalog name for entities which do not explicitly declare one
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#PHYSICAL_NAMING_STRATEGY[`hibernate.physical_naming_strategy`] | A `PhysicalNamingStrategy` implementing your database naming standards
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#IMPLICIT_NAMING_STRATEGY[`hibernate.implicit_naming_strategy`] | An `ImplicitNamingStrategy` which specifies how "logical" names of relational objects should be inferred when no name is specified in annotations
|===
[TIP]
@ -507,8 +507,8 @@ The following settings enable automatic quoting:
|===
| Configuration property name | Purpose
| `hibernate.auto_quote_keyword` | Automatically quote any identifier which is a SQL keyword
| `hibernate.globally_quoted_identifiers` | Automatically quote every identifier
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#KEYWORD_AUTO_QUOTING_ENABLED[`hibernate.auto_quote_keyword`] | Automatically quote any identifier which is a SQL keyword
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#GLOBALLY_QUOTED_IDENTIFIERS[`hibernate.globally_quoted_identifiers`] | Automatically quote every identifier
|===
Note that `hibernate.globally_quoted_identifiers` is a synonym for `<delimited-identifiers/>` in <<configuration-jpa,`persistence.xml`>>.
@ -532,7 +532,7 @@ So, if you're working with SQL Server, you might need to force Hibernate to use
|===
| Configuration property name | Purpose
| `hibernate.use_nationalized_character_data` | Use `nchar` and `nvarchar` instead of `char` and `varchar`
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#USE_NATIONALIZED_CHARACTER_DATA[`hibernate.use_nationalized_character_data`] | Use `nchar` and `nvarchar` instead of `char` and `varchar`
|===
On the other hand, if only _some_ columns store nationalized data, use the link:{doc-javadoc-url}org/hibernate/annotations/Nationalized.html[`@Nationalized`] annotation to indicate fields of your entities which map these columns.
@ -543,3 +543,31 @@ On the other hand, if only _some_ columns store nationalized data, use the link:
Alternatively, you can configure SQL Server to use the UTF-8 enabled collation `_UTF8`.
====
[[datetime-jdbc]]
=== Date and time types and JDBC
By default, Hibernate handles date and time types defined by `java.time` by:
- converting `java.time` types to JDBC date/time types defined in `java.sql` when sending data to the database, and
- reading `java.sql` types from JDBC and then converting them to `java.time` types when retrieving data from the database.
This works best when the database server time zone agrees with JVM system time zone.
TIP: We therefore recommend setting things up so that the database server and the JVM agree on the same time zone. **Hint:** when in doubt, UTC quite a nice time zone.
There are two system configuration properties which influence this behavior:
.Settings for JDBC date/time handling
[%breakable,cols="35,~"]
|===
| Configuration property name | Purpose
| link:{doc-javadoc-url}org/hibernate/cfg/JdbcSettings.html#JDBC_TIME_ZONE[`hibernate.jdbc.time_zone`] | Use an explicit time zone when interacting with JDBC
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#JAVA_TIME_USE_DIRECT_JDBC[`hibernate.type.java_time_use_direct_jdbc`] | Read and write `java.time` types directly to and from JDBC
|===
You may set `hibernate.jdbc.time_zone` to the time zone of the database server if for some reason the JVM needs to operate in a different time zone.
We do not recommend this approach.
On the other hand, we would love to recommend the use of `hibernate.type.java_time_use_direct_jdbc`, but this option is still experimental for now, and does result in some subtle differences in behavior which might affect legacy programs using Hibernate.