Query D1 from Python Workers

Learn how to query D1 from a Python Worker

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:

npx wrangler d1 create my-first-db

npx wrangler d1 info some-existing-db

# ┌───────────────────┬──────────────────────────────────────┐
# │                   │ 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
wrangler.json

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"

{
  "name": "python-and-d1",
  "main": "src/entry.py",
  "compatibility_flags": [
    "python_workers"
  ],
  "compatibility_date": "2024-03-29",
  "d1_databases": [
    {
      "binding": "DB",
      "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:

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 Workers Binding API and how to query D1 databases.
Learn how to import data to your D1 database.

Was this helpful?

Cloudflare Dashboard Discord Community Learning Center Support Portal