Skip to content

Commit 3d7170f

Browse files
grouegroue
committed
DocC: Configuration
1 parent 2c5a864 commit 3d7170f

File tree

3 files changed

+113
-96
lines changed

3 files changed

+113
-96
lines changed

‎GRDB/Core/Configuration.swift‎

Lines changed: 0 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,6 @@
11
import Dispatch
22
import Foundation
33

4-
/// The configuration of a database connection.
5-
///
6-
/// You create a `Configuration` before opening a database connection:
7-
///
8-
/// ```swift
9-
/// var config = Configuration()
10-
/// config.readonly = true
11-
/// config.maximumReaderCount = 2 // (DatabasePool only) The default is 5
12-
/// config.prepareDatabase { db in // A function to run on connection
13-
/// db.trace { print("SQL >", $0) }
14-
/// }
15-
///
16-
/// let dbQueue = try DatabaseQueue( // or DatabasePool
17-
/// path: "/path/to/database.sqlite",
18-
/// configuration: config)
19-
/// ```
20-
///
21-
/// See <doc:DatabaseConnections>.
22-
///
23-
/// ## Topics
24-
///
25-
/// ### Creating a Configuration
26-
///
27-
/// - ``init()``
28-
///
29-
/// ### Configuring SQLite Connections
30-
///
31-
/// - ``acceptsDoubleQuotedStringLiterals``
32-
/// - ``busyMode``
33-
/// - ``foreignKeysEnabled``
34-
/// - ``readonly``
35-
///
36-
/// ### Configuring GRDB Connections
37-
///
38-
/// - ``allowsUnsafeTransactions``
39-
/// - ``defaultTransactionKind``
40-
/// - ``label``
41-
/// - ``maximumReaderCount``
42-
/// - ``observesSuspensionNotifications``
43-
/// - ``prepareDatabase(_:)``
44-
/// - ``publicStatementArguments``
45-
///
46-
/// ### Configuring the Quality of Service
47-
///
48-
/// - ``qos``
49-
/// - ``readQoS``
50-
/// - ``writeQoS``
51-
/// - ``targetQueue``
52-
/// - ``writeTargetQueue``
534
public struct Configuration {
545

556
// MARK: - Misc options

‎GRDB/Documentation.docc/Extension/Configuration.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# ``GRDB/Configuration``
2+
3+
The configuration of a database connection.
4+
5+
## Overview
6+
7+
You create a `Configuration` before opening a database connection:
8+
9+
```swift
10+
var config = Configuration()
11+
config.readonly = true
12+
config.maximumReaderCount = 2 // (DatabasePool only) The default is 5
13+
14+
let dbQueue = try DatabaseQueue( // or DatabasePool
15+
path: "/path/to/database.sqlite",
16+
configuration: config)
17+
```
18+
19+
See <doc:DatabaseConnections>.
20+
21+
## Frequent Use Cases
22+
23+
#### Tracing SQL Statements
24+
25+
You can setup a tracing function that prints out all executed SQL requests with ``prepareDatabase(_:)`` and ``Database/trace(options:_:)``:
26+
27+
```swift
28+
var config = Configuration()
29+
config.prepareDatabase { db in
30+
db.trace { print("SQL> \($0)") }
31+
}
32+
33+
let dbQueue = try DatabaseQueue(
34+
path: "/path/to/database.sqlite",
35+
configuration: config)
36+
37+
// Prints "SQL> SELECT COUNT(*) FROM player"
38+
let playerCount = dbQueue.read { db in
39+
try Player.fetchCount(db)
40+
}
41+
```
42+
43+
#### Public Statement Arguments
44+
45+
Debugging is easier when database errors and tracing functions expose the values sent to the database. Since those values may contain sensitive information, verbose logging is disabled by default. You turn it on with ``publicStatementArguments``:
46+
47+
```swift
48+
var config = Configuration()
49+
#if DEBUG
50+
// Protect sensitive information by enabling
51+
// verbose debugging in DEBUG builds only.
52+
config.publicStatementArguments = true
53+
#endif
54+
55+
let dbQueue = try DatabaseQueue(
56+
path: "/path/to/database.sqlite",
57+
configuration: config)
58+
59+
do {
60+
try dbQueue.write { db in
61+
user.name = ...
62+
user.location = ...
63+
user.address = ...
64+
user.phoneNumber = ...
65+
try user.save(db)
66+
}
67+
} catch {
68+
// Prints sensitive information in debug builds only
69+
print(error)
70+
}
71+
```
72+
73+
> Warning: It is your responsibility to prevent sensitive information from leaking in unexpected locations, so you should not set the `publicStatementArguments` flag in release builds (think about GDPR and other privacy-related rules).
74+
75+
## Topics
76+
77+
### Creating a Configuration
78+
79+
- ``init()``
80+
81+
### Configuring SQLite Connections
82+
83+
- ``acceptsDoubleQuotedStringLiterals``
84+
- ``busyMode``
85+
- ``foreignKeysEnabled``
86+
- ``readonly``
87+
88+
### Configuring GRDB Connections
89+
90+
- ``allowsUnsafeTransactions``
91+
- ``defaultTransactionKind``
92+
- ``label``
93+
- ``maximumReaderCount``
94+
- ``observesSuspensionNotifications``
95+
- ``prepareDatabase(_:)``
96+
- ``publicStatementArguments``
97+
98+
### Configuring the Quality of Service
99+
100+
- ``qos``
101+
- ``readQoS``
102+
- ``writeQoS``
103+
- ``targetQueue``
104+
- ``writeTargetQueue``

‎README.md‎

Lines changed: 9 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -557,7 +557,7 @@ See the [Concurrency] guide for asynchronous database accesses.
557557

558558
- When you don't need to modify the database, prefer the `read` method, because several threads can perform reads in parallel.
559559

560-
Reads are generally non-blocking, unless the maximum number of concurrent reads has been reached. In this case, a read has to wait for another read to complete. That maximum number can be [configured](#database-configuration).
560+
Reads are generally non-blocking, unless the maximum number of concurrent reads has been reached. In this case, a read has to wait for another read to complete. That maximum number can be [configured](https://swiftpackageindex.com/groue/grdb.swift/documentation/grdb/configuration).
561561

562562
- Reads are guaranteed an immutable view of the last committed state of the database, regardless of concurrent writes. This kind of isolation is called [snapshot isolation](https://sqlite.org/isolation.html).
563563

@@ -576,48 +576,6 @@ See [Database Configuration] for DatabasePool options.
576576
> :bulb: **Tip**: see the [Demo Applications] for sample code.
577577

578578

579-
## Database Configuration
580-
581-
```swift
582-
var config = Configuration()
583-
config.readonly = true
584-
config.foreignKeysEnabled = true // Default is already true
585-
config.label = "MyDatabase" // Useful when your app opens multiple databases
586-
config.maximumReaderCount = 10 // (DatabasePool only) The default is 5
587-
588-
let dbQueue = try DatabaseQueue( // or DatabasePool
589-
path: "/path/to/database.sqlite",
590-
configuration: config)
591-
```
592-
593-
In debug builds, you can increase the verbosity of [error descriptions](#databaseerror) and [trace events](#how-do-i-print-a-request-as-sql) if you opt in for public statement arguments:
594-
595-
```swift
596-
#if DEBUG
597-
// Protect sensitive information by enabling verbose debugging in DEBUG builds only
598-
config.publicStatementArguments = true
599-
#endif
600-
601-
let dbQueue = try DatabaseQueue(path: ..., configuration: config)
602-
603-
do {
604-
try dbQueue.write { db in
605-
user.name = ...
606-
user.location = ...
607-
user.address = ...
608-
user.phoneNumber = ...
609-
try user.save(db)
610-
}
611-
} catch {
612-
// Prints sensitive information in debug builds only
613-
print(error)
614-
}
615-
```
616-
617-
> **Warning**: It is your responsibility to prevent sensitive information from leaking in unexpected locations, so you should not set the `publicStatementArguments` flag in release builds (think about GDPR and other privacy-related rules).
618-
619-
See [Configuration](https://swiftpackageindex.com/groue/grdb.swift/documentation/grdb/configuration) for more details and configuration options.
620-
621579

622580
SQLite API
623581
==========
@@ -6133,7 +6091,7 @@ do {
61336091
}
61346092
```
61356093

6136-
If you want to see statement arguments in the error description, [make statement arguments public](#database-configuration).
6094+
If you want to see statement arguments in the error description, [make statement arguments public](https://swiftpackageindex.com/groue/grdb.swift/configuration/publicstatementarguments).
61376095

61386096
**SQLite uses [results codes](https://www.sqlite.org/rescode.html) to distinguish between various errors**.
61396097

@@ -6637,7 +6595,7 @@ try dbQueue.read { db in
66376595
}
66386596
```
66396597

6640-
If you want to see statement arguments such as `'[email protected]'` in the logged statements, [make statement arguments public](#database-configuration).
6598+
If you want to see statement arguments such as `'[email protected]'` in the logged statements, [make statement arguments public](https://swiftpackageindex.com/groue/grdb.swift/configuration/publicstatementarguments).
66416599

66426600
> **Note**: the generated SQL may change between GRDB releases, without notice: don't have your application rely on any specific SQL output.
66436601

@@ -6674,7 +6632,7 @@ try dbQueue.read { db in
66746632
}
66756633
```
66766634

6677-
If you want to see statement arguments such as `'[email protected]'` in the logged statements, [make statement arguments public](#database-configuration).
6635+
If you want to see statement arguments such as `'[email protected]'` in the logged statements, [make statement arguments public](https://swiftpackageindex.com/groue/grdb.swift/configuration/publicstatementarguments).
66786636

66796637
### What Are Experimental Features?
66806638

@@ -7084,6 +7042,10 @@ This chapter was replaced with [Persistence Callbacks].
70847042

70857043
This chapter has [moved](https://swiftpackageindex.com/groue/grdb.swift/documentation/grdb/databaseobservation).
70867044

7045+
#### Database Configuration
7046+
7047+
This chapter has [moved](https://swiftpackageindex.com/groue/grdb.swift/documentation/grdb/configuration).
7048+
70877049
#### Database Snapshots
70887050

70897051
This chapter has [moved](https://swiftpackageindex.com/groue/grdb.swift/documentation/grdb/concurrency).
@@ -7207,7 +7169,7 @@ This chapter has been superseded by [ValueObservation] and [DatabaseRegionObserv
72077169
[SQL literal]: Documentation/SQLInterpolation.md#sql-literal
72087170
[Identifiable]: https://developer.apple.com/documentation/swift/identifiable
72097171
[Query Interface Organization]: Documentation/QueryInterfaceOrganization.md
7210-
[Database Configuration]: #database-configuration
7172+
[Database Configuration]: https://swiftpackageindex.com/groue/grdb.swift/documentation/grdb/configuration
72117173
[Persistence Methods]: #persistence-methods
72127174
[persistence methods]: #persistence-methods
72137175
[RecordError]: #recorderror

0 commit comments

Comments
 (0)