@ -40,7 +40,7 @@ class PersonLoadListener extends AbstractRelationalEventListener<Person> {
}
}
----
----
The following table describes the available events.For more details about the exact relation between process steps see the link:#jdbc.entity-callbacks[description of available callbacks] which map 1:1 to events.
The following table describes the available events.For more details about the exact relation between process steps see the link:#jdbc.entity-callbacks[description of available callbacks] which map 1:1 to events.
@ -21,7 +21,7 @@ Spring Data JDBC includes direct support for the following databases:
* Microsoft SQL Server
* Microsoft SQL Server
* MySQL
* MySQL
* Oracle
* Oracle
* Postgres
* PostgreSQL
If you use a different database then your application won’t start up.
If you use a different database then your application won’t start up.
The <<jdbc.dialects,dialect>> section contains further detail on how to proceed in such case.
The <<jdbc.dialects,dialect>> section contains further detail on how to proceed in such case.
@ -33,7 +33,7 @@ To create a Spring project in STS:
. Go to File -> New -> Spring Template Project -> Simple Spring Utility Project, and press Yes when prompted.
. Go to File -> New -> Spring Template Project -> Simple Spring Utility Project, and press Yes when prompted.
Then enter a project and a package name, such as `org.spring.jdbc.example`.
Then enter a project and a package name, such as `org.spring.jdbc.example`.
. Add the following to the `pom.xml` files `dependencies` element:
. Add the following to the `pom.xml` file `dependencies` element:
+
+
[source,xml,subs="+attributes"]
[source,xml,subs="+attributes"]
----
----
@ -77,7 +77,7 @@ The repository is also https://repo.spring.io/milestone/org/springframework/data
Spring Data JDBC does little to no logging on its own.
Spring Data JDBC does little to no logging on its own.
Instead, the mechanics of `JdbcTemplate` to issue SQL statements provide logging.
Instead, the mechanics of `JdbcTemplate` to issue SQL statements provide logging.
Thus, if you want to inspect what SQL statements are run, activate logging for Spring's {spring-framework-docs}/data-access.html#jdbc-JdbcTemplate[`NamedParameterJdbcTemplate`] or https://www.mybatis.org/mybatis-3/logging.html[MyBatis].
Thus, if you want to inspect what SQL statements are run, activate logging for Spring's {spring-framework-docs}/data-access/jdbc/core.html#jdbc-NamedParameterJdbcTemplate[`NamedParameterJdbcTemplate`] or https://www.mybatis.org/mybatis-3/logging.html[MyBatis].
You may also want to set the logging level to `DEBUG` to see some additional information.
You may also want to set the logging level to `DEBUG` to see some additional information.
To do so, edit the `application.properties` file to have the following content:
To do so, edit the `application.properties` file to have the following content:
@ -125,8 +125,8 @@ class ApplicationConfig extends AbstractJdbcConfiguration {
}
}
----
----
<1> `@EnableJdbcRepositories` creates implementations for interfaces derived from `Repository`
<1> `@EnableJdbcRepositories` creates implementations for interfaces derived from `Repository`.
<2> javadoc:org.springframework.data.jdbc.repository.config.AbstractJdbcConfiguration[] provides various default beans required by Spring Data JDBC
<2> javadoc:org.springframework.data.jdbc.repository.config.AbstractJdbcConfiguration[] provides various default beans required by Spring Data JDBC.
<3> Creates a `DataSource` connecting to a database.
<3> Creates a `DataSource` connecting to a database.
This is required by the following two bean methods.
This is required by the following two bean methods.
<4> Creates the `NamedParameterJdbcOperations` used by Spring Data JDBC to access the database.
<4> Creates the `NamedParameterJdbcOperations` used by Spring Data JDBC to access the database.
@ -158,13 +158,13 @@ Alternatively, you can implement your own `Dialect`.
[TIP]
[TIP]
====
====
Dialects are resolved by javadoc:org.springframework.data.jdbc.repository.config.DialectResolver[] from a `JdbcOperations` instance, typically by inspecting `Connection.getMetaData()`.
Dialects are resolved by javadoc:org.springframework.data.jdbc.repository.config.DialectResolver[] from a `JdbcOperations` instance, typically by inspecting `Connection.getMetaData()`. +
+ You can let Spring auto-discover your javadoc:org.springframework.data.jdbc.core.dialect.JdbcDialect[] by registering a class that implements `org.springframework.data.jdbc.repository.config.DialectResolver$JdbcDialectProvider` through `META-INF/spring.factories`.
You can let Spring auto-discover your javadoc:org.springframework.data.jdbc.core.dialect.JdbcDialect[] by registering a class that implements `org.springframework.data.jdbc.repository.config.DialectResolver$JdbcDialectProvider` through `META-INF/spring.factories`.
`DialectResolver` discovers dialect provider implementations from the class path using Spring's `SpringFactoriesLoader`.
`DialectResolver` discovers dialect provider implementations from the class path using Spring's `SpringFactoriesLoader`.
To do so:
To do so:
. Implement your own `Dialect`.
. Implement your own `Dialect`.
. Implement a `JdbcDialectProvider` returning the `Dialect`.
. Implement a `JdbcDialectProvider` returning the `Dialect`.
. Register the provider by creating a `spring.factories` resource under `META-INF` and perform the registration by adding a line +
. Register the provider by creating a `spring.factories` resource under `META-INF` and perform the registration by adding a line +
`org.springframework.data.jdbc.repository.config.DialectResolver$JdbcDialectProvider=<fully qualified name of your JdbcDialectProvider>`
`org.springframework.data.jdbc.repository.config.DialectResolver$JdbcDialectProvider=<fully qualified name of your JdbcDialectProvider>`.
You should not include attributes in your entities to hold the actual value of a back reference, nor of the key column of maps or lists.
You should not include attributes in your entities to hold the actual value of a back reference, nor of the key column of maps or lists.
If you want these value to be available in your domain model we recommend to do this in a `AfterConvertCallback` and store the values in transient values.
If you want these values to be available in your domain model we recommend to do this in an `AfterConvertCallback` and store the values in transient values.
:mapped-collection: true
:mapped-collection: true
:embedded-entities: true
:embedded-entities: true
@ -210,7 +210,7 @@ If you are migrating from an older version of Spring Data JDBC and have `Abstrac
[TIP]
[TIP]
====
====
If you want to rely on https://spring.io/projects/spring-boot[Spring Boot] to bootstrap Spring Data JDBC, but still want to override certain aspects of the configuration, you may want to expose beans of that type.
If you want to rely on https://spring.io/projects/spring-boot[Spring Boot] to bootstrap Spring Data JDBC, but still want to override certain aspects of the configuration, you may want to expose beans of that type.
For custom conversions you may e.g. choose to register a bean of type `JdbcCustomConversions` that will be picked up the by the Boot infrastructure.
For custom conversions you may e.g. choose to register a bean of type `JdbcCustomConversions` that will be picked up by the Boot infrastructure.
To learn more about this please make sure to read the Spring Boot https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#data.sql.jdbc[Reference Documentation].
To learn more about this please make sure to read the Spring Boot https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#data.sql.jdbc[Reference Documentation].
The query is derived by parsing the method name for constraints that can be concatenated with `And` and `Or`.
The query is derived by parsing the method name for constraints that can be concatenated with `And` and `Or`.
Thus, the method name results in a query expression of `SELECT … FROM person WHERE firstname = :firstname`.
Thus, the method name results in a query expression of `SELECT … FROM person WHERE firstname = :firstname`.
<2> Use `Pageable` to pass offset and sorting parameters to the database.
<2> Use `Pageable` to pass offset and sorting parameters to the database.
<3> Return a `Slice<Person>`.Selects `LIMIT+1` rows to determine whether there's more data to consume. `ResultSetExtractor` customization is not supported.
<3> Return a `Slice<Person>`.Selects `LIMIT+1` rows to determine whether there's more data to consume. `ResultSetExtractor` customization is not supported.
<4> Run a paginated query returning `Page<Person>`.Selects only data within the given page bounds and potentially a count query to determine the total count. `ResultSetExtractor` customization is not supported.
<4> Run a paginated query returning `Page<Person>`.Selects only data within the given page bounds and potentially a count query to determine the total count. `ResultSetExtractor` customization is not supported.
<5> Find a single entity for the given criteria.
<5> Find a single entity for the given criteria.
It completes with `IncorrectResultSizeDataAccessException` on non-unique results.
It completes with `IncorrectResultSizeDataAccessException` on non-unique results.
@ -143,7 +143,7 @@ NOTE: Query derivation is limited to properties that can be used in a `WHERE` cl
The JDBC module supports defining a query manually as a String in a `@Query` annotation or as named query in a property file.
The JDBC module supports defining a query manually as a String in a `@Query` annotation or as named query in a property file.
Deriving a query from the name of the method is is currently limited to simple properties, that means properties present in the aggregate root directly.
Deriving a query from the name of the method is currently limited to simple properties, that means properties present in the aggregate root directly.
Also, only select queries are supported by this approach.
Also, only select queries are supported by this approach.
For converting the query result into entities the same `RowMapper` is used by default as for the queries Spring Data JDBC generates itself.
For converting the query result into entities the same `RowMapper` is used by default as for the queries Spring Data JDBC generates itself.
The query you provide must match the format the `RowMapper` expects.
The query you provide must match the format the `RowMapper` expects.
Columns for all properties that are used in the constructor of an entity must be provided.
Columns for all properties that are used in the constructor of an entity must be provided.
Columns for properties that get set via setter, wither or field access are optional.
Columns for properties that get set via setter or field access are optional.
Properties that don't have a matching column in the result will not be set.
Properties that don't have a matching column in the result will not be set.
The query is used for populating the aggregate root, embedded entities and one-to-one relationships including arrays of primitive types which get stored and loaded as SQL-array-types.
The query is used for populating the aggregate root, embedded entities and one-to-one relationships including arrays of primitive types which get stored and loaded as SQL-array-types.
Separate queries are generated for maps, lists, sets and arrays of entities.
Separate queries are generated for maps, lists, sets and arrays of entities.
Properties one-to-one relationships must have there name prefixed by the name of the relationship plus `_`.
Properties one-to-one relationships must have their name prefixed by the name of the relationship plus `_`.
For example if the `User` from the example above has an `address` with the property `city` the column for that `city` must be labeled `address_city`.
For example if the `User` from the example above has an `address` with the property `city` the column for that `city` must be labeled `address_city`.
@ -190,7 +190,7 @@ Person findWithSpEL(PersonRef person);
----
----
This can be used to access members of a parameter, as demonstrated in the example above.
This can be used to access members of a parameter, as demonstrated in the example above.
For more involved use cases an `EvaluationContextExtension` can be made available in the application context, which in turn can make any object available in to the SpEL.
For more involved use cases an `EvaluationContextExtension` can be made available in the application context, which in turn can make any object available in the SpEL.
The other variant can be used anywhere in the query and the result of evaluating the query will replace the expression in the query string.
The other variant can be used anywhere in the query and the result of evaluating the query will replace the expression in the query string.
Column types are computed from an object implementing the `SqlTypeMapping` strategy interface.
Column types are computed from an object implementing the `SqlTypeMapping` strategy interface.
Nullability is inferred from the type and set to `false` if a property type use primitive Java types.
Nullability is inferred from the type and set to `false` if a property type uses primitive Java types.
Schema support can assist you throughout the application development lifecycle.
Schema support can assist you throughout the application development lifecycle.
In differential mode, you provide an existing Liquibase `Database` to the schema writer instance and the schema writer compares existing tables to mapped entities and derives from the difference which tables and columns to create/to drop.
In differential mode, you provide an existing Liquibase `Database` to the schema writer instance and the schema writer compares existing tables to mapped entities and derives from the difference which tables and columns to create/to drop.
By default, no tables and no columns are dropped unless you configure `dropTableFilter` and `dropColumnFilter`.
By default, no tables and no columns are dropped unless you configure `dropTableFilter` and `dropColumnFilter`.
Both filter predicate provide the table name respective column name so your code can computer which tables and columns can be dropped.
Both filter predicates provide the table name respective column name so your code can compute which tables and columns can be dropped.
@ -85,7 +85,7 @@ Thus, the method is with the `readOnly` flag set to `false`.
NOTE: It is highly recommended to make query methods transactional.
NOTE: It is highly recommended to make query methods transactional.
These methods might execute more than one query in order to populate an entity.
These methods might execute more than one query in order to populate an entity.
Without a common transaction Spring Data JDBC executes the queries in different connections.
Without a common transaction Spring Data JDBC executes the queries in different connections.
This may put excessive strain on the connection pool and might even lead to deadlocks when multiple methods request a fresh connection while holding on to one.
This may put excessive strain on the connection pool and might even lead to deadlocks when multiple methods request a fresh connection while holding on to one.
NOTE: It is definitely reasonable to mark read-only queries as such by setting the `readOnly` flag.
NOTE: It is definitely reasonable to mark read-only queries as such by setting the `readOnly` flag.
This does not, however, act as a check that you do not trigger a manipulating query (although some databases reject `INSERT` and `UPDATE` statements inside a read-only transaction).
This does not, however, act as a check that you do not trigger a manipulating query (although some databases reject `INSERT` and `UPDATE` statements inside a read-only transaction).
Nathan Xu
2 months ago
committed by
Jens Schauder