← Cloudflare Workers / workers / tutorials

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

Это руководство поможет вам создавать глобально распределенные приложения с помощью Cloudflare Workers и Turso ↗, распределенная база данных на основе libSQL, размещаемая на периферийной сети (edge). Используя Workers и Turso, вы можете создавать приложения, максимально приближенные к вашим конечным пользователям, не поддерживая и не эксплуатируя инфраструктуру в десятках или сотнях регионов.

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

Прежде чем продолжить работу с этим руководством, у вас должно быть:

Успешно создали свой первый Cloudflare Worker и/или уже развёртывали Cloudflare Worker ранее.
Установлено Wrangler, инструмент командной строки для создания Cloudflare Workers.
A Учётная запись GitHub ↗, необходимый для аутентификации в Turso.
Базовое знакомство с установкой и использованием приложений командной строки (CLI).

Установка Turso CLI

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

# On macOS or Linux with Homebrew
brew install chiselstrike/tap/turso

# Manual scripted installation
curl -sSfL <https://get.tur.so/install.sh> | bash

После установки Turso CLI убедитесь, что CLI доступен в PATH вашей командной оболочки:

turso --version

# This should output your current Turso CLI version (your installed version may be higher):
turso version v0.51.0

Создание и заполнение базы данных

Прежде чем создать первую базу данных Turso, необходимо войти в CLI с помощью учётной записи GitHub, выполнив команду:

turso auth login


Waiting for authentication...
✔  Success! Logged in as <your GitHub username>

turso auth login откроет окно браузера и предложит вам войти в аккаунт GitHub, если вы ещё не выполнили вход. При первом запуске вам нужно будет предоставить приложению Turso разрешение на использование вашего аккаунта. Выберите Одобрить чтобы предоставить Turso необходимые разрешения.

После аутентификации вы можете создать базу данных, выполнив turso db create <DATABASE_NAME>. Turso автоматически выберет ближайшее к вам местоположение.

turso db create my-db

# Example:
[===>                ]
Creating database my-db in Los Angeles, California (US) (lax)
# Once succeeded:
Created database my-db in Los Angeles, California (US) (lax) in 34 seconds.

После создания первой базы данных к ней можно подключиться напрямую и выполнять SQL-запросы:

turso db shell my-db

Чтобы начать работу с базой данных, создайте и опишите схему для первой таблицы. В этом примере вы создадите example_users таблицу с одним столбцом: email (типа text) и затем заполните его одним адресом электронной почты.

В открытой оболочке вставьте следующий SQL:

create table example_users (email text);
insert into example_users values ('[email protected]');

Если SQL-инструкции выполнены успешно, вывод отсутствует. Обратите внимание, что завершающие точки с запятой (;) необходимы для завершения каждого SQL-выражения.

Тип .quit чтобы выйти из оболочки.

Используйте Wrangler, чтобы создать проект Workers

Интерфейс командной строки Workers, Wrangler, позволяет создавать, разрабатывать локально и развертывать ваши проекты Workers.

Чтобы создать новый проект Workers (с именем worker-turso-ts), выполните следующую команду:

npm create cloudflare@latest -- worker-turso-ts

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

Для С чего вы хотите начать?, выберите Hello World example.
Для Какой шаблон вы хотите использовать?, выберите Worker only.
Для Какой язык вы хотите использовать?, выберите TypeScript.
Для Хотите использовать git для контроля версий?, выберите Yes.
Для Хотите развернуть приложение?, выберите No (мы внесём некоторые изменения перед развёртыванием).

Чтобы начать разработку Worker, cd в каталог вашего нового проекта:

cd worker-turso-ts

Теперь в каталоге проекта у вас есть следующие файлы:

wrangler.json / wrangler.toml: конфигурационный файл Wrangler
src/index.ts: Минимальный Worker Hello World, написанный на TypeScript
package.json: Минимальный файл конфигурации зависимостей Node.
tsconfig.json: Конфигурация TypeScript, включающая типы Workers. Создаётся только при явном указании.

Для этого руководства нужен только конфигурационный файл Wrangler и src/index.ts файле имеют значение. Остальные файлы редактировать не нужно, их следует оставить как есть.

Настройка Worker для базы данных Turso

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

LIBSQL_DB_URL - Строка подключения для вашей базы данных Turso.
LIBSQL_DB_AUTH_TOKEN - Токен аутентификации для вашей базы данных Turso. Храните его в секрете и не добавляйте в исходный код.

Чтобы получить URL-адрес базы данных, выполните следующую команду Turso CLI и скопируйте результат:

turso db show my-db --url

libsql://my-db-<your-github-username>.turso.io

Откройте конфигурационный файл Wrangler в редакторе и в конце файла создайте новый [vars] раздел, представляющий переменные окружения для вашего проекта:

{
	"vars": {
		"LIBSQL_DB_URL": "paste-your-url-here"
	}
}

[vars]
LIBSQL_DB_URL = "paste-your-url-here"

Сохраните изменения в конфигурационный файл Wrangler.

Затем создайте долгоживущий токен аутентификации, который Worker будет использовать при подключении к базе данных. Выполните следующую команду Turso CLI и скопируйте результат в буфер обмена:

turso db tokens create my-db -e none
# Will output a long text string (an encoded JSON Web Token)

Чтобы сохранить этот токен в тайне:

Вы создадите .dev.vars файл для локальной разработки. Не добавляйте этот файл в систему контроля версий. Вам следует добавить .dev.vars to your .gitignore` файл, если вы используете Git.

Вы также создадите secret чтобы токен аутентификации оставался конфиденциальным.

Сначала создайте новый файл с именем .dev.vars следующей структурой. Вставьте токен аутентификации в кавычки:

LIBSQL_DB_AUTH_TOKEN="<YOUR_AUTH_TOKEN>"

Сохраните свои изменения в .dev.vars. Затем сохраните токен аутентификации как секрет, на который будет ссылаться ваш продакшен-Worker. Выполните следующую wrangler secret команду, чтобы создать секрет с вашим токеном:

# Ensure you specify the secret name exactly: your Worker will need to reference it later.
npx wrangler secret put LIBSQL_DB_AUTH_TOKEN

? Enter a secret value: › <paste your token here>

Выберите <Enter> на клавиатуре, чтобы сохранить токен как секрет. Оба LIBSQL_DB_URL и LIBSQL_DB_AUTH_TOKEN будет доступен в окружении вашего Worker во время выполнения.

Установка дополнительных библиотек

Установите клиентскую библиотеку Turso и роутер:

npm i @libsql/client itty-router

@libsql/client библиотека позволяет выполнять запросы к базе данных Turso. itty-router библиотека представляет собой лёгкий маршрутизатор, который вы будете использовать для обработки входящих запросов к worker.

Напишите свой Worker

Теперь вы напишете Worker, который будет:

Обработка HTTP-запроса.
Направьте его конкретному обработчику, чтобы либо вывести список всех пользователей в базе данных, либо добавить нового пользователя.
Возвращает результаты и/или признак успешного выполнения.

Откройте src/index.ts и удалите существующий шаблон. Скопируйте приведённый ниже код без изменений и вставьте его в файл:

import { Client as LibsqlClient, createClient } from "@libsql/client/web";
import { Router, RouterType } from "itty-router";

export interface Env {
	// The environment variable containing your the URL for your Turso database.
	LIBSQL_DB_URL?: string;
	// The Secret that contains the authentication token for your Turso database.
	LIBSQL_DB_AUTH_TOKEN?: string;

	// These objects are created before first use, then stashed here
	// for future use
	router?: RouterType;
}

export default {
	async fetch(request, env): Promise<Response> {
		if (env.router === undefined) {
			env.router = buildRouter(env);
		}

		return env.router.fetch(request);
	},
} satisfies ExportedHandler<Env>;

function buildLibsqlClient(env: Env): LibsqlClient {
	const url = env.LIBSQL_DB_URL?.trim();
	if (url === undefined) {
		throw new Error("LIBSQL_DB_URL env var is not defined");
	}

	const authToken = env.LIBSQL_DB_AUTH_TOKEN?.trim();
	if (authToken === undefined) {
		throw new Error("LIBSQL_DB_AUTH_TOKEN env var is not defined");
	}

	return createClient({ url, authToken });
}

function buildRouter(env: Env): RouterType {
	const router = Router();

	router.get("/users", async () => {
		const client = buildLibsqlClient(env);
		const rs = await client.execute("select * from example_users");
		return Response.json(rs);
	});

	router.get("/add-user", async (request) => {
		const client = buildLibsqlClient(env);
		const email = request.query.email;
		if (email === undefined) {
			return new Response("Missing email", { status: 400 });
		}
		if (typeof email !== "string") {
			return new Response("email must be a single string", { status: 400 });
		}
		if (email.length === 0) {
			return new Response("email length must be > 0", { status: 400 });
		}

		try {
			await client.execute({
				sql: "insert into example_users values (?)",
				args: [email],
			});
		} catch (e) {
			console.error(e);
			return new Response("database insert failed");
		}

		return new Response("Added");
	});

	router.all("*", () => new Response("Not Found.", { status: 404 }));

	return router;
}

Сохраните ваш src/index.ts файл своими изменениями.

Примечание:

При работе с Cloudflare Workers импорт клиентской библиотеки libSQL '@libsql/client/web' необходимо использовать именно в таком виде, как показано. Импорт без web не будет работать в среде Workers.
Env интерфейс содержит переменную окружения и секрет, которые вы определили ранее.
Env интерфейс также кеширует объект клиента libSQL и маршрутизатор, которые создаются при первом запросе к Worker.
/users маршрут получает все строки из example_users таблицу, которую вы создали в оболочке Turso. Он просто сериализует ResultSet объект в виде JSON напрямую вызывающей стороне.
/add-user маршрут добавляет новую строку, используя значение, переданное в строке запроса.

Настроив окружение и подготовив код, вы протестируете Worker локально перед развертыванием.

Запустите Worker локально с помощью Wrangler

Чтобы запустить локальный экземпляр нашего Worker (полностью на своей машине), выполните следующую команду:

npx wrangler dev

Вы должны увидеть вывод, похожий на следующий:

Your worker has access to the following bindings:
- Vars:
  - LIBSQL_DB_URL: "your-url"
⎔ Starting a local server...
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ [b] open a browser, [d] open Devtools, [l] turn off local mode, [c] clear console, [x] to exit                                                                  	│
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Debugger listening on ws://127.0.0.1:61918/1064babd-bc9d-4bed-b171-b35dab3b7680
For help, see: https://nodejs.org/en/docs/inspector
Debugger attached.
[mf:inf] Worker reloaded! (40.25KiB)
[mf:inf] Listening on 0.0.0.0:8787
[mf:inf] - http://127.0.0.1:8787
[mf:inf] - http://192.168.1.136:8787
[mf:inf] Updated `Request.cf` object cache!

Адрес localhost: тот, что начинается с 127.0.0.1 в нём, представляет собой веб-сервер, запущенный локально на вашем компьютере.

Подключитесь к нему и убедитесь, что ваш Worker возвращает адрес электронной почты, который вы указали при создании example_users таблицу, перейдя в /users маршрут в браузере: http://127.0.0.1:8787/users ↗.

Вы должны увидеть JSON, похожий на приведённый ниже, с данными из example_users таблица:

{
	"columns": ["email"],
	"rows": [{ "email": "[email protected]" }],
	"rowsAffected": 0
}

Тестирование /add-users маршрут и передать в него адрес электронной почты для вставки: http://127.0.0.1:8787/[email protected] ↗

Вы должны увидеть текст “Added”. Если открыть первый URL с /users маршрут снова (http://127.0.0.1:8787/users ↗), отобразится только что добавленная строка. Это можно повторять сколько угодно раз. Обратите внимание, что из-за особенностей архитектуры приложение не будет запрещать добавление повторяющихся адресов электронной почты.

Чтобы выйти из Wrangler, введите q в оболочку, в которой он был запущен.

Deploy to Cloudflare

После того как вы убедились, что Worker может подключаться к базе данных Turso, разверните Worker. Выполните следующую команду Wrangler, чтобы развернуть Worker в глобальной сети Cloudflare:

npx wrangler deploy

При первом запуске этой команды откроется браузер, который предложит вам войти в свою учётную запись Cloudflare и предоставить Wrangler необходимые разрешения.

deploy команда выведет следующее:

Your worker has access to the following bindings:
- Vars:
  - LIBSQL_DB_URL: "your-url"
...
Published worker-turso-ts (0.19 sec)
  https://worker-turso-ts.<your-Workers-subdomain>.workers.dev
Current Deployment ID: f9e6b48f-5aac-40bd-8f44-8a40be2212ff

Теперь у вас развёрнут Worker, который может подключаться к базе данных Turso, выполнять к ней запросы и добавлять новые данные.

Необязательно: очистка

Чтобы удалить ресурсы, созданные в ходе этого руководства:

Если вы не хотите сохранять этот Worker, выполните npx wrangler delete worker-turso-ts чтобы удалить развёрнутый Worker.
Также базу данных Turso можно удалить через turso db destroy my-db.

Найдите полный исходный код проекта на GitHub ↗.
Узнайте, как отладка вашего Cloudflare Worker.
Присоединяйтесь к Cloudflare Developer Discord ↗.
Присоединяйтесь к ChiselStrike (Turso) Discord ↗.