← Hyperdrive (Postgres & MySQL) / hyperdrive / observability

Řešení problémů a ladění

Řešení a ladění chyb, které se běžně vyskytují při připojování k databázi pomocí Hyperdrive.

Chyby konfigurace

Při vytváření nové konfigurace Hyperdrive nebo úpravě parametrů připojení u existující konfigurace provede Hyperdrive na pozadí zkušební připojení k databázi, a to ještě před vytvořením nebo aktualizací konfigurace.

Hyperdrive rovněž odešle prázdný testovací dotaz, a to ; v PostgreSQL, abyste ověřili, že dokáže předávat dotazy do vaší databáze.

Kód chyby	Podrobnosti	Doporučené opravy
`2008`	Neplatný název hostitele.	Hyperdrive nedokázal přeložit hostname databáze. Ověřte, že existuje ve veřejném DNS.
`2009`	Název hostitele se nepřekládá na veřejnou IP adresu, nebo IP adresa není veřejná adresa.	Hyperdrive se může připojovat pouze k veřejným IP adresám. Privátní IP adresy, jako `10.1.5.0` nebo `192.168.2.1`, v současné době nejsou podporovány.
`2010`	Nelze se připojit k host:port.	Hyperdrive se nemohl k hostname připojit: ujistěte se, že má veřejný DNS záznam, který se překládá na veřejnou IP adresu. Zkontrolujte, že hostname není napsán s překlepem.
`2011`	Připojení odmítnuto.	Požadavky od Hyperdrive nejspíš odmítá síťový firewall nebo seznam řízení přístupu (ACL). Ověřte, že máte povolená připojení z veřejného internetu.
`2012`	Databáze nepodporuje TLS (SSL).	Hyperdrive vyžaduje k připojení TLS (SSL). Nakonfigurujte TLS na své databázi.
`2013`	Neplatné přihlašovací údaje k databázi.	Ujistěte se, že vaše uživatelské jméno je správné (a existuje) a že heslo je správné (rozlišují se velká a malá písmena).
`2014`	Zadaný název databáze neexistuje.	Zkontrolujte, že název databáze (nikoli tabulky), který jste zadali, existuje v databázi, ke které se má Hyperdrive připojit.
`2015`	Obecná chyba.	Hyperdrive se nepodařilo připojit a příčinu se nepodařilo zjistit. Otevřete tiket podpory, aby to Cloudflare mohl prošetřit.
`2016`	Testovací dotaz se nezdařil.	Ověřte, že uživatel, pod kterým se Hyperdrive připojuje, má oprávnění zadávat čtecí a zápisové dotazy do dané databáze.

Selhání připojení

Hyperdrive může také vydávat Failed to connect to the provided database když se nepodaří připojit k databázi při pokusu o vytvoření konfigurace Hyperdrive. K tomu může dojít, pokud jsou nesprávně nastaveny certifikáty TLS (SSL). Následuje neúplný přehled možných chyb při připojování:

Chybová zpráva	Podrobnosti	Doporučené opravy
Server return error and closed connection.	Tato zpráva se zobrazuje, když se pokusíte připojit k databázi, která má povoleno ověřování klientských certifikátů.	Ujistěte se, že Hyperdrive konfigurujete s klientské certifikáty pokud je vaše databáze vyžaduje.
Navázání TLS spojení se nezdařilo: ověření certifikátu selhalo.	Tato zpráva se zobrazuje, pokud je Hyperdrive nakonfigurován s certifikáty CA serveru a certifikát poskytnutý serverem nebyl podepsán očekávaným certifikátem CA.	Ujistěte se, že pro Hyperdrive používáte správný certifikát CA a že se připojujete ke správné databázi.

Chyby připojení

Hyperdrive může za běhu vracet i chyby. Může k tomu dojít při počátečním navazování připojení nebo jako reakce na dotaz či jiný příkaz síťového protokolu odeslaný vaším ovladačem.

Tyto chyby se vrací jako ErrorResponse zprávy protokolu wire, se kterými většina ovladačů pracuje tak, že u příslušného dotazu vyvolají výjimku nebo aktivují událost chyby. Chyby Hyperdrive, které neodpovídají 1:1 kódu chybové zprávy podle dokumentace PostgreSQL ↗ použijte 58000 signalizuje právě takový případ.

Hyperdrive se také může setkat s ErrorResponse zprávy protokolu wire odeslané vaší databází. Hyperdrive tyto chyby pokud možno předá beze změny.

Chyby specifické pro Hyperdrive

Chybová zpráva	Podrobnosti	Doporučené opravy
`Internal error.`	Problém je na naší straně.	Zkontrolujte, zda neprobíhá incident ovlivňující Hyperdrive, a kontaktujte Cloudflare Support. Opakování dotazu je vhodné, pokud to odpovídá způsobu, jakým aplikaci používáte.
`Failed to acquire a connection from the pool.`	Hyperdrive vypršel časový limit při čekání na připojení k vaší databázi, nebo se vůbec nemůže připojit.	Pokud se tato chyba objevuje občas, znamená to, že se vyčerpává pool Hyperdrive, protože váš worker drží otevřených příliš mnoho připojení příliš dlouho. Příčin může být celá řada, nejčastějším viníkem však bývají dlouho běžící dotazy nebo transakce.
`Server connection attempt failed: connection_refused`	Hyperdrive nedokáže vytvářet nová připojení k vaší zdrojové databázi.	Požadavky od Hyperdrive nejspíš odmítá síťový firewall nebo seznam řízení přístupu (ACL). Ověřte, že máte povolená připojení z veřejného internetu. Někdy to může způsobit i poskytovatel hostingu vaší databáze, pokud po překročení limitu odmítá příchozí připojení.
`Hyperdrive does not currently support MySQL COM_STMT_PREPARE messages`	Hyperdrive nepodporuje prepared statements pro databáze MySQL.	Odstraňte připravené příkazy z dotazů MySQL.

Chyby Node

Chybová zpráva	Podrobnosti	Doporučené opravy
`Uncaught Error: No such module "node:<module>"`	Váš projekt Cloudflare Workers nebo knihovna, kterou importuje, se pokouší přistoupit k modulu Node.js, který není dostupný.	Povolit Kompatibilita s Node.js pro váš projekt Cloudflare Workers, abyste maximalizovali kompatibilitu.

Zastaralá čtení po zápisech

Pokud vaše aplikace zapíše data a následné čtení vrátí starší data, může to znamenat, že ukládání dotazů do mezipaměti ve službě Hyperdrive vrací výsledek čtecího dotazu z mezipaměti. Zkontrolujte metriky Hyperdrive pomocí cacheStatus k ověření, zda čtení vracejí hit, miss, disabled, nebo uncacheable. Viz Metriky a analytika.

Informace o řešení zastaralých čtení po zápisu najdete v Ukládání dotazů do mezipaměti s návodem, jak oddělit aktuální čtení od čtení, která lze ukládat do mezipaměti, včetně použití konfigurace Hyperdrive s vypnutou mezipamětí pro čtení, jež musí vracet aktuální data.

Dotazy mimo cache

Pokud vaše dotazy nejsou ukládány do mezipaměti, přestože má Hyperdrive ukládání do mezipaměti povolené, zkontrolujte následující:

Stabilní nebo volatilní funkce PostgreSQL ve vašem dotazu: Dotazy, které obsahují funkce PostgreSQL kategorizované jako STABLE nebo VOLATILE nelze ukládat do mezipaměti. Mezi běžné příklady patří NOW(), CURRENT_TIMESTAMP, CURRENT_DATE, RANDOM(), a LASTVAL(). Tento problém vyřešíte přesunutím volání funkce do kódu vaší aplikace a předáním výsledku jako parametru dotazu. Místo WHERE created_at > NOW(), vypočítejte časové razítko ve svém Workeru a předejte ho jako parametr: WHERE created_at > $1. Viz Ukládání dotazů do mezipaměti kompletní seznam funkcí, které nelze ukládat do mezipaměti.
Názvy funkcí v komentářích SQL: Hyperdrive používá textové porovnávání vzorů k odhalení některých funkcí, jejichž výsledky nelze ukládat do mezipaměti. Odkazy na názvy funkcí jako NOW() v komentářích SQL může způsobit, že bude dotaz považován za nekešovatelný, i když funkce ve skutečnosti není volána. Odkazy na názvy nekešovatelných funkcí odstraňte z textu dotazu, včetně komentářů.
Konfigurace ovladače: Váš ovladač může být nakonfigurován tak, že vaše dotazy nelze v Hyperdrive ukládat do mezipaměti. K tomu může dojít, pokud používáte Postgres.js ↗ ovladač s prepare: false ↗. Tento problém vyřešíte povolením připravených příkazů pomocí prepare: true.

Chyby ovladače

Chybová zpráva	Podrobnosti	Doporučené opravy
`Code generation from strings disallowed for this context`	Ovladač databáze, který používáte, se pokouší použít `eval()` příkaz, který není na Cloudflare Workers podporován (běžné u `mysql2` ovladač).	Nakonfigurujte databázový ovladač tak, aby nepoužíval `eval()`. Přečtěte si, jak nakonfigurovat `mysql2` k zakázání používání `eval()`.

Chyby zastaralého připojení a kontextu I/O

K těmto chybám dochází, když je databázový klient nebo připojení vytvořeno v globálním rozsahu (mimo request handler) nebo je opakovaně používáno napříč požadavky. Workers neumožňují I/O napříč požadavky, a databázová připojení z předchozího kontextu požadavku se stanou nepoužitelnými. Vždy vytvářet databázové klienty uvnitř svých handlerů.

Chyby runtime prostředí Workers

Chybová zpráva	Podrobnosti	Doporučené opravy
`Disallowed operation called within global scope. Asynchronous I/O (ex: fetch() or connect()), setting a timeout, and generating random values are not allowed within global scope.`	Váš Worker se pokouší otevřít připojení k databázi nebo provést I/O operaci při spuštění skriptu, mimo handler požadavku.	Přesuňte vytvoření klienta databáze do `fetch`, `queue`, nebo jiné obslužné funkce.
`Cannot perform I/O on behalf of a different request. I/O objects (such as streams, request/response bodies, and others) created in the context of one request handler cannot be accessed from a different request's handler.`	Připojení k databázi nebo klient vytvořený v rámci jednoho požadavku se opakovaně používá i v následujícím požadavku.	Při každém požadavku vytvořte nového databázového klienta, místo abyste ho ukládali do globální proměnné. Sdružování připojení v Hyperdrive už samo eliminuje režii spojenou s navazováním připojení.

node-postgres (`pg`) chyby

Chybová zpráva	Podrobnosti	Doporučené opravy
`Connection terminated`	Klienta `.end()` metoda byla zavolána, nebo bylo připojení uklizeno na konci předchozího požadavku.	Vytvořte nový `Client` uvnitř handleru, místo abyste opakovaně použili instanci z předchozího požadavku.
`Connection terminated unexpectedly`	Podkladové připojení bylo přerušeno bez explicitního `.end()` volání, například pokud byl kontext předchozího požadavku uvolněn garbage collectorem.	Vytvořte nový `Client` uvnitř handleru pro každý požadavek.
`Client has encountered a connection error and is not queryable`	Na připojení došlo k chybě na úrovni socketu (běžné při opakovaném použití klienta napříč požadavky).	Vytvořte nový `Client` uvnitř handleru. Klienty neukládejte do globálních proměnných.
`Client was closed and is not queryable`	Dotaz byl proveden na klientovi, jehož `.end()` metoda již byla zavolána.	Vytvořte nový `Client` uvnitř handleru, místo abyste jej opakovaně použili.
`Cannot use a pool after calling end on the pool`	`pool.connect()` bylo zavoláno na `Pool` instanci, která již byla ukončena.	Nepoužívejte `new Pool()` v globálním rozsahu. Vytvořte `new Client()` uvnitř handleru: Hyperdrive za vás řeší connection pooling.
`Client has already been connected. You cannot reuse a client.`	`client.connect()` bylo zavoláno na klientovi, který již byl připojen z předchozího volání.	Vytvořte nový `Client` na požadavek. Klienty node-postgres nelze po připojení znovu připojit.

Postgres.js (`postgres`) chyby

Chybové zprávy Postgres.js obsahují kód chyby a cílový hostitel. Tento code vlastnost objektu chyby obsahuje kód chyby.

Chybová zpráva	Podrobnosti	Doporučené opravy
`write CONNECTION_ENDED <host>:<port>`	Dotaz byl proveden poté, co `sql.end()` bylo zavoláno, nebo bylo připojení vyčištěno po předchozím požadavku. Kód chyby: `CONNECTION_ENDED`.	Vytvořte nový `postgres()` instanci uvnitř handleru.
`write CONNECTION_DESTROYED <host>:<port>`	Připojení bylo násilně ukončeno, například během `sql.end({ timeout })` vypršení platnosti, nebo protože připojení již bylo ukončeno. Kód chyby: `CONNECTION_DESTROYED`.	Vytvořte nový `postgres()` instanci uvnitř handleru pro každý požadavek.
`write CONNECTION_CLOSED <host>:<port>`	Podkladový socket se neočekávaně uzavřel, zatímco dotazy stále čekaly na zpracování. Chybový kód: `CONNECTION_CLOSED`.	Vytvořte nový `postgres()` instanci uvnitř handleru. Pokud k tomu dojde v rámci jednoho požadavku, zkontrolujte, zda nejde o problémy se sítí nebo časové limity dotazů.

chyby mysql2

Chybová zpráva	Podrobnosti	Doporučené opravy
`Can't add new command when connection is in closed state`	Dotaz byl proveden na připojení, které bylo již ukončeno nebo u kterého došlo k závažné chybě.	Vytvářejte nové připojení uvnitř handleru, místo abyste opakovaně používali připojení z globálního rozsahu.
`Connection lost: The server closed the connection.`	Podkladový socket byl uzavřen serverem nebo byl mezi požadavky uvolněn garbage collectorem. Chybový kód: `PROTOCOL_CONNECTION_LOST`.	Pro každý požadavek vytvořte nové připojení uvnitř handleru.
`Pool is closed.`	`pool.getConnection()` bylo zavoláno na fondu, který už byl uzavřen.	Nepoužívejte `createPool()` v globálním rozsahu. Vytvořte nový `createConnection()` uvnitř handleru: Hyperdrive za vás řeší pooling.

chyby mysql

Chybová zpráva	Podrobnosti	Doporučené opravy
`Cannot enqueue Query after fatal error.`	Dotaz byl proveden na připojení, u kterého již dříve došlo k závažné chybě. Kód chyby: `PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR`.	Vytvářejte nové připojení uvnitř handleru, místo abyste opakovaně používali připojení z globálního rozsahu.
`Cannot enqueue Query after invoking quit.`	Dotaz byl proveden na připojení poté, co `.end()` bylo zavoláno. Kód chyby: `PROTOCOL_ENQUEUE_AFTER_QUIT`.	Pro každý požadavek vytvořte nové připojení uvnitř handleru.
`Cannot enqueue Handshake after already enqueuing a Handshake.`	`.connect()` bylo zavoláno na připojení, které již bylo připojeno z předchozího požadavku. Kód chyby: `PROTOCOL_ENQUEUE_HANDSHAKE_TWICE`.	Vytvářejte nové připojení pro každý požadavek. Připojení mysql nelze po navázání znovu připojit.

Zlepšení výkonu

Pokud je provoz dotazů zapisován jako transakce, může to omezit výkon. Důvodem je to, že u transakce musí zůstat připojení otevřené po celou dobu jejího trvání, což omezuje multiplexování připojení. Obsahuje-li transakce více dotazů, dopad na multiplexování připojení může být ještě výraznější. Pokud je to možné, doporučujeme dotazy do transakcí nezabalovat, aby bylo možné připojení sdílet intenzivněji.