Cloudflare Workers database integration
Use the Cloudflare database integration feature to automatically connect Workers to your PlanetScale database.
Introduction
Cloudflare Workers database integration is designed to connect your Cloudflare Workers to data sources automatically by generating connection strings and storing them in the worker's secrets.
This article will utilize a sample repository that is a preconfigured Cloudflare Worker you can use to deploy to your Cloudflare account.
Prerequisites
- NodeJS installed
- A PlanetScale account
- The PlanetScale CLI
- A Cloudflare account
Set up the database
- Create a database in your PlanetScale account named
bookings_db
.
pscale database create bookings_db
- Connect to the
main
branch of the new database.
pscale shell bookings_db main
- Run the following commands to create a table in the database and populate it with some data.
CREATE TABLE hotels (
id INT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(50) NOT NULL,
address VARCHAR(50) NOT NULL,
stars FLOAT(2) UNSIGNED
);
INSERT INTO hotels (name, address, stars) VALUES
('Hotel California', '1967 Can Never Leave Ln, San Fancisco CA, 94016', 7.6),
('The Galt House', '140 N Fourth St, Louisville, KY 40202', 8.0);
Deploy the Cloudflare Worker
- Clone the sample repository.
git clone https://github.com/planetscale/cloudflare-workers-quickstart.git
- Navigate to the
worker
folder of the repository and install the dependencies.
cd cloudflare-workers-quickstart/worker
npm install
- Deploy the Worker to your Cloudflare account.
npx wrangler publish
Configure the Cloudflare PlanetScale integration
- Log into the Cloudflare dashboard and navigate to "Workers" > "Overview". You should see a service in the list named "planetscale-worker". Select it from the list.
- Select the "Settings" tab, then "Integrations", and finally "Add Integration" in the PlanetScale card.
- Click "Accept" under Review and grant permissions to allow the wizard to write the database connection details to the Worker secrets.
- Under Connect to PlanetScale, click "Connect" to start the process of connecting your PlanetScale and Cloudflare accounts.
- A modal will appear allowing you to grant access to your organization, database, and branch. Start by selecting your organization from the list. This demonstration uses an organization named “ps-deved”.
- Select the “bookings_db” database from the list in the Databases card, and the “main” branch from the list in the Branches card. Finally, click "Authorize access".
- Select your organization again from the list and click "Continue".
- Select your database and the user role you want the integration to have.
- Select the “main” branch from the list and click "Continue".
- You’ll be given the option to rename the secrets that will be configured on your behalf. These can be left as is. Click "Add Integration" to complete the process.
Test the integration
Back in the overview of the Worker, there is a preview URL that you can use to open a new tab in your browser that runs the Worker and displays the results. Once you’ve located the preview URL, click it to test the Worker.
Once the integration is configured, you can also run the project on your computer using:
npx wrangler dev
This will automatically use the secrets defined in Cloudflare to run the Worker on your computer.
Test other database operations (optional)
To test other database operations that are mapped to HTTP methods, you may use the provided tests.http
file which is designed to work with the VSCode REST client plugin. The file is preconfigured to work with the local environment, or you can change the @host
variable to match the URL provided in the Cloudflare dashboard that cooresponds with your Worker project.
Method | Operation |
---|---|
GET / | Get a list of all hotels. |
POST / | Create a hotel. |
PUT /:id | Update a hotel. |
DELETE /:id | Delete a hotel. |
What's next?
Once you're done with development, it is highly recommended that safe migrations be turned on for your main
production branch to protect from accidental schema changes and enable zero-downtime deployments.
When you're ready to make more schema changes, you'll create a new branch off of your production branch. Branching your database creates an isolated copy of your production schema so that you can easily test schema changes in development. Once you're happy with the changes, you'll open a deploy request. This will generate a diff showing the changes that will be deployed, making it easy for your team to review.
Learn more about how PlanetScale allows you to make non-blocking schema changes to your database tables without locking or causing downtime for production databases.
Need help?
Get help from the PlanetScale support team, or join our GitHub discussion board to see how others are using PlanetScale.