INTEGRITY Dokumentace

← Hyperdrive (Postgres & MySQL) / hyperdrive / tutorials

Vytvořte serverless a globálně distribuované API pro časové řady s Timescale

V tomto tutoriálu se naučíte vytvořit API na Workers, které bude přijímat a dotazovat časové řady dat uložených v Timescale ↗ (zrychlují PostgreSQL v cloudu).

Vytvoříte a nasadíte funkci Worker, která zpřístupní API routy pro příjem dat, a použijete Hyperdrive ↗ k proxování vašeho připojení k databázi z edge sítě a k udržování fondu připojení, aby nebylo nutné vytvářet nové připojení k databázi při každém požadavku.

Naučíte se, jak:

Více o Timescale se dozvíte přečtením jejich dokumentace ↗.

1. Vytvořte projekt Worker

Spusťte následující příkaz a z příkazové řádky vytvořte projekt Worker:

npm create cloudflare@latest -- timescale-api

Při nastavení vyberte následující možnosti:

Poznamenejte si URL, na kterou byla vaše aplikace nasazena. Budete ji potřebovat při konfiguraci GitHub webhooku.

Přejděte do adresáře, který jste právě vytvořili pro svůj projekt Worker:

cd timescale-api

2. Připravte svou Timescale Service

Pokud vytváříte novou službu, přejděte na Timescale Console ↗ a postupujte podle těchto kroků:

  1. Vyberte Create Service kliknutím na černé plus v pravém horním rohu.
  2. Vyberte Časové řady jako typ služby.
  3. Zvolte požadovaný region a velikost instance. Pro tento návod postačí 1 CPU.
  4. Nastavte název služby, který nahradí ten náhodně vygenerovaný.
  5. Vyberte Create Service.
  6. Na pravé straně rozbalte Informace o připojení dialogovém okně a zkopírujte URL služby.
  7. Zkopírujte zobrazené heslo. Znovu ho už později zobrazit nepůjde.
  8. Vyberte Heslo mám uložené, přejít na přehled služby.

Pokud používáte službu, kterou jste vytvořili dříve, informace o připojení ke službě najdete v Timescale Console ↗:

  1. Vyberte službu (databázi), ke které se má Hyperdrive připojit.
  2. Rozbalit Informace o připojení.
  3. Zkopírujte URL služby. Service URL je připojovací řetězec, který Hyperdrive použije k připojení. Tento řetězec obsahuje název hostitele databáze, číslo portu a název databáze.

Vložte své heslo do URL služby následovně (část za znakem @ ponechte beze změny):

postgres://tsdbadmin:YOURPASSWORD@...

Dále bude označováno jako SERVICEURL v následujících částech.

3. Vytvořte svou Hypertable

Timescale umožňuje převést běžné tabulky PostgreSQL na hypertables ↗, tabulky určené pro časové řady, události nebo analytická data. Po této změně Timescale automaticky spravuje rozdělení hypertabulky na oddíly a zároveň umožňuje využívat další funkce, jako je komprese nebo průběžné agregace.

Připojte se ke své databázi Timescale pomocí Service URL, které jste zkopírovali v předchozím kroku (obsahuje vložené heslo).

Pokud používáte výchozí nástroj příkazové řádky PostgreSQL psql ↗ k připojení byste spustili psql podobně jako níže (přičemž nahradíte vaše URL služby z předchozího kroku). Připojit se můžete také pomocí grafického nástroje, jako je PgAdmin ↗.

psql <SERVICEURL>

Jakmile jste připojeni, vytvořte tabulku vložením následujícího SQL:

CREATE TABLE readings(
  ts timestamptz DEFAULT now() NOT NULL,
  sensor UUID NOT NULL,
  metadata jsonb,
  value numeric NOT NULL
 );

SELECT create_hypertable('readings', 'ts');

O zbytek se při příjmu a dotazování dat postará Timescale.

4. Vytvořte konfiguraci databáze

Pro vytvoření nové instance Hyperdrive budete potřebovat:

Hyperdrive využívá create příkaz s --connection-string argument pro předání těchto informací. Spusťte jej následovně:

npx wrangler hyperdrive create hyperdrive --connection-string="SERVICEURL"

Tento příkaz vypíše ID vašeho Hyperdrive. Nyní můžete konfiguraci Hyperdrive připojit (bind) k vašemu Workeru v konfiguraci Wrangler tak, že nahradíte obsah následujícím:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "timescale-api",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"compatibility_flags": [
		"nodejs_compat"
	],
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "your-id-here"
		}
	]
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "timescale-api"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"
compatibility_flags = [ "nodejs_compat" ]

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "your-id-here"

Nainstalujte ovladač Postgres do svého projektu Worker:

npm i pg

Nyní zkopírujte níže uvedený kód Workeru a nahraďte jím aktuální kód v ./src/index.ts. Následující kód:

  1. Pro připojení k Timescale využívá Hyperdrive připojovací řetězec vygenerovaný z env.HYPERDRIVE.connectionString přímo ovladači.
  2. Vytvoří POST trasu, která přijímá pole odečtů JSON a vkládá je do Timescale v rámci jedné transakce.
  3. Vytvoří GET trasu, která přijímá limit parametr a vrací nejnovější naměřené hodnoty. Toto řešení lze upravit tak, aby filtrovalo podle ID nebo podle časového razítka.
import { Client } from "pg";

export interface Env {
	HYPERDRIVE: Hyperdrive;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a new client on each request. Hyperdrive maintains the underlying
		// database connection pool, so creating a new client is fast.
		const client = new Client({
			connectionString: env.HYPERDRIVE.connectionString,
		});
		await client.connect();

		const url = new URL(request.url);
		// Create a route for inserting JSON as readings
		if (request.method === "POST" && url.pathname === "/readings") {
			// Parse the request's JSON payload
			const productData = await request.json();

			// Write the raw query. You are using jsonb_to_recordset to expand the JSON
			// to PG INSERT format to insert all items at once, and using coalesce to
			// insert with the current timestamp if no ts field exists
			const insertQuery = `
      INSERT INTO readings (ts, sensor, metadata, value)
      SELECT coalesce(ts, now()), sensor, metadata, value FROM jsonb_to_recordset($1::jsonb)
      AS t(ts timestamptz, sensor UUID, metadata jsonb, value numeric)
  `;

			const insertResult = await client.query(insertQuery, [
				JSON.stringify(productData),
			]);

			// Collect the raw row count inserted to return
			const resp = new Response(JSON.stringify(insertResult.rowCount), {
				headers: { "Content-Type": "application/json" },
			});

			return resp;

			// Create a route for querying within a time-frame
		} else if (request.method === "GET" && url.pathname === "/readings") {
			const limit = url.searchParams.get("limit");

			// Query the readings table using the limit param passed
			const result = await client.query(
				"SELECT * FROM readings ORDER BY ts DESC LIMIT $1",
				[limit],
			);

			// Return the result as JSON
			const resp = new Response(JSON.stringify(result.rows), {
				headers: { "Content-Type": "application/json" },
			});

			return resp;
		}
	},
} satisfies ExportedHandler<Env>;

5. Nasaďte svůj Worker

Spusťte následující příkaz a znovu nasaďte svůj Worker:

npx wrangler deploy

Vaše aplikace je nyní spuštěná a dostupná na adrese timescale-api.<YOUR_SUBDOMAIN>.workers.dev. Přesné URI se zobrazí ve výstupu příkazu wrangler, který jste právě spustili.

Po nasazení můžete se svou databází Timescale s IoT záznamy komunikovat pomocí Cloudflare Worker. Připojení z edge bude rychlejší, protože k připojení z edge využíváte Cloudflare Hyperdrive.

Svůj Cloudflare Worker nyní můžete použít k vkládání nových řádků do readings tabulky. Chcete-li tuto funkci otestovat, odešlete POST požadavek na URL adresu vašeho Workeru s /readings cestu spolu s JSON payloadem obsahujícím data nového produktu:

[
	{ "sensor": "6f3e43a4-d1c1-4cb6-b928-0ac0efaf84a5", "value": 0.3 },
	{ "sensor": "d538f9fa-f6de-46e5-9fa2-d7ee9a0f0a68", "value": 10.8 },
	{ "sensor": "5cb674a0-460d-4c80-8113-28927f658f5f", "value": 18.8 },
	{ "sensor": "03307bae-d5b8-42ad-8f17-1c810e0fbe63", "value": 20.0 },
	{ "sensor": "64494acc-4aa5-413c-bd09-2e5b3ece8ad7", "value": 13.1 },
	{ "sensor": "0a361f03-d7ec-4e61-822f-2857b52b74b3", "value": 1.1 },
	{ "sensor": "50f91cdc-fd19-40d2-b2b0-c90db3394981", "value": 10.3 }
]

Tento návod vynechává ts (časové razítko) a metadata (JSON blob) tak, aby byly nastaveny na now() a NULL v uvedeném pořadí.

Jakmile odešlete POST požadavku můžete také odeslat GET požadavek na URL adresu vašeho Workeru s /readings cestě. Nastavte limit parametr pro řízení počtu vrácených záznamů.

Pokud máte curl nainstalovaný můžete otestovat pomocí následujících příkazů (nahraďte <YOUR_SUBDOMAIN> s vaší subdoménou z výše uvedeného příkazu pro nasazení):

Vložení dat
curl --request POST --data @- 'https://timescale-api.<YOUR_SUBDOMAIN>.workers.dev/readings' <<EOF
[
  { "sensor": "6f3e43a4-d1c1-4cb6-b928-0ac0efaf84a5", "value":0.3},
  { "sensor": "d538f9fa-f6de-46e5-9fa2-d7ee9a0f0a68", "value":10.8},
  { "sensor": "5cb674a0-460d-4c80-8113-28927f658f5f", "value":18.8},
  { "sensor": "03307bae-d5b8-42ad-8f17-1c810e0fbe63", "value":20.0},
  { "sensor": "64494acc-4aa5-413c-bd09-2e5b3ece8ad7", "value":13.1},
  { "sensor": "0a361f03-d7ec-4e61-822f-2857b52b74b3", "value":1.1},
  { "sensor": "50f91cdc-fd19-40d2-b2b0-c90db3394981", "metadata": {"color": "blue" }, "value":10.3}
]
EOF
Dotaz na některá data
curl "https://timescale-api.<YOUR_SUBDOMAIN>.workers.dev/readings?limit=10"

V tomto tutoriálu jste se naučili, jak vytvořit funkční příklad pro příjem a dotazování naměřených hodnot z edge pomocí Timescale, Workers, Hyperdrive a TypeScript.

Další kroky