1## Migrating Between Versions
2
3* [To v8](#v8)
4* [To v7](#v7)
5
6<a name="v8"></a>
7### `v7 to v8`
8
9A major change the the API was made in `v8` to seperate concerns between the different SQL statement types.
10
11**Why the change?**
12
131. There were feature requests that could not be cleanly implemented with everything in a single dataset.
142. Too much functionality was encapsulated in a single datastructure.
15 * It was unclear what methods could be used for each SQL statement type.
16 * Changing a feature for one statement type had the possiblity of breaking another statement type.
17 * Test coverage was decent but was almost solely concerned about SELECT statements, breaking them up allowed for focused testing on each statement type.
18 * Most the SQL generation methods (`ToInsertSQL`, `ToUpdateSQL` etc.) took arguments which lead to an ugly API that was not uniform for each statement type, and proved to be inflexible.
19
20**What Changed**
21
22There are now five dataset types, `SelectDataset`, `InsertDataset`, `UpdateDataset`, `DeleteDataset` and `TruncateDataset`
23
24Each dataset type has its own entry point.
25
26* `goqu.From`, `Database#From`, `DialectWrapper#From` - Create SELECT
27* `goqu.Insert`, `Database#Insert`, `DialectWrapper#Insert` - Create INSERT
28* `goqu.Update`, `Database#db.Update`, `DialectWrapper#Update` - Create UPDATE
29* `goqu.Delete`, `Database#Delete`, `DialectWrapper#Delete` - Create DELETE
30* `goqu.Truncate`, `Database#Truncate`, `DialectWrapper#Truncate` - Create TRUNCATE
31
32`ToInsertSQL`, `ToUpdateSQL`, `ToDeleteSQL`, and `ToTruncateSQL` (and variations of them) methods have been removed from the `SelectDataset`. Instead use the `ToSQL` methods on each dataset type.
33
34Each dataset type will have an `Executor` and `ToSQL` method so a common interface can be created for each type.
35
36**How to insert.**
37
38In older versions of `goqu` there was `ToInsertSQL` method on the `Dataset` in the latest version there is a new entry point to create INSERTS.
39
40```go
41// old way
42goqu.From("test").ToInsertSQL(...rows)
43
44// new way
45goqu.Insert("test").Rows(...rows).ToSQL()
46goqu.From("test").Insert().Rows(...rows).ToSQL()
47```
48
49In older versions of `goqu` there was `Insert` method on the `Dataset` to execute an insert in the latest version there is a new `Exectutor` method.
50
51```go
52// old way
53db.From("test").Insert(...rows).Exec()
54
55// new way
56db.Insert("test").Rows(...rows).Executor().Exec()
57// or
58db.From("test").Insert().Rows(...rows).Executor().Exec()
59```
60
61The new `InsertDataset` also has an `OnConflict` method that replaces the `ToInsertConflictSQL` and `ToInsertIgnoreSQL`
62
63```go
64// old way
65goqu.From("test").ToInsertIgnoreSQL(...rows)
66
67// new way
68goqu.Insert("test").Rows(...rows).OnConflict(goqu.DoNothing()).ToSQL()
69// OR
70goqu.From("test").Insert().Rows(...rows).OnConflict(goqu.DoNothing()).ToSQL()
71```
72
73```go
74// old way
75goqu.From("items").ToInsertConflictSQL(
76 goqu.DoUpdate("key", goqu.Record{"updated": goqu.L("NOW()")}),
77 goqu.Record{"name": "Test1", "address": "111 Test Addr"},
78 goqu.Record{"name": "Test2", "address": "112 Test Addr"},
79)
80fmt.Println(sql, args)
81
82// new way
83goqu.Insert("test").
84 Rows(
85 goqu.Record{"name": "Test1", "address": "111 Test Addr"},
86 goqu.Record{"name": "Test2", "address": "112 Test Addr"},
87 ).
88 OnConflict(goqu.DoUpdate("key", goqu.Record{"updated": goqu.L("NOW()")})).
89 ToSQL()
90// OR
91goqu.From("test").
92 Insert().
93 Rows(
94 goqu.Record{"name": "Test1", "address": "111 Test Addr"},
95 goqu.Record{"name": "Test2", "address": "112 Test Addr"},
96 ).
97 OnConflict(goqu.DoUpdate("key", goqu.Record{"updated": goqu.L("NOW()")})).
98 ToSQL()
99```
100
101**How to update.**
102
103In older versions of `goqu` there was `ToUpdateSQL` method on the `Dataset` in the latest version there is a new entry point to create UPDATEs.
104
105```go
106// old way
107goqu.From("items").ToUpdateSQL(
108 goqu.Record{"name": "Test", "address": "111 Test Addr"},
109)
110
111// new way
112goqu.Update("items").
113 Set(goqu.Record{"name": "Test", "address": "111 Test Addr"}).
114 ToSQL()
115// OR
116goqu.From("items").
117 Update()
118 Set(goqu.Record{"name": "Test", "address": "111 Test Addr"}).
119 ToSQL()
120```
121
122In older versions of `goqu` there was `Insert` method on the `Dataset` to execute an insert in the latest version there is a new `Exectutor` method.
123
124```go
125// old way
126db.From("items").Update(
127 goqu.Record{"name": "Test", "address": "111 Test Addr"},
128).Exec()
129
130// new way
131db.Update("items").
132 Set(goqu.Record{"name": "Test", "address": "111 Test Addr"}).
133 Executor().Exec()
134// OR
135db.From("items").
136 Update().
137 Set(goqu.Record{"name": "Test", "address": "111 Test Addr"}).
138 Executor().Exec()
139
140```
141
142**How to delete.**
143
144In older versions of `goqu` there was `ToDeleteSQL` method on the `Dataset` in the latest version there is a new entry point to create DELETEs.
145
146```go
147// old way
148goqu.From("items").
149 Where(goqu.Ex{"id": goqu.Op{"gt": 10}}).
150 ToDeleteSQL()
151
152// new way
153goqu.Delete("items").
154 Where(goqu.Ex{"id": goqu.Op{"gt": 10}}).
155 ToSQL()
156// OR
157goqu.From("items").
158 Delete()
159 Where(goqu.Ex{"id": goqu.Op{"gt": 10}}).
160 ToSQL()
161```
162
163In older versions of `goqu` there was `Delete` method on the `Dataset` to execute an insert in the latest version there is a new `Exectutor` method.
164
165```go
166// old way
167db.From("items").
168 Where(goqu.Ex{"id": goqu.Op{"gt": 10}}).
169 Delete().Exec()
170
171// new way
172db.Delete("items").
173 Where(goqu.Ex{"id": goqu.Op{"gt": 10}}).
174 Executor().Exec()
175// OR
176db.From("items").
177 Delete()
178 Where(goqu.Ex{"id": goqu.Op{"gt": 10}}).
179 Executor().Exec()
180```
181
182**How to truncate.**
183
184In older versions of `goqu` there was `ToTruncateSQL` method on the `Dataset` in the latest version there is a new entry point to create TRUNCATEs.
185
186```go
187// old way
188goqu.From("items").ToTruncateSQL()
189
190// new way
191goqu.Truncate("items").ToSQL()
192```
193
194<a name="v7"></a>
195### `<v7 to v7`
196
197* Updated all sql generations methods to from `Sql` to `SQL`
198 * `ToSql` -> `ToSQL`
199 * `ToInsertSql` -> `ToInsertSQL`
200 * `ToUpdateSql` -> `ToUpdateSQL`
201 * `ToDeleteSql` -> `ToDeleteSQL`
202 * `ToTruncateSql` -> `ToTruncateSQL`
203* Abstracted out `dialect_options` from the adapter to make the dialect self contained.
204 * This also removed the `dataset<->adapter` co dependency making the dialect self contained.
205 * Added new dialect options to specify the order than SQL statements are built.
206* Refactored the `goqu.I` method.
207 * Added new `goqu.S`, `goqu.T` and `goqu.C` methods to clarify why type of identifier you are using.
208 * `goqu.I` should only be used when you have a qualified identifier (e.g. `goqu.I("my_schema.my_table.my_col")
209* Added new `goqu.Dialect` method to make using `goqu` as an SQL builder easier.
210
211
212
View as plain text