Query D1 from Python Workers
The Cloudflare Workers platform supports multiple languages, including TypeScript, JavaScript, Rust and Python. This guide shows you how to query a D1 database from Python and deploy your application globally.
Prerequisites
Before getting started, you should:
- Review the D1 tutorial for TypeScript and JavaScript to learn how to create a D1 database and configure a Workers project.
- Refer to the Python language guide to understand how Python support works on the Workers platform.
- Have basic familiarity with the Python language.
If you are new to Cloudflare Workers, refer to the Get started guide first before continuing with this example.
Query from Python
This example assumes you have an existing D1 database. To allow your Python Worker to query your database, you first need to create a binding between your Worker and your D1 database and define this in your wrangler.toml
configuration file.
You will need the database_name
and database_id
for a D1 database. You can use the wrangler
CLI to create a new database or fetch the ID for an existing database as follows:
# Create a database
$ npx wrangler d1 create my-first-db
# Retrieve the database ID for an existing database
$ npx wrangler d1 info some-existing-db
# This will output a table with the database name and ID - for example:
# -------------------
# ┌───────────────────┬──────────────────────────────────────┐
# │ │ c89db32e-83f4-4e62-8cd7-7c8f97659029 │
# ├───────────────────┼──────────────────────────────────────┤
# │ name │ db-enam │
# ├───────────────────┼──────────────────────────────────────┤
# │ created_at │ 2023-06-12T16:52:03.071Z │
# └───────────────────┴──────────────────────────────────────┘
1. Configure bindings
In your wrangler.toml
file, create a new [[d1_databases]]
configuration block and set database_name
and database_id
to the name and id (respectively) of the D1 database you want to query:
wrangler.tomlname = "python-and-d1"
main = "src/entry.py"
compatibility_flags = ["python_workers"] # Required for Python Workers
compatibility_date = "2024-03-29"
[[d1_databases]]
binding = "DB" # This will be how you refer to your database in your Worker
database_name = "YOUR_DATABASE_NAME"
database_id = "YOUR_DATABASE_ID"
The value of binding
is how you will refer to your database from within your Worker. If you change this, you must change this in your Worker script as well.
2. Create your Python Worker
To create a Python Worker, create an empty file at src/entry.py
, matching the value of main
in your wrangler.toml
file with the contents below:
src/entry.pyfrom js import Response
async def on_fetch(request, env): # Do anything else you'd like on request here!
# Query D1 - we'll list all tables in our database in this example results = await env.DB.prepare("PRAGMA table_list").all() # Return a JSON response return Response.json(results)
The value of binding
in your wrangler.toml
file exactly must match the name of the variable in your Python code. This example refers to the database via a DB
binding, and query this binding via await env.DB.prepare(...)
.
You can then deploy your Python Worker directly:
$ npx wrangler deploy
# Example output
#
# Your worker has access to the following bindings:
# - D1 Databases:
# - DB: db-enam (c89db32e-83f4-4e62-8cd7-7c8f97659029)
# Total Upload: 0.18 KiB / gzip: 0.17 KiB
# Uploaded python-and-d1 (4.93 sec)
# Published python-and-d1 (0.51 sec)
# https://python-and-d1.YOUR_SUBDOMAIN.workers.dev
# Current Deployment ID: 80b72e19-da82-4465-83a2-c12fb11ccc72
Your Worker will be available at https://python-and-d1.YOUR_SUBDOMAIN.workers.dev
.
If you receive an error deploying:
- Make sure you have configured your
wrangler.toml
with thedatabase_id
anddatabase_name
of a valid D1 database. - Ensure
compatibility_flags = ["python_workers"]
is set in yourwrangler.toml
, which is required for Python. - Review the list of error codes, and ensure your code does not throw an uncaught exception.
Next steps
- Refer to Workers Python documentation to learn more about how to use Python in Workers.
- Review the D1 client API and how to query D1 databases.
- Learn how to import data to your D1 database.