Skip to content

[D1] Cleaning up Build with D1 #18321

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 26 commits into from
Dec 11, 2024
Merged

[D1] Cleaning up Build with D1 #18321

Show file tree
Hide file tree
Changes from 19 commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
fac3401
Moving Error section away from "Query D1".
Oxyjun Nov 21, 2024
1b1583a
Redirecting Query D1 to Workers Binding API section.
Oxyjun Nov 21, 2024
6db092a
Replacing all interlinks to Query D1 chapter, to the new structure.
Oxyjun Nov 21, 2024
0996b32
Update src/content/docs/d1/worker-api/prepared-statements.mdx
Oxyjun Nov 21, 2024
4dab631
Fixing grammar.
Oxyjun Nov 21, 2024
194a953
Moving Wrangler commands out of Reference. Reshuffling chapters.
Oxyjun Nov 22, 2024
a0dfc1c
Updating branch with master
Oxyjun Nov 22, 2024
0b2506c
Resolving merge conflict, adding global commands once at the bottom.
Oxyjun Nov 22, 2024
cd9e478
Moving "global commands" out of the partial.
Oxyjun Nov 22, 2024
52dfe8e
Introducing APIs in Query D1. Introducing Wrangler commands properly.
Oxyjun Nov 22, 2024
c6a77bb
Setting up redirects, fixing broken link.
Oxyjun Nov 22, 2024
cd6be4c
Adding missing `/`
Oxyjun Nov 22, 2024
425ec46
Fixing redirects.
Oxyjun Nov 25, 2024
8b38884
Resolving two conflicting redirects.
Oxyjun Nov 25, 2024
890c682
Fixing redirect
Oxyjun Nov 26, 2024
3f7bcc7
Merge commit '8464c5596d3875f159c1a99b1d006eaf9f86608b' into jun/d1/a…
Oxyjun Dec 5, 2024
5cc5506
Reordering API pages, moving Remote dev below Local dev.
Oxyjun Dec 5, 2024
ac438d2
Editing chapter contents to action feedback.
Oxyjun Dec 6, 2024
8ac8712
Renaming "Build with D1" to "Best practices".
Oxyjun Dec 6, 2024
d2e10d8
Merge commit '32aa062cc0062388d8f2643179f514bd004c2a79' into jun/d1/a…
Oxyjun Dec 9, 2024
8bf038d
Moving foreign keys and query json into SQL API.
Oxyjun Dec 9, 2024
baa60a6
Moving foreign keys and query json into sql api.
Oxyjun Dec 9, 2024
ec24c8d
Removing "D1" from REST and Wrangler sidebar.
Oxyjun Dec 9, 2024
05a130b
Introducing query JSON and foreign keys in Query databases chapter.
Oxyjun Dec 9, 2024
55a9385
Restructuring "Query database", changing the example of
Oxyjun Dec 9, 2024
66776f5
Editing Wrangler example. Restructuring to better explain how SQL fit…
Oxyjun Dec 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 32 additions & 22 deletions public/_redirects
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,42 +258,52 @@
/constellation/ /workers-ai/ 301

# D1
/d1/client-api/ /d1/build-with-d1/d1-client-api/ 301
/d1/client-api/ /d1/worker-api/ 301
/d1/build-with-d1/d1-client-api/ /d1/worker-api/ 301
/d1/build-with-d1/import-data/ /d1/best-practices/import-export-data/ 301
/d1/build-with-d1/ /d1/best-practices/ 301
/d1/build-with-d1/import-export-data/ /d1/best-practices/import-export-data/ 301
/d1/build-with-d1/use-indexes/ /d1/best-practices/use-indexes/ 301
/d1/build-with-d1/remote-development/ /d1/best-practices/remote-development/ 301
/d1/build-with-d1/local-development/ /d1/best-practices/local-development/ 301
/d1/build-with-d1/foreign-keys/ /d1/best-practices/foreign-keys/ 301
/d1/build-with-d1/query-json/ /d1/best-practices/query-json/ 301
/d1/build-with-d1/use-d1-from-pages/ /d1/best-practices/use-d1-from-pages/ 301
/d1/learning/using-d1-from-pages/ /pages/functions/bindings/#d1-databases 301
/d1/learning/debug-d1/ /d1/observability/debug-d1/ 301
/d1/learning/using-indexes/ /d1/build-with-d1/use-indexes/ 301
/d1/learning/querying-json/ /d1/build-with-d1/query-json/ 301
/d1/learning/importing-data/ /d1/build-with-d1/import-export-data/ 301
/d1/learning/using-indexes/ /d1/best-practices/use-indexes/ 301
/d1/learning/querying-json/ /d1/best-practices/query-json/ 301
/d1/learning/importing-data/ /d1/best-practices/import-export-data/ 301
/d1/learning/generated-columns/ /d1/reference/generated-columns/ 301
/d1/learning/local-development/ /d1/build-with-d1/local-development/ 301
/d1/learning/remote-development/ /d1/build-with-d1/remote-development/ 301
/d1/learning/local-development/ /d1/best-practices/local-development/ 301
/d1/learning/remote-development/ /d1/best-practices/remote-development/ 301
/d1/learning/data-location/ /d1/configuration/data-location/ 301
/d1/migrations/ /d1/reference/migrations/ 301
/d1/platform/wrangler-commands/ /workers/wrangler/commands/#d1 301
/d1/platform/community-projects/ /d1/reference/community-projects/ 301
/d1/platform/client-api/ /d1/build-with-d1/d1-client-api/ 301
/d1/platform/client-api/ /d1/worker-api/ 301
/d1/platform/data-security/ /d1/reference/data-security/ 301
/d1/platform/environments/ /d1/configuration/environments/ 301
/d1/platform/metrics-analytics/ /d1/observability/metrics-analytics/ 301
/d1/platform/migrations/ /d1/reference/migrations/ 301
/d1/reference/client-api/ /d1/build-with-d1/d1-client-api/ 301
/d1/reference/client-api/ /d1/worker-api/ 301
/d1/reference/environments/ /d1/configuration/environments/ 301
/d1/reference/metrics-analytics/ /d1/observability/metrics-analytics/ 301
/d1/how-to/ /d1/build-with-d1/ 301
/d1/how-to/query-databases/ /d1/build-with-d1/d1-client-api/ 301
/d1/how-to/using-indexes/ /d1/build-with-d1/use-indexes/ 301
/d1/how-to/querying-json/ /d1/build-with-d1/query-json/ 301
/d1/how-to/importing-data/ /d1/build-with-d1/import-export-data/ 301
/d1/reference/wrangler-commands/ / /d1/wrangler-commands/ 301
/d1/how-to/ /d1/best-practices/ 301
/d1/how-to/query-databases/ /d1/best-practices/query-d1/ 301
/d1/how-to/using-indexes/ /d1/best-practices/use-indexes/ 301
/d1/how-to/querying-json/ /d1/best-practices/query-json/ 301
/d1/how-to/importing-data/ /d1/best-practices/import-export-data/ 301
/d1/how-to/generated-columns/ /d1/reference/generated-columns/ 301
/d1/build-databases/ /d1/build-with-d1/ 301
/d1/build-databases/query-databases/ /d1/build-with-d1/d1-client-api/ 301
/d1/build-databases/use-indexes/ /d1/build-with-d1/use-indexes/ 301
/d1/build-databases/import-data/ /d1/build-with-d1/import-export-data/ 301
/d1/build-databases/client-api/ /d1/build-with-d1/d1-client-api/ 301
/d1/reference/query-json/ /d1/build-with-d1/query-json/ 301
/d1/configuration/local-development/ /d1/build-with-d1/local-development/ 301
/d1/configuration/remote-development/ /d1/build-with-d1/remote-development/ 301
/d1/build-with-d1/import-data/ /d1/build-with-d1/import-export-data/ 301
/d1/build-databases/ /d1/best-practices/ 301
/d1/build-databases/query-databases/ /d1/best-practices/query-d1/ 301
/d1/build-databases/use-indexes/ /d1/best-practices/use-indexes/ 301
/d1/build-databases/import-data/ /d1/best-practices/import-export-data/ 301
/d1/build-databases/client-api/ /d1/worker-api/ 301
/d1/reference/query-json/ /d1/best-practices/query-json/ 301
/d1/configuration/local-development/ /d1/best-practices/local-development/ 301
/d1/configuration/remote-development/ /d1/best-practices/remote-development/ 301
/d1/reference/database-commands/ /d1/reference/sql-statements/ 301
/d1/reference/sql-statements/ /d1/sql-api/sql-statements/ 301

Expand Down
30 changes: 15 additions & 15 deletions src/content/changelogs/d1.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ entries:
- publish_date: "2024-07-26"
title: Fixed bug in TypeScript typings for run() API
description: |-
The `run()` method as part of the [D1 Client API](/d1/build-with-d1/d1-client-api/) had an incorrect (outdated) type definition, which has now been addressed as of [`@cloudflare/workers-types`](https://www.npmjs.com/package/@cloudflare/workers-types) version `4.20240725.0`.
The `run()` method as part of the [D1 Client API](/d1/worker-api/) had an incorrect (outdated) type definition, which has now been addressed as of [`@cloudflare/workers-types`](https://www.npmjs.com/package/@cloudflare/workers-types) version `4.20240725.0`.

The correct type definition is `stmt.run<T>(): D1Result`, as `run()` returns the result rows of the query. The previously _incorrect_ type definition was `stmt.run(): D1Response`, which only returns query metadata and no results.

Expand All @@ -28,7 +28,7 @@ entries:
description: |-
Previously, D1's [HTTP API](/api/operations/cloudflare-d1-query-database) returned a HTTP `500 Internal Server` error for queries that came in while a D1 database was overloaded. These requests now correctly return a `HTTP 429 Too Many Requests` error.

D1's [Workers API](/d1/build-with-d1/d1-client-api/) is unaffected by this change.
D1's [Workers API](/d1/worker-api/) is unaffected by this change.

- publish_date: "2024-04-30"
title: D1 alpha databases will stop accepting live SQL queries on August 15, 2024
Expand All @@ -42,7 +42,7 @@ entries:
description: |-
Previously, D1's [HTTP API](/api/operations/cloudflare-d1-query-database) returned a HTTP `500 Internal Server` error for an invalid query. An invalid SQL query now correctly returns a `HTTP 400 Bad Request` error.

D1's [Workers API](/d1/build-with-d1/d1-client-api/) is unaffected by this change.
D1's [Workers API](/d1/worker-api/) is unaffected by this change.

- publish_date: "2024-04-05"
title: D1 alpha databases are deprecated
Expand All @@ -58,7 +58,7 @@ entries:

* Developers with a Workers Paid plan now have a 10GB GB per-database limit (up from 2GB), which can be combined with existing limit of 50,000 databases per account.
* Developers with a Workers Free plan retain the 500 MB per-database limit and can create up to 10 databases per account.
* D1 databases can be [exported](/d1/build-with-d1/import-export-data/#export-an-existing-d1-database) as a SQL file.
* D1 databases can be [exported](/d1/best-practices/import-export-data/#export-an-existing-d1-database) as a SQL file.

- publish_date: "2024-03-12"
title: Change in `wrangler d1 execute` default
Expand All @@ -81,24 +81,24 @@ entries:
- publish_date: "2024-02-16"
title: API changes to `run()`
description: |-
A previous change (made on 2024-02-13) to the `run()` [query statement method](/d1/build-with-d1/d1-client-api/#await-stmtrun) has been reverted.
A previous change (made on 2024-02-13) to the `run()` [query statement method](/d1/worker-api/prepared-statements/#run) has been reverted.

`run()` now returns a `D1Result`, including the result rows, matching its original behaviour prior to the change on 2024-02-13.
`run()` now returns a `D1Result`, including the result rows, matching its original behavior prior to the change on 2024-02-13.

Future change to `run()` to return a [`D1ExecResult`](/d1/build-with-d1/d1-client-api/#return-object), as originally intended and documented, will be gated behind a [compatibility date](/workers/configuration/compatibility-dates/) as to avoid breaking existing Workers relying on the way `run()` currently works.
Future change to `run()` to return a [`D1ExecResult`](/d1/worker-api/return-object/#d1execresult), as originally intended and documented, will be gated behind a [compatibility date](/workers/configuration/compatibility-dates/) as to avoid breaking existing Workers relying on the way `run()` currently works.

- publish_date: "2024-02-13"
title: API changes to `raw()`, `all()` and `run()`
description: |-
D1's `raw()`, `all()` and `run()` [query statement methods](/d1/build-with-d1/d1-client-api/#query-statement-methods) have been updated to reflect their intended behaviour and improve compatibility with ORM libraries.
D1's `raw()`, `all()` and `run()` [query statement methods](/d1/worker-api/prepared-statements/) have been updated to reflect their intended behavior and improve compatibility with ORM libraries.

`raw()` now correctly returns results as an array of arrays, allowing the correct handling of duplicate column names (such as when joining tables), as compared to `all()`, which is unchanged and returns an array of objects. To include an array of column names in the results when using `raw()`, use `raw({columnNames: true})`.

`run()` no longer incorrectly returns a `D1Result` and instead returns a [`D1ExecResult`](/d1/build-with-d1/d1-client-api/#return-object) as originally intended and documented.
`run()` no longer incorrectly returns a `D1Result` and instead returns a [`D1ExecResult`](/d1/worker-api/return-object/#d1execresult) as originally intended and documented.

This may be a breaking change for some applications that expected `raw()` to return an array of objects.

Refer to [D1 client API](/d1/build-with-d1/d1-client-api/) to review D1's query methods, return types and TypeScript support in detail.
Refer to [D1 client API](/d1/worker-api/) to review D1's query methods, return types and TypeScript support in detail.

- publish_date: "2024-01-18"
title: Support for LIMIT on UPDATE and DELETE statements
Expand Down Expand Up @@ -138,9 +138,9 @@ entries:
- publish_date: "2023-08-19"
title: Row count now returned per query
description: |-
D1 now returns a count of `rows_written` and `rows_read` for every query executed, allowing you to assess the cost of query for both [pricing](/d1/platform/pricing/) and [index optimization](/d1/build-with-d1/use-indexes/) purposes.
D1 now returns a count of `rows_written` and `rows_read` for every query executed, allowing you to assess the cost of query for both [pricing](/d1/platform/pricing/) and [index optimization](/d1/best-practices/use-indexes/) purposes.

The `meta` object returned in [D1's Client API](/d1/build-with-d1/d1-client-api/) contains a total count of the rows read (`rows_read`) and rows written (`rows_written`) by that query. For example, a query that performs a full table scan (for example, `SELECT * FROM users`) from a table with 5000 rows would return a `rows_read` value of `5000`:
The `meta` object returned in [D1's Client API](/d1/worker-api/return-object/#d1result) contains a total count of the rows read (`rows_read`) and rows written (`rows_written`) by that query. For example, a query that performs a full table scan (for example, `SELECT * FROM users`) from a table with 5000 rows would return a `rows_read` value of `5000`:
```json
"meta": {
"duration": 0.20472300052642825,
Expand Down Expand Up @@ -195,12 +195,12 @@ entries:
New documentation has been published on how to use D1's support for
[generated columns](/d1/reference/generated-columns/) to define columns that are
dynamically generated on write (or read). Generated columns allow you to extract
data from [JSON objects](/d1/build-with-d1/query-json/) or use the output of other
data from [JSON objects](/d1/best-practices/query-json/) or use the output of other
SQL functions.
- publish_date: "2023-06-12"
title: Deprecating Error.cause
description: |-
As of [`wrangler v3.1.1`](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%403.1.1) the [D1 client API](/d1/build-with-d1/d1-client-api/) now returns [detailed error messages](/d1/build-with-d1/d1-client-api/#errors) within the top-level `Error.message` property, and no longer requires developers to inspect the `Error.cause.message` property.
As of [`wrangler v3.1.1`](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%403.1.1) the [D1 client API](/d1/worker-api/) now returns [detailed error messages](/d1/observability/debug-d1/) within the top-level `Error.message` property, and no longer requires developers to inspect the `Error.cause.message` property.

To facilitate a transition from the previous `Error.cause` behaviour, detailed error messages will continue to be populated within `Error.cause` as well as the top-level `Error` object until approximately July 14th, 2023. Future versions of both `wrangler` and the D1 client API will no longer populate `Error.cause` after this date.
- publish_date: "2023-05-19"
Expand All @@ -223,7 +223,7 @@ entries:
- publish_date: "2023-05-17"
title: Query JSON
description:
"[New documentation](/d1/build-with-d1/query-json/) has been published
"[New documentation](/d1/best-practices/query-json/) has been published
that covers D1's extensive JSON function support. JSON functions allow you to
parse, query and modify JSON directly from your SQL queries, reducing the number
of round trips to your database, or data queried."
6 changes: 3 additions & 3 deletions ...nt/docs/d1/build-with-d1/foreign-keys.mdx → ...t/docs/d1/best-practices/foreign-keys.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ By default, D1 enforces that foreign key constraints are valid within all querie

## Defer foreign key constraints

When running a [query](/d1/build-with-d1/d1-client-api/), [migration](/d1/reference/migrations/) or [importing data](/d1/build-with-d1/import-export-data/) against a D1 database, there may be situations in which you need to disable foreign key validation during table creation or changes to your schema.
When running a [query](/d1/worker-api/), [migration](/d1/reference/migrations/) or [importing data](/d1/best-practices/import-export-data/) against a D1 database, there may be situations in which you need to disable foreign key validation during table creation or changes to your schema.

D1's foreign key enforcement is equivalent to SQLite's `PRAGMA foreign_keys = on` directive. Because D1 runs every query inside an implicit transaction, user queries cannot change this during a query or migration.

Expand Down Expand Up @@ -87,7 +87,7 @@ There are five actions you can set when defining the `ON UPDATE` and/or `ON DELE

:::caution[CASCADE usage]

Although `CASCADE` can be the desired behavior in some cases, deleting child rows across tables can have undesirable effects and/or result in unintended side effects for your users.
Although `CASCADE` can be the desired behavior in some cases, deleting child rows across tables can have undesirable effects and/or result in unintended side effects for your users.
:::

In the following example, deleting a user from the `users` table will delete all related rows in the `scores` table as you have defined `ON DELETE CASCADE`. Delete all related rows in the `scores` table if you do not want to retain the scores for any users you have deleted entirely. This might mean that *other* users can no longer look up or refer to scores that were still valid.
Expand All @@ -110,5 +110,5 @@ CREATE TABLE scores (
## Next Steps

* Read the SQLite [`FOREIGN KEY`](https://www.sqlite.org/foreignkeys.html) documentation.
* Learn how to [use the D1 client API](/d1/build-with-d1/d1-client-api/) from within a Worker.
* Learn how to [use the D1 Workers Binding API](/d1/worker-api/) from within a Worker.
* Understand how [database migrations work](/d1/reference/migrations/) with D1.
18 changes: 9 additions & 9 deletions ...s/d1/build-with-d1/import-export-data.mdx → .../d1/best-practices/import-export-data.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ sidebar:

D1 allows you to import existing SQLite tables and their data directly, enabling you to migrate existing data into D1 quickly and easily. This can be useful when migrating applications to use Workers and D1, or when you want to prototype a schema locally before importing it to your D1 database(s).

D1 also allows you to export a database. This can be useful for [local development](/d1/build-with-d1/local-development/) or testing.
D1 also allows you to export a database. This can be useful for [local development](/d1/best-practices/local-development/) or testing.

## Import an existing database

Expand Down Expand Up @@ -69,7 +69,7 @@ The `_cf_KV` table is a reserved table used by D1's underlying storage system. I

:::

From here, you can now query our new table from our Worker [using the D1 client API](/d1/build-with-d1/d1-client-api/).
From here, you can now query our new table from our Worker [using the D1 Workers Binding API](/d1/worker-api/).

:::caution[Known limitations]

Expand Down Expand Up @@ -105,12 +105,6 @@ Once you have run the above command, you will need to edit the output SQL file t

You can then follow the steps to [import an existing database](#import-an-existing-database) into D1 by using the `.sql` file you generated from the database dump as the input to `wrangler d1 execute`.

## Foreign key constraints

When importing data, you may need to temporarily disable [foreign key constraints](/d1/build-with-d1/foreign-keys/). To do so, call `PRAGMA defer_foreign_keys = true` before making changes that would violate foreign keys.

Refer to the [foreign key documentation](/d1/build-with-d1/foreign-keys/) to learn more about how to work with foreign keys and D1.

## Export an existing D1 database

In addition to importing existing SQLite databases, you might want to export a D1 database for local development or testing. You can export a D1 database to a `.sql` file using [wrangler d1 export](/workers/wrangler/commands/#export) and then execute (import) with `d1 execute --file`.
Expand Down Expand Up @@ -198,8 +192,14 @@ VALUES
('1000', 'Boris Pewter', '2022-12-15 22:16:15');
```

## Foreign key constraints

When importing data, you may need to temporarily disable [foreign key constraints](/d1/best-practices/foreign-keys/). To do so, call `PRAGMA defer_foreign_keys = true` before making changes that would violate foreign keys.

Refer to the [foreign key documentation](/d1/best-practices/foreign-keys/) to learn more about how to work with foreign keys and D1.

## Next Steps

- Read the SQLite [`CREATE TABLE`](https://www.sqlite.org/lang_createtable.html) documentation.
- Learn how to [use the D1 client API](/d1/build-with-d1/d1-client-api/) from within a Worker.
- Learn how to [use the D1 Workers Binding API](/d1/worker-api/) from within a Worker.
- Understand how [database migrations work](/d1/reference/migrations/) with D1.
2 changes: 1 addition & 1 deletion src/content/docs/d1/build-with-d1/index.mdx → src/content/docs/d1/best-practices/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Build with D1
title: Best practices
pcx_content_type: navigation
sidebar:
order: 3
Expand Down
0 ...cs/d1/build-with-d1/local-development.mdx → ...s/d1/best-practices/local-development.mdx
View file
Open in desktop
File renamed without changes.
Loading
Loading