Skip to content

Commit b51ac8e

Browse files
committed
Actioning first round of feedback.
1 parent 98666d5 commit b51ac8e

File tree

1 file changed

+44
-21
lines changed

1 file changed

+44
-21
lines changed

src/content/docs/d1/get-started.mdx

Lines changed: 44 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,24 @@ This guide instructs you through:
1212

1313
- Creating your first database using D1, Cloudflare's native serverless SQL database.
1414
- 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.
1616

1717
You can perform these tasks through the CLI or through the Cloudflare dashboard.
1818

1919
:::note
2020
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).
2121
:::
2222

23+
## Quick start
24+
25+
If you want to skip the steps and get started quickly, click on the button below.
26+
27+
[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](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.
32+
2333
## Prerequisites
2434

2535
<Render file="prereqs" product="workers" />
@@ -90,7 +100,7 @@ For example: `CI=true npm create cloudflare@latest d1-tutorial --type=simple --g
90100

91101
## 2. Create a database
92102

93-
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).
94104

95105
To create your first D1 database:
96106

@@ -103,31 +113,40 @@ To create your first D1 database:
103113
cd d1-tutorial
104114
```
105115

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+
:::
107123

108124
```sh
109-
npx wrangler d1 create prod-d1-tutorial
125+
npx wrangler@latest d1 create prod-d1-tutorial
110126
```
111127

112128
```sh output
113129

114-
✅ Successfully created DB 'prod-d1-tutorial'
130+
✅ Successfully created DB 'prod-d1-tutorial' in region WEUR
131+
Created your new D1 database.
115132

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+
}
121142

122-
</Steps>
143+
```
123144

124-
This creates a new D1 database and outputs the [binding](/workers/runtime-apis/bindings/) configuration needed in the next step.
125145

126-
:::note
127146

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>
129148

130-
:::
149+
This creates a new D1 database and outputs the [binding](/workers/runtime-apis/bindings/) configuration needed in the next step.
131150

132151
</TabItem> <TabItem label='Dashboard'>
133152

@@ -217,11 +236,11 @@ You create bindings by adding them to the Worker you have created.
217236

218237
## 4. Run a query against your D1 database
219238

220-
### Configure your D1 database
239+
### Populate your D1 database
221240

222241
<Tabs syncKey='CLIvDash'> <TabItem label='CLI'>
223242

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.
225244

226245
<Steps>
227246
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
238257
npx wrangler d1 execute prod-d1-tutorial --local --file=./schema.sql
239258
```
240259

241-
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:
242265

243266
```sh
244267
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.
329352

330353
In the code above, you:
331354

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`.
333356
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.
335358
4. Execute the query by calling `all()` to return all rows (or none, if the query returns none).
336359
5. Return your query results, if any, in JSON format with `Response.json(results)`.
337360

@@ -385,7 +408,7 @@ Deploy your database on Cloudflare's global network.
385408

386409
<Tabs syncKey='CLIvDash'> <TabItem label='CLI'>
387410

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.
389412

390413
<Steps>
391414
1. Bootstrap your database with the `schema.sql` file you created in step 4:

0 commit comments

Comments
 (0)