diff --git a/src/content/docs/durable-objects/get-started/tutorial-with-sql-api.mdx b/src/content/docs/durable-objects/get-started/tutorial-with-sql-api.mdx new file mode 100644 index 000000000000000..cfc02cef3aec8cc --- /dev/null +++ b/src/content/docs/durable-objects/get-started/tutorial-with-sql-api.mdx @@ -0,0 +1,259 @@ +--- +title: Tutorial with SQL API +pcx_content_type: get-started +sidebar: + order: 2 +--- + +import { Render, TabItem, Tabs, PackageManagers } from "~/components"; + +This guide will instruct you through: + +- Writing a JavaScript class that defines a Durable Object. +- Using Durable Objects SQL API to query a Durable Object's private, embedded SQLite database. +- Instantiating and communicating with a Durable Object from another Worker. +- Deploying a Durable Object and a Worker that communicates with a Durable Object. + +:::note[SQLite in Durable Objects Beta] + +The new beta version of Durable Objects is available where each Durable Object has a private, embedded SQLite database. When deploying a new Durable Object class, users can [opt-in to a SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend) in order to access new [SQL API](/durable-objects/api/storage-api/#sqlexec), part of Durable Objects Storage API. + +::: + +## Prerequisites + + + +## 1. Enable Durable Objects in the dashboard + +To enable Durable Objects, you will need to purchase the Workers Paid plan: + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account. +2. Go to **Workers & Pages** > **Plans**. +3. Select **Purchase Workers Paid** and complete the payment process to enable Durable Objects. + +## 2. Create a Worker project to access Durable Objects + +You will access your Durable Object from a [Worker](/workers/). Your Worker application is an interface to interact with your Durable Object. + +To create a Worker project, run: + + + +Running `create cloudflare@latest` will install [Wrangler](/workers/wrangler/install-and-update/), the Workers CLI. You will use Wrangler to test and deploy your project. + + + +This will create a new directory, which will include either a `src/index.js` or `src/index.ts` file to write your code and a [`wrangler.toml`](/workers/wrangler/configuration/) configuration file. + +Move into your new directory: + +```sh +cd durable-object-starter +``` + +## 3. Write a class to define a Durable Object that uses SQL API + +Before you create and access a Durable Object, its behavior must be defined by an ordinary exported JavaScript class. + +:::note + +If you do not use JavaScript or TypeScript, you will need a [shim](https://developer.mozilla.org/en-US/docs/Glossary/Shim) to translate your class definition to a JavaScript class. +::: + +Your `MyDurableObject` class will have a constructor with two parameters. The first parameter, `ctx`, passed to the class constructor contains state specific to the Durable Object, including methods for accessing storage. The second parameter, `env`, contains any bindings you have associated with the Worker when you uploaded it. + + + +```js +export class MyDurableObject extends DurableObject { + constructor(ctx, env) {} +} +``` + + + +```ts +export class MyDurableObject extends DurableObject { + constructor(ctx: DurableObjectState, env: Env) {} +} +``` + + + +Workers communicate with a Durable Object using [remote-procedure call](/workers/runtime-apis/rpc/#_top). Public methods on a Durable Object class are exposed as [RPC methods](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/#call-rpc-methods) to be called by another Worker. + +Your file should now look like: + + + +```js +export class MyDurableObject extends DurableObject { + constructor(ctx, env) {} + + async sayHello() { + let result = this.ctx.storage.sql.exec("SELECT 'Hello, World!' as greeting").one(); + return result.greeting; + } +} +``` + + + +```ts +export class MyDurableObject extends DurableObject { + constructor(ctx: DurableObjectState, env: Env) {} + + async sayHello() { + let result = this.ctx.storage.sql.exec("SELECT 'Hello, World!' as greeting").one(); + return result.greeting; + } +} +``` + + + +In the code above, you have: +1. Defined a RPC method, `sayHello()`, that can be called by a Worker to communicate with a Durable Object. +2. Accessed a Durable Object's attached storage, which is a private SQLite database only accesible to the object, using [SQL API](/durable-objects/api/storage-api/#sqlexec) methods (`sql.exec()`) available on `ctx.storage` . +3. Returned an object representing the single row query result using `one()`, which checks that the query result has exactly one row. +4. Return the `greeting` column from the row object result. + +## 4. Instantiate and communicate with a Durable Object + +:::note + +Durable Objects do not receive requests directly from the Internet. Durable Objects receive requests from Workers or other Durable Objects. +This is achieved by configuring a binding in the calling Worker for each Durable Object class that you would like it to be able to talk to. These bindings must be configured at upload time. Methods exposed by the binding can be used to communicate with particular Durable Object instances. +::: + +A Worker is used to [access Durable Objects](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/). + +To communicate with a Durable Object, the Worker's fetch handler should look like the following: + + + +```js +export default { + async fetch(request, env) { + let id = env.MY_DURABLE_OBJECT.idFromName(new URL(request.url).pathname); + + let stub = env.MY_DURABLE_OBJECT.get(id); + + let greeting = await stub.sayHello(); + + return new Response(greeting); + }, +}; +``` + + + +```ts +export default { + async fetch(request, env, ctx): Promise { + let id = env.MY_DURABLE_OBJECT.idFromName(new URL(request.url).pathname); + + let stub = env.MY_DURABLE_OBJECT.get(id); + + let greeting = await stub.sayHello(); + + return new Response(greeting); + }, +} satisfies ExportedHandler; +``` + + + +In the code above, you have: + +1. Exported your Worker's main event handlers, such as the `fetch()` handler for receiving HTTP requests. +2. Passed `env` into the `fetch()` handler. Bindings are delivered as a property of the environment object passed as the second parameter when an event handler or class constructor is invoked. By calling the `idFromName()` function on the binding, you use a string-derived object ID. You can also ask the system to [generate random unique IDs](/durable-objects/best-practices/access-durable-objects-from-a-worker/#generate-ids-randomly). System-generated unique IDs have better performance characteristics, but require you to store the ID somewhere to access the Object again later. +3. Derived an object ID from the URL path. `MY_DURABLE_OBJECT.idFromName()` always returns the same ID when given the same string as input (and called on the same class), but never the same ID for two different strings (or for different classes). In this case, you are creating a new object for each unique path. +4. Constructed the stub for the Durable Object using the ID. A stub is a client object used to send messages to the Durable Object. +5. Called a Durable Object by invoking a RPC method, `sayHello()`, on the Durable Object, which returns a `Hello, World!` string greeting. +6. Received an HTTP response back to the client by constructing a HTTP Response with `return new Response()`. + +Refer to [Access a Durable Object from a Worker](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/) to learn more about communicating with a Durable Object. + +## 5. Configure Durable Object bindings + +[Bindings](/workers/runtime-apis/bindings/) allow your Workers to interact with resources on the Cloudflare developer platform. The Durable Object bindings in your Worker project's `wrangler.toml` will include a binding name (for this guide, use `MY_DURABLE_OBJECT`) and the class name (`MyDurableObject`). + +```toml +[[durable_objects.bindings]] +name = "MY_DURABLE_OBJECT" +class_name = "MyDurableObject" + +# or + +[durable_objects] +bindings = [ + { name = "MY_DURABLE_OBJECT", class_name = "MyDurableObject" } +] +``` + +The `[[durable_objects.bindings]]` section contains the following fields: + +- `name` - Required. The binding name to use within your Worker. +- `class_name` - Required. The class name you wish to bind to. +- `script_name` - Optional. Defaults to the current [environment's](/durable-objects/reference/environments/) Worker code. + +## 6. Configure Durable Object class with SQLite storage backend + +A migration is a mapping process from a class name to a runtime state. You perform a migration when creating a new Durable Object class, or when renaming, deleting or transferring an existing Durable Object class. + +Migrations are performed through the `[[migrations]]` configurations key in your `wrangler.toml` file. + +The Durable Object migration to create a new Durable Object class with SQLite storage backend will look like the following in your Worker's `wrangler.toml` file: + +```toml +[[migrations]] +tag = "v1" # Should be unique for each entry +new_sqlite_classes = ["MyDurableObject"] # Array of new classes +``` + +Refer to [Durable Objects migrations](/durable-objects/reference/durable-objects-migrations/) to learn more about the migration process. + +## 7. Develop a Durable Object Worker locally + +To test your Durable Object locally, run [`wrangler dev`](/workers/wrangler/commands/#dev): + +```sh +npx wrangler dev +``` + +In your console, you should see a`Hello world` string returned by the Durable Object. + +## 8. Deploy your Durable Object Worker + +To deploy your Durable Object Worker: + +```sh +npx wrangler deploy +``` + +Once deployed, you should be able to see your newly created Durable Object Worker on the [Cloudflare dashboard](https://dash.cloudflare.com/), **Workers & Pages** > **Overview**. + +Preview your Durable Object Worker at `..workers.dev`. + +By finishing this tutorial, you have successfully created, tested and deployed a Durable Object. + +### Related resources + +- [Access a Durable Object from a Worker](/durable-objects/best-practices/access-durable-objects-from-a-worker/) +- [Create Durable Object stubs](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/) +- [Access Durable Objects Storage](/durable-objects/best-practices/access-durable-objects-storage/) +- [Miniflare](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare) - Helpful tools for mocking and testing your Durable Objects. diff --git a/src/content/docs/durable-objects/get-started/video-series/index.mdx b/src/content/docs/durable-objects/get-started/video-series/index.mdx index 36c1cbdbd38fac2..02e39e4204066db 100644 --- a/src/content/docs/durable-objects/get-started/video-series/index.mdx +++ b/src/content/docs/durable-objects/get-started/video-series/index.mdx @@ -2,7 +2,7 @@ pcx_content_type: navigation title: Video series sidebar: - order: 2 + order: 3 next: true ---