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
[D1] Adding information on D1PreparedStatement object. (#19051)
* Adding information on D1PreparedStatement object.
* Relocating `bind` documentation, tweaking docs to accommodate this change.
* Adding an example in-situ for convenience for readers.
- An object which only contains methods. Refer to [Prepared statement methods](/d1/worker-api/prepared-statements/).
39
40
40
41
#### Guidance
41
42
42
-
- D1 follows the [SQLite convention](https://www.sqlite.org/lang_expr.html#varparam) for prepared statements parameter binding. Currently, D1 only supports Ordered (`?NNNN`) and Anonymous (`?`) parameters. In the future, D1 will support named parameters as well.
|`?NNN`| Ordered | A question mark followed by a number `NNN` holds a spot for the `NNN`-th parameter. `NNN` must be between `1` and `SQLITE_MAX_VARIABLE_NUMBER`|
47
-
|`?`| Anonymous | A question mark that is not followed by a number creates a parameter with a number one greater than the largest parameter number already assigned. If this means the parameter number is greater than `SQLITE_MAX_VARIABLE_NUMBER`, it is an error. This parameter format is provided for compatibility with other database engines. But because it is easy to miscount the question marks, the use of this parameter format is discouraged. Programmers are encouraged to use one of the symbolic formats below or the `?NNN` format above instead. |
48
-
49
-
To bind a parameter, use the `.bind` method.
43
+
You can use the `bind` method to dynamically bind a value into the query statement, as shown below.
50
44
51
-
Order and anonymous examples:
45
+
- Example of a static statement without using `bind`:
52
46
53
47
```js
54
-
conststmt=db.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind("");
48
+
conststmt= db
49
+
.prepare("SELECT * FROM Customers WHERE CompanyName = Alfreds Futterkiste AND CustomerId = 1")
55
50
```
56
51
52
+
- Example of an ordered statement using `bind`:
53
+
57
54
```js
58
55
conststmt= db
59
56
.prepare("SELECT * FROM Customers WHERE CompanyName = ? AND CustomerId = ?")
60
57
.bind("Alfreds Futterkiste", 1);
61
58
```
62
59
63
-
```js
64
-
conststmt= db
65
-
.prepare("SELECT * FROM Customers WHERE CompanyName = ?2 AND CustomerId = ?1")
66
-
.bind(1, "Alfreds Futterkiste");
67
-
```
68
-
69
-
#### Static statements
70
-
71
-
D1 API supports static statements. Static statements are SQL statements where the variables have been hard coded. When writing a static statement, you manually type the variable within the statement string.
72
-
73
-
:::note
74
-
The recommended approach is to bind parameters to create a prepared statement (which are precompiled objects used by the database) to run the SQL. Prepared statements lead to faster overall execution and prevent SQL injection attacks.
75
-
:::
76
-
77
-
Example of a prepared statement with dynamically bound value:
78
-
79
-
```js
80
-
constsomeVariable=`Bs Beverages`;
81
-
conststmt=env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
82
-
// A variable (someVariable) will replace the placeholder '?' in the query.
83
-
// `stmt` is a prepared statement.
84
-
```
85
-
86
-
Example of a static statement:
87
-
88
-
```js
89
-
conststmt=env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = Bs Beverages");
90
-
// "Bs Beverages" is hard-coded into the query.
91
-
// `stmt` is a static statement.
92
-
```
60
+
Refer to the [`bind` method documentation](/d1/worker-api/prepared-statements/#bind) for more information.
- A `D1PreparedStatement` where the input parameter has been included in the statement.
32
+
33
+
#### Guidance
34
+
35
+
- D1 follows the [SQLite convention](https://www.sqlite.org/lang_expr.html#varparam) for prepared statements parameter binding. Currently, D1 only supports Ordered (`?NNNN`) and Anonymous (`?`) parameters. In the future, D1 will support named parameters as well.
|`?NNN`| Ordered | A question mark followed by a number `NNN` holds a spot for the `NNN`-th parameter. `NNN` must be between `1` and `SQLITE_MAX_VARIABLE_NUMBER`|
40
+
|`?`| Anonymous | A question mark that is not followed by a number creates a parameter with a number one greater than the largest parameter number already assigned. If this means the parameter number is greater than `SQLITE_MAX_VARIABLE_NUMBER`, it is an error. This parameter format is provided for compatibility with other database engines. But because it is easy to miscount the question marks, the use of this parameter format is discouraged. Programmers are encouraged to use one of the symbolic formats below or the `?NNN` format above instead. |
41
+
42
+
To bind a parameter, use the `.bind` method.
43
+
44
+
Order and anonymous examples:
45
+
46
+
```js
47
+
conststmt=db.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind("");
48
+
```
49
+
50
+
```js
51
+
conststmt= db
52
+
.prepare("SELECT * FROM Customers WHERE CompanyName = ? AND CustomerId = ?")
53
+
.bind("Alfreds Futterkiste", 1);
54
+
```
55
+
56
+
```js
57
+
conststmt= db
58
+
.prepare("SELECT * FROM Customers WHERE CompanyName = ?2 AND CustomerId = ?1")
59
+
.bind(1, "Alfreds Futterkiste");
60
+
```
61
+
62
+
#### Static statements
63
+
64
+
D1 API supports static statements. Static statements are SQL statements where the variables have been hard coded. When writing a static statement, you manually type the variable within the statement string.
65
+
66
+
:::note
67
+
The recommended approach is to bind parameters to create a prepared statement (which are precompiled objects used by the database) to run the SQL. Prepared statements lead to faster overall execution and prevent SQL injection attacks.
68
+
:::
69
+
70
+
Example of a prepared statement with dynamically bound value:
71
+
72
+
```js
73
+
constsomeVariable=`Bs Beverages`;
74
+
conststmt=env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
75
+
// A variable (someVariable) will replace the placeholder '?' in the query.
76
+
// `stmt` is a prepared statement.
77
+
```
78
+
79
+
Example of a static statement:
80
+
81
+
```js
82
+
conststmt=env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = Bs Beverages");
83
+
// "Bs Beverages" is hard-coded into the query.
84
+
// `stmt` is a static statement.
85
+
```
86
+
14
87
### `run()`
15
88
16
89
Runs the prepared query (or queries) and returns results. The returned results includes metadata.
0 commit comments