INTEGRITY Документация

← Cloudflare Workers / workers / tutorials

Подключение к базе данных PostgreSQL с помощью Cloudflare Workers

В этом руководстве вы узнаете, как создать приложение Cloudflare Workers и подключить его к базе данных PostgreSQL с помощью TCP-сокеты и Hyperdrive. Приложение Workers, которое вы создадите в этом руководстве, будет взаимодействовать с базой данных товаров в PostgreSQL.

Предварительные требования

Чтобы продолжить:

  1. Зарегистрируйтесь для получения Аккаунт Cloudflare ↗ если вы ещё этого не сделали.
  2. Установка npm ↗.
  3. Установка Node.js ↗. Используйте менеджер версий Node, например Volta ↗ или nvm ↗ чтобы избежать проблем с правами доступа и переключать версии Node.js. Wrangler требует версии Node 16.17.0 или более поздней версии.
  4. Убедитесь, что у вас есть доступ к базе данных PostgreSQL.

1. Создайте приложение Worker

Сначала используйте create-cloudflare CLI ↗ чтобы создать новое приложение Worker. Для этого откройте окно терминала и выполните следующую команду:

npm create cloudflare@latest -- postgres-tutorial

Это предложит вам установить create-cloudflare ↗ пакет и проведёт вас через мастер настройки.

Для настройки выберите следующие параметры:

Если вы решите развернуть проект, вам будет предложено пройти аутентификацию (если вход еще не выполнен), после чего проект будет развернут. После этого вы всё равно сможете изменить код Worker и развернуть его повторно в конце этого руководства.

Теперь перейдите в только что созданный каталог:

cd postgres-tutorial

Включите совместимость с Node.js

Совместимость с Node.js требуется для драйверов баз данных, включая Postgres.js, и должен быть настроен для вашего проекта Workers.

Для дат совместимости 2026-08-04 или более поздней версии проекты Workers и Pages включают оба nodejs_compat и nodejs_compat_v2 по умолчанию. Встроенные API среды выполнения и полифиллы доступны без дополнительной настройки. Для этих дат совместимости данные флаги не используются. Существующим проектам не нужно удалять их при обновлении даты совместимости.

Если ваша дата совместимости раньше 2026-08-04, добавьте nodejs_compat флаг совместимости в ваш конфигурационный файл Wrangler чтобы включить:

{
	"compatibility_flags": [
		"nodejs_compat"
	]
}
compatibility_flags = [ "nodejs_compat" ]

Чтобы отключить Совместимость с Node.js полностью при дате совместимости 2026-08-04 или более поздней версии удалите положительные флаги, если они есть. Затем добавьте оба no_nodejs_compat и no_nodejs_compat_v2. Примеры настройки см. в Флаг совместимости с Node.js.

2. Добавление библиотеки подключения PostgreSQL

Чтобы подключиться к базе данных PostgreSQL, вам потребуется pg библиотека. В каталоге приложения Worker выполните следующую команду, чтобы установить библиотеку:

npm i pg

Затем установите типы TypeScript для pg библиотеку, чтобы включить проверку типов и автодополнение в коде TypeScript:

npm i -D @types/pg

3. Настройка подключения к базе данных PostgreSQL

Выберите один из двух способов подключения к базе данных PostgreSQL:

  1. Используйте строку подключения.
  2. Настройка явных параметров.

Используйте строку подключения

Строка подключения содержит всю информацию, необходимую для подключения к базе данных. Это URL, который содержит следующую информацию:

postgresql://username:password@host:port/database

Замените username, password, host, port, а также database соответствующими значениями для вашей базы данных PostgreSQL.

Укажите свою строку подключения как secret чтобы он не хранился в виде открытого текста. Используйте wrangler secret put с именем переменной из примера DB_URL:

npx wrangler secret put DB_URL
➜  wrangler secret put DB_URL
-------------------------------------------------------
? Enter a secret value: › ********************
✨ Success! Uploaded secret DB_URL

Задайте свой DB_URL секрет локально в .dev.vars файл, как описано в Локальная разработка с секретами.

.dev.vars
DB_URL="<ENTER YOUR POSTGRESQL CONNECTION STRING>"

Настройка явных параметров

Настройте каждый параметр базы данных как переменная окружения через Панель управления Cloudflare или в файле Wrangler. Ознакомьтесь с примером конфигурации файла Wrangler:

{
	"vars": {
		"DB_USERNAME": "postgres",
		// Set your password by creating a secret so it is not stored as plain text
		"DB_HOST": "ep-aged-sound-175961.us-east-2.aws.neon.tech",
		"DB_PORT": 5432,
		"DB_NAME": "productsdb"
	}
}
[vars]
DB_USERNAME = "postgres"
DB_HOST = "ep-aged-sound-175961.us-east-2.aws.neon.tech"
DB_PORT = 5_432
DB_NAME = "productsdb"

Чтобы задать пароль в качестве secret чтобы он не хранился в виде открытого текста, используйте wrangler secret put. DB_PASSWORD это пример имени переменной для обращения к этому секрету в вашем Worker:

npx wrangler secret put DB_PASSWORD
-------------------------------------------------------
? Enter a secret value: › ********************
✨ Success! Uploaded secret DB_PASSWORD

4. Подключитесь к базе данных PostgreSQL в Worker

Откройте основной файл вашего Worker (например, worker.ts) и импортируйте Client класс из pg библиотека:

import { Client } from "pg";

В fetch обработчике события, подключитесь к базе данных PostgreSQL выбранным способом: либо через строку подключения, либо через явные параметры.

Используйте строку подключения

// create a new Client instance using the connection string
const sql = new Client({ connectionString: env.DB_URL });
// connect to the PostgreSQL database
await sql.connect();

Настройка явных параметров

// create a new Client instance using explicit parameters
const sql = new Client({
	username: env.DB_USERNAME,
	password: env.DB_PASSWORD,
	host: env.DB_HOST,
	port: env.DB_PORT,
	database: env.DB_NAME,
	ssl: true, // Enable SSL for secure connections
});
// connect to the PostgreSQL database
await sql.connect();

5. Работайте с базой данных продуктов

Чтобы показать, как взаимодействовать с базой данных продуктов, вы получите данные из products таблицу, выполняя запрос к ней при получении запроса.

Замените существующий код в worker.ts файл следующим кодом:

import { Client } from "pg";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a new Client instance using the connection string
		// or explicit parameters as shown in the previous steps.
		// Here, we are using the connection string method.
		const sql = new Client({
			connectionString: env.DB_URL,
		});
        // Connect to the PostgreSQL database
        await sql.connect();

        // Query the products table
        const result = await sql.query("SELECT * FROM products");

        // Return the result as JSON
        return new Response(JSON.stringify(result.rows), {
            headers: {
                "Content-Type": "application/json",
            },
        });
	},
} satisfies ExportedHandler<Env>;

Этот код устанавливает соединение с базой данных PostgreSQL из приложения Worker и выполняет запрос к products таблицу и возвращает результаты в виде ответа JSON.

6. Разверните Worker

Выполните следующую команду, чтобы развернуть Worker:

npx wrangler deploy

Ваше приложение теперь доступно по адресу <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev.

После развёртывания вы можете взаимодействовать с базой данных продуктов PostgreSQL с помощью своего Cloudflare Worker. При каждом запросе к URL вашего Worker он будет получать данные из products таблицу и вернуть их в виде ответа JSON. Вы можете изменить запрос по своему усмотрению, чтобы получить нужные данные из базы данных продуктов.

7. Вставьте новую строку в базу данных продуктов

Чтобы вставить новую строку в products таблицу, создайте в своем Worker новую конечную точку API, которая обрабатывает POST запрос. Когда POST запрос получен с полезной нагрузкой JSON, Worker вставит новую строку в products таблицу указанными данными.

Предположим, products таблица содержит следующие столбцы: id, name, description, а также price.

Добавьте следующий фрагмент кода внутрь fetch обработчик события в вашем worker.ts файл, перед существующим кодом запроса:

import { Client } from "pg";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a new Client instance using the connection string
		// or explicit parameters as shown in the previous steps.
		// Here, we are using the connection string method.
		const sql = new Client({
			connectionString: env.DB_URL,
		});
        // Connect to the PostgreSQL database
        await sql.connect();

        const url = new URL(request.url);
        if (request.method === "POST" && url.pathname === "/products") {
            // Parse the request's JSON payload
            const productData = (await request.json()) as {
                name: string;
                description: string;
                price: number;
            };

            const name = productData.name,
                description = productData.description,
                price = productData.price;

            // Insert the new product into the products table
            const insertResult = await sql.query(
                `INSERT INTO products(name, description, price) VALUES($1, $2, $3)
    RETURNING *`,
                [name, description, price],
            );

            // Return the inserted row as JSON
            return new Response(JSON.stringify(insertResult.rows), {
                headers: { "Content-Type": "application/json" },
            });
        }

        // Query the products table
        const result = await sql.query("SELECT * FROM products");

        // Return the result as JSON
        return new Response(JSON.stringify(result.rows), {
            headers: {
                "Content-Type": "application/json",
            },
        });
	},
} satisfies ExportedHandler<Env>;

Этот фрагмент кода выполняет следующее:

  1. Проверяет, является ли запрос POST запрос, а путь URL: /products.
  2. Разбирает полезную нагрузку JSON из запроса.
  3. Создает INSERT SQL-запрос с использованием предоставленных данных о продукте.
  4. Выполняет запрос и добавляет новую строку в products в таблице.
  5. Возвращает добавленную строку в виде JSON-ответа.

Теперь при отправке POST запрос по URL вашего Worker с /products путь и данные в формате JSON, Worker добавит новую строку в products таблицу указанными данными. Когда поступает запрос к / будет выполнен, Worker вернет все товары из базы данных.

После внесения этих изменений повторно разверните Worker, выполнив:

npx wrangler deploy

Теперь Cloudflare Worker можно использовать для добавления новых строк в products таблица. Чтобы проверить эту функциональность, отправьте POST запрос по URL вашего Worker с /products путь, а также данные в формате JSON, содержащие данные нового продукта:

{
	"name": "Sample Product",
	"description": "This is a sample product",
	"price": 19.99
}

Вы успешно создали Cloudflare Worker, который подключается к базе данных PostgreSQL, получает данные и добавляет новые строки в таблицу products.

8. Используйте Hyperdrive для ускорения запросов

Создайте конфигурацию Hyperdrive, используя строку подключения к вашей базе данных PostgreSQL.

npx wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --caching-disabled

Эта команда выводит конфигурацию Hyperdrive id который будет использоваться для вашего Hyperdrive привязка. Настройте привязку, указав id в файле Wrangler.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "hyperdrive-example",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Pasted from the output of `wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string=[...]` above.
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"
		}
	]
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "hyperdrive-example"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"
compatibility_flags = [ "nodejs_compat" ]

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"

Создайте типы для привязки Hyperdrive с помощью следующей команды:

npx wrangler types

Замените имеющуюся строку подключения в коде Worker на строку подключения Hyperdrive.

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const sql = new Client({connectionString: env.HYPERDRIVE.connectionString})

		const url = new URL(request.url);

		//rest of the routes and database queries
	},
} satisfies ExportedHandler<Env>;

9. Повторно разверните Worker

Выполните следующую команду, чтобы развернуть Worker:

npx wrangler deploy

Ваше приложение Worker теперь доступно по адресу <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev, с помощью Hyperdrive. Hyperdrive ускоряет запросы к базе данных, объединяя соединения в пул и кешируя запросы по всему миру.

Следующие шаги

Чтобы узнать больше о работе с базами данных и Workers, см. Руководства и изучите Документация по базам данных.

Если у вас есть вопросы, нужна помощь или вы хотите поделиться своим проектом, присоединяйтесь к сообществу разработчиков Cloudflare на Discord ↗ чтобы пообщаться с другими разработчиками и командой Cloudflare.