You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: source/documentation/auto-macros.html.md.erb
+23-13Lines changed: 23 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -8,13 +8,13 @@ title: Auto Macros - ScalikeJDBC
8
8
### Avoid Boilerplate Code
9
9
<hr/>
10
10
11
-
You can avoid writing boilerplate code when using `scalikejdbc-syntax-support-macro`.
11
+
If you want to avoid writing lots of boilerplate code, `scalikejdbc-syntax-support-macro` can be greatly helpful for reducing such troublesome coding tasks.
12
12
13
13
<hr/>
14
14
### Setup
15
15
<hr/>
16
16
17
-
Add the following aditional dependency to your sbt project.
17
+
In addition to the core library, you can add the following optional dependency in `buid.sbt`:
#### autoConstruct for extracting entities from ResultSet
28
28
29
-
Usually, we should write ResultSet extractor method as follows.
29
+
When you don't use the macros, the usual code to extract data from `ResultSet` should look like below:
30
30
31
31
```scala
32
-
case class Company(id: Long, name: String, countryId: Option[Long], country: Option[Country] = None)
32
+
case class Company(
33
+
id: Long,
34
+
name: String,
35
+
countryId: Option[Long],
36
+
country: Option[Country] = None
37
+
)
33
38
34
39
object Company extends SQLSyntaxSupport[Company] {
35
40
@@ -41,31 +46,36 @@ object Company extends SQLSyntaxSupport[Company] {
41
46
}
42
47
```
43
48
44
-
When using scalikejdbc-syntax-support-macro, you can use `#autoConstruct` macro.
49
+
When using scalikejdbc-syntax-support-macro, you can use `#autoConstruct` macro instead. As you can see, now the code is significantly simpler and much easier to maintain for the future.
45
50
46
51
```scala
47
-
case class Company(id: Long, name: String, countryId: Option[Long], country: Option[Country] = None)
52
+
case class Company(
53
+
id: Long,
54
+
name: String,
55
+
countryId: Option[Long],
56
+
// This property never comes from ResultSet
57
+
country: Option[Country] = None
58
+
)
48
59
49
60
object Company extends SQLSyntaxSupport[Company] {
50
61
51
62
def apply(rs: WrappedResultSet, rn: ResultName[Company]): Company =
52
-
autoConstruct(rs, rn, "country") // "country" will be ignored when binding values from ResultSet
63
+
// "country" is execluded when binding values from ResultSet
64
+
// Note that the property neeeds to have the default `None` value
65
+
autoConstruct(rs, rn, "country")
53
66
}
54
67
```
55
68
56
69
The `#autoConstruct` method binds all the fields defined at the primary constructor automatically.
57
70
58
-
The `country` field in the above example class should be ignored. In such cases, you should specify additional String parameter such as `"country"`.
59
-
Of course, the `"country"` will be verified at Scala compilation time. We believe that's pretty cool and useful.
60
-
71
+
The `country` field in the above example class should be ignored. In such cases, you should specify an additional String parameter such as "country". Of course, the "country" will be verified at Scala compilation time!
61
72
62
73
<hr/>
63
74
#### autoColumns to avoid accessing JDBC metadata
64
75
65
-
When your code load ScalikeJDBC DAO objects, ScalikeJDBC automatically fetches all the column names for the table specified by SQLSyntaxSupport's `tableName` (via JDBC metadata API).
76
+
When your code loads ScalikeJDBC DAO objects, ScalikeJDBC automatically fetches all the column names for the table specified by `SQLSyntaxSupport`'s `tableName` via the JDBC metadata API.
66
77
67
-
If you don't prefer the behavior, you can choose loading column names from the entity class's field names instead.
68
-
The following code won't access JDBC metadata and will resolve column names from Company class's fields, primary constructor's parameters, by simply converting them to snake-cased ones or applying nameConverters to them.
78
+
If you don't prefer the behavior, you can choose to load column names from the entity class's field names instead. The following code won't access JDBC metadata and will resolve column names from the `Company` class's fields and primary constructor's parameters by simply converting them to snake-cased ones or applying name converters to them.
69
79
70
80
```scala
71
81
case class Company(id: Long, name: String, countryId: Option[Long], country: Option[Country] = None)
Copy file name to clipboardExpand all lines: source/documentation/auto-session.html.md
+9-16Lines changed: 9 additions & 16 deletions
Original file line number
Diff line number
Diff line change
@@ -8,9 +8,7 @@ title: Auto Session - ScalikeJDBC
8
8
### Why AutoSession?
9
9
<hr/>
10
10
11
-
Basic usage of ScalikeJDBC is using `DB.autoCommit/readOnly/localTx/withinTx { ...}` blocks.
12
-
13
-
However, if you'd like to re-use methods, they might not be available.
11
+
Typically, ScalikeJDBC operations are encapsulated within `DB.autoCommit`, `DB.readOnly`, and other transaction blocks. For reusing methods across different transaction contexts as below,
When you use the above method in a transaction block, the code won't work as you expected.
23
-
24
-
The reason is that since `#findById(Long)` uses another session(=connection), it couldn't access uncommitted data.
20
+
`AutoSession` becomes essential. In a transaction block, this method may not perform as expected because it uses a separate session and cannot access uncommitted data. The reason is that since `#findById(Long)` uses another session(=connection), it couldn't access uncommitted data.
25
21
26
22
```scala
27
23
DB localTx { implicit session =>
@@ -30,15 +26,15 @@ DB localTx { implicit session =>
30
26
}
31
27
```
32
28
33
-
You need to changemethod's API to accept implicit parameters and now you don't need `DB`block inside the method.
29
+
With this change, the method can access the current transaction context. Instead of having `DB`blocks inside, your method can accept an implict DBSession paramter from external code to join an existing transactional session.
sql"select id, name from members where id = ${id}"
38
34
.map(rs =>Member(rs)).single.apply()
39
35
```
40
36
41
-
This one works as expected.
37
+
With the change, the following code works as you expect.
42
38
43
39
```scala
44
40
DB localTx { implicit session =>
@@ -47,7 +43,7 @@ DB localTx { implicit session =>
47
43
}
48
44
```
49
45
50
-
But unfortunately, now we need to pass implicit parameter to `#findById` every time to use it.
46
+
But unfortunately, now that we need to pass implicit parameter to `#findById` every time to use the method, it could be troublesome especially for simple code snippets.
51
47
52
48
```scala
53
49
// now we cannot use this method directly
@@ -56,22 +52,22 @@ findById(id) // implicit parameter not found!
56
52
DB readOnly { implicit session => findById(id) }
57
53
```
58
54
59
-
`AutoSession` is a solution for this issue. Use`AutoSession` as default value of the implicit parameter.
55
+
`AutoSession` is a solution for the issue. You can have`AutoSession` as default value of the implicit parameter.
Since version 1.7.4, `ReadOnlyAutoSession` and `NamedReadOnlyAutoSession` is also available.
86
-
87
-
These auto sessions disallow update/execute operations.
88
-
81
+
Since version 1.7.4, `ReadOnlyAutoSession` and `NamedReadOnlyAutoSession` is also available, which are tailored for read-only operations, preventing any update or execute operations.
However many modern JDBC implementations will be automatically loaded when they are present on the classpath.
27
-
28
-
If you use `scalikejdbc-config` or `scalikejdbc-play-plugin`, they do the legacy work for you.
26
+
Many modern JDBC drivers, however, automatically load themselves when included in the classpath. Nonetheless, when you're using `scalikejdbc-config` or `scalikejdbc-play-plugin`, these handle the above loading process for safety.
29
27
30
28
<hr/>
31
29
### Connection Pool Settings
32
30
<hr/>
33
31
34
-
ConnectionPool should be initialized when starting your applications.
32
+
It's required to initialize a ConnectionPool at the start of your applications:
35
33
36
34
```scala
37
35
importscalikejdbc._
@@ -50,7 +48,7 @@ val settings = ConnectionPoolSettings(
Further details in the [source code](https://github.com/scalikejdbc/scalikejdbc/blob/master/scalikejdbc-core/src/main/scala/scalikejdbc/ConnectionPool.scala)
86
84
87
85
88
86
<hr/>
89
87
### Global Settings
90
88
<hr/>
91
89
92
-
Global settings for logging for query inspection and so on.
90
+
Configure global settings for SQL error logging, query inspection, and more:
Reference the [source code](https://github.com/scalikejdbc/scalikejdbc/blob/master/scalikejdbc-core/src/main/scala/scalikejdbc/GlobalSettings.scala) for more details.
106
104
107
105
<hr/>
108
106
### scalikejdbc-config
109
107
<hr/>
110
108
111
-
If you use `scalikejdbc-config`which is an easy-to-use configuration loader for ScalikeJDBC which reads typesafe config, configuration is much simple.
109
+
The `scalikejdbc-config`library simplifies the configuration process by utilizing Typesafe Config to read settings:
After just calling `scalikejdbc.config.DBs.setupAll()`, Connection pools are prepared. `DBs.setup/DBs.setupAll`loads specified JDBC driver classes as well.
149
+
When setting up with `scalikejdbc.config.DBs.setupAll()`, the module automatically loads the specified JDBC drivers and prepares connection pools.
152
150
153
-
Note that due to the way JDBC works, these drivers are loaded globally for the entire JVM, and then a particular driver is selected from the global JVM list by locating the first which is able to handle the connection URL. This usually produces the expected behaviour anyway, unless you have multiple JDBC drivers in your classpath which handle the same URL (such as MySQL and MariaDB JDBC implementations, which both handle URLs of the form `jdbc:mysql:`). In these cases you may not get the implementation you are expecting, since the presence of JDBC packages in the classpath is, for many drivers, enough to have them registered globally.
151
+
DBC drivers, once loaded, are globally available to the entire Java Virtual Machine (JVM). The selection process for a specific driver from the global list typically targets the first one capable of managing the given connection URL. This approach generally yields the correct behavior, except when multiple drivers capable of handling the same URL type (such as MySQL and MariaDB drivers, both supporting `jdbc:mysql:` URLs) are present in the classpath. In such cases, the expected driver might not be used, as the mere presence of JDBC drivers on the classpath often leads to their global registration, irrespective of their intended use.
154
152
155
153
```scala
156
154
importscalikejdbc._
@@ -180,7 +178,7 @@ DBs.closeAll()
180
178
### scalikejdbc-config with Environment
181
179
<hr/>
182
180
183
-
It's also possible to add prefix(e.g. environment).
181
+
You can manage different configurations for multiple environments:
184
182
185
183
```
186
184
development.db.default.driver="org.h2.Driver"
@@ -199,8 +197,7 @@ prod {
199
197
}
200
198
}
201
199
```
202
-
203
-
Use `DBsWithEnv` instead of `DBs`.
200
+
To activate these settings, use `DBsWithEnv` instead of `DBs`.
0 commit comments