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: src/content/docs/d1/get-started.mdx
+44-21Lines changed: 44 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,14 +12,24 @@ This guide instructs you through:
12
12
13
13
- Creating your first database using D1, Cloudflare's native serverless SQL database.
14
14
- Creating a schema and querying your database via the command-line.
15
-
- Connecting a [Cloudflare Worker](/workers/) to your D1 database to query your D1 database programmatically.
15
+
- Connecting a [Cloudflare Worker](/workers/) to your D1 database using bindings, and querying your D1 database programmatically.
16
16
17
17
You can perform these tasks through the CLI or through the Cloudflare dashboard.
18
18
19
19
:::note
20
20
If you already have an existing Worker and an existing D1 database, follow this tutorial from [3. Bind your Worker to your D1 database](/d1/get-started/#3-bind-your-worker-to-your-d1-database).
21
21
:::
22
22
23
+
## Quick start
24
+
25
+
If you want to skip the steps and get started quickly, click on the button below.
26
+
27
+
[](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/d1-get-started/d1/d1-get-started)
28
+
29
+
This creates a repository in your GitHub account and deploys the application to Cloudflare Workers. Use this option if you are familiar with Cloudflare Workers, and wish to skip the step-by-step guidance.
30
+
31
+
You may wish to manually follow the steps if you are new to Cloudflare Workers.
A D1 database is conceptually similar to many other databases: a database may contain one or more tables, the ability to query those tables, and optional indexes. D1 uses the familiar [SQL query language](https://www.sqlite.org/lang.html) (as used by SQLite).
103
+
A D1 database is conceptually similar to many other SQL databases: a database may contain one or more tables, the ability to query those tables, and optional indexes. D1 uses the familiar [SQL query language](https://www.sqlite.org/lang.html) (as used by SQLite).
94
104
95
105
To create your first D1 database:
96
106
@@ -103,31 +113,40 @@ To create your first D1 database:
103
113
cd d1-tutorial
104
114
```
105
115
106
-
2. Run the following `wrangler d1` command and give your database a name. In this tutorial, the database is named `prod-d1-tutorial`:
116
+
2. Run the following `wrangler@latest d1` command and give your database a name. In this tutorial, the database is named `prod-d1-tutorial`:
117
+
118
+
:::note
119
+
The [Wrangler command-line interface](/workers/wrangler/) is Cloudflare's tool for managing and deploying Workers applications and D1 databases in your terminal. It was installed when you used `npm create cloudflare@latest` to initialize your new project.
120
+
121
+
While Wrangler gets installed locally to your project, you can use it outside the project by using the command `npx wrangler`.
122
+
:::
107
123
108
124
```sh
109
-
npx wrangler d1 create prod-d1-tutorial
125
+
npx wrangler@latest d1 create prod-d1-tutorial
110
126
```
111
127
112
128
```sh output
113
129
114
-
✅ Successfully created DB 'prod-d1-tutorial'
130
+
✅ Successfully created DB 'prod-d1-tutorial'in region WEUR
131
+
Created your new D1 database.
115
132
116
-
[[d1_databases]]
117
-
binding = "DB"# available in your Worker on env.DB
118
-
database_name = "prod-d1-tutorial"
119
-
database_id = "<unique-ID-for-your-database>"
120
-
```
133
+
{
134
+
"d1_databases": [
135
+
{
136
+
"binding": "DB",
137
+
"database_name": "prod-d1-tutorial",
138
+
"database_id": "<unique-ID-for-your-database>"
139
+
}
140
+
]
141
+
}
121
142
122
-
</Steps>
143
+
```
123
144
124
-
This creates a new D1 database and outputs the [binding](/workers/runtime-apis/bindings/) configuration needed in the next step.
125
145
126
-
:::note
127
146
128
-
The `wrangler` command-line interface is Cloudflare's tool for managing and deploying Workers applications and D1 databases in your terminal. It was installed when you used `npm create cloudflare@latest` to initialize your new project.
147
+
</Steps>
129
148
130
-
:::
149
+
This creates a new D1 database and outputs the [binding](/workers/runtime-apis/bindings/) configuration needed in the next step.
131
150
132
151
</TabItem> <TabItemlabel='Dashboard'>
133
152
@@ -217,11 +236,11 @@ You create bindings by adding them to the Worker you have created.
217
236
218
237
## 4. Run a query against your D1 database
219
238
220
-
### Configure your D1 database
239
+
### Populate your D1 database
221
240
222
241
<TabssyncKey='CLIvDash'> <TabItemlabel='CLI'>
223
242
224
-
After correctly preparing your [Wrangler configuration file](/workers/wrangler/configuration/), set up your database. Use the example `schema.sql` file below to initialize your database.
243
+
After correctly preparing your [Wrangler configuration file](/workers/wrangler/configuration/), set up your database. Create a `schema.sql` file using the SQL syntax below to initialize your database.
225
244
226
245
<Steps>
227
246
1. Copy the following code and save it as a `schema.sql` file in the `d1-tutorial` Worker directory you created in step 1:
@@ -238,7 +257,11 @@ After correctly preparing your [Wrangler configuration file](/workers/wrangler/c
3. Validate your data is in your database by running:
260
+
:::note
261
+
The command `npx wrangler d1 execute` initializes your database locally, not on the remote database.
262
+
:::
263
+
264
+
3. Validate that your data is in the database by running:
242
265
243
266
```sh
244
267
npx wrangler d1 execute prod-d1-tutorial --local --command="SELECT * FROM Customers"
@@ -329,9 +352,9 @@ After you have set up your database, run an SQL query from within your Worker.
329
352
330
353
In the code above, you:
331
354
332
-
1. Define a binding to your D1 database in your TypeScript code. This binding matches the `binding` value you set in the [Wrangler configuration file](/workers/wrangler/configuration/) under `[[d1_databases]]`.
355
+
1. Define a binding to your D1 database in your code. This binding matches the `binding` value you set in the [Wrangler configuration file](/workers/wrangler/configuration/) under `d1_databases`.
333
356
2. Query your database using `env.DB.prepare` to issue a [prepared query](/d1/worker-api/d1-database/#prepare) with a placeholder (the `?` in the query).
334
-
3. Call `bind()` to safely and securely bind a value to that placeholder. In a real application, you would allow a user to define the `CompanyName` they want to list results for. Using `bind()` prevents users from executing arbitrary SQL (known as "SQL injection") against your application and deleting or otherwise modifying your database.
357
+
3. Call `bind()` to safely and securely bind a value to that placeholder. In a real application, you would allow a user to pass the `CompanyName` they want to list results for. Using `bind()` prevents users from executing arbitrary SQL (known as "SQL injection") against your application and deleting or otherwise modifying your database.
335
358
4. Execute the query by calling `all()` to return all rows (or none, if the query returns none).
336
359
5. Return your query results, if any, in JSON format with `Response.json(results)`.
337
360
@@ -385,7 +408,7 @@ Deploy your database on Cloudflare's global network.
385
408
386
409
<TabssyncKey='CLIvDash'> <TabItemlabel='CLI'>
387
410
388
-
To deploy your Worker to production using Wrangler, you must first repeat the [database configuration](/d1/get-started/#configure-your-d1-database) steps after replacing the `--local` flag with the `--remote` flag to give your Worker data to read. This creates the database tables and imports the data into the production version of your database.
411
+
To deploy your Worker to production using Wrangler, you must first repeat the [database configuration](/d1/get-started/#populate-your-d1-database) steps after replacing the `--local` flag with the `--remote` flag to give your Worker data to read. This creates the database tables and imports the data into the production version of your database.
389
412
390
413
<Steps>
391
414
1. Bootstrap your database with the `schema.sql` file you created in step 4:
0 commit comments