image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-jdbc%2Fmaster&subject=Moore%20(master)["Spring Data JDBC", link="https://jenkins.spring.io/view/SpringData/job/spring-data-jdbc/"]
image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-jdbc%2F1.0.x&subject=Lovelace%20(1.0.x)["Spring Data JDBC", link="https://jenkins.spring.io/view/SpringData/job/spring-data-jdbc/"]
== Running CI tasks locally
Since this pipeline is purely Docker-based, it's easy to:
* Debug what went wrong on your local machine.
* Test out a a tweak to your `test.sh` script before sending it out.
* Experiment against a new image before submitting your pull request.
All of these use cases are great reasons to essentially run what the CI server does on your local machine.
IMPORTANT: To do this you must have Docker installed on your machine.
image:https://spring.io/badges/spring-data-jdbc/ga.svg["Spring Data JDBC", link="https://spring.io/projects/spring-data-jdbc#learn"]
image:https://spring.io/badges/spring-data-jdbc/snapshot.svg["Spring Data JDBC", link="https://spring.io/projects/spring-data-jdbc#learn"]
image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-jdbc%2Fmaster&subject=Moore%20(master)["Spring Data JDBC", link="https://jenkins.spring.io/view/SpringData/job/spring-data-jdbc/"]
image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-jdbc%2F1.0.x&subject=Lovelace%20(1.0.x)["Spring Data JDBC", link="https://jenkins.spring.io/view/SpringData/job/spring-data-jdbc/"]
= Spring Data JDBC image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-jdbc%2Fmaster&subject=Build[link=https://jenkins.spring.io/view/SpringData/job/spring-data-jdbc/] https://gitter.im/spring-projects/spring-data[image:https://badges.gitter.im/spring-projects/spring-data.svg[Gitter]]
= Spring Data Relational
The primary goal of the https://projects.spring.io/spring-data[Spring Data] project is to make it easier to build Spring-powered applications that use new data access technologies such as non-relational databases, map-reduce frameworks, and cloud based data services.
The primary goal of the https://projects.spring.io/spring-data[Spring Data] project is to make it easier to build Spring-powered applications that use data access technologies. *Spring Data Relational* offers the popular Repository abstraction based on link:spring-data-jdbc[JDBC].
Spring Data JDBC, part of the larger Spring Data family, makes it easy to implement JDBC based repositories. This module deals with enhanced support for JDBC based data access layers. It makes it easier to build Spring powered applications that use data access technologies.
It aims at being conceptually easy.
In order to achieve this it does NOT offer caching, lazy loading, write behind or many other features of JPA.
@ -22,124 +21,155 @@ This makes Spring Data JDBC a simple, limited, opinionated ORM.
@@ -22,124 +21,155 @@ This makes Spring Data JDBC a simple, limited, opinionated ORM.
* JavaConfig based repository configuration by introducing `EnableJdbcRepository`
* Integration with MyBatis
== Maven Coordinates
== Code of Conduct
[source,xml]
----
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-jdbc</artifactId>
<version>1.1.0.BUILD-SNAPSHOT</version>
</dependency>
This project is governed by the link:CODE_OF_CONDUCT.adoc[Spring Code of Conduct]. By participating, you are expected to uphold this code of conduct. Please report unacceptable behavior to spring-code-of-conduct@pivotal.io.
== Getting Started
Here is a quick teaser of an application using Spring Data Repositories in Java:
[source,java]
----
public interface PersonRepository extends CrudRepository<Person, Long> {
== Modules
@Query("SELECT * FROM person WHERE lastname = :lastname")
List<Person> findByLastname(String lastname);
Spring Data Relational ships with multiple modules:
@Query("SELECT * FROM person WHERE firstname LIKE :lastname")
* Spring Data Relational: Common infrastructure abstracting general aspects of relational database access.
* link:spring-data-jdbc[Spring Data JDBC]: Repository support for JDBC-based datasources.
@Service
public class MyService {
== Getting Help
private final PersonRepository repository;
If you are new to Spring Data JDBC read the following two articles https://spring.io/blog/2018/09/17/introducing-spring-data-jdbc["Introducing Spring Data JDBC"] and https://spring.io/blog/2018/09/24/spring-data-jdbc-references-and-aggregates["Spring Data JDBC, References, and Aggregates"]
public MyService(PersonRepository repository) {
this.repository = repository;
}
There are also examples in the https://github.com/spring-projects/spring-data-examples/tree/master/jdbc[Spring Data Examples] project.
public void doWork() {
A very good source of information is the source code in this repository.
Especially the integration tests (if you are reading this on github, type `t` and then `IntegrationTests.java`)
repository.deleteAll();
We are keeping an eye on the https://stackoverflow.com/questions/tagged/spring-data-jdbc[spring-data-jdbc tag on stackoverflow].
Person person = new Person();
person.setFirstname("Jens");
person.setLastname("Schauder");
repository.save(person);
If you think you found a bug, or have a feature request please https://jira.spring.io/browse/DATAJDBC/?selectedTab=com.atlassian.jira.jira-projects-plugin:summary-panel[create a ticket in our issue tracker].
class ApplicationConfig extends AbstractJdbcConfiguration {
You don't need to build from source to use Spring Data Relational (binaries in https://repo.spring.io[repo.spring.io]).
If you want to try out the latest and greatest, Spring Data Relational can be easily built with Maven.
You also need JDK 1.8.
@Bean
public DataSource dataSource() {
return …;
}
[source]
----
$ mvn clean install
@Bean
public NamedParameterJdbcTemplate namedParameterJdbcTemplate(DataSource dataSource) {
return new NamedParameterJdbcTemplate(dataSource);
}
}
----
=== Fast running tests
=== Maven configuration
Fast running tests can be executed with a simple
Add the Maven dependency:
[source]
[source,xml]
----
$ mvn test
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-jdbc</artifactId>
<version>${version}.RELEASE</version>
</dependency>
----
This will execute unit tests and integration tests using an in-memory database.
=== Running tests with a real database
In order to run the integration tests against a specific database you need to have a local Docker installation available, and then execute.
If you'd rather like the latest snapshots of the upcoming major version, use our Maven snapshot repository and declare the appropriate dependency version.
[source]
[source,xml]
----
$ mvn test -Dspring.profiles.active=<databasetype>
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-jdbc</artifactId>
<version>${version}.BUILD-SNAPSHOT</version>
</dependency>
<repository>
<id>spring-libs-snapshot</id>
<name>Spring Snapshot Repository</name>
<url>https://repo.spring.io/libs-snapshot</url>
</repository>
----
This will also execute the unit tests.
== Getting Help
Currently the following _databasetypes_ are available:
Having trouble with Spring Data? We’d love to help!
* hsql (default, does not require a running database)
* mysql
* postgres
* mariadb
* mssql
* If you are new to Spring Data JDBC read the following two articles https://spring.io/blog/2018/09/17/introducing-spring-data-jdbc["Introducing Spring Data JDBC"] and https://spring.io/blog/2018/09/24/spring-data-jdbc-references-and-aggregates["Spring Data JDBC, References, and Aggregates"].
* Check the
https://docs.spring.io/spring-data/jdbc/docs/current/reference/html/[reference documentation], and https://docs.spring.io/spring-data/jdbc/docs/current/api/[Javadocs].
* Learn the Spring basics – Spring Data builds on Spring Framework, check the https://spring.io[spring.io] web-site for a wealth of reference documentation.
If you are just starting out with Spring, try one of the https://spring.io/guides[guides].
* If you are upgrading, check out the https://docs.spring.io/spring-data/jdbc/docs/current/changelog.txt[changelog] for "`new and noteworthy`" features.
* Ask a question - we monitor https://stackoverflow.com[stackoverflow.com] for questions tagged with https://stackoverflow.com/tags/spring-data[`spring-data-jdbc`].
You can also chat with the community on https://gitter.im/spring-projects/spring-data[Gitter].
* Report bugs with Spring Data JDBC at https://jira.spring.io/browse/DATAJDBC[jira.spring.io/browse/DATAJDBC].
=== Run tests with all databases
== Reporting Issues
[source]
----
$ mvn test -Pall-dbs
----
Spring Data uses JIRA as issue tracking system to record bugs and feature requests. If you want to raise an issue, please follow the recommendations below:
* Before you log a bug, please search the
https://jira.spring.io/browse/DATAJDBC[issue tracker] to see if someone has already reported the problem.
* If the issue doesn’t already exist, https://jira.spring.io/browse/DATAJDBC[create a new issue].
* Please provide as much information as possible with the issue report, we like to know the version of Spring Data that you are using and JVM version.
* If you need to paste code, or include a stack trace use JIRA `{code}…{code}` escapes before and after your text.
* If possible try to create a test-case or project that replicates the issue. Attach a link to your code or a compressed file containing your code.
== Building from Source
This will execute the unit tests, and all the integration tests with all the databases we currently support for testing. Running the integration-tests depends on Docker.
You don’t need to build from source to use Spring Data (binaries in https://repo.spring.io[repo.spring.io]), but if you want to try out the latest and greatest, Spring Data can be easily built with the https://github.com/takari/maven-wrapper[maven wrapper].
You also need JDK 1.8.
== Running CI tasks locally
[source,bash]
----
$ ./mvnw clean install
----
Since this pipeline is purely Docker-based, it's easy to:
If you want to build with the regular `mvn` command, you will need https://maven.apache.org/run-maven/index.html[Maven v3.5.0 or above].
* Debug what went wrong on your local machine.
* Test out a a tweak to your `test.sh` script before sending it out.
* Experiment against a new image before submitting your pull request.
_Also see link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] if you wish to submit pull requests, and in particular please sign the https://cla.pivotal.io/sign/spring[Contributor’s Agreement] before your first change, is trivial._
All of these use cases are great reasons to essentially run what the CI server does on your local machine.
=== Building reference documentation
IMPORTANT: To do this you must have Docker installed on your machine.
Building the documentation builds also the project without running tests.
This will launch the Docker image and mount your source code at `spring-data-jdbc-github`.
+
2. `cd spring-data-jdbc-github`
+
Next, test everything from inside the container:
+
3. `./mvnw -Pci,all-dbs clean dependency:list test -Dsort -B` (or whatever test configuration you must use)
[source,bash]
----
$ ./mvnw clean install -Pdistribute
----
Since the container is binding to your source, you can make edits from your IDE and continue to run build jobs.
The generated documentation is available from `target/site/reference/html/index.html`.
NOTE: Docker containers can eat up disk space fast! From time to time, run `docker system prune` to clean out old images.
== Modules
== Contributing to Spring Data Relational
There are a number of modules in this project, here is a quick overview:
Here are some ways for you to get involved in the community:
* Spring Data Relational: Common infrastructure abstracting general aspects of relational database access.
* link:spring-data-jdbc[Spring Data JDBC]: Repository support for JDBC-based datasources.
* Get involved with the Spring community by helping out on Stackoverflow for https://stackoverflow.com/questions/tagged/spring-data-jdbc[Spring Data JDBC] by responding to questions and joining the debate.
* Create https://jira.spring.io/browse/DATAJDBC[JIRA] tickets for bugs and new features and comment and vote on the ones that you are interested in.
* Github is for social coding: if you want to write code, we encourage contributions through pull requests from https://help.github.com/forking/[forks of this repository]. If you want to contribute code this way, please reference a JIRA ticket as well, covering the specific issue you are addressing.
* Watch for upcoming articles on Spring by https://spring.io/blog[subscribing] to spring.io.
== Examples
Before we accept a non-trivial patch or pull request we will need you to https://cla.pivotal.io/sign/spring[sign the Contributor License Agreement]. Signing the contributor’s agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. If you forget to do so, you'll be reminded when you submit a pull request. Active contributors might be asked to join the core team, and given the ability to merge pull requests.
* https://github.com/spring-projects/spring-data-examples/[Spring Data Examples] contains example projects that explain specific features in more detail.
== License
link:src/main/resources/license.txt[The license under which Spring Data Relational is published can be found here].
Spring Data JDBC is Open Source software released under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].
@ -79,14 +79,3 @@ mvn test -Pall-dbs
@@ -79,14 +79,3 @@ mvn test -Pall-dbs
----
This will execute the unit tests, and all the integration tests with all the databases we currently support for testing. Running the integration-tests depends on Docker.
== Contributing to Spring Data JDBC
Here are some ways for you to get involved in the community:
* Get involved with the Spring community by helping out on https://stackoverflow.com/questions/tagged/spring-data-jdbc[stackoverflow] by responding to questions and joining the debate.
* Create https://jira.spring.io/browse/DATAJDBC[JIRA] tickets for bugs and new features and comment and vote on the ones that you are interested in.
* Github is for social coding: if you want to write code, we encourage contributions through pull requests from https://help.github.com/forking/[forks of this repository]. If you want to contribute code this way, please reference a JIRA ticket as well, covering the specific issue you are addressing.
* Watch for upcoming articles on Spring by https://spring.io/blog[subscribing] to spring.io.
Before we accept a non-trivial patch or pull request we will need you to https://cla.pivotal.io/sign/spring[sign the Contributor License Agreement]. Signing the contributor’s agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. If you forget to do so, you'll be reminded when you submit a pull request. Active contributors might be asked to join the core team, and given the ability to merge pull requests.
Mark Paluch
7 years ago