Skip to content

Commit 6d2b421

Browse files
manticore-projectsmanticore-projects
committed
doc: migration guide
1 parent b6fab2a commit 6d2b421

File tree

3 files changed

+147
-24
lines changed

3 files changed

+147
-24
lines changed

‎README.md

Lines changed: 8 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,14 @@ SELECT 1 FROM dual WHERE a = b
1818
```
1919

2020
```text
21-
SQL Text
22-
└─Statements: net.sf.jsqlparser.statement.select.Select
23-
├─selectItems -> Collection<SelectItem>
24-
│ └─LongValue: 1
25-
├─Table: dual
26-
└─where: net.sf.jsqlparser.expression.operators.relational.EqualsTo
27-
├─Column: a
28-
└─Column: b
21+
SQL Text
22+
└─Statements: statement.select.PlainSelect
23+
├─selectItems: statement.select.SelectItem
24+
│ └─LongValue: 1
25+
├─Table: dual
26+
└─where: expression.operators.relational.EqualsTo
27+
├─Column: a
28+
└─Column: b
2929
```
3030

3131
```java
@@ -61,9 +61,6 @@ Assertions.assertEquals("b", b.getColumnName());
6161

6262
**JSqlParser** can also be used to create SQL Statements from Java Code with a fluent API (see [Samples](https://jsqlparser.github.io/JSqlParser/usage.html#build-a-sql-statements)).
6363

64-
## Alternatives to JSqlParser?
65-
[**General SQL Parser**](http://www.sqlparser.com/features/introduce.php?utm_source=github-jsqlparser&utm_medium=text-general) looks pretty good, with extended SQL syntax (like PL/SQL and T-SQL) and java + .NET APIs. The tool is commercial (license available online), with a free download option.
66-
6764
## [Documentation](https://jsqlparser.github.io/JSqlParser)
6865

6966
### [Samples](https://jsqlparser.github.io/JSqlParser/usage.html#parse-a-sql-statements)

‎src/site/sphinx/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ Java SQL Parser Library
1212

1313
usage
1414
contribution
15+
migration
1516
syntax_stable
1617
syntax_snapshot
1718
javadoc_stable

‎src/site/sphinx/migration.rst

Lines changed: 138 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,146 @@
11
*********************************
2-
Migration to JSQLParser Version 5
2+
Migration to 5.0
33
*********************************
44

5-
* ``ValueListExpression`` has been replaced by ``Values``, which implements ``Select`` `Statement` and `Expression`
6-
* ``ValuesStatement`` has been replaced by ``Values``, which implements ``Select`` `Statement` and `Expression`
7-
* ``ItemsList`` has been removed and ``ExpressionList`` is used instead
8-
* ``MultiExpressionList`` has been removed and ``ExpressionList`` is used instead (with ``ExpressionList`` elements)
9-
* ``SelectBody`` has been removed and `PlainSelect` can be used directly
10-
* ``SubJoin`` has been removed, using normal ```ParenthesedFromItem`` instead
11-
* ``SubSelect`` has been removed and any instance of ``Select`` (`PlainSelect`, `Values` or `SetOperationList`) can be used instead
12-
*
5+
`Values` Clause
6+
---------------------------------
7+
The ``ValueListExpression`` has been replaced by ``Values``, which implements ``Select`` `Statement` and `Expression`.
138

14-
* `hasBrackets()`, 'isUsingBrackets()' and similar methods have been removed, instead the Parser will return ``ParenthesedExpressionList`` or ``ParenthesedSelect`` or ```ParenthesedFromItem`` or ``Parenthesis`` wrapping the object within brackets
9+
The ``ValuesStatement`` has been replaced by ``Values``, which implements ``Select`` `Statement` and `Expression`.
1510

16-
* any instance of `List<Expression>` is considered an Anti Pattern and `ExpressionList<?>` shall be used instead
11+
.. tab:: Statement
1712

18-
* ``List<UpdateSet>`` is used for any `Set` clause within `Insert`, `Update`, `Upsert` or `Merge` statements
13+
.. code-block:: SQL
14+
:caption: `VALUES` examples
1915
20-
* ``Statements`` extends `List<Statement>` directly and so ``Statements.getStatements()`` is obsolete
16+
VALUES ( 1, 2, 3 )
17+
;
18+
19+
20+
.. code-block:: TEXT
21+
:caption: AST for the `VALUES` examples
22+
23+
SQL Text
24+
└─Statements: statement.select.Values
25+
└─ParenthesedExpressionList: (1, 2, 3)
26+
27+
.. raw:: html
28+
29+
<pre>
30+
SQL Text
31+
└─<span style="color: #000080;">Statements</span>: <span style="color: #808000;">statement.select.PlainSelect</span>
32+
├─<span style="color: #000080;">selectItems</span>: <span style="color: #808000;">statement.select.SelectItem</span>
33+
│ └─<span style="color: #000080;">AllColumns</span>: <span style="color: #808000;">*</span>
34+
├─<span style="color: #000080;">Table</span>: <span style="color: #808000;">cfe.test</span>
35+
└─<span style="color: #000080;">where</span>: <span style="color: #808000;">expression.operators.relational.EqualsTo</span>
36+
├─<span style="color: #000080;">Column</span>: <span style="color: #808000;">a</span>
37+
└─<span style="color: #000080;">Column</span>: <span style="color: #808000;">b</span>
38+
39+
</pre>
40+
41+
42+
43+
.. tab:: Sub-query
44+
45+
.. code-block:: SQL
46+
:caption: `VALUES` examples
47+
48+
SELECT *
49+
FROM ( VALUES 1, 2, 3 )
50+
;
51+
52+
53+
.. code-block:: TEXT
54+
:caption: AST for the `VALUES` examples
55+
56+
SQL Text
57+
└─Statements: statement.select.PlainSelect
58+
├─selectItems: statement.select.SelectItem
59+
│ └─AllColumns: *
60+
└─fromItem: statement.select.ParenthesedSelect
61+
└─select: statement.select.Values
62+
└─ExpressionList: 1, 2, 3
63+
64+
.. tab:: Expression
65+
66+
.. code-block:: SQL
67+
:caption: `VALUES` examples
68+
69+
UPDATE test
70+
SET ( a
71+
, b
72+
, c ) = ( VALUES 1, 2, 3 )
73+
;
74+
75+
76+
.. code-block:: TEXT
77+
:caption: AST for the `VALUES` examples
78+
79+
SQL Text
80+
└─Statements: statement.update.Update
81+
├─Table: test
82+
└─updateSets: statement.update.UpdateSet
83+
├─ParenthesedExpressionList: (a, b, c)
84+
└─ExpressionList: (VALUES 1, 2, 3)
85+
86+
.. tab:: Clause
87+
88+
.. code-block:: SQL
89+
:caption: `VALUES` examples
90+
91+
INSERT INTO test
92+
VALUES ( 1, 2, 3 )
93+
;
94+
95+
.. code-block:: TEXT
96+
:caption: AST for the `VALUES` examples
97+
98+
SQL Text
99+
└─Statements: statement.insert.Insert
100+
├─Table: test
101+
└─select: statement.select.Values
102+
└─ParenthesedExpressionList: (1, 2, 3)
103+
104+
`Expression` Lists
105+
---------------------------------
106+
107+
The class ``ExpressionList`` extends ``List<Expression>`` directly and so ``ExpressionList.getExpressions()`` is obsolete.
108+
109+
Any instance of `List<Expression>` is considered an Anti Pattern and the class ``ExpressionList<T extends Expression>`` shall be used instead.
110+
111+
``ItemsList`` has been removed and ``ExpressionList`` is used instead.
112+
113+
``MultiExpressionList`` has been removed and ``ExpressionList`` is used instead (with ``ExpressionList`` elements).
114+
115+
Generic `SelectItem`
116+
---------------------------------
117+
118+
The class ``SelectItem<T extends Expression>`` is now generic and various derivatives (e. |_| g. ``SelectExpressionItem``, ``FunctionItem``, ``ExpressionListItem``) have been removed.
119+
120+
121+
`Select` Statement
122+
---------------------------------
123+
124+
``SelectBody`` has been removed and `PlainSelect` can be used directly
125+
126+
``SubJoin`` has been replaced by `ParenthesedFromItem`` (implementing a ``FromItem`` with a regular list of ``Join``)
127+
128+
``SubSelect`` has been removed and any instance of ``Select`` (`PlainSelect`, `Values` or `SetOperationList`) can be used instead
129+
130+
Brackets
131+
---------------------------------
132+
133+
Any `hasBrackets()`, `isUsingBrackets()` and similar methods have been removed; instead the Parser will return a ``ParenthesedExpressionList`` or ``ParenthesedSelect`` or ```ParenthesedFromItem`` or ``Parenthesis`` wrapping the object within brackets.
134+
135+
This allows for much better bracket handling.
136+
137+
`UpdateSet` clause
138+
---------------------------------
139+
140+
A ``List<UpdateSet>`` is used for any `Set` clause within `Insert`, `Update`, `Upsert` or `Merge` statements.
141+
142+
`Statements` collection
143+
---------------------------------
144+
145+
The ``Statements`` class extends `List<Statement>` directly and so ``Statements.getStatements()`` is obsolete.
21146

0 commit comments

Comments
 (0)