Skip to content

Commit db65b14

Browse files
bsboddenbsbodden
committed
docs: add migration guide for Spring Boot 3.5.x and Jedis 6.0.0
- Add comprehensive migration guide documenting Jedis 6.0.0 query escaping changes - Update version requirements page with Spring Boot 3.5.8 and Jedis 6.0.0 - Add migration guide to documentation navigation - Include before/after code examples for query string updates - Document who is affected by the Jedis breaking change The Jedis 6.0.0 upgrade changes how multi-word search terms are quoted in RediSearch queries. Users with custom repository implementations need to update from single quotes to double quotes.
1 parent dacea95 commit db65b14

File tree

3 files changed

+126
-11
lines changed

3 files changed

+126
-11
lines changed

‎docs/content/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
* xref:version-requirements.adoc[Version Requirements]
88
* xref:configuration.adoc[Configuration]
99
* xref:quickstart.adoc[Quick Start Example]
10+
* xref:migration-guide.adoc[Migration Guide]
1011
1112
.Core Concepts
1213
* xref:data-models.adoc[Redis Data Models]

‎docs/content/modules/ROOT/pages/migration-guide.adoc‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
= Migration Guide
2+
:navtitle: Migration Guide
3+
4+
This guide helps you migrate between major versions of Redis OM Spring.
5+
6+
== Upgrading to 1.1.0 (Spring Boot 3.5.x)
7+
8+
Redis OM Spring 1.1.0 introduces support for Spring Boot 3.5.x and includes important dependency upgrades.
9+
10+
=== Dependency Changes
11+
12+
[cols="1,1,1"]
13+
|===
14+
|Dependency |Previous Version |New Version
15+
16+
|Spring Boot
17+
|3.4.x
18+
|3.5.8
19+
20+
|Spring Data Redis
21+
|3.4.x
22+
|3.5.6
23+
24+
|Jedis
25+
|5.2.0
26+
|6.0.0
27+
|===
28+
29+
=== Breaking Changes
30+
31+
==== Jedis 6.0.0 Query Escaping
32+
33+
**Impact:** Users writing custom RediSearch queries using Jedis directly.
34+
35+
Jedis 6.0.0 changed how it handles query string escaping for RediSearch queries. Multi-word search terms must now use double quotes (`"`) instead of single quotes (`'`).
36+
37+
**Before (Jedis 5.2.0):**
38+
[source,java]
39+
----
40+
SearchOperations<String> ops = modulesOperations.opsForSearch("myIndex");
41+
SearchResult result = ops.search(new Query("@title:'hello world'"));
42+
----
43+
44+
**After (Jedis 6.0.0):**
45+
[source,java]
46+
----
47+
SearchOperations<String> ops = modulesOperations.opsForSearch("myIndex");
48+
SearchResult result = ops.search(new Query("@title:\"hello world\""));
49+
----
50+
51+
**Who is affected:**
52+
53+
* Users implementing custom repository methods that construct `Query` objects with Jedis
54+
* Users directly using `SearchOperations` with string-based queries containing spaces
55+
56+
**Who is NOT affected:**
57+
58+
* Users only using Redis OM Spring's built-in repository query methods
59+
* Users using Entity Streams API
60+
* Users using `@Query` annotations (these are handled internally by Redis OM Spring)
61+
62+
=== Migration Steps
63+
64+
. Update your `pom.xml` or `build.gradle` to use Redis OM Spring 1.1.0
65+
. If you have custom repository implementations using Jedis `Query` objects:
66+
.. Review all custom query strings
67+
.. Replace single quotes with double quotes around multi-word search terms
68+
.. Test your custom queries thoroughly
69+
70+
=== Example Migration
71+
72+
Here's a complete example of migrating a custom repository method:
73+
74+
.Before (1.0.x)
75+
[source,java]
76+
----
77+
@Override
78+
public Optional<MyEntity> findByTitle(String title) {
79+
SearchOperations<String> ops = modulesOperations.opsForSearch(MyEntity.class.getName() + "Idx");
80+
SearchResult result = ops.search(new Query("@title:'" + title + "'")); // <1>
81+
if (result.getTotalResults() > 0) {
82+
Document doc = result.getDocuments().get(0);
83+
return Optional.of(ObjectUtils.documentToEntity(doc, MyEntity.class, converter));
84+
}
85+
return Optional.empty();
86+
}
87+
----
88+
<1> Single quotes around the title value
89+
90+
.After (1.1.0)
91+
[source,java]
92+
----
93+
@Override
94+
public Optional<MyEntity> findByTitle(String title) {
95+
SearchOperations<String> ops = modulesOperations.opsForSearch(MyEntity.class.getName() + "Idx");
96+
SearchResult result = ops.search(new Query("@title:\"" + title + "\"")); // <1>
97+
if (result.getTotalResults() > 0) {
98+
Document doc = result.getDocuments().get(0);
99+
return Optional.of(ObjectUtils.documentToEntity(doc, MyEntity.class, converter));
100+
}
101+
return Optional.empty();
102+
}
103+
----
104+
<1> Double quotes around the title value
105+
106+
=== Testing Your Migration
107+
108+
After upgrading, ensure you test:
109+
110+
. All custom repository methods that use Jedis `Query` objects
111+
. Any direct usage of `SearchOperations`
112+
. Integration tests with multi-word search terms
113+
114+
The Redis OM Spring test suite includes comprehensive tests for query escaping. Refer to the test examples in the repository for best practices.

‎docs/content/modules/ROOT/pages/version-requirements.adoc‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,12 @@ Redis OM Spring has the following version requirements:
1919

2020
|Spring Boot
2121
|3.3.x
22-
|3.4.x or 3.5.x
23-
|Built with Spring Boot 3.4.5
22+
|3.5.8 or later
23+
|Built with Spring Boot 3.5.8
2424

2525
|Spring Data Redis
2626
|3.4.1
27-
|3.4.5 or later
27+
|3.5.6 or later
2828
|Aligned with Spring Boot version
2929

3030
|Spring Framework
@@ -33,9 +33,9 @@ Redis OM Spring has the following version requirements:
3333
|Transitive via Spring Boot
3434

3535
|Jedis
36-
|5.2.0
37-
|5.2.0 or later
38-
|Redis Java client
36+
|6.0.0
37+
|6.0.0 or later
38+
|Redis Java client. **Breaking change in 6.0.0** - see xref:migration-guide.adoc[Migration Guide]
3939

4040
|Java
4141
|17
@@ -58,11 +58,11 @@ Redis OM Spring follows an **N-2 support policy** for Spring Boot versions:
5858

5959
=== Example
6060

61-
As of Redis OM Spring 1.0.0-RC4 (August 2025):
61+
As of Redis OM Spring 1.1.0 (November 2025):
6262

63-
* **Built with**: Spring Boot 3.4.8
63+
* **Built with**: Spring Boot 3.5.8
6464
* **Minimum supported**: Spring Boot 3.3.x (OSS support until June 2025)
65-
* **Recommended**: Spring Boot 3.4.x or 3.5.x
65+
* **Recommended**: Spring Boot 3.5.x
6666

6767
[WARNING]
6868
====
@@ -146,8 +146,8 @@ When using Redis OM Spring, ensure your dependencies are aligned:
146146
[source,xml]
147147
----
148148
<properties>
149-
<spring-boot.version>3.4.5</spring-boot.version>
150-
<redis-om-spring.version>1.0.0-RC4</redis-om-spring.version>
149+
<spring-boot.version>3.5.8</spring-boot.version>
150+
<redis-om-spring.version>1.1.0</redis-om-spring.version>
151151
</properties>
152152
153153
<dependencies>

0 commit comments

Comments
 (0)