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:

1. Review the D1 tutorial for TypeScript and JavaScript to learn how to create a D1 database and configure a Workers project.
2. Refer to the Python language guide to understand how Python support works on the Workers platform.
3. 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.toml
name = "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.py
from 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 the database_id and database_name of a valid D1 database.
• Ensure compatibility_flags = ["python_workers"] is set in your wrangler.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.