From d7eb2e1e905042f307c54d7dafe855c54fa5109f Mon Sep 17 00:00:00 2001 From: Thomas Gauvin Date: Mon, 24 Mar 2025 17:23:33 -0400 Subject: [PATCH 01/24] [Hyperdrive] drafting custom cert support for Hyperdrive --- .../custom-certificates-for-hyperdrive.mdx | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 src/content/docs/hyperdrive/configuration/custom-certificates-for-hyperdrive.mdx diff --git a/src/content/docs/hyperdrive/configuration/custom-certificates-for-hyperdrive.mdx b/src/content/docs/hyperdrive/configuration/custom-certificates-for-hyperdrive.mdx new file mode 100644 index 00000000000000..12fa5fe8b02a92 --- /dev/null +++ b/src/content/docs/hyperdrive/configuration/custom-certificates-for-hyperdrive.mdx @@ -0,0 +1,112 @@ +--- +pcx_content_type: concept +title: Custom CA and client certificates +sidebar: + order: 6 + badge: + text: Beta +--- + +import { TabItem, Tabs, Render, WranglerConfig } from "~/components"; + +By default, all Hyperdrive configurations are encrypted with SSL/TLS (`sslmode=require`). Databases commonly support 2 additional [SSL modes](https://www.postgresql.org/docs/current/libpq-ssl.html), +(`verify-ca` and `verify-full`) which allow for a more stringent security between Hyperdrive and the database server. + +When using `verify-ca`, Hyperdrive will verify the server certificate when creating a connection, also known as [client verification of server certificates](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBQ-SSL-CERTIFICATES). +This will configure Hyperdrive to verify that the certificate provided by the database server in the SSL/TLS handshake matches the certificate authority (CA) root certificate. +This provides an additional security check to prevent man-in-the-middle attacks. + +You can also configure Hyperdrive to use `verify-full`. +In this case, Hyperdrive will do the [client verification of server certificates](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBQ-SSL-CERTIFICATES) and +provide certificates during the SSL/TLS handshake to allow [server verification of client certificates](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT). +This is a feature of databases that allow them to use client certificates as an additional factor to authenticate clients (in addition to the username and password). + +The table below explains the various SSL modes of SQL databases: + +| SSL Mode | Password authentication | Encrypted connections | Server certificate verification[^1] | Client certificates verification[^2] | +| ------------- | ----------------------- | ----------------------- | ------------------------------------------ | ------------------------------------------ | +| `require` (default) | ✅ | ✅ | ❌ | ❌ | +| `verify-ca` | ✅ | ✅ | ✅ | ❌ | +| `verify-full` | ✅ | ✅ | ✅ | ✅ | + +[^1]: Hyperdrive will verify that the certificates provided by the server have been signed by a certificate authority. This can help prevent man-in-the-middle attacks. +[^2]: The database is configured to verify both the username/password of Hyperdrive and a client certificate. This provides a second factor for authentication. + +## Prerequisites + +- An external database with SSL/TLS enabled. +- The root certificate authority (CA) certificate with which the SSL/TLS certificate of the database has been signed with (for `verify-ca` and `verify-full`). +- If using `verify-full`, you will need client certificates that have been signed by the same certificate authority (CA) as expected by the database server. + +## Client verification of server certificates + +Client verification of server certificates means that Hyperdrive will verify that the +certificate provided by the database server in the [SSL/TLS handshake](https://www.postgresql.org/docs/current/ssl-tcp.html) +matches the root certificate authority (CA) certificate. + +To do this, you must provide Hyperdrive with the certificate of the root certificate authority (CA) or an immediate certificate which +has been used to sign the certificate of your database. + +### Step 1: Upload your the root certificate authority (CA) certificate + +Using Wrangler, you can upload your root certificate authority (CA) certificate: + +```bash +npx wrangler cert upload certificate-authority --ca-cert \.pem --name \ + +--- + +Uploading CA Certificate tmp-cert... +Success! Uploaded CA Certificate \ +ID: \ +... +``` + +### Step 2: Create your Hyperdrive configuration using the CA certificate + +Once your CA certificate has been created, you can create a Hyperdrive configuration with the newly created +certificates using either the dashboard or Wrangler. +Using Wrangler, enter the following command in your terminal: + +```bash +npx wrangler hyperdrive create \ --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --certificate-authority-id \ +``` + +When creating the Hyperdrive configuration, Hyperdrive will attempt to connect to the database with the +provided credentials. If the command provides successful results, you have properly configured your Hyperdrive +configuration to verify the certificates provided by your database server. + +:::note + +Hyperdrive will attempt to connect to your database with the provided credentials to verify they are correct before creating a configuration. If you encounter an error when attempting to connect, refer to Hyperdrive's [troubleshooting documentation](/hyperdrive/observability/troubleshooting/) to debug possible causes. + +::: + +## Server verification of client certificates + +For the database server to be able to verify the client certificates, Hyperdrive must be configured to provide a certificate +file (`client-cert.pem`) and a private key with which the certificate was generated (`private-key.pem`). + +### Step 1: Upload your client certificates (mTLS certificates) + +Upload your client certificates to be used by Hyperdrive using Wrangler: + +```bash +npx wrangler cert upload mtls-certificate --cert client-cert.pem --key client-key.pem --name + +--- + +Uploading client certificate ... +Success! Uploaded client certificate +ID: +... +``` + +### Step 2: Create a Hyperdrive configuration + +You can now create a Hyperdrive configuration using the newly created client certificate bundle using the dashboard or Wrangler. +Using Wrangler, run the following command: + +```bash +npx wrangler hyperdrive create --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --certificate-authority-id --mtls-certificate-uuid +``` From d578ae1d1bf08930cd0ea2004147103d4f44d90d Mon Sep 17 00:00:00 2001 From: Thomas Gauvin Date: Fri, 28 Mar 2025 09:34:02 -0400 Subject: [PATCH 02/24] corrections --- .../custom-certificates-for-hyperdrive.mdx | 112 ------------------ .../tls-ssl-certificates-for-hyperdrive.mdx | 105 +++++----------- .../reference/supported-databases.mdx | 49 ++++++++ 3 files changed, 78 insertions(+), 188 deletions(-) delete mode 100644 src/content/docs/hyperdrive/configuration/custom-certificates-for-hyperdrive.mdx create mode 100644 src/content/docs/hyperdrive/reference/supported-databases.mdx diff --git a/src/content/docs/hyperdrive/configuration/custom-certificates-for-hyperdrive.mdx b/src/content/docs/hyperdrive/configuration/custom-certificates-for-hyperdrive.mdx deleted file mode 100644 index 12fa5fe8b02a92..00000000000000 --- a/src/content/docs/hyperdrive/configuration/custom-certificates-for-hyperdrive.mdx +++ /dev/null @@ -1,112 +0,0 @@ ---- -pcx_content_type: concept -title: Custom CA and client certificates -sidebar: - order: 6 - badge: - text: Beta ---- - -import { TabItem, Tabs, Render, WranglerConfig } from "~/components"; - -By default, all Hyperdrive configurations are encrypted with SSL/TLS (`sslmode=require`). Databases commonly support 2 additional [SSL modes](https://www.postgresql.org/docs/current/libpq-ssl.html), -(`verify-ca` and `verify-full`) which allow for a more stringent security between Hyperdrive and the database server. - -When using `verify-ca`, Hyperdrive will verify the server certificate when creating a connection, also known as [client verification of server certificates](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBQ-SSL-CERTIFICATES). -This will configure Hyperdrive to verify that the certificate provided by the database server in the SSL/TLS handshake matches the certificate authority (CA) root certificate. -This provides an additional security check to prevent man-in-the-middle attacks. - -You can also configure Hyperdrive to use `verify-full`. -In this case, Hyperdrive will do the [client verification of server certificates](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBQ-SSL-CERTIFICATES) and -provide certificates during the SSL/TLS handshake to allow [server verification of client certificates](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT). -This is a feature of databases that allow them to use client certificates as an additional factor to authenticate clients (in addition to the username and password). - -The table below explains the various SSL modes of SQL databases: - -| SSL Mode | Password authentication | Encrypted connections | Server certificate verification[^1] | Client certificates verification[^2] | -| ------------- | ----------------------- | ----------------------- | ------------------------------------------ | ------------------------------------------ | -| `require` (default) | ✅ | ✅ | ❌ | ❌ | -| `verify-ca` | ✅ | ✅ | ✅ | ❌ | -| `verify-full` | ✅ | ✅ | ✅ | ✅ | - -[^1]: Hyperdrive will verify that the certificates provided by the server have been signed by a certificate authority. This can help prevent man-in-the-middle attacks. -[^2]: The database is configured to verify both the username/password of Hyperdrive and a client certificate. This provides a second factor for authentication. - -## Prerequisites - -- An external database with SSL/TLS enabled. -- The root certificate authority (CA) certificate with which the SSL/TLS certificate of the database has been signed with (for `verify-ca` and `verify-full`). -- If using `verify-full`, you will need client certificates that have been signed by the same certificate authority (CA) as expected by the database server. - -## Client verification of server certificates - -Client verification of server certificates means that Hyperdrive will verify that the -certificate provided by the database server in the [SSL/TLS handshake](https://www.postgresql.org/docs/current/ssl-tcp.html) -matches the root certificate authority (CA) certificate. - -To do this, you must provide Hyperdrive with the certificate of the root certificate authority (CA) or an immediate certificate which -has been used to sign the certificate of your database. - -### Step 1: Upload your the root certificate authority (CA) certificate - -Using Wrangler, you can upload your root certificate authority (CA) certificate: - -```bash -npx wrangler cert upload certificate-authority --ca-cert \.pem --name \ - ---- - -Uploading CA Certificate tmp-cert... -Success! Uploaded CA Certificate \ -ID: \ -... -``` - -### Step 2: Create your Hyperdrive configuration using the CA certificate - -Once your CA certificate has been created, you can create a Hyperdrive configuration with the newly created -certificates using either the dashboard or Wrangler. -Using Wrangler, enter the following command in your terminal: - -```bash -npx wrangler hyperdrive create \ --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --certificate-authority-id \ -``` - -When creating the Hyperdrive configuration, Hyperdrive will attempt to connect to the database with the -provided credentials. If the command provides successful results, you have properly configured your Hyperdrive -configuration to verify the certificates provided by your database server. - -:::note - -Hyperdrive will attempt to connect to your database with the provided credentials to verify they are correct before creating a configuration. If you encounter an error when attempting to connect, refer to Hyperdrive's [troubleshooting documentation](/hyperdrive/observability/troubleshooting/) to debug possible causes. - -::: - -## Server verification of client certificates - -For the database server to be able to verify the client certificates, Hyperdrive must be configured to provide a certificate -file (`client-cert.pem`) and a private key with which the certificate was generated (`private-key.pem`). - -### Step 1: Upload your client certificates (mTLS certificates) - -Upload your client certificates to be used by Hyperdrive using Wrangler: - -```bash -npx wrangler cert upload mtls-certificate --cert client-cert.pem --key client-key.pem --name - ---- - -Uploading client certificate ... -Success! Uploaded client certificate -ID: -... -``` - -### Step 2: Create a Hyperdrive configuration - -You can now create a Hyperdrive configuration using the newly created client certificate bundle using the dashboard or Wrangler. -Using Wrangler, run the following command: - -```bash -npx wrangler hyperdrive create --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --certificate-authority-id --mtls-certificate-uuid -``` diff --git a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx index 425efe79672a95..0aef6e939cfcd8 100644 --- a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx +++ b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx @@ -9,16 +9,13 @@ sidebar: import { TabItem, Tabs, Render, WranglerConfig } from "~/components"; -Hyperdrive provides additional ways to secure connectivity to your database. Hyperdrive supports: - -1. **Server certificates** for TLS (SSL) modes such as `verify-ca` and `verify-full` for increased security. When configured, Hyperdrive will verify that the certificates have been signed by the expected certificate authority (CA) to avoid man-in-the-middle attacks. -2. **Client certificates** for Hyperdrive to authenticate itself to your database with credentials beyond beyond username/password. To properly use client certificates, your database must be configured to verify the client certificates provided by a client, such as Hyperdrive, to allow access to the database. - -Hyperdrive can be configured to use only server certificates, only client certificates, or both depending on your security requirements and database configurations. +Hyperdrive provides additional ways to secure connectivity to your database. Hyperdrive supports +verification of server certificates for TLS (SSL) encryption for increased security. Hyperdrive also supports +using client certificates to authenticate itself to your database for stricter authentication beyond username/password. :::note -Support for server certificates and client certificates is not available for MySQL (beta). Support for server certificates and client certificates is only available for local development using `npx wrangler dev --remote` which runs your Workers and Hyperdrive in Cloudflare's network with local debugging. +Support for server certificates and client certificates is not available for MySQL (beta). ::: @@ -28,67 +25,50 @@ Hyperdrive supports 3 common encryption [TLS/SSL modes](https://www.postgresql.o - `require` (default): TLS is required for encrypted connectivity and server certificates are validated (based on WebPKI). - `verify-ca`: Hyperdrive will verify that the database server is trustworthy by verifying that the certificates of the server have been signed by the expected root certificate authority or intermediate certificate authority. -- `verify-full`: Identical to `verify-ca`, but Hyperdrive also requires the database hostname to match a Subject Alternative Name (SAN) present on the certificate. +- `verify-full`: Identical to `verify-ca`, but Hyperdrive also requires the database hostname must match a Subject Alternative Name (SAN) present on the certificate. -By default, all Hyperdrive configurations are encrypted with SSL/TLS (`require`). This requires your database to be configured to accept encrypted connections (with SSL/TLS). +By default, all Hyperdrive configurations are encrypted with SSL/TLS (`require`). This requires +that your database is configured to accept encrypted connections (with SSL/TLS). -You can configure Hyperdrive to use `verify-ca` and `verify-full` for a more stringent security configuration, which provide additional verification checks of the server's certificates. This helps guard against man-in-the-middle attacks. +You can configure Hyperdrive to use +`verify-ca` and `verify-full` for a more stringent security configuration, which +provide additional verification checks of the server's certificates. This +helps guard against man-in-the-middle attacks. -To configure Hyperdrive to verify the certificates of the server, you must provide Hyperdrive with the certificate of the root certificate authority (CA) or an intermediate certificate which has been used to sign the certificate of your database. +To configure Hyperdrive to verify the certificates of the server, you must provide Hyperdrive with the certificate of the root certificate authority (CA) or an intermediate certificate which +has been used to sign the certificate of your database. ### Step 1: Upload your the root certificate authority (CA) certificate Using Wrangler, you can upload your root certificate authority (CA) certificate: ```bash -# requires Wrangler 4.9.0 or greater npx wrangler cert upload certificate-authority --ca-cert \.pem --name \ --- Uploading CA Certificate tmp-cert... -Success! Uploaded CA Certificate -ID: +Success! Uploaded CA Certificate \ +ID: \ ... ``` -:::note - -You must use the CA certificate bundle that is for your specific region. You can not use a CA certificate bundle that contains more than one CA certificate, such as a global bundle of CA certificates containing each region's certificate. - -::: - ### Step 2: Create your Hyperdrive configuration using the CA certificate and the SSL mode -Once your CA certificate has been created, you can create a Hyperdrive configuration with the newly created certificates using either the dashboard or Wrangler. You must also specify the SSL mode of `verify-ca` or `verify-full` to use. - - +Once your CA certificate has been created, you can create a Hyperdrive configuration with the newly created +certificates using either the dashboard or Wrangler. You must also specify the SSL mode of `verify-ca` or `verify-full` to use. - +Using Wrangler, enter the following command in your terminal: -Using Wrangler, enter the following command in your terminal to create a Hyperdrive configuration with the CA certificate and a `verify-full` SSL mode: +UPDATE WRANGLER ```bash -npx wrangler hyperdrive create --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --ca-certificate-id --sslmode verify-full +npx wrangler hyperdrive create \ --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --certificate-authority-id \ ``` - - - -From the dashboard, follow these steps to create a Hyperdrive configuration with server certificates: - -1. In the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive), navigate to **Storage & Databases > Hyperdrive** and click **Create configuration**. -2. Select **Server certificates**. -3. Specify a SSL mode of **Verify CA** or **Verify full** -4. Select the SSL certificate of the certificate authority (CA) of your database that you have previously uploaded with Wrangler. - - - - - - - -When creating the Hyperdrive configuration, Hyperdrive will attempt to connect to the database with the provided credentials. If the command provides successful results, you have properly configured your Hyperdrive configuration to verify the certificates provided by your database server. +When creating the Hyperdrive configuration, Hyperdrive will attempt to connect to the database with the +provided credentials. If the command provides successful results, you have properly configured your Hyperdrive +configuration to verify the certificates provided by your database server. :::note @@ -98,16 +78,17 @@ Hyperdrive will attempt to connect to your database with the provided credential ## Client certificates -Your database can be configured to [verify a certificate provided by the client](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT), in this case, Hyperdrive. This serves as an additional factor to authenticate clients (in addition to the username and password). +Your database can be configured to [verify a certificate provided by the client](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT), in this case, Hyperdrive. This serves +as an additional factor to authenticate clients (in addition to the username and password). -For the database server to be able to verify the client certificates, Hyperdrive must be configured to provide a certificate file (`client-cert.pem`) and a private key with which the certificate was generated (`private-key.pem`). +For the database server to be able to verify the client certificates, Hyperdrive must be configured to provide a certificate +file (`client-cert.pem`) and a private key with which the certificate was generated (`private-key.pem`). ### Step 1: Upload your client certificates (mTLS certificates) Upload your client certificates to be used by Hyperdrive using Wrangler: ```bash -# requires Wrangler 4.9.0 or greater npx wrangler cert upload mtls-certificate --cert client-cert.pem --key client-key.pem --name --- @@ -121,36 +102,8 @@ ID: ### Step 2: Create a Hyperdrive configuration You can now create a Hyperdrive configuration using the newly created client certificate bundle using the dashboard or Wrangler. - - - - - - -Using Wrangler, enter the following command in your terminal to create a Hyperdrive configuration with using the client certificate pair: +Using Wrangler, run the following command: ```bash -npx wrangler hyperdrive create --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --mtls-certificate-id +npx wrangler hyperdrive create --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --certificate-authority-id --mtls-certificate-uuid ``` - - - - -From the dashboard, follow these steps to create a Hyperdrive configuration with server certificates: - -1. In the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive), navigate to **Storage & Databases > Hyperdrive** and click **Create configuration**. -2. Select **Client certificates**. -3. Select the SSL client certificate and private key pair for Hyperdrive to use during the connection setup with your database server. - - - - - - -When Hyperdrive connects to your database, it will provide a client certificate signed with the private key to the database server. This allows the database server to confirm that the client, in this case Hyperdrive, has both the private key and the client certificate. By using client certificates, you can add an additional authentication layer for your database to ensures that only Hyperdrive can connect to it. - -:::note - -Hyperdrive will attempt to connect to your database with the provided credentials to verify they are correct before creating a configuration. If you encounter an error when attempting to connect, refer to Hyperdrive's [troubleshooting documentation](/hyperdrive/observability/troubleshooting/) to debug possible causes. - -::: \ No newline at end of file diff --git a/src/content/docs/hyperdrive/reference/supported-databases.mdx b/src/content/docs/hyperdrive/reference/supported-databases.mdx new file mode 100644 index 00000000000000..b8fd7f1952943e --- /dev/null +++ b/src/content/docs/hyperdrive/reference/supported-databases.mdx @@ -0,0 +1,49 @@ +--- +pcx_content_type: concept +title: Supported databases +sidebar: + order: 2 +--- + +## Database support + +Details on which database engines and/or specific database providers are supported are detailed in the following table. + +| Database Engine | Supported | Known supported versions | Details | +| --------------- | ------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------- | +| PostgreSQL | ✅ | `9.0` to `16.x` | Both self-hosted and managed (AWS, Google Cloud, Oracle) instances are supported. | +| Neon | ✅ | All | Neon currently runs Postgres 15.x | +| Supabase | ✅ | All | Supabase currently runs Postgres 15.x | +| Timescale | ✅ | All | See the [Timescale guide](/hyperdrive/examples/timescale/) to connect. | +| Materialize | ✅ | All | Postgres-compatible. Refer to the [Materialize guide](/hyperdrive/examples/materialize/) to connect. | +| CockroachDB | ✅ | All | Postgres-compatible. Refer to the [CockroachDB](/hyperdrive/examples/cockroachdb/) guide to connect. | +| MySQL | Coming soon | | | +| SQL Server | Not currently supported. | | | +| MongoDB | Not currently supported. | | | + +## Supported PostgreSQL authentication modes + +Hyperdrive supports the following [authentication modes](https://www.postgresql.org/docs/current/auth-methods.html) for connecting to PostgreSQL databases: + +- Password Authentication (`md5`) +- Password Authentication (`password`) (clear-text password) +- SASL Authentication (`SCRAM-SHA-256`) + +## Supported TLS (SSL) modes + +Hyperdrive supports the following [PostgreSQL TLS (SSL)](https://www.postgresql.org/docs/current/libpq-ssl.html) connection modes when connecting to your origin database: + +| Mode | Supported | Details | +| ------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `none` | No | Hyperdrive does not support insecure plain text connections. | +| `prefer` | No (use `require`) | Hyperdrive will always use TLS. | +| `require` | Yes (default) | TLS is required, and server certificates are validated (based on WebPKI). | +| `verify-ca` | Yes | Verifies the server's TLS certificate is signed by a root CA on the client. This ensures the server has a certificate the client trusts. | +| `verify-full` | Yes | Identical to `verify-ca`, but also requires the database hostname must match a Subject Alternative Name (SAN) present on the certificate. | + +Refer to [SSL/TLS certificates](/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive/) documentation for details on how to configure `verify-ca` or `verify-full` TLS (SSL) modes for Hyperdrive. +:::note + +Hyperdrive support for `verify-ca` and `verify-full` is not available for MySQL (beta). + +::: From 7a2aeb5079892613dcf649e99900b112712faf90 Mon Sep 17 00:00:00 2001 From: Thomas Gauvin Date: Tue, 8 Apr 2025 10:48:42 -0400 Subject: [PATCH 03/24] wip --- .../tls-ssl-certificates-for-hyperdrive.mdx | 14 +++--- .../reference/supported-databases.mdx | 49 ------------------- 2 files changed, 8 insertions(+), 55 deletions(-) delete mode 100644 src/content/docs/hyperdrive/reference/supported-databases.mdx diff --git a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx index 0aef6e939cfcd8..11b1cb57b08148 100644 --- a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx +++ b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx @@ -48,8 +48,8 @@ npx wrangler cert upload certificate-authority --ca-cert \ -ID: \ +Success! Uploaded CA Certificate +ID: ... ``` @@ -60,10 +60,8 @@ certificates using either the dashboard or Wrangler. You must also specify the S Using Wrangler, enter the following command in your terminal: -UPDATE WRANGLER - ```bash -npx wrangler hyperdrive create \ --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --certificate-authority-id \ +npx wrangler hyperdrive create --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --ca-certificate-id --sslmode verify-full ``` When creating the Hyperdrive configuration, Hyperdrive will attempt to connect to the database with the @@ -105,5 +103,9 @@ You can now create a Hyperdrive configuration using the newly created client cer Using Wrangler, run the following command: ```bash -npx wrangler hyperdrive create --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --certificate-authority-id --mtls-certificate-uuid +npx wrangler hyperdrive create --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --mtls-certificate-id ``` + +When Hyperdrive will connect to your database, it will provide a client certificate signed with the private key to the database server. This will allow the database server to confirm that the +client, in this case Hyperdrive, has both the private key and the client certificate. By using client certificates, you can add an additional authentication layer for your database that ensures +that only Hyperdrive can connect to it. \ No newline at end of file diff --git a/src/content/docs/hyperdrive/reference/supported-databases.mdx b/src/content/docs/hyperdrive/reference/supported-databases.mdx deleted file mode 100644 index b8fd7f1952943e..00000000000000 --- a/src/content/docs/hyperdrive/reference/supported-databases.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -pcx_content_type: concept -title: Supported databases -sidebar: - order: 2 ---- - -## Database support - -Details on which database engines and/or specific database providers are supported are detailed in the following table. - -| Database Engine | Supported | Known supported versions | Details | -| --------------- | ------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------- | -| PostgreSQL | ✅ | `9.0` to `16.x` | Both self-hosted and managed (AWS, Google Cloud, Oracle) instances are supported. | -| Neon | ✅ | All | Neon currently runs Postgres 15.x | -| Supabase | ✅ | All | Supabase currently runs Postgres 15.x | -| Timescale | ✅ | All | See the [Timescale guide](/hyperdrive/examples/timescale/) to connect. | -| Materialize | ✅ | All | Postgres-compatible. Refer to the [Materialize guide](/hyperdrive/examples/materialize/) to connect. | -| CockroachDB | ✅ | All | Postgres-compatible. Refer to the [CockroachDB](/hyperdrive/examples/cockroachdb/) guide to connect. | -| MySQL | Coming soon | | | -| SQL Server | Not currently supported. | | | -| MongoDB | Not currently supported. | | | - -## Supported PostgreSQL authentication modes - -Hyperdrive supports the following [authentication modes](https://www.postgresql.org/docs/current/auth-methods.html) for connecting to PostgreSQL databases: - -- Password Authentication (`md5`) -- Password Authentication (`password`) (clear-text password) -- SASL Authentication (`SCRAM-SHA-256`) - -## Supported TLS (SSL) modes - -Hyperdrive supports the following [PostgreSQL TLS (SSL)](https://www.postgresql.org/docs/current/libpq-ssl.html) connection modes when connecting to your origin database: - -| Mode | Supported | Details | -| ------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | -| `none` | No | Hyperdrive does not support insecure plain text connections. | -| `prefer` | No (use `require`) | Hyperdrive will always use TLS. | -| `require` | Yes (default) | TLS is required, and server certificates are validated (based on WebPKI). | -| `verify-ca` | Yes | Verifies the server's TLS certificate is signed by a root CA on the client. This ensures the server has a certificate the client trusts. | -| `verify-full` | Yes | Identical to `verify-ca`, but also requires the database hostname must match a Subject Alternative Name (SAN) present on the certificate. | - -Refer to [SSL/TLS certificates](/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive/) documentation for details on how to configure `verify-ca` or `verify-full` TLS (SSL) modes for Hyperdrive. -:::note - -Hyperdrive support for `verify-ca` and `verify-full` is not available for MySQL (beta). - -::: From 1bb1afc3b83741d38183bbd2b5d5c00aa905133f Mon Sep 17 00:00:00 2001 From: Thomas Gauvin Date: Tue, 8 Apr 2025 11:00:26 -0400 Subject: [PATCH 04/24] add changelog --- ...-hyperdrive-custom-certificate-support.mdx | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 src/content/changelog/hyperdrive/2025-04-08-hyperdrive-custom-certificate-support.mdx diff --git a/src/content/changelog/hyperdrive/2025-04-08-hyperdrive-custom-certificate-support.mdx b/src/content/changelog/hyperdrive/2025-04-08-hyperdrive-custom-certificate-support.mdx new file mode 100644 index 00000000000000..05ed48110f8e3b --- /dev/null +++ b/src/content/changelog/hyperdrive/2025-04-08-hyperdrive-custom-certificate-support.mdx @@ -0,0 +1,36 @@ +--- +title: Hyperdrive now supports custom TLS/SSL certificates +description: You can now configure custom certificates for secure database connections with Hyperdrive, including both server certificate verification and client certificates +products: + - hyperdrive +date: 2025-04-08T17:00:00Z +--- + +import { Code } from "~/components"; + +Hyperdrive now supports more SSL/TLS security options for your database connections: + +- Configure Hyperdrive to verify server certificates with `verify-ca` or `verify-full` SSL modes and protect against man-in-the-middle attacks +- Configure Hyperdrive to provide client certificates to the database server to authenticate itself (mTLS) for stronger security beyond username and password + +Use the new `wrangler cert` commands to create certificate authority (CA) certificate bundles or client certificate pairs: + +```bash +# Create CA certificate bundle +npx wrangler cert upload certificate-authority --ca-cert your-ca-cert.pem --name your-custom-ca-name + +# Create client certificate pair +npx wrangler cert upload mtls-certificate --cert client-cert.pem --key client-key.pem --name your-client-cert-name +``` + +Then create a Hyperdrive configuration with the certificates and desired SSL mode: + +```bash +npx wrangler hyperdrive create your-hyperdrive-config \ + --connection-string="postgres://user:password@hostname:port/database" \ + --ca-certificate-id \ + --mtls-certificate-id + --sslmode verify-full +``` + +Learn more about [configuring SSL/TLS certificates for Hyperdrive](/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive/) to enhance your database security posture. From 2eb045c4a964ac92c95500002c468f51139ccecf Mon Sep 17 00:00:00 2001 From: Thomas Gauvin Date: Tue, 8 Apr 2025 16:54:34 -0400 Subject: [PATCH 05/24] adjust per comments --- .../tls-ssl-certificates-for-hyperdrive.mdx | 63 ++++++++++++++++--- 1 file changed, 56 insertions(+), 7 deletions(-) diff --git a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx index 11b1cb57b08148..cc38765b44b599 100644 --- a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx +++ b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx @@ -9,9 +9,12 @@ sidebar: import { TabItem, Tabs, Render, WranglerConfig } from "~/components"; -Hyperdrive provides additional ways to secure connectivity to your database. Hyperdrive supports -verification of server certificates for TLS (SSL) encryption for increased security. Hyperdrive also supports -using client certificates to authenticate itself to your database for stricter authentication beyond username/password. +Hyperdrive provides additional ways to secure connectivity to your database. Hyperdrive supports: + +1. **Server certificates** for TLS (SSL) modes such as `verify-ca` and `verify-full` for increased security. When configured, Hyperdrive will verify that the certificates have been signed by the expected certificate authority (CA) to avoid man-in-the-middle attacks. +2. **Client certificates** for Hyperdrive to authenticate itself to your database with credentials beyond beyond username/password. To properly use client certificates, your database must be configured to verify the client certificates provided by a client, such as Hyperdrive, to allow access to the database. + +Hyperdrive can be configured to use only server certificates, only client certificates, or both depending on your security requirements and database configurations. :::note @@ -58,11 +61,31 @@ ID: Once your CA certificate has been created, you can create a Hyperdrive configuration with the newly created certificates using either the dashboard or Wrangler. You must also specify the SSL mode of `verify-ca` or `verify-full` to use. -Using Wrangler, enter the following command in your terminal: + + + + +Using Wrangler, enter the following command in your terminal to create a Hyperdrive configuration with the CA certificate and a `verify-full` SSL mode: ```bash -npx wrangler hyperdrive create --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --ca-certificate-id --sslmode verify-full +npx wrangler hyperdrive create --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --ca-certificate-id --sslmode verify-full ``` + + + + +From the dashboard, follow these steps to create a Hyperdrive configuration with server certificates: + +1. In the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive), navigate to **Storage & Databases > Hyperdrive** and click **Create configuration**. +2. Select **Server certificates**. +3. Specify a SSL mode of **Verify CA** or **Verify full** +4. Select the SSL certificate of the certificate authority (CA) of your database that you've previously uploaded with Wrangler. + + + + + + When creating the Hyperdrive configuration, Hyperdrive will attempt to connect to the database with the provided credentials. If the command provides successful results, you have properly configured your Hyperdrive @@ -100,12 +123,38 @@ ID: ### Step 2: Create a Hyperdrive configuration You can now create a Hyperdrive configuration using the newly created client certificate bundle using the dashboard or Wrangler. -Using Wrangler, run the following command: + + + + + + +Using Wrangler, enter the following command in your terminal to create a Hyperdrive configuration with using the client certificate pair: ```bash npx wrangler hyperdrive create --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --mtls-certificate-id ``` + + + + +From the dashboard, follow these steps to create a Hyperdrive configuration with server certificates: + +1. In the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive), navigate to **Storage & Databases > Hyperdrive** and click **Create configuration**. +2. Select **Client certificates**. +3. Select the SSL client certificate and private key pair for Hyperdrive to use during the connection setup with your database server. + + + + + When Hyperdrive will connect to your database, it will provide a client certificate signed with the private key to the database server. This will allow the database server to confirm that the client, in this case Hyperdrive, has both the private key and the client certificate. By using client certificates, you can add an additional authentication layer for your database that ensures -that only Hyperdrive can connect to it. \ No newline at end of file +that only Hyperdrive can connect to it. + +:::note + +Hyperdrive will attempt to connect to your database with the provided credentials to verify they are correct before creating a configuration. If you encounter an error when attempting to connect, refer to Hyperdrive's [troubleshooting documentation](/hyperdrive/observability/troubleshooting/) to debug possible causes. + +::: \ No newline at end of file From 61311586539c72253a085311b64e200459d42c22 Mon Sep 17 00:00:00 2001 From: Thomas Gauvin Date: Tue, 8 Apr 2025 17:05:47 -0400 Subject: [PATCH 06/24] add note on wrangler version --- .../configuration/tls-ssl-certificates-for-hyperdrive.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx index cc38765b44b599..f030efd7e6679f 100644 --- a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx +++ b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx @@ -18,7 +18,7 @@ Hyperdrive can be configured to use only server certificates, only client certif :::note -Support for server certificates and client certificates is not available for MySQL (beta). +Support for server certificates and client certificates is not available for MySQL (beta). Support for server certificates and client certificates is only available for local development using `npx wrangler dev --remote` which runs your Workers and Hyperdrive in Cloudflare's network with local debugging. ::: @@ -46,6 +46,7 @@ has been used to sign the certificate of your database. Using Wrangler, you can upload your root certificate authority (CA) certificate: ```bash +# requires Wrangler 4.7.0 or greater npx wrangler cert upload certificate-authority --ca-cert \.pem --name \ --- @@ -110,6 +111,7 @@ file (`client-cert.pem`) and a private key with which the certificate was genera Upload your client certificates to be used by Hyperdrive using Wrangler: ```bash +# requires Wrangler 4.7.0 or greater npx wrangler cert upload mtls-certificate --cert client-cert.pem --key client-key.pem --name --- From a4409e72ce2bad4fa1c72fc38464e14b4f0244ee Mon Sep 17 00:00:00 2001 From: Thomas Gauvin Date: Tue, 8 Apr 2025 17:45:49 -0400 Subject: [PATCH 07/24] add troubleshooting guides for ssl certs --- .../configuration/tls-ssl-certificates-for-hyperdrive.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx index f030efd7e6679f..b36509bebc13fe 100644 --- a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx +++ b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx @@ -57,6 +57,12 @@ ID: ... ``` +:::note + +You must use the CA certificate bundle that is for your specific region. You can not use a CA certificate bundle that contains more than one CA certificate, such as a global bundle of CA certificates containing each region's certificate. + +::: + ### Step 2: Create your Hyperdrive configuration using the CA certificate and the SSL mode Once your CA certificate has been created, you can create a Hyperdrive configuration with the newly created From a5bcb696712ff258c2fbb2939b1b360c08966193 Mon Sep 17 00:00:00 2001 From: Thomas Gauvin Date: Tue, 8 Apr 2025 17:46:43 -0400 Subject: [PATCH 08/24] change changelog entry date --- ...-hyperdrive-custom-certificate-support.mdx | 36 ------------------- 1 file changed, 36 deletions(-) delete mode 100644 src/content/changelog/hyperdrive/2025-04-08-hyperdrive-custom-certificate-support.mdx diff --git a/src/content/changelog/hyperdrive/2025-04-08-hyperdrive-custom-certificate-support.mdx b/src/content/changelog/hyperdrive/2025-04-08-hyperdrive-custom-certificate-support.mdx deleted file mode 100644 index 05ed48110f8e3b..00000000000000 --- a/src/content/changelog/hyperdrive/2025-04-08-hyperdrive-custom-certificate-support.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Hyperdrive now supports custom TLS/SSL certificates -description: You can now configure custom certificates for secure database connections with Hyperdrive, including both server certificate verification and client certificates -products: - - hyperdrive -date: 2025-04-08T17:00:00Z ---- - -import { Code } from "~/components"; - -Hyperdrive now supports more SSL/TLS security options for your database connections: - -- Configure Hyperdrive to verify server certificates with `verify-ca` or `verify-full` SSL modes and protect against man-in-the-middle attacks -- Configure Hyperdrive to provide client certificates to the database server to authenticate itself (mTLS) for stronger security beyond username and password - -Use the new `wrangler cert` commands to create certificate authority (CA) certificate bundles or client certificate pairs: - -```bash -# Create CA certificate bundle -npx wrangler cert upload certificate-authority --ca-cert your-ca-cert.pem --name your-custom-ca-name - -# Create client certificate pair -npx wrangler cert upload mtls-certificate --cert client-cert.pem --key client-key.pem --name your-client-cert-name -``` - -Then create a Hyperdrive configuration with the certificates and desired SSL mode: - -```bash -npx wrangler hyperdrive create your-hyperdrive-config \ - --connection-string="postgres://user:password@hostname:port/database" \ - --ca-certificate-id \ - --mtls-certificate-id - --sslmode verify-full -``` - -Learn more about [configuring SSL/TLS certificates for Hyperdrive](/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive/) to enhance your database security posture. From 28638fa8450b8f6359d300e3a297760066543584 Mon Sep 17 00:00:00 2001 From: Thomas Gauvin <35609369+thomasgauvin@users.noreply.github.com> Date: Tue, 8 Apr 2025 20:16:40 -0400 Subject: [PATCH 09/24] Update src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx --- .../configuration/tls-ssl-certificates-for-hyperdrive.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx index b36509bebc13fe..2368df68663a84 100644 --- a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx +++ b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx @@ -46,7 +46,7 @@ has been used to sign the certificate of your database. Using Wrangler, you can upload your root certificate authority (CA) certificate: ```bash -# requires Wrangler 4.7.0 or greater +# requires Wrangler 4.9.0 or greater npx wrangler cert upload certificate-authority --ca-cert \.pem --name \ --- From 8442a7b989396a88b533d37496d2c522ac82cbea Mon Sep 17 00:00:00 2001 From: Thomas Gauvin <35609369+thomasgauvin@users.noreply.github.com> Date: Tue, 8 Apr 2025 20:16:56 -0400 Subject: [PATCH 10/24] Update src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx --- .../configuration/tls-ssl-certificates-for-hyperdrive.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx index 2368df68663a84..8388fb0865d280 100644 --- a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx +++ b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx @@ -117,7 +117,7 @@ file (`client-cert.pem`) and a private key with which the certificate was genera Upload your client certificates to be used by Hyperdrive using Wrangler: ```bash -# requires Wrangler 4.7.0 or greater +# requires Wrangler 4.9.0 or greater npx wrangler cert upload mtls-certificate --cert client-cert.pem --key client-key.pem --name --- From a63792535e113d168a1c5850dec37a9bec606c1f Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Apr 2025 09:31:07 +0100 Subject: [PATCH 11/24] PCX review --- .../tls-ssl-certificates-for-hyperdrive.mdx | 32 ++++++------------- 1 file changed, 10 insertions(+), 22 deletions(-) diff --git a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx index 8388fb0865d280..425efe79672a95 100644 --- a/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx +++ b/src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx @@ -28,18 +28,13 @@ Hyperdrive supports 3 common encryption [TLS/SSL modes](https://www.postgresql.o - `require` (default): TLS is required for encrypted connectivity and server certificates are validated (based on WebPKI). - `verify-ca`: Hyperdrive will verify that the database server is trustworthy by verifying that the certificates of the server have been signed by the expected root certificate authority or intermediate certificate authority. -- `verify-full`: Identical to `verify-ca`, but Hyperdrive also requires the database hostname must match a Subject Alternative Name (SAN) present on the certificate. +- `verify-full`: Identical to `verify-ca`, but Hyperdrive also requires the database hostname to match a Subject Alternative Name (SAN) present on the certificate. -By default, all Hyperdrive configurations are encrypted with SSL/TLS (`require`). This requires -that your database is configured to accept encrypted connections (with SSL/TLS). +By default, all Hyperdrive configurations are encrypted with SSL/TLS (`require`). This requires your database to be configured to accept encrypted connections (with SSL/TLS). -You can configure Hyperdrive to use -`verify-ca` and `verify-full` for a more stringent security configuration, which -provide additional verification checks of the server's certificates. This -helps guard against man-in-the-middle attacks. +You can configure Hyperdrive to use `verify-ca` and `verify-full` for a more stringent security configuration, which provide additional verification checks of the server's certificates. This helps guard against man-in-the-middle attacks. -To configure Hyperdrive to verify the certificates of the server, you must provide Hyperdrive with the certificate of the root certificate authority (CA) or an intermediate certificate which -has been used to sign the certificate of your database. +To configure Hyperdrive to verify the certificates of the server, you must provide Hyperdrive with the certificate of the root certificate authority (CA) or an intermediate certificate which has been used to sign the certificate of your database. ### Step 1: Upload your the root certificate authority (CA) certificate @@ -65,8 +60,7 @@ You must use the CA certificate bundle that is for your specific region. You can ### Step 2: Create your Hyperdrive configuration using the CA certificate and the SSL mode -Once your CA certificate has been created, you can create a Hyperdrive configuration with the newly created -certificates using either the dashboard or Wrangler. You must also specify the SSL mode of `verify-ca` or `verify-full` to use. +Once your CA certificate has been created, you can create a Hyperdrive configuration with the newly created certificates using either the dashboard or Wrangler. You must also specify the SSL mode of `verify-ca` or `verify-full` to use. @@ -86,7 +80,7 @@ From the dashboard, follow these steps to create a Hyperdrive configuration with 1. In the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive), navigate to **Storage & Databases > Hyperdrive** and click **Create configuration**. 2. Select **Server certificates**. 3. Specify a SSL mode of **Verify CA** or **Verify full** -4. Select the SSL certificate of the certificate authority (CA) of your database that you've previously uploaded with Wrangler. +4. Select the SSL certificate of the certificate authority (CA) of your database that you have previously uploaded with Wrangler. @@ -94,9 +88,7 @@ From the dashboard, follow these steps to create a Hyperdrive configuration with -When creating the Hyperdrive configuration, Hyperdrive will attempt to connect to the database with the -provided credentials. If the command provides successful results, you have properly configured your Hyperdrive -configuration to verify the certificates provided by your database server. +When creating the Hyperdrive configuration, Hyperdrive will attempt to connect to the database with the provided credentials. If the command provides successful results, you have properly configured your Hyperdrive configuration to verify the certificates provided by your database server. :::note @@ -106,11 +98,9 @@ Hyperdrive will attempt to connect to your database with the provided credential ## Client certificates -Your database can be configured to [verify a certificate provided by the client](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT), in this case, Hyperdrive. This serves -as an additional factor to authenticate clients (in addition to the username and password). +Your database can be configured to [verify a certificate provided by the client](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT), in this case, Hyperdrive. This serves as an additional factor to authenticate clients (in addition to the username and password). -For the database server to be able to verify the client certificates, Hyperdrive must be configured to provide a certificate -file (`client-cert.pem`) and a private key with which the certificate was generated (`private-key.pem`). +For the database server to be able to verify the client certificates, Hyperdrive must be configured to provide a certificate file (`client-cert.pem`) and a private key with which the certificate was generated (`private-key.pem`). ### Step 1: Upload your client certificates (mTLS certificates) @@ -157,9 +147,7 @@ From the dashboard, follow these steps to create a Hyperdrive configuration with -When Hyperdrive will connect to your database, it will provide a client certificate signed with the private key to the database server. This will allow the database server to confirm that the -client, in this case Hyperdrive, has both the private key and the client certificate. By using client certificates, you can add an additional authentication layer for your database that ensures -that only Hyperdrive can connect to it. +When Hyperdrive connects to your database, it will provide a client certificate signed with the private key to the database server. This allows the database server to confirm that the client, in this case Hyperdrive, has both the private key and the client certificate. By using client certificates, you can add an additional authentication layer for your database to ensures that only Hyperdrive can connect to it. :::note From a244fa68dcf34d9a5a1c2057222cc1e726baebcd Mon Sep 17 00:00:00 2001 From: Thomas Gauvin Date: Wed, 30 Apr 2025 19:31:16 -0400 Subject: [PATCH 12/24] add drivers and orms to hyperdrive docs --- .../connect-to-private-database.mdx | 2 +- .../examples/connect-to-mysql/index.mdx | 66 +------- .../aws-rds-aurora.mdx | 1 + .../{ => mysql-database-providers}/azure.mdx | 1 + .../google-cloud-sql.mdx | 1 + .../mysql-database-providers/index.mdx | 14 ++ .../planetscale.mdx | 10 ++ .../drizzle-orm.mdx | 122 +++++++++++++++ .../mysql-drivers-and-libraries/index.mdx | 12 ++ .../mysql-drivers-and-libraries/mysql.mdx | 15 ++ .../mysql-drivers-and-libraries/mysql2.mdx | 13 ++ .../examples/connect-to-postgres/index.mdx | 62 +------- .../aws-rds-aurora.mdx | 1 + .../azure.mdx | 1 + .../cockroachdb.mdx | 1 + .../digital-ocean.mdx | 1 + .../{ => postgres-database-providers}/fly.mdx | 1 + .../google-cloud-sql.mdx | 1 + .../postgres-database-providers/index.mdx | 14 ++ .../materialize.mdx | 1 + .../neon.mdx | 11 ++ .../nile.mdx | 1 + .../pgedge.mdx | 1 + .../supabase.mdx | 10 ++ .../timescale.mdx | 1 + .../xata.mdx | 1 + .../drizzle-orm.mdx | 117 ++++++++++++++ .../postgres-drivers-and-libraries/index.mdx | 12 ++ .../node-postgres.mdx | 14 ++ .../postgres-js.mdx | 14 ++ .../prisma-orm.mdx | 144 ++++++++++++++++++ ...ate-hyperdrive-config-mysql-next-steps.mdx | 9 ++ .../create-hyperdrive-config-mysql.mdx | 6 - .../create-hyperdrive-config-next-steps.mdx | 9 ++ .../hyperdrive/create-hyperdrive-config.mdx | 8 +- ...erdrive-node-compatibility-requirement.mdx | 19 +++ .../hyperdrive/use-mysql-to-make-query.mdx | 56 +++++++ .../hyperdrive/use-mysql2-to-make-query.mdx | 36 ++--- .../use-node-postgres-to-make-query.mdx | 60 ++++++++ .../use-postgres-js-to-make-query.mdx | 60 ++++++++ .../use-postgresjs-to-make-query.mdx | 56 ------- 41 files changed, 772 insertions(+), 213 deletions(-) rename src/content/docs/hyperdrive/examples/connect-to-mysql/{ => mysql-database-providers}/aws-rds-aurora.mdx (98%) rename src/content/docs/hyperdrive/examples/connect-to-mysql/{ => mysql-database-providers}/azure.mdx (96%) rename src/content/docs/hyperdrive/examples/connect-to-mysql/{ => mysql-database-providers}/google-cloud-sql.mdx (96%) create mode 100644 src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/index.mdx rename src/content/docs/hyperdrive/examples/connect-to-mysql/{ => mysql-database-providers}/planetscale.mdx (64%) create mode 100644 src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx create mode 100644 src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/index.mdx create mode 100644 src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql.mdx create mode 100644 src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql2.mdx rename src/content/docs/hyperdrive/examples/connect-to-postgres/{ => postgres-database-providers}/aws-rds-aurora.mdx (98%) rename src/content/docs/hyperdrive/examples/connect-to-postgres/{ => postgres-database-providers}/azure.mdx (96%) rename src/content/docs/hyperdrive/examples/connect-to-postgres/{ => postgres-database-providers}/cockroachdb.mdx (97%) rename src/content/docs/hyperdrive/examples/connect-to-postgres/{ => postgres-database-providers}/digital-ocean.mdx (96%) rename src/content/docs/hyperdrive/examples/connect-to-postgres/{ => postgres-database-providers}/fly.mdx (97%) rename src/content/docs/hyperdrive/examples/connect-to-postgres/{ => postgres-database-providers}/google-cloud-sql.mdx (98%) create mode 100644 src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/index.mdx rename src/content/docs/hyperdrive/examples/connect-to-postgres/{ => postgres-database-providers}/materialize.mdx (97%) rename src/content/docs/hyperdrive/examples/connect-to-postgres/{ => postgres-database-providers}/neon.mdx (69%) rename src/content/docs/hyperdrive/examples/connect-to-postgres/{ => postgres-database-providers}/nile.mdx (96%) rename src/content/docs/hyperdrive/examples/connect-to-postgres/{ => postgres-database-providers}/pgedge.mdx (95%) rename src/content/docs/hyperdrive/examples/connect-to-postgres/{ => postgres-database-providers}/supabase.mdx (65%) rename src/content/docs/hyperdrive/examples/connect-to-postgres/{ => postgres-database-providers}/timescale.mdx (97%) rename src/content/docs/hyperdrive/examples/connect-to-postgres/{ => postgres-database-providers}/xata.mdx (94%) create mode 100644 src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx create mode 100644 src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/index.mdx create mode 100644 src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres.mdx create mode 100644 src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js.mdx create mode 100644 src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx create mode 100644 src/content/partials/hyperdrive/create-hyperdrive-config-mysql-next-steps.mdx create mode 100644 src/content/partials/hyperdrive/create-hyperdrive-config-next-steps.mdx create mode 100644 src/content/partials/hyperdrive/hyperdrive-node-compatibility-requirement.mdx create mode 100644 src/content/partials/hyperdrive/use-mysql-to-make-query.mdx create mode 100644 src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx create mode 100644 src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx delete mode 100644 src/content/partials/hyperdrive/use-postgresjs-to-make-query.mdx diff --git a/src/content/docs/hyperdrive/configuration/connect-to-private-database.mdx b/src/content/docs/hyperdrive/configuration/connect-to-private-database.mdx index 67c603bd6d7368..94533499ae6380 100644 --- a/src/content/docs/hyperdrive/configuration/connect-to-private-database.mdx +++ b/src/content/docs/hyperdrive/configuration/connect-to-private-database.mdx @@ -199,7 +199,7 @@ Validate that you can connect to your database from Workers and make queries. Use Postgres.js to send a test query to validate that the connection has been successful. - + Now, deploy your Worker: diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/index.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/index.mdx index 7ca8964c52605f..f1da4356b4b152 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/index.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/index.mdx @@ -32,19 +32,7 @@ npx wrangler hyperdrive create my-first-hyperdrive --connection-string="mysql:// The command above will output the ID of your Hyperdrive, which you will need to set in the [Wrangler configuration file](/workers/wrangler/configuration/) for your Workers project: - - -```toml -# required for database drivers to function -compatibility_flags = ["nodejs_compat"] -compatibility_date = "2024-09-23" - -[[hyperdrive]] -binding = "HYPERDRIVE" -id = "" -``` - - + This will allow Hyperdrive to generate a dynamic connection string within your Worker that you can pass to your existing database driver. Refer to [Driver examples](#driver-examples) to learn how to set up a database driver with Hyperdrive. @@ -105,57 +93,9 @@ The following Workers code shows you how to use [mysql2](https://github.com/sido ### `mysql` -Install the `mysql` driver: +The following Workers code shows you how to use [mysql](https://github.com/mysqljs/mysql) with Hyperdrive. -```sh -npm install mysql -``` - -**Ensure you have `compatibility_flags` and `compatibility_date` set in your [Wrangler configuration file](/workers/wrangler/configuration/)** as shown below: - - - -Create a new connection and pass the Hyperdrive parameters: - -```ts -import { createConnection } from "mysql"; - -export interface Env { - HYPERDRIVE: Hyperdrive; -} - -export default { - async fetch(request, env, ctx): Promise { - const result = await new Promise((resolve) => { - const connection = createConnection({ - host: env.HYPERDRIVE.host, - user: env.HYPERDRIVE.user, - password: env.HYPERDRIVE.password, - database: env.HYPERDRIVE.database, - port: env.HYPERDRIVE.port, - }); - - connection.connect((error: { message: string }) => { - if (error) { - throw new Error(error.message); - } - - connection.query("SHOW tables;", [], (error, rows, fields) => { - connection.end(); - - resolve({ fields, rows }); - }); - }); - }); - - return new Response(JSON.stringify(result), { - headers: { - "Content-Type": "application/json", - }, - }); - }, -} satisfies ExportedHandler; -``` + ## Identify connections from Hyperdrive diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/aws-rds-aurora.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/aws-rds-aurora.mdx similarity index 98% rename from src/content/docs/hyperdrive/examples/connect-to-mysql/aws-rds-aurora.mdx rename to src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/aws-rds-aurora.mdx index 207799ee411390..feee9b1f413f54 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/aws-rds-aurora.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/aws-rds-aurora.mdx @@ -97,3 +97,4 @@ With a database user, password, database endpoint (hostname and port), and datab ## 3. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/azure.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/azure.mdx similarity index 96% rename from src/content/docs/hyperdrive/examples/connect-to-mysql/azure.mdx rename to src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/azure.mdx index 33de0b0bd3e96c..db66a9deef1cde 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/azure.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/azure.mdx @@ -38,3 +38,4 @@ To connect to a private Azure Database for MySQL instance, refer to [Connect to ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/google-cloud-sql.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/google-cloud-sql.mdx similarity index 96% rename from src/content/docs/hyperdrive/examples/connect-to-mysql/google-cloud-sql.mdx rename to src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/google-cloud-sql.mdx index c446f01dd8b8c1..8969f2feeae021 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/google-cloud-sql.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/google-cloud-sql.mdx @@ -41,3 +41,4 @@ With the username, password, public IP address and (optional) database name (def ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/index.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/index.mdx new file mode 100644 index 00000000000000..f91f8e5e15c8f2 --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/index.mdx @@ -0,0 +1,14 @@ +--- +type: overview +pcx_content_type: navigation +title: Database Providers +hideChildren: false +sidebar: + order: 5 + group: + hideIndex: true +--- + +import { DirectoryListing } from "~/components"; + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/planetscale.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale.mdx similarity index 64% rename from src/content/docs/hyperdrive/examples/connect-to-mysql/planetscale.mdx rename to src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale.mdx index 6330eb71943e2a..4b458c840b9074 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/planetscale.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale.mdx @@ -27,3 +27,13 @@ With the host, database name, username and password, you can now create a Hyperd ## 2. Create a database configuration + +:::note + +When connection to a Planetscale database with Hyperdrive, you should use a driver like [node-postgres (pg)](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/) or [Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/) +to connect directly to the underlying database instead of the [Planetscale serverless driver](https://planetscale.com/docs/tutorials/planetscale-serverless-driver). Hyperdrive is optimized for database access for Workers and +will perform global connection pooling and fast query routing by connecting directly to your database. + +::: + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx new file mode 100644 index 00000000000000..08471eee6e31cc --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx @@ -0,0 +1,122 @@ +--- +pcx_content_type: example +title: Drizzle ORM +sidebar: + order: 3 +meta: + title: Using Drizzle ORM with Hyperdrive for MySQL +--- + +import { Render } from "~/components"; + +[Drizzle ORM](https://orm.drizzle.team/) is a lightweight TypeScript ORM with a focus on type safety. This example demonstrates how to use Drizzle ORM with MySQL via Cloudflare Hyperdrive in a Workers application. + +## Prerequisites + +- A Cloudflare account with Workers access +- A MySQL database +- A [Hyperdrive configuration to your MySQL database](/hyperdrive/get-started/#3-connect-hyperdrive-to-a-database) + +## Installation + +Install the Drizzle ORM and its dependencies such as the [mysql2](https://github.com/sidorares/node-mysql2) driver: + +```sh +# mysql2 v3.13.0 or later is required +npm i drizzle-orm mysql2 dotenv +npm i -D drizzle-kit tsx @types/node +``` + +Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: + + + +## Configure Drizzle + +### Define a schema + +With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL. Here's how to define a users table: + +```ts +// src/schema.ts +import { mysqlTable, int, varchar, timestamp } from "drizzle-orm/mysql-core"; + +export const users = mysqlTable("users", { + id: int("id").primaryKey().autoincrement(), + name: varchar("name", { length: 255 }).notNull(), + email: varchar("email", { length: 255 }).notNull().unique(), + createdAt: timestamp("created_at").defaultNow(), +}); +``` + +### Connect Drizzle ORM to the database with Hyperdrive + +Use your the credentials of your Hyperdrive configuration for your database when using the +Drizzle ORM within your Worker project as such: + +```ts +// src/db/schema.ts + +import { drizzle } from "drizzle-orm/mysql2"; +import { createConnection } from "mysql2"; +import { users } from "./db/schema"; + +export default { + async fetch(request, env, ctx): Promise { + // Create a connection using the mysql2 driver with the Hyperdrive credentials (only accessible from your Worker). + const connection = await createConnection({ + host: env.HYPERDRIVE.host, + user: env.HYPERDRIVE.user, + password: env.HYPERDRIVE.password, + database: env.HYPERDRIVE.database, + port: env.HYPERDRIVE.port, + + // Required to enable mysql2 compatibility for Workers + disableEval: true, + }); + + // Create the Drizzle client with the mysql2 driver connection + const db = drizzle(connection); + + // Sample query to get all users + const allUsers = await db.select().from(users); + + return Response.json(allUsers); + }, +} satisfies ExportedHandler; +``` + +### Configure Drizzle-Kit for migrations (optional) + +You can generate and run SQL migrations on your database based on your schema +using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/mysql-new) for additional guidance. + +1. Create a `.env` file and add your database connection string. The Drizzle Kit CLI will use + this connection string to create and apply the migrations. + + ```toml + # Replace with your direct database connection string + DATABASE_URL='mysql://user:password@db-host.cloud/database-name' + ``` + +2. Create a `drizzle.config.ts` file in the root of your project to configure Drizzle Kit + and add the following content: + + ```ts + import 'dotenv/config'; + import { defineConfig } from 'drizzle-kit'; + export default defineConfig({ + out: './drizzle', + schema: './src/db/schema.ts', + dialect: 'mysql', + dbCredentials: { + url: process.env.DATABASE_URL!, + }, + }); + ``` + +3. Generate the migration file for your database according to your schema files and apply the migrations to your database. + `bash +npx drizzle-kit generate +npx drizzle-kit migrate +` diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/index.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/index.mdx new file mode 100644 index 00000000000000..591fb248c977c9 --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/index.mdx @@ -0,0 +1,12 @@ +--- +pcx_content_type: navigation +title: Libraries and Drivers +sidebar: + order: 8 + group: + hideIndex: true +--- + +import { DirectoryListing } from "~/components"; + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql.mdx new file mode 100644 index 00000000000000..0e76bbb27c8777 --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql.mdx @@ -0,0 +1,15 @@ +--- +pcx_content_type: example +title: mysql +sidebar: + order: 2 +meta: + title: Using mysql driver with Hyperdrive +--- + +import { Render } from "~/components"; + +The [mysql](https://github.com/mysqljs/mysql) package is a MySQL driver for Node.js. +This example demonstrates how to use it with Cloudflare Workers and Hyperdrive. + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql2.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql2.mdx new file mode 100644 index 00000000000000..ba488788cc08a3 --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql2.mdx @@ -0,0 +1,13 @@ +--- +pcx_content_type: example +title: mysql2 +sidebar: + order: 1 +--- + +import { Render } from "~/components"; + +The [mysql2](https://github.com/sidorares/node-mysql2) package is a modern MySQL driver for Node.js with better performance and built-in Promise support. +This example demonstrates how to use it with Cloudflare Workers and Hyperdrive. + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/index.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/index.mdx index e4a9a590490e74..21284205d1cae3 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/index.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/index.mdx @@ -32,19 +32,7 @@ npx wrangler hyperdrive create my-first-hyperdrive --connection-string="postgres The command above will output the ID of your Hyperdrive, which you will need to set in the [Wrangler configuration file](/workers/wrangler/configuration/) for your Workers project: - - -```toml -# required for database drivers to function -compatibility_flags = ["nodejs_compat"] -compatibility_date = "2024-09-23" - -[[hyperdrive]] -binding = "HYPERDRIVE" -id = "" -``` - - + This will allow Hyperdrive to generate a dynamic connection string within your Worker that you can pass to your existing database driver. Refer to [Driver examples](#driver-examples) to learn how to set up a database driver with Hyperdrive. @@ -84,57 +72,13 @@ The following examples show you how to: The following Workers code shows you how to use [Postgres.js](https://github.com/porsager/postgres) with Hyperdrive. - + ### node-postgres / pg Install the `node-postgres` driver: -```sh -npm install pg -``` - -**Ensure you have `compatibility_flags` and `compatibility_date` set in your [Wrangler configuration file](/workers/wrangler/configuration/)** as shown below: - - - -Create a new `Client` instance and pass the Hyperdrive parameters: - -```ts -import { Client } from "pg"; - -export interface Env { - // If you set another name in the Wrangler configuration file as the value for 'binding', - // replace "HYPERDRIVE" with the variable name you defined. - HYPERDRIVE: Hyperdrive; -} - -export default { - async fetch(request, env, ctx): Promise { - const client = new Client({ - connectionString: env.HYPERDRIVE.connectionString, - }); - - try { - // Connect to your database - await client.connect(); - - // A very simple test query - const result = await client.query({ text: "SELECT * FROM pg_tables" }); - - // Clean up the client, ensuring we don't kill the worker before that is - // completed. - ctx.waitUntil(client.end()); - - // Return result rows as JSON - return Response.json({ result: result }); - } catch (e) { - console.log(e); - return Response.json({ error: e.message }, { status: 500 }); - } - }, -} satisfies ExportedHandler; -``` + ## Identify connections from Hyperdrive diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/aws-rds-aurora.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora.mdx similarity index 98% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/aws-rds-aurora.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora.mdx index 5446dbf3609685..fd21e2dc5b028d 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/aws-rds-aurora.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora.mdx @@ -91,3 +91,4 @@ With a database user, password, database endpoint (hostname and port) and databa ## 3. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/azure.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/azure.mdx similarity index 96% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/azure.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/azure.mdx index 9edf6ec42a57bb..24f42672b188a4 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/azure.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/azure.mdx @@ -38,3 +38,4 @@ To connect to a private Azure Database for PostgreSQL instance, refer to [Connec ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/cockroachdb.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb.mdx similarity index 97% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/cockroachdb.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb.mdx index 1447ad8f64cb64..3ca5d23a131ad5 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/cockroachdb.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb.mdx @@ -41,3 +41,4 @@ By default, the CockroachDB cloud enables connections from the public Internet ( ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/digital-ocean.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/digital-ocean.mdx similarity index 96% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/digital-ocean.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/digital-ocean.mdx index c37f8eb30111ff..5010d0ec4f5c09 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/digital-ocean.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/digital-ocean.mdx @@ -29,6 +29,7 @@ With the connection string, you can now create a Hyperdrive database configurati ## 2. Create a database configuration + :::note If you see a DNS-related error, it is possible that the DNS for your vendor's database has not yet been propagated. Try waiting 10 minutes before retrying the operation. Refer to [DigitalOcean support page](https://docs.digitalocean.com/support/why-does-my-domain-fail-to-resolve/) for more information. diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/fly.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/fly.mdx similarity index 97% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/fly.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/fly.mdx index 1074dbf1a29e82..567b5ba464391d 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/fly.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/fly.mdx @@ -62,3 +62,4 @@ You can connect Hyperdrive to any existing Fly database by: ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/google-cloud-sql.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/google-cloud-sql.mdx similarity index 98% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/google-cloud-sql.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/google-cloud-sql.mdx index cdefec657b84a5..7563fd076ef22d 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/google-cloud-sql.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/google-cloud-sql.mdx @@ -61,3 +61,4 @@ Refer to [Google Cloud's documentation](https://cloud.google.com/sql/docs/postgr ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/index.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/index.mdx new file mode 100644 index 00000000000000..f91f8e5e15c8f2 --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/index.mdx @@ -0,0 +1,14 @@ +--- +type: overview +pcx_content_type: navigation +title: Database Providers +hideChildren: false +sidebar: + order: 5 + group: + hideIndex: true +--- + +import { DirectoryListing } from "~/components"; + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/materialize.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/materialize.mdx similarity index 97% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/materialize.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/materialize.mdx index 2290a067860993..ece14edd5ad15c 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/materialize.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/materialize.mdx @@ -43,3 +43,4 @@ With the username, app password, hostname, port and database name, you can now c ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/neon.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon.mdx similarity index 69% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/neon.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon.mdx index 9e104549698ad7..59548df05e224d 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/neon.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon.mdx @@ -28,3 +28,14 @@ With both the connection string and the password, you can now create a Hyperdriv ## 2. Create a database configuration + +:::note + +When connection to a Neon database with Hyperdrive, you should use a driver like [node-postgres (pg)](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/) or [Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/) +to connect directly to the underlying database +instead of the [Neon serverless driver](https://neon.tech/docs/serverless/serverless-driver). Hyperdrive is optimized for database access for Workers and +will perform global connection pooling and fast query routing by connecting directly to your database. + +::: + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/nile.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/nile.mdx similarity index 96% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/nile.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/nile.mdx index 12cca7c471d528..d0cb043b746f4e 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/nile.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/nile.mdx @@ -39,3 +39,4 @@ With the connection string, you can now create a Hyperdrive database configurati ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/pgedge.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/pgedge.mdx similarity index 95% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/pgedge.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/pgedge.mdx index fa6f3487f25ea6..8413afda667b79 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/pgedge.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/pgedge.mdx @@ -26,3 +26,4 @@ To retrieve your connection string from the pgEdge dashboard: ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/supabase.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase.mdx similarity index 65% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/supabase.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase.mdx index bb80699588f5e1..8cc51478f244a5 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/supabase.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase.mdx @@ -31,3 +31,13 @@ With a database user, password, database endpoint (hostname and port) and databa ## 2. Create a database configuration + +:::note + +When connection to a Supabase database with Hyperdrive, you should use a driver like [node-postgres (pg)](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/) or [Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/) +to connect directly to the underlying database instead of the [Supabase JavaScript client](https://github.com/supabase/supabase-js). Hyperdrive is optimized for database access for Workers and +will perform global connection pooling and fast query routing by connecting directly to your database. + +::: + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/timescale.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale.mdx similarity index 97% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/timescale.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale.mdx index bdb88a6d991917..20d3590afaa913 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/timescale.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale.mdx @@ -45,3 +45,4 @@ With the connection string, you can now create a Hyperdrive database configurati ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/xata.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/xata.mdx similarity index 94% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/xata.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/xata.mdx index e595cf5ab933df..13400393686128 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/xata.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/xata.mdx @@ -28,3 +28,4 @@ To retrieve your connection string from the Xata dashboard: ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx new file mode 100644 index 00000000000000..ca68c7537b4ad8 --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx @@ -0,0 +1,117 @@ +--- +pcx_content_type: example +title: Drizzle ORM +sidebar: + order: 3 +meta: + title: Using Drizzle ORM with Hyperdrive for PostgreSQL +--- + +[Drizzle ORM](https://orm.drizzle.team/) is a lightweight TypeScript ORM with a focus on type safety. This example demonstrates how to use Drizzle ORM with PostgreSQL via Cloudflare Hyperdrive in a Workers application. + +## Prerequisites + +- A Cloudflare account with Workers access +- A PostgreSQL database +- A [Hyperdrive configuration to your PostgreSQL database](/hyperdrive/get-started/#3-connect-hyperdrive-to-a-database) + +## Installation + +Install the Drizzle ORM and its dependencies such as the [postgres](https://github.com/porsager/postgres) driver: + +```sh +# postgres 3.4.5 or later is recommended +npm i drizzle-orm postgres dotenv +npm i -D drizzle-kit tsx @types/node +``` + +Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: + + + +## Configure Drizzle + +### Define a schema + +With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL. Here's how to define a users table: + +```ts +// src/db/schema.ts +import { pgTable, serial, varchar, timestamp } from "drizzle-orm/pg-core"; + +export const users = pgTable("users", { + id: serial("id").primaryKey(), + name: varchar("name", { length: 255 }).notNull(), + email: varchar("email", { length: 255 }).notNull().unique(), + createdAt: timestamp("created_at").defaultNow(), +}); +``` + +### Connect Drizzle ORM to the database with Hyperdrive + +Use your Hyperdrive configuration for your database when using the +Drizzle ORM within your Worker project as such: + +```ts +// src/index.ts +import { drizzle } from "drizzle-orm/postgres-js"; +import postgres from "postgres"; +import { users } from "./db/schema"; + +export interface Env { + HYPERDRIVE: Hyperdrive; +} + +export default { + async fetch(request, env, ctx): Promise { + // Create a database client with postgres.js driver connected via Hyperdrive + const sql = postgres(env.HYPERDRIVE.connectionString); + + // Create the Drizzle client with the postgres.js connection + const db = drizzle(sql); + + // Sample query to get all users + const allUsers = await db.select().from(users); + + // Clean up the connection + ctx.waitUntil(sql.end()); + + return Response.json(allUsers); + }, +} satisfies ExportedHandler; +``` + +### Configure Drizzle-Kit for migrations (optional) + +You can generate and run SQL migrations on your database based on your schema +using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/postgresql) for additional guidance. + +1. Create a `.env` file and add your database connection string. The Drizzle Kit CLI will use + this connection string to create and apply the migrations. + + ```toml + # Replace with your direct database connection string + DATABASE_URL='postgres://user:password@db-host.cloud/database-name' + ``` + +2. Create a `drizzle.config.ts` file in the root of your project to configure Drizzle Kit + and add the following content: + + ```ts + import "dotenv/config"; + import { defineConfig } from "drizzle-kit"; + export default defineConfig({ + out: "./drizzle", + schema: "./src/db/schema.ts", + dialect: "postgresql", + dbCredentials: { + url: process.env.DATABASE_URL!, + }, + }); + ``` + +3. Generate the migration file for your database according to your schema files and apply the migrations to your database. + ```bash + npx drizzle-kit generate + npx drizzle-kit migrate + ``` diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/index.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/index.mdx new file mode 100644 index 00000000000000..591fb248c977c9 --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/index.mdx @@ -0,0 +1,12 @@ +--- +pcx_content_type: navigation +title: Libraries and Drivers +sidebar: + order: 8 + group: + hideIndex: true +--- + +import { DirectoryListing } from "~/components"; + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres.mdx new file mode 100644 index 00000000000000..8cc2e3a61b699c --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres.mdx @@ -0,0 +1,14 @@ +--- +pcx_content_type: example +title: node-postgres (pg) +sidebar: + order: 1 +meta: + title: Using node-postgres with Hyperdrive +--- + +import { Render } from "~/components"; + +[node-postgres](https://node-postgres.com/) (pg) is a widely-used PostgreSQL driver for Node.js applications. This example demonstrates how to use node-postgres with Cloudflare Hyperdrive in a Workers application. + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js.mdx new file mode 100644 index 00000000000000..8792a7a33b05f3 --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js.mdx @@ -0,0 +1,14 @@ +--- +pcx_content_type: example +title: Postgres.js +sidebar: + order: 2 +meta: + title: Using Postgres.js with Hyperdrive +--- + +import { Render } from "~/components"; + +[Postgres.js](https://github.com/porsager/postgres) is a modern, fully-featured PostgreSQL driver for Node.js. This example demonstrates how to use Postgres.js with Cloudflare Hyperdrive in a Workers application. + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx new file mode 100644 index 00000000000000..6bb8ce1452432b --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx @@ -0,0 +1,144 @@ +--- +pcx_content_type: example +title: Prisma ORM +sidebar: + order: 4 +meta: + title: Using Prisma ORM with Hyperdrive for PostgreSQL +--- + +[Prisma](https://www.prisma.io/) is a modern ORM that provides a type-safe API for working with databases. This example demonstrates how to use Prisma ORM with PostgreSQL via Cloudflare Hyperdrive in a Workers application. + +## Prerequisites + +- A Cloudflare account with Workers access +- A PostgreSQL database +- A [Hyperdrive configuration to your PostgreSQL database](/hyperdrive/get-started/#3-connect-hyperdrive-to-a-database) + +## Installation + +Install Prisma, its dependencies, node-postgres driver, and generate the client: + +```sh +npm install @prisma/client @prisma/adapter-pg pg +npm install prisma @types/pg --save-dev +``` + +Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: + + + +## Configure Prisma + +### Define a schema + +With Prisma, we define the schema using the Prisma Schema Language (PSL). Create a `prisma/schema.prisma` file in your project: + +```prisma +// prisma/schema.prisma +generator client { + provider = "prisma-client-js" + previewFeatures = ["driverAdapters"] + output = "../node_modules/.prisma/client" +} + +datasource db { + provider = "postgresql" + url = env("DATABASE_URL") +} + +model User { + id Int @id @default(autoincrement()) + name String + email String @unique + createdAt DateTime @default(now()) @map("created_at") + + @@map("users") +} +``` + +After defining your schema, generate the Prisma Client: + +```sh +npx prisma generate +``` + +### Connect Prisma to the database with Hyperdrive + +Use your Hyperdrive configuration for your database when using Prisma with the node-postgres adapter within your Worker project: + +```ts +// src/index.ts +import { PrismaClient } from "@prisma/client"; +import { PrismaPg } from "@prisma/adapter-pg"; +import pg from "pg"; + +pg.defaults.poolSize = 5; + +export interface Env { + HYPERDRIVE: Hyperdrive; +} + +export default { + async fetch(request, env, ctx): Promise { + // Create a connection pool using node-postgres + const pool = new pg.Pool({ + connectionString: env.HYPERDRIVE.connectionString, + }); + + // Create Prisma adapter with the node-postgres pool + const adapter = new PrismaPg(pool); + + // Initialize Prisma Client with the adapter + const prisma = new PrismaClient({ adapter }); + + try { + // Sample query to get all users + const users = await prisma.user.findMany(); + + // Clean up the connection + ctx.waitUntil(Promise.all([prisma.$disconnect(), pool.end()])); + + return Response.json(users); + } catch (error) { + console.error("Database error:", error); + + // Ensure we clean up the connection + ctx.waitUntil( + Promise.all([ + prisma + .$disconnect() + .catch((e) => console.error("Error disconnecting Prisma:", e)), + pool.end().catch((e) => console.error("Error closing pool:", e)), + ]), + ); + + return Response.json( + { error: "Database connection failed" }, + { status: 500 }, + ); + } + }, +} satisfies ExportedHandler; +``` + +### Prisma Migrations (optional) + +You can use Prisma Migrate to create and manage your database schema: + +1. Create a `.env` file in your project root with your direct database connection string: + `toml +DATABASE_URL='postgresql://user:password@db-host.cloud/database-name' +` + +2. Initialize and generate your first migration (for development only): + `sh +npx prisma migrate dev --name init +` + + This will create SQL migration files in the `prisma/migrations` directory and apply them to your database. + +3. For production environments, apply migrations without generating new ones: + `sh +npx prisma migrate deploy +` diff --git a/src/content/partials/hyperdrive/create-hyperdrive-config-mysql-next-steps.mdx b/src/content/partials/hyperdrive/create-hyperdrive-config-mysql-next-steps.mdx new file mode 100644 index 00000000000000..8d4aea94647740 --- /dev/null +++ b/src/content/partials/hyperdrive/create-hyperdrive-config-mysql-next-steps.mdx @@ -0,0 +1,9 @@ +--- +{} +--- + +## Next steps + +- Learn more about [How Hyperdrive Works](/hyperdrive/configuration/how-hyperdrive-works/). +- Refer to the [troubleshooting guide](/hyperdrive/observability/troubleshooting/) to debug common issues. +- Understand more about other [storage options](/workers/platform/storage-options/) available to Cloudflare Workers. diff --git a/src/content/partials/hyperdrive/create-hyperdrive-config-mysql.mdx b/src/content/partials/hyperdrive/create-hyperdrive-config-mysql.mdx index eac765e7a356c5..b05de5035082e0 100644 --- a/src/content/partials/hyperdrive/create-hyperdrive-config-mysql.mdx +++ b/src/content/partials/hyperdrive/create-hyperdrive-config-mysql.mdx @@ -55,9 +55,3 @@ id = "" ## 3. Use Hyperdrive from your Worker - -## Next steps - -- Learn more about [How Hyperdrive Works](/hyperdrive/configuration/how-hyperdrive-works/). -- Refer to the [troubleshooting guide](/hyperdrive/observability/troubleshooting/) to debug common issues. -- Understand more about other [storage options](/workers/platform/storage-options/) available to Cloudflare Workers. diff --git a/src/content/partials/hyperdrive/create-hyperdrive-config-next-steps.mdx b/src/content/partials/hyperdrive/create-hyperdrive-config-next-steps.mdx new file mode 100644 index 00000000000000..8d4aea94647740 --- /dev/null +++ b/src/content/partials/hyperdrive/create-hyperdrive-config-next-steps.mdx @@ -0,0 +1,9 @@ +--- +{} +--- + +## Next steps + +- Learn more about [How Hyperdrive Works](/hyperdrive/configuration/how-hyperdrive-works/). +- Refer to the [troubleshooting guide](/hyperdrive/observability/troubleshooting/) to debug common issues. +- Understand more about other [storage options](/workers/platform/storage-options/) available to Cloudflare Workers. diff --git a/src/content/partials/hyperdrive/create-hyperdrive-config.mdx b/src/content/partials/hyperdrive/create-hyperdrive-config.mdx index df47e407458561..6ea9ab2726db34 100644 --- a/src/content/partials/hyperdrive/create-hyperdrive-config.mdx +++ b/src/content/partials/hyperdrive/create-hyperdrive-config.mdx @@ -51,10 +51,4 @@ id = "" ## 3. Use Hyperdrive from your Worker - - -## Next steps - -- Learn more about [How Hyperdrive Works](/hyperdrive/configuration/how-hyperdrive-works/). -- Refer to the [troubleshooting guide](/hyperdrive/observability/troubleshooting/) to debug common issues. -- Understand more about other [storage options](/workers/platform/storage-options/) available to Cloudflare Workers. + diff --git a/src/content/partials/hyperdrive/hyperdrive-node-compatibility-requirement.mdx b/src/content/partials/hyperdrive/hyperdrive-node-compatibility-requirement.mdx new file mode 100644 index 00000000000000..4095a504681756 --- /dev/null +++ b/src/content/partials/hyperdrive/hyperdrive-node-compatibility-requirement.mdx @@ -0,0 +1,19 @@ +--- +{} +--- + +import { WranglerConfig } from "~/components"; + + + +```toml +# required for database drivers to function +compatibility_flags = ["nodejs_compat"] +compatibility_date = "2024-09-23" + +[[hyperdrive]] +binding = "HYPERDRIVE" +id = "" +``` + + diff --git a/src/content/partials/hyperdrive/use-mysql-to-make-query.mdx b/src/content/partials/hyperdrive/use-mysql-to-make-query.mdx new file mode 100644 index 00000000000000..be408a719f7c35 --- /dev/null +++ b/src/content/partials/hyperdrive/use-mysql-to-make-query.mdx @@ -0,0 +1,56 @@ +--- +{} +--- + +import { Render } from "~/components"; + +Install the [mysql](https://github.com/mysqljs/mysql) driver: + +```sh +npm install mysql +``` + +Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: + + + +Create a new connection and pass the Hyperdrive parameters: + +```ts +import { createConnection } from "mysql"; + +export default { + async fetch(request, env, ctx): Promise { + const result = await new Promise((resolve) => { + // Create a connection using the mysql driver with the Hyperdrive credentials (only accessible from your Worker). + const connection = createConnection({ + host: env.HYPERDRIVE.host, + user: env.HYPERDRIVE.user, + password: env.HYPERDRIVE.password, + database: env.HYPERDRIVE.database, + port: env.HYPERDRIVE.port, + }); + + connection.connect((error: { message: string }) => { + if (error) { + throw new Error(error.message); + } + + // Sample query + connection.query("SHOW tables;", [], (error, rows, fields) => { + connection.end(); + + resolve({ fields, rows }); + }); + }); + }); + + // Return result as JSON + return new Response(JSON.stringify(result), { + headers: { + "Content-Type": "application/json", + }, + }); + }, +} satisfies ExportedHandler; +``` diff --git a/src/content/partials/hyperdrive/use-mysql2-to-make-query.mdx b/src/content/partials/hyperdrive/use-mysql2-to-make-query.mdx index 361d32f0b7e1d3..a492d5ab756c3a 100644 --- a/src/content/partials/hyperdrive/use-mysql2-to-make-query.mdx +++ b/src/content/partials/hyperdrive/use-mysql2-to-make-query.mdx @@ -2,6 +2,8 @@ {} --- +import { Render } from "~/components"; + Install the [mysql2](https://github.com/sidorares/node-mysql2) driver: ```sh @@ -9,22 +11,19 @@ Install the [mysql2](https://github.com/sidorares/node-mysql2) driver: npm install mysql2 ``` +Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: + + + Create a new `connection` instance and pass the Hyperdrive parameters: ```ts // mysql2 v3.13.0 or later is required import { createConnection } from "mysql2/promise"; -export interface Env { - // If you set another name in the Wrangler config file as the value for 'binding', - // replace "HYPERDRIVE" with the variable name you defined. - HYPERDRIVE: Hyperdrive; -} - export default { async fetch(request, env, ctx): Promise { - // Create a connection using the mysql2 driver (or any support driver, ORM or query builder) - // with the Hyperdrive credentials. These credentials are only accessible from your Worker. + // Create a connection using the mysql2 driver with the Hyperdrive credentials (only accessible from your Worker). const connection = await createConnection({ host: env.HYPERDRIVE.host, user: env.HYPERDRIVE.user, @@ -32,9 +31,7 @@ export default { database: env.HYPERDRIVE.database, port: env.HYPERDRIVE.port, - // The following line is needed for mysql2 compatibility with Workers - // mysql2 uses eval() to optimize result parsing for rows with > 100 columns - // Configure mysql2 to use static parsing instead of eval() parsing with disableEval + // Required to enable mysql2 compatibility for Workers disableEval: true, }); @@ -46,19 +43,16 @@ export default { ctx.waitUntil(connection.end()); // Return result rows as JSON - return new Response(JSON.stringify({ results, fields }), { - headers: { - "Content-Type": "application/json", - "Access-Control-Allow-Origin": "*", - }, - }); + return Response.json({ results, fields }); } catch (e) { console.error(e); - return Response.json( - { error: e instanceof Error ? e.message : e }, - { status: 500 }, - ); } }, } satisfies ExportedHandler; ``` + +:::note + +The minimum version of `mysql2` required for Hyperdrive is `3.13.0`. + +::: diff --git a/src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx b/src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx new file mode 100644 index 00000000000000..39aff3e24c5158 --- /dev/null +++ b/src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx @@ -0,0 +1,60 @@ +--- +{} +--- + +import { Render } from "~/components"; + +Install the `node-postgres` driver: + +```sh +npm install pg +``` + +Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: + + + +Create a new `Client` instance and pass the Hyperdrive `connectionString`: + +```ts +// filepath: src/index.ts +import { Client } from "pg"; + +export default { + async fetch( + request: Request, + env: Env, + ctx: ExecutionContext, + ): Promise { + // Create a new client instance for each request. + const client = new Client({ + connectionString: env.HYPERDRIVE.connectionString, + }); + + try { + // Connect to the database + await client.connect(); + console.log("Connected to PostgreSQL database"); + + // Perform a simple query + const result = await client.query("SELECT * FROM pg_tables"); + + // Clean up the client after the response is returned, before the Worker is killed + env.waitUntil(client.end()); + + return Response.json({ + success: true, + result: result.rows, + }); + } catch (error: any) { + console.error("Database error:", error.message); + } + }, +}; +``` + +:::note + +The minimum version of `node-postgres` required for Hyperdrive is `8.13.0`. + +::: diff --git a/src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx b/src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx new file mode 100644 index 00000000000000..d58756148042f8 --- /dev/null +++ b/src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx @@ -0,0 +1,60 @@ +--- +{} +--- + +import { Render } from "~/components"; + +Install [Postgres.js](https://github.com/porsager/postgres): + +```sh +# Postgres.js 3.4.5 or later is recommended +npm install postgres +``` + +Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: + + + +Create a Worker that connects to your PostgreSQL database via Hyperdrive: + +```ts +// filepath: src/index.ts +import postgres from "postgres"; + +export default { + async fetch( + request: Request, + env: Env, + ctx: ExecutionContext, + ): Promise { + // Create a database client that connects to your database via Hyperdrive + // using the Hyperdrive credentials + const sql = postgres(env.HYPERDRIVE.connectionString, { + // Limit the connections for the Worker request to 5 due to Workers' limits on concurrent external connections + max: 5, + // If you are not using array types in your Postgres schema, disable `fetch_types` to avoid an additional round-trip (unnecessary latency) + fetch_types: false, + }); + + try { + // A very simple test query + const result = await sql`select * from pg_tables`; + + // Clean up the client, ensuring we don't kill the worker before that is + // completed. + ctx.waitUntil(sql.end()); + + // Return result rows as JSON + return Response.json({ success: true, result: result }); + } catch (e: any) { + console.error("Database error:", e.message); + } + }, +} satisfies ExportedHandler; +``` + +:::note + +The minimum version of `postgres-js` required for Hyperdrive is `3.4.5`. + +::: diff --git a/src/content/partials/hyperdrive/use-postgresjs-to-make-query.mdx b/src/content/partials/hyperdrive/use-postgresjs-to-make-query.mdx deleted file mode 100644 index 4d7782c6fc8bdf..00000000000000 --- a/src/content/partials/hyperdrive/use-postgresjs-to-make-query.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -{} ---- - -Install the Postgres.js driver: - -```sh -npm install postgres -``` - -Create a new `sql` instance and pass the Hyperdrive parameters: - -```ts -import postgres from "postgres"; - -export interface Env { - // If you set another name in the Wrangler configuration file as the value for 'binding', - // replace "HYPERDRIVE" with the variable name you defined. - HYPERDRIVE: Hyperdrive; -} - -export default { - async fetch(request: Request, env: Env, ctx: ExecutionContext) { - // NOTE: if `prepare: false` is passed when connecting, performance will - // be slower but still correctly supported. - const sql = postgres( - env.HYPERDRIVE.connectionString, - { - // Workers limit the number of concurrent external connections, so be sure to limit - // the size of the local connection pool that postgres.js may establish. - max: 5, - - // If you are using array types in your Postgres schema, it is necessary to fetch - // type information to correctly de/serialize them. However, if you are not using - // those, disabling this will save you an extra round-trip every time you connect. - fetch_types: false, - }, - ); - - try { - // A very simple test query - const result = await sql`select * from pg_tables LIMIT 10`; - - // Clean up the client, ensuring we don't kill the worker before that is - // completed. - ctx.waitUntil(sql.end()); - - // Return result rows as JSON - return Response.json({ result: result }); - } catch (e) { - console.log(e); - return Response.json({ error: e.message }, { status: 500 }); - } - }, -} satisfies ExportedHandler; -``` \ No newline at end of file From d4906268bc012713f687ae8c2395b03dce8e2291 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 1 May 2025 11:31:33 +0100 Subject: [PATCH 13/24] Apply suggestions from code review --- .../mysql-database-providers/planetscale.mdx | 4 +-- .../drizzle-orm.mdx | 35 +++++++++--------- .../postgres-database-providers/neon.mdx | 5 +-- .../postgres-database-providers/supabase.mdx | 4 +-- .../drizzle-orm.mdx | 35 +++++++++--------- .../prisma-orm.mdx | 36 +++++++++---------- 6 files changed, 53 insertions(+), 66 deletions(-) diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale.mdx index 4b458c840b9074..eee8792368b9e2 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale.mdx @@ -30,9 +30,7 @@ With the host, database name, username and password, you can now create a Hyperd :::note -When connection to a Planetscale database with Hyperdrive, you should use a driver like [node-postgres (pg)](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/) or [Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/) -to connect directly to the underlying database instead of the [Planetscale serverless driver](https://planetscale.com/docs/tutorials/planetscale-serverless-driver). Hyperdrive is optimized for database access for Workers and -will perform global connection pooling and fast query routing by connecting directly to your database. +When connecting to a Planetscale database with Hyperdrive, you should use a driver like [node-postgres (pg)](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/) or [Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/) to connect directly to the underlying database instead of the [Planetscale serverless driver](https://planetscale.com/docs/tutorials/planetscale-serverless-driver). Hyperdrive is optimized for database access for Workers and will perform global connection pooling and fast query routing by connecting directly to your database. ::: diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx index 08471eee6e31cc..41ab339107d315 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx @@ -17,7 +17,7 @@ import { Render } from "~/components"; - A MySQL database - A [Hyperdrive configuration to your MySQL database](/hyperdrive/get-started/#3-connect-hyperdrive-to-a-database) -## Installation +## 1. Install Drizzle Install the Drizzle ORM and its dependencies such as the [mysql2](https://github.com/sidorares/node-mysql2) driver: @@ -31,11 +31,11 @@ Add the required Node.js compatibility flags and Hyperdrive binding to your `wra -## Configure Drizzle +## 2. Configure Drizzle -### Define a schema +### 2.1 Define a schema -With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL. Here's how to define a users table: +With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL. Here is how to define a `users` table: ```ts // src/schema.ts @@ -49,10 +49,9 @@ export const users = mysqlTable("users", { }); ``` -### Connect Drizzle ORM to the database with Hyperdrive +### 2.2 Connect Drizzle ORM to the database with Hyperdrive -Use your the credentials of your Hyperdrive configuration for your database when using the -Drizzle ORM within your Worker project as such: +Use your the credentials of your Hyperdrive configuration for your database when using the Drizzle ORM within your Worker project as shown: ```ts // src/db/schema.ts @@ -86,21 +85,18 @@ export default { } satisfies ExportedHandler; ``` -### Configure Drizzle-Kit for migrations (optional) +### 2.3 Configure Drizzle-Kit for migrations (optional) -You can generate and run SQL migrations on your database based on your schema -using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/mysql-new) for additional guidance. +You can generate and run SQL migrations on your database based on your schema using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/mysql-new) for additional guidance. -1. Create a `.env` file and add your database connection string. The Drizzle Kit CLI will use - this connection string to create and apply the migrations. +1. Create a `.env` file and add your database connection string. The Drizzle Kit CLI will use this connection string to create and apply the migrations. ```toml # Replace with your direct database connection string DATABASE_URL='mysql://user:password@db-host.cloud/database-name' ``` -2. Create a `drizzle.config.ts` file in the root of your project to configure Drizzle Kit - and add the following content: +2. Create a `drizzle.config.ts` file in the root of your project to configure Drizzle Kit and add the following content: ```ts import 'dotenv/config'; @@ -115,8 +111,9 @@ using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs }); ``` -3. Generate the migration file for your database according to your schema files and apply the migrations to your database. - `bash -npx drizzle-kit generate -npx drizzle-kit migrate -` +3. Generate the migration file for your database according to your schema files and apply the migrations to your database. + + ```bash + npx drizzle-kit generate + npx drizzle-kit migrate + ``` diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon.mdx index 59548df05e224d..53b3d68f8c6d92 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon.mdx @@ -31,10 +31,7 @@ With both the connection string and the password, you can now create a Hyperdriv :::note -When connection to a Neon database with Hyperdrive, you should use a driver like [node-postgres (pg)](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/) or [Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/) -to connect directly to the underlying database -instead of the [Neon serverless driver](https://neon.tech/docs/serverless/serverless-driver). Hyperdrive is optimized for database access for Workers and -will perform global connection pooling and fast query routing by connecting directly to your database. +When connecting to a Neon database with Hyperdrive, you should use a driver like [node-postgres (pg)](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/) or [Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/) to connect directly to the underlying database instead of the [Neon serverless driver](https://neon.tech/docs/serverless/serverless-driver). Hyperdrive is optimized for database access for Workers and will perform global connection pooling and fast query routing by connecting directly to your database. ::: diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase.mdx index 8cc51478f244a5..df8d1184c0c4c7 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase.mdx @@ -34,9 +34,7 @@ With a database user, password, database endpoint (hostname and port) and databa :::note -When connection to a Supabase database with Hyperdrive, you should use a driver like [node-postgres (pg)](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/) or [Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/) -to connect directly to the underlying database instead of the [Supabase JavaScript client](https://github.com/supabase/supabase-js). Hyperdrive is optimized for database access for Workers and -will perform global connection pooling and fast query routing by connecting directly to your database. +When connecting to a Supabase database with Hyperdrive, you should use a driver like [node-postgres (pg)](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/) or [Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/) to connect directly to the underlying database instead of the [Supabase JavaScript client](https://github.com/supabase/supabase-js). Hyperdrive is optimized for database access for Workers and will perform global connection pooling and fast query routing by connecting directly to your database. ::: diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx index ca68c7537b4ad8..5b15558e26a07c 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx @@ -15,7 +15,7 @@ meta: - A PostgreSQL database - A [Hyperdrive configuration to your PostgreSQL database](/hyperdrive/get-started/#3-connect-hyperdrive-to-a-database) -## Installation +## 1. Install Drizzle Install the Drizzle ORM and its dependencies such as the [postgres](https://github.com/porsager/postgres) driver: @@ -29,11 +29,11 @@ Add the required Node.js compatibility flags and Hyperdrive binding to your `wra -## Configure Drizzle +## 2. Configure Drizzle -### Define a schema +### 2.1 Define a schema -With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL. Here's how to define a users table: +With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL. Here is how to define a `users` table: ```ts // src/db/schema.ts @@ -47,10 +47,9 @@ export const users = pgTable("users", { }); ``` -### Connect Drizzle ORM to the database with Hyperdrive +### 2.2 Connect Drizzle ORM to the database with Hyperdrive -Use your Hyperdrive configuration for your database when using the -Drizzle ORM within your Worker project as such: +Use your Hyperdrive configuration for your database when using the Drizzle ORM within your Worker project as shown: ```ts // src/index.ts @@ -81,21 +80,18 @@ export default { } satisfies ExportedHandler; ``` -### Configure Drizzle-Kit for migrations (optional) +### 2.3 Configure Drizzle-Kit for migrations (optional) -You can generate and run SQL migrations on your database based on your schema -using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/postgresql) for additional guidance. +You can generate and run SQL migrations on your database based on your schema using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/postgresql) for additional guidance. -1. Create a `.env` file and add your database connection string. The Drizzle Kit CLI will use - this connection string to create and apply the migrations. +1. Create a `.env` file and add your database connection string. The Drizzle Kit CLI will use this connection string to create and apply the migrations. - ```toml - # Replace with your direct database connection string - DATABASE_URL='postgres://user:password@db-host.cloud/database-name' - ``` + ```toml + # Replace with your direct database connection string + DATABASE_URL='postgres://user:password@db-host.cloud/database-name' + ``` -2. Create a `drizzle.config.ts` file in the root of your project to configure Drizzle Kit - and add the following content: +2. Create a `drizzle.config.ts` file in the root of your project to configure Drizzle Kit and add the following content: ```ts import "dotenv/config"; @@ -110,7 +106,8 @@ using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs }); ``` -3. Generate the migration file for your database according to your schema files and apply the migrations to your database. +3. Generate the migration file for your database according to your schema files and apply the migrations to your database. + ```bash npx drizzle-kit generate npx drizzle-kit migrate diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx index 6bb8ce1452432b..8dbb7970e87f6b 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx @@ -15,7 +15,7 @@ meta: - A PostgreSQL database - A [Hyperdrive configuration to your PostgreSQL database](/hyperdrive/get-started/#3-connect-hyperdrive-to-a-database) -## Installation +## 1. Install Prisma Install Prisma, its dependencies, node-postgres driver, and generate the client: @@ -28,9 +28,9 @@ Add the required Node.js compatibility flags and Hyperdrive binding to your `wra -## Configure Prisma +## 2. Configure Prisma -### Define a schema +### 2.1 Define a schema With Prisma, we define the schema using the Prisma Schema Language (PSL). Create a `prisma/schema.prisma` file in your project: @@ -63,7 +63,7 @@ After defining your schema, generate the Prisma Client: npx prisma generate ``` -### Connect Prisma to the database with Hyperdrive +### 2.2 Connect Prisma to the database with Hyperdrive Use your Hyperdrive configuration for your database when using Prisma with the node-postgres adapter within your Worker project: @@ -122,23 +122,23 @@ export default { } satisfies ExportedHandler; ``` -### Prisma Migrations (optional) +### 2.3 Migrate Prisma (optional) You can use Prisma Migrate to create and manage your database schema: -1. Create a `.env` file in your project root with your direct database connection string: - `toml -DATABASE_URL='postgresql://user:password@db-host.cloud/database-name' -` +1. Create a `.env` file in your project root with your direct database connection string: + ```toml + DATABASE_URL='postgresql://user:password@db-host.cloud/database-name' + ``` -2. Initialize and generate your first migration (for development only): - `sh -npx prisma migrate dev --name init -` +2. Initialize and generate your first migration (for development only): + ```sh + npx prisma migrate dev --name init + ``` - This will create SQL migration files in the `prisma/migrations` directory and apply them to your database. + This will create SQL migration files in the `prisma/migrations` directory and apply them to your database. -3. For production environments, apply migrations without generating new ones: - `sh -npx prisma migrate deploy -` +3. For production environments, apply migrations without generating new ones: + ```sh + npx prisma migrate deploy + ``` From 9297e73a3a0dbfe432a51ff1a9aaf5a984ff2014 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 1 May 2025 11:33:08 +0100 Subject: [PATCH 14/24] Apply suggestions from code review --- .../postgres-drivers-and-libraries/prisma-orm.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx index 8dbb7970e87f6b..63620c6c271aad 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx @@ -139,6 +139,6 @@ You can use Prisma Migrate to create and manage your database schema: This will create SQL migration files in the `prisma/migrations` directory and apply them to your database. 3. For production environments, apply migrations without generating new ones: - ```sh + ```sh npx prisma migrate deploy ``` From 28676b204512189a34a023463f4ccf88eaa371d1 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 1 May 2025 14:03:50 +0100 Subject: [PATCH 15/24] Specifying product when rendering partials --- .../mysql-drivers-and-libraries/drizzle-orm.mdx | 2 +- .../postgres-drivers-and-libraries/drizzle-orm.mdx | 2 +- .../postgres-drivers-and-libraries/prisma-orm.mdx | 2 +- src/content/partials/hyperdrive/use-mysql-to-make-query.mdx | 2 +- src/content/partials/hyperdrive/use-mysql2-to-make-query.mdx | 2 +- .../partials/hyperdrive/use-node-postgres-to-make-query.mdx | 2 +- .../partials/hyperdrive/use-postgres-js-to-make-query.mdx | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx index 41ab339107d315..89b2814ffb8c5b 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx @@ -29,7 +29,7 @@ npm i -D drizzle-kit tsx @types/node Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: - + ## 2. Configure Drizzle diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx index 5b15558e26a07c..fb225025ee573d 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx @@ -27,7 +27,7 @@ npm i -D drizzle-kit tsx @types/node Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: - + ## 2. Configure Drizzle diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx index 63620c6c271aad..64a609e5bc9f72 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx @@ -26,7 +26,7 @@ npm install prisma @types/pg --save-dev Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: - + ## 2. Configure Prisma diff --git a/src/content/partials/hyperdrive/use-mysql-to-make-query.mdx b/src/content/partials/hyperdrive/use-mysql-to-make-query.mdx index be408a719f7c35..5b59fd54b3a420 100644 --- a/src/content/partials/hyperdrive/use-mysql-to-make-query.mdx +++ b/src/content/partials/hyperdrive/use-mysql-to-make-query.mdx @@ -12,7 +12,7 @@ npm install mysql Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: - + Create a new connection and pass the Hyperdrive parameters: diff --git a/src/content/partials/hyperdrive/use-mysql2-to-make-query.mdx b/src/content/partials/hyperdrive/use-mysql2-to-make-query.mdx index a492d5ab756c3a..5860e8d38ce76c 100644 --- a/src/content/partials/hyperdrive/use-mysql2-to-make-query.mdx +++ b/src/content/partials/hyperdrive/use-mysql2-to-make-query.mdx @@ -13,7 +13,7 @@ npm install mysql2 Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: - + Create a new `connection` instance and pass the Hyperdrive parameters: diff --git a/src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx b/src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx index 39aff3e24c5158..65764a562e3de4 100644 --- a/src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx +++ b/src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx @@ -12,7 +12,7 @@ npm install pg Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: - + Create a new `Client` instance and pass the Hyperdrive `connectionString`: diff --git a/src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx b/src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx index d58756148042f8..1479e01fde2ac4 100644 --- a/src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx +++ b/src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx @@ -13,7 +13,7 @@ npm install postgres Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: - + Create a Worker that connects to your PostgreSQL database via Hyperdrive: From 721b41ea1e697b025e2b18b4cbd8299911f73df4 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 1 May 2025 14:21:11 +0100 Subject: [PATCH 16/24] Importing Render components --- .../postgres-drivers-and-libraries/drizzle-orm.mdx | 2 ++ .../postgres-drivers-and-libraries/prisma-orm.mdx | 2 ++ 2 files changed, 4 insertions(+) diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx index fb225025ee573d..250d5a3d184d1d 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx @@ -7,6 +7,8 @@ meta: title: Using Drizzle ORM with Hyperdrive for PostgreSQL --- +import { Render } from "~/components"; + [Drizzle ORM](https://orm.drizzle.team/) is a lightweight TypeScript ORM with a focus on type safety. This example demonstrates how to use Drizzle ORM with PostgreSQL via Cloudflare Hyperdrive in a Workers application. ## Prerequisites diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx index 64a609e5bc9f72..35666426485d87 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx @@ -7,6 +7,8 @@ meta: title: Using Prisma ORM with Hyperdrive for PostgreSQL --- +import { Render } from "~/components"; + [Prisma](https://www.prisma.io/) is a modern ORM that provides a type-safe API for working with databases. This example demonstrates how to use Prisma ORM with PostgreSQL via Cloudflare Hyperdrive in a Workers application. ## Prerequisites From 0410c7ba344b8ab11bed49c8251a615bbc07dcf3 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 1 May 2025 14:43:40 +0100 Subject: [PATCH 17/24] Fixing invalid links --- .../reference/supported-databases-and-features.mdx | 10 +++++----- .../docs/workers/databases/connecting-to-databases.mdx | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/hyperdrive/reference/supported-databases-and-features.mdx b/src/content/docs/hyperdrive/reference/supported-databases-and-features.mdx index de7057d8f63bdf..1f86026ee9b4b0 100644 --- a/src/content/docs/hyperdrive/reference/supported-databases-and-features.mdx +++ b/src/content/docs/hyperdrive/reference/supported-databases-and-features.mdx @@ -18,18 +18,18 @@ The following table shows which database engines and/or specific database provid ## Supported database providers -Hyperdrive supports managed Postgres and MySQL databases provided by various providers, including AWS, Azure, and GCP. Refer to [Examples](/hyperdrive/examples/connect-to-postgres/) to see how to connect to various database providers. +Hyperdrive supports managed Postgres and MySQL databases provided by various providers, including AWS, Azure, and GCP. Refer to [Examples](/hyperdrive/examples/connect-to-postgres/) to see how to connect to various database providers. Hyperdrive also supports databases that are compatible with the Postgres or MySQL protocol. The following is a non-exhaustive list of Postgres or MySQL-compatible database providers: | Database Engine | Supported | Known supported versions | Details | | --------------- | --------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ | -| AWS Aurora | ✅ | All | Postgres-compatible and MySQL-compatible. Refer to AWS Aurora examples for [MySQL](/hyperdrive/examples/connect-to-mysql/aws-rds-aurora/) and [Postgres](/hyperdrive/examples/connect-to-postgres/aws-rds-aurora/). | +| AWS Aurora | ✅ | All | Postgres-compatible and MySQL-compatible. Refer to AWS Aurora examples for [MySQL](/hyperdrive/examples/connect-to-mysql/mysql-database-providers/aws-rds-aurora/) and [Postgres](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora/). | | Neon | ✅ | All | Neon currently runs Postgres 15.x | | Supabase | ✅ | All | Supabase currently runs Postgres 15.x | -| Timescale | ✅ | All | See the [Timescale guide](/hyperdrive/examples/connect-to-postgres/timescale/) to connect. | -| Materialize | ✅ | All | Postgres-compatible. Refer to the [Materialize guide](/hyperdrive/examples/connect-to-postgres/materialize/) to connect. | -| CockroachDB | ✅ | All | Postgres-compatible. Refer to the [CockroachDB](/hyperdrive/examples/connect-to-postgres/cockroachdb/) guide to connect. | +| Timescale | ✅ | All | See the [Timescale guide](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale/) to connect. | +| Materialize | ✅ | All | Postgres-compatible. Refer to the [Materialize guide](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/materialize/) to connect. | +| CockroachDB | ✅ | All | Postgres-compatible. Refer to the [CockroachDB](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb/) guide to connect. | | Planetscale | ✅ | All | Planetscale currently runs MySQL 8.x | | MariaDB | ✅ | All | MySQL-compatible. | diff --git a/src/content/docs/workers/databases/connecting-to-databases.mdx b/src/content/docs/workers/databases/connecting-to-databases.mdx index 674fd21b3e944f..a35b55a8a17c8d 100644 --- a/src/content/docs/workers/databases/connecting-to-databases.mdx +++ b/src/content/docs/workers/databases/connecting-to-databases.mdx @@ -26,7 +26,7 @@ D1 is Cloudflare's own SQL-based, serverless database. It is optimized for globa Traditional databases use SQL drivers that use [TCP sockets](/workers/runtime-apis/tcp-sockets/) to connect to the database. TCP is the de-facto standard protocol that many databases, such as PostgreSQL and MySQL, use for client connectivity. These drivers are also widely compatible with your preferred ORM libraries and query builders. -This also includes serverless databases that are PostgreSQL or MySQL-compatible like [Supabase](/hyperdrive/examples/connect-to-postgres/neon/), [Neon](/hyperdrive/examples/connect-to-postgres/neon/) or [PlanetScale](/hyperdrive/examples/connect-to-mysql/planetscale/), +This also includes serverless databases that are PostgreSQL or MySQL-compatible like [Supabase](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase/), [Neon](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon/) or [PlanetScale](/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale/), which can be connected to using both native [TCP sockets and Hyperdrive](/hyperdrive/) or [serverless HTTP-based drivers](/workers/databases/connecting-to-databases/#serverless-databases) (detailed below). | Database | Integration | Library or Driver | Connection Method | From 03cb1cc270415552f484d421e96a88b274cbcf72 Mon Sep 17 00:00:00 2001 From: Thomas Gauvin Date: Fri, 2 May 2025 10:38:14 -0400 Subject: [PATCH 18/24] adjust per discord feedback --- .../examples/connect-to-postgres/index.mdx | 2 +- .../drizzle-orm.mdx | 48 ++++++++++++------- .../use-node-postgres-to-make-query.mdx | 4 ++ .../use-postgres-js-to-make-query.mdx | 2 + 4 files changed, 37 insertions(+), 19 deletions(-) diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/index.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/index.mdx index 21284205d1cae3..5448a53f6c80a7 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/index.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/index.mdx @@ -44,7 +44,7 @@ Hyperdrive uses Workers [TCP socket support](/workers/runtime-apis/tcp-sockets/# | Driver | Documentation | Minimum Version Required | Notes | | ---------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Postgres.js (**recommended**) | [Postgres.js documentation](https://github.com/porsager/postgres) | `postgres@3.4.4` | Supported in both Workers & Pages. | +| Postgres.js | [Postgres.js documentation](https://github.com/porsager/postgres) | `postgres@3.4.4` | Supported in both Workers & Pages. | | node-postgres - `pg` | [node-postgres - `pg` documentation](https://node-postgres.com/) | `pg@8.13.0` | `8.11.4` introduced a bug with URL parsing and will not work. `8.11.5` fixes this. Requires `compatibility_flags = ["nodejs_compat"]` and `compatibility_date = "2024-09-23"` - refer to [Node.js compatibility](/workers/runtime-apis/nodejs). Requires wrangler `3.78.7` or later. | | Drizzle | [Drizzle documentation](https://orm.drizzle.team/) | `0.26.2`^ | | | Kysely | [Kysely documentation](https://kysely.dev/) | `0.26.3`^ | | diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx index 250d5a3d184d1d..350bc38b3cb83e 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx @@ -29,7 +29,7 @@ npm i -D drizzle-kit tsx @types/node Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: - + ## 2. Configure Drizzle @@ -66,7 +66,12 @@ export interface Env { export default { async fetch(request, env, ctx): Promise { // Create a database client with postgres.js driver connected via Hyperdrive - const sql = postgres(env.HYPERDRIVE.connectionString); + const sql = postgres(env.HYPERDRIVE.connectionString, { + // Limit the connections for the Worker request to 5 due to Workers' limits on concurrent external connections + max: 5, + // If you are not using array types in your Postgres schema, disable `fetch_types` to avoid an additional round-trip (unnecessary latency) + fetch_types: false, + }); // Create the Drizzle client with the postgres.js connection const db = drizzle(sql); @@ -82,6 +87,13 @@ export default { } satisfies ExportedHandler; ``` +:::note + +You may use [node-postgres](https://orm.drizzle.team/docs/get-started-postgresql#node-postgres) or [Postgres.js](https://orm.drizzle.team/docs/get-started-postgresql#postgresjs) +when using Drizzle ORM. Both are supported and compatible. + +::: + ### 2.3 Configure Drizzle-Kit for migrations (optional) You can generate and run SQL migrations on your database based on your schema using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/postgresql) for additional guidance. @@ -95,22 +107,22 @@ You can generate and run SQL migrations on your database based on your schema us 2. Create a `drizzle.config.ts` file in the root of your project to configure Drizzle Kit and add the following content: - ```ts - import "dotenv/config"; - import { defineConfig } from "drizzle-kit"; - export default defineConfig({ - out: "./drizzle", - schema: "./src/db/schema.ts", - dialect: "postgresql", - dbCredentials: { - url: process.env.DATABASE_URL!, - }, - }); - ``` + ```ts + import "dotenv/config"; + import { defineConfig } from "drizzle-kit"; + export default defineConfig({ + out: "./drizzle", + schema: "./src/db/schema.ts", + dialect: "postgresql", + dbCredentials: { + url: process.env.DATABASE_URL!, + }, + }); + ``` 3. Generate the migration file for your database according to your schema files and apply the migrations to your database. - ```bash - npx drizzle-kit generate - npx drizzle-kit migrate - ``` + ```bash + npx drizzle-kit generate + npx drizzle-kit migrate + ``` diff --git a/src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx b/src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx index 65764a562e3de4..c3f471fd1c92d1 100644 --- a/src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx +++ b/src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx @@ -8,6 +8,8 @@ Install the `node-postgres` driver: ```sh npm install pg +# If using TypeScript +npm i --save-dev @types/pg ``` Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: @@ -48,6 +50,8 @@ export default { }); } catch (error: any) { console.error("Database error:", error.message); + + return Response.error(); } }, }; diff --git a/src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx b/src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx index 1479e01fde2ac4..600d78d51bc682 100644 --- a/src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx +++ b/src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx @@ -48,6 +48,8 @@ export default { return Response.json({ success: true, result: result }); } catch (e: any) { console.error("Database error:", e.message); + + return Response.error(); } }, } satisfies ExportedHandler; From 249d6d60f8385e6172edc692b765526dd8d1e52e Mon Sep 17 00:00:00 2001 From: Thomas Gauvin Date: Fri, 2 May 2025 10:53:39 -0400 Subject: [PATCH 19/24] more nits --- public/__redirects | 18 ++- .../prisma-orm.mdx | 146 ------------------ 2 files changed, 17 insertions(+), 147 deletions(-) delete mode 100644 src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx diff --git a/public/__redirects b/public/__redirects index 22184a143de584..77bb7b1de3951d 100644 --- a/public/__redirects +++ b/public/__redirects @@ -1709,7 +1709,23 @@ /hyperdrive/examples/timescale/ /hyperdrive/examples/connect-to-postgres/timescale/ 301 /hyperdrive/examples/xata/ /hyperdrive/examples/connect-to-postgres/xata/ 301 /hyperdrive/examples/fly/ /hyperdrive/examples/connect-to-postgres/fly/ 301 - +/hyperdrive/examples/aws-rds-aurora/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora/ 301 +/hyperdrive/examples/azure/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/azure/ 301 +/hyperdrive/examples/cockroachdb/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb/ 301 +/hyperdrive/examples/digital-ocean/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/digital-ocean/ 301 +/hyperdrive/examples/google-cloud-sql/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/google-cloud-sql/ 301 +/hyperdrive/examples/materialize/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/materialize/ 301 +/hyperdrive/examples/neon/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon/ 301 +/hyperdrive/examples/nile/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/nile/ 301 +/hyperdrive/examples/pgedge/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/pgedge/ 301 +/hyperdrive/examples/supabase/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase/ 301 +/hyperdrive/examples/timescale/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale/ 301 +/hyperdrive/examples/xata/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/xata/ 301 +/hyperdrive/examples/fly/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/fly/ 301 +/hyperdrive/examples/connect-to-mysql/planetscale/ /hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale/ 301 +/hyperdrive/examples/connect-to-mysql/azure/ /hyperdrive/examples/connect-to-mysql/mysql-database-providers/azure/ 301 +/hyperdrive/examples/connect-to-mysql/google-cloud-sql/ /hyperdrive/examples/connect-to-mysql/mysql-database-providers/google-cloud-sql/ 301 +/hyperdrive/examples/connect-to-mysql/aws-rds-aurora/ /hyperdrive/examples/connect-to-mysql/mysql-database-providers/aws-rds-aurora/ 301 /hyperdrive/reference/supported-databases/ /hyperdrive/reference/supported-databases-and-features/ 301 /hyperdrive/configuration/connect-to-postgres/ /hyperdrive/examples/connect-to-postgres/ 301 diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx deleted file mode 100644 index 35666426485d87..00000000000000 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx +++ /dev/null @@ -1,146 +0,0 @@ ---- -pcx_content_type: example -title: Prisma ORM -sidebar: - order: 4 -meta: - title: Using Prisma ORM with Hyperdrive for PostgreSQL ---- - -import { Render } from "~/components"; - -[Prisma](https://www.prisma.io/) is a modern ORM that provides a type-safe API for working with databases. This example demonstrates how to use Prisma ORM with PostgreSQL via Cloudflare Hyperdrive in a Workers application. - -## Prerequisites - -- A Cloudflare account with Workers access -- A PostgreSQL database -- A [Hyperdrive configuration to your PostgreSQL database](/hyperdrive/get-started/#3-connect-hyperdrive-to-a-database) - -## 1. Install Prisma - -Install Prisma, its dependencies, node-postgres driver, and generate the client: - -```sh -npm install @prisma/client @prisma/adapter-pg pg -npm install prisma @types/pg --save-dev -``` - -Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: - - - -## 2. Configure Prisma - -### 2.1 Define a schema - -With Prisma, we define the schema using the Prisma Schema Language (PSL). Create a `prisma/schema.prisma` file in your project: - -```prisma -// prisma/schema.prisma -generator client { - provider = "prisma-client-js" - previewFeatures = ["driverAdapters"] - output = "../node_modules/.prisma/client" -} - -datasource db { - provider = "postgresql" - url = env("DATABASE_URL") -} - -model User { - id Int @id @default(autoincrement()) - name String - email String @unique - createdAt DateTime @default(now()) @map("created_at") - - @@map("users") -} -``` - -After defining your schema, generate the Prisma Client: - -```sh -npx prisma generate -``` - -### 2.2 Connect Prisma to the database with Hyperdrive - -Use your Hyperdrive configuration for your database when using Prisma with the node-postgres adapter within your Worker project: - -```ts -// src/index.ts -import { PrismaClient } from "@prisma/client"; -import { PrismaPg } from "@prisma/adapter-pg"; -import pg from "pg"; - -pg.defaults.poolSize = 5; - -export interface Env { - HYPERDRIVE: Hyperdrive; -} - -export default { - async fetch(request, env, ctx): Promise { - // Create a connection pool using node-postgres - const pool = new pg.Pool({ - connectionString: env.HYPERDRIVE.connectionString, - }); - - // Create Prisma adapter with the node-postgres pool - const adapter = new PrismaPg(pool); - - // Initialize Prisma Client with the adapter - const prisma = new PrismaClient({ adapter }); - - try { - // Sample query to get all users - const users = await prisma.user.findMany(); - - // Clean up the connection - ctx.waitUntil(Promise.all([prisma.$disconnect(), pool.end()])); - - return Response.json(users); - } catch (error) { - console.error("Database error:", error); - - // Ensure we clean up the connection - ctx.waitUntil( - Promise.all([ - prisma - .$disconnect() - .catch((e) => console.error("Error disconnecting Prisma:", e)), - pool.end().catch((e) => console.error("Error closing pool:", e)), - ]), - ); - - return Response.json( - { error: "Database connection failed" }, - { status: 500 }, - ); - } - }, -} satisfies ExportedHandler; -``` - -### 2.3 Migrate Prisma (optional) - -You can use Prisma Migrate to create and manage your database schema: - -1. Create a `.env` file in your project root with your direct database connection string: - ```toml - DATABASE_URL='postgresql://user:password@db-host.cloud/database-name' - ``` - -2. Initialize and generate your first migration (for development only): - ```sh - npx prisma migrate dev --name init - ``` - - This will create SQL migration files in the `prisma/migrations` directory and apply them to your database. - -3. For production environments, apply migrations without generating new ones: - ```sh - npx prisma migrate deploy - ``` From 02df4beeb023d4fac12fbff24a09cee8855a6ec3 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Tue, 6 May 2025 15:20:20 +0100 Subject: [PATCH 20/24] Pushing changes to Postgres Drizzle ORM tutorial --- .../drizzle-orm.mdx | 86 ++++++++++++++----- 1 file changed, 63 insertions(+), 23 deletions(-) diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx index 350bc38b3cb83e..3f2971d68c1166 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx @@ -7,7 +7,7 @@ meta: title: Using Drizzle ORM with Hyperdrive for PostgreSQL --- -import { Render } from "~/components"; +import { Render, Steps } from "~/components"; [Drizzle ORM](https://orm.drizzle.team/) is a lightweight TypeScript ORM with a focus on type safety. This example demonstrates how to use Drizzle ORM with PostgreSQL via Cloudflare Hyperdrive in a Workers application. @@ -33,27 +33,35 @@ Add the required Node.js compatibility flags and Hyperdrive binding to your `wra ## 2. Configure Drizzle -### 2.1 Define a schema +### 2.1. Define a schema -With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL. Here is how to define a `users` table: +With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL. -```ts -// src/db/schema.ts -import { pgTable, serial, varchar, timestamp } from "drizzle-orm/pg-core"; + +1. Create a folder `/db/` in `/src/`. +2. Create a `schema.ts` file. +3. In `schema.ts`, define a `users` table as shown below. -export const users = pgTable("users", { - id: serial("id").primaryKey(), - name: varchar("name", { length: 255 }).notNull(), - email: varchar("email", { length: 255 }).notNull().unique(), - createdAt: timestamp("created_at").defaultNow(), -}); -``` + ```ts title="src/db/schema.ts" + // src/db/schema.ts + import { pgTable, serial, varchar, timestamp } from "drizzle-orm/pg-core"; + + export const users = pgTable("users", { + id: serial("id").primaryKey(), + name: varchar("name", { length: 255 }).notNull(), + email: varchar("email", { length: 255 }).notNull().unique(), + createdAt: timestamp("created_at").defaultNow(), + }); + ``` + + +### 2.2. Connect Drizzle ORM to the database with Hyperdrive -### 2.2 Connect Drizzle ORM to the database with Hyperdrive +Use your Hyperdrive configuration for your database when using the Drizzle ORM. -Use your Hyperdrive configuration for your database when using the Drizzle ORM within your Worker project as shown: +Populate your `index.ts` file as shown below. -```ts +```ts title="src/index.ts" // src/index.ts import { drizzle } from "drizzle-orm/postgres-js"; import postgres from "postgres"; @@ -88,26 +96,29 @@ export default { ``` :::note - You may use [node-postgres](https://orm.drizzle.team/docs/get-started-postgresql#node-postgres) or [Postgres.js](https://orm.drizzle.team/docs/get-started-postgresql#postgresjs) when using Drizzle ORM. Both are supported and compatible. - ::: -### 2.3 Configure Drizzle-Kit for migrations (optional) +If your database is empty, continue to step [2.3. Configure Drizzle-Kit for migration](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm/#23-configure-drizzle-kit-for-migrations-optional). -You can generate and run SQL migrations on your database based on your schema using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/postgresql) for additional guidance. +### 2.3. Configure Drizzle-Kit for migrations (optional) -1. Create a `.env` file and add your database connection string. The Drizzle Kit CLI will use this connection string to create and apply the migrations. +You can generate and run SQL migrations on your database based on your schema using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/postgresql-new) for additional guidance. - ```toml + +1. Create a `.env` file in your `/src/` folder, and add your database connection string. The Drizzle Kit CLI will use this connection string to create and apply the migrations. + + ```toml title="src/.env" + # src/.env # Replace with your direct database connection string DATABASE_URL='postgres://user:password@db-host.cloud/database-name' ``` 2. Create a `drizzle.config.ts` file in the root of your project to configure Drizzle Kit and add the following content: - ```ts + ```ts title="drizzle.config.ts" + // drizzle.config.ts import "dotenv/config"; import { defineConfig } from "drizzle-kit"; export default defineConfig({ @@ -122,7 +133,36 @@ You can generate and run SQL migrations on your database based on your schema us 3. Generate the migration file for your database according to your schema files and apply the migrations to your database. + Run the following two commands: + ```bash npx drizzle-kit generate + ``` + ```bash output + No config path provided, using default 'drizzle.config.ts' + Reading config file '/Users/junlee/tutorials/jun-hyperdrive-drizzle/drizzle.config.ts' + 1 tables + users 4 columns 0 indexes 0 fks + + [✓] Your SQL migration file ➜ drizzle/0000_mysterious_queen_noir.sql 🚀 + ``` + + ```bash npx drizzle-kit migrate ``` + ```bash output + No config path provided, using default 'drizzle.config.ts' + Reading config file '/Users/junlee/tutorials/jun-hyperdrive-drizzle/drizzle.config.ts' + Using 'postgres' driver for database querying + ``` + + +## 3. Deploy your Worker + +Deploy your Worker. + +```bash +npx wrangler deploy +``` + + \ No newline at end of file From 0517e7bb2dd0979201eacb2311042647bb1ed827 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 7 May 2025 18:16:57 +0100 Subject: [PATCH 21/24] Editing MySQL version of the tutorial --- .../drizzle-orm.mdx | 130 ++++++++++++------ .../drizzle-orm.mdx | 8 +- 2 files changed, 91 insertions(+), 47 deletions(-) diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx index 89b2814ffb8c5b..a43bc010ac26c5 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx @@ -7,7 +7,7 @@ meta: title: Using Drizzle ORM with Hyperdrive for MySQL --- -import { Render } from "~/components"; +import { Render, Steps } from "~/components"; [Drizzle ORM](https://orm.drizzle.team/) is a lightweight TypeScript ORM with a focus on type safety. This example demonstrates how to use Drizzle ORM with MySQL via Cloudflare Hyperdrive in a Workers application. @@ -33,33 +33,45 @@ Add the required Node.js compatibility flags and Hyperdrive binding to your `wra ## 2. Configure Drizzle -### 2.1 Define a schema +### 2.1. Define a schema -With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL. Here is how to define a `users` table: +With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL. -```ts -// src/schema.ts -import { mysqlTable, int, varchar, timestamp } from "drizzle-orm/mysql-core"; + +1. Create a folder `/db/` in `/src/`. +2. Create a `schema.ts` file. +3. In `schema.ts`, define a `users` table as shown below. -export const users = mysqlTable("users", { - id: int("id").primaryKey().autoincrement(), - name: varchar("name", { length: 255 }).notNull(), - email: varchar("email", { length: 255 }).notNull().unique(), - createdAt: timestamp("created_at").defaultNow(), -}); -``` + ```ts title="src/db/schema.ts" + // src/schema.ts + import { mysqlTable, int, varchar, timestamp } from "drizzle-orm/mysql-core"; + + export const users = mysqlTable("users", { + id: int("id").primaryKey().autoincrement(), + name: varchar("name", { length: 255 }).notNull(), + email: varchar("email", { length: 255 }).notNull().unique(), + createdAt: timestamp("created_at").defaultNow(), + }); + ``` + + +### 2.2. Connect Drizzle ORM to the database with Hyperdrive -### 2.2 Connect Drizzle ORM to the database with Hyperdrive +Use your the credentials of your Hyperdrive configuration for your database when using the Drizzle ORM. -Use your the credentials of your Hyperdrive configuration for your database when using the Drizzle ORM within your Worker project as shown: +Populate your `index.ts` file as shown below. -```ts -// src/db/schema.ts +```ts title="src/index.ts" +// src/index.ts import { drizzle } from "drizzle-orm/mysql2"; import { createConnection } from "mysql2"; import { users } from "./db/schema"; +export interface Env { + HYPERDRIVE: Hyperdrive; + } + export default { async fetch(request, env, ctx): Promise { // Create a connection using the mysql2 driver with the Hyperdrive credentials (only accessible from your Worker). @@ -85,35 +97,67 @@ export default { } satisfies ExportedHandler; ``` -### 2.3 Configure Drizzle-Kit for migrations (optional) - -You can generate and run SQL migrations on your database based on your schema using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/mysql-new) for additional guidance. - -1. Create a `.env` file and add your database connection string. The Drizzle Kit CLI will use this connection string to create and apply the migrations. +If your database is empty, continue to step [2.3. Configure Drizzle-Kit for migration](/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm/#23-configure-drizzle-kit-for-migrations-optional). - ```toml - # Replace with your direct database connection string - DATABASE_URL='mysql://user:password@db-host.cloud/database-name' - ``` +### 2.3. Configure Drizzle-Kit for migrations (optional) -2. Create a `drizzle.config.ts` file in the root of your project to configure Drizzle Kit and add the following content: +You can generate and run SQL migrations on your database based on your schema using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/mysql-new) for additional guidance. - ```ts - import 'dotenv/config'; - import { defineConfig } from 'drizzle-kit'; - export default defineConfig({ - out: './drizzle', - schema: './src/db/schema.ts', - dialect: 'mysql', - dbCredentials: { - url: process.env.DATABASE_URL!, - }, - }); - ``` + +1. Create a `.env` file in the root folder of your project, and add your database connection string. The Drizzle Kit CLI will use this connection string to create and apply the migrations. + + ```toml title=".env" + # .env + # Replace with your direct database connection string + DATABASE_URL='mysql://user:password@db-host.cloud/database-name' + ``` + +2. Create a `drizzle.config.ts` file in the root folder of your project to configure Drizzle Kit and add the following content: + + ```ts title="drizzle.config.ts" + import 'dotenv/config'; + import { defineConfig } from 'drizzle-kit'; + export default defineConfig({ + out: './drizzle', + schema: './src/db/schema.ts', + dialect: 'mysql', + dbCredentials: { + url: process.env.DATABASE_URL!, + }, + }); + ``` 3. Generate the migration file for your database according to your schema files and apply the migrations to your database. - ```bash - npx drizzle-kit generate - npx drizzle-kit migrate - ``` + ```bash + npx drizzle-kit generate + ``` + ```bash output + No config path provided, using default 'drizzle.config.ts' + Reading config file '/Users/junlee/tutorials/jun-hyperdrive-drizzle-mysql/drizzle.config.ts' + Reading schema files: + /Users/junlee/tutorials/jun-hyperdrive-drizzle-mysql/src/db/schema.ts + + 1 tables + users 4 columns 0 indexes 0 fks + + [✓] Your SQL migration file ➜ drizzle/0000_daffy_rhodey.sql 🚀 + ``` + ```bash + npx drizzle-kit migrate + ``` + ```bash output + No config path provided, using default 'drizzle.config.ts' + Reading config file '/Users/junlee/tutorials/jun-hyperdrive-drizzle-mysql/drizzle.config.ts' + ``` + + +## 3. Deploy your Worker + +Deploy your Worker. + +```bash +npx wrangler deploy +``` + + \ No newline at end of file diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx index 3f2971d68c1166..3a607271033a1f 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx @@ -107,15 +107,15 @@ If your database is empty, continue to step [2.3. Configure Drizzle-Kit for migr You can generate and run SQL migrations on your database based on your schema using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/postgresql-new) for additional guidance. -1. Create a `.env` file in your `/src/` folder, and add your database connection string. The Drizzle Kit CLI will use this connection string to create and apply the migrations. +1. Create a `.env` file the root folder of your project, and add your database connection string. The Drizzle Kit CLI will use this connection string to create and apply the migrations. - ```toml title="src/.env" - # src/.env + ```toml title=".env" + # .env # Replace with your direct database connection string DATABASE_URL='postgres://user:password@db-host.cloud/database-name' ``` -2. Create a `drizzle.config.ts` file in the root of your project to configure Drizzle Kit and add the following content: +2. Create a `drizzle.config.ts` file in the root folder of your project to configure Drizzle Kit and add the following content: ```ts title="drizzle.config.ts" // drizzle.config.ts From 955db1e97304c1c50aaf2d0c4c0035c288a0a0e8 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 8 May 2025 16:55:40 +0100 Subject: [PATCH 22/24] Adding note about when to run the optional migration step. --- .../mysql-drivers-and-libraries/drizzle-orm.mdx | 14 +++++++++----- .../postgres-drivers-and-libraries/drizzle-orm.mdx | 12 ++++++++---- 2 files changed, 17 insertions(+), 9 deletions(-) diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx index a43bc010ac26c5..99cb93fd7439f0 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx @@ -97,10 +97,14 @@ export default { } satisfies ExportedHandler; ``` -If your database is empty, continue to step [2.3. Configure Drizzle-Kit for migration](/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm/#23-configure-drizzle-kit-for-migrations-optional). - ### 2.3. Configure Drizzle-Kit for migrations (optional) +:::note +You need to set up the tables in your database so that Drizzle ORM can make queries that work. + +If you have already set it up (for example, if another user has applied the schema to your database), or if you are starting to use Drizzle ORM and the schema matches what already exists in your database, then you do not need to run the migration. +::: + You can generate and run SQL migrations on your database based on your schema using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/mysql-new) for additional guidance. @@ -134,9 +138,9 @@ You can generate and run SQL migrations on your database based on your schema us ``` ```bash output No config path provided, using default 'drizzle.config.ts' - Reading config file '/Users/junlee/tutorials/jun-hyperdrive-drizzle-mysql/drizzle.config.ts' + Reading config file 'drizzle.config.ts' Reading schema files: - /Users/junlee/tutorials/jun-hyperdrive-drizzle-mysql/src/db/schema.ts + /src/db/schema.ts 1 tables users 4 columns 0 indexes 0 fks @@ -148,7 +152,7 @@ You can generate and run SQL migrations on your database based on your schema us ``` ```bash output No config path provided, using default 'drizzle.config.ts' - Reading config file '/Users/junlee/tutorials/jun-hyperdrive-drizzle-mysql/drizzle.config.ts' + Reading config file 'drizzle.config.ts' ``` diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx index 3a607271033a1f..53605c7085db2c 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx @@ -100,10 +100,14 @@ You may use [node-postgres](https://orm.drizzle.team/docs/get-started-postgresql when using Drizzle ORM. Both are supported and compatible. ::: -If your database is empty, continue to step [2.3. Configure Drizzle-Kit for migration](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm/#23-configure-drizzle-kit-for-migrations-optional). - ### 2.3. Configure Drizzle-Kit for migrations (optional) +:::note +You need to set up the tables in your database so that Drizzle ORM can make queries that work. + +If you have already set it up (for example, if another user has applied the schema to your database), or if you are starting to use Drizzle ORM and the schema matches what already exists in your database, then you do not need to run the migration. +::: + You can generate and run SQL migrations on your database based on your schema using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/postgresql-new) for additional guidance. @@ -140,7 +144,7 @@ You can generate and run SQL migrations on your database based on your schema us ``` ```bash output No config path provided, using default 'drizzle.config.ts' - Reading config file '/Users/junlee/tutorials/jun-hyperdrive-drizzle/drizzle.config.ts' + Reading config file 'drizzle.config.ts' 1 tables users 4 columns 0 indexes 0 fks @@ -152,7 +156,7 @@ You can generate and run SQL migrations on your database based on your schema us ``` ```bash output No config path provided, using default 'drizzle.config.ts' - Reading config file '/Users/junlee/tutorials/jun-hyperdrive-drizzle/drizzle.config.ts' + Reading config file 'drizzle.config.ts' Using 'postgres' driver for database querying ``` From ed882f48ea92e23e3f2d117282f6d3455e1daf67 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 8 May 2025 17:02:07 +0100 Subject: [PATCH 23/24] Removing outdated redirects to avoid breaking --- public/__redirects | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/public/__redirects b/public/__redirects index 77bb7b1de3951d..19afc2851589ef 100644 --- a/public/__redirects +++ b/public/__redirects @@ -1690,25 +1690,13 @@ /hyperdrive/learning/how-hyperdrive-works/ /hyperdrive/configuration/how-hyperdrive-works/ 301 /hyperdrive/learning/connect-to-postgres/ /hyperdrive/examples/connect-to-postgres/ 301 /hyperdrive/learning/query-caching/ /hyperdrive/configuration/query-caching/ 301 -/hyperdrive/learning/troubleshooting/ /hyperdrive/reference/troubleshooting/ 301 +/hyperdrive/learning/troubleshooting/ /hyperdrive/observability/troubleshooting/ 301 /hyperdrive/changelog/ /hyperdrive/platform/release-notes/ 301 /hyperdrive/platform/changelog/ /hyperdrive/platform/release-notes/ 301 /hyperdrive/learning/ /hyperdrive/configuration/ 301 /hyperdrive/reference/metrics/ /hyperdrive/observability/metrics/ 301 /hyperdrive/reference/troubleshooting/ /hyperdrive/observability/troubleshooting/ 301 -/hyperdrive/examples/aws-rds-aurora/ /hyperdrive/examples/connect-to-postgres/aws-rds-aurora/ 301 -/hyperdrive/examples/azure/ /hyperdrive/examples/connect-to-postgres/azure/ 301 -/hyperdrive/examples/cockroachdb/ /hyperdrive/examples/connect-to-postgres/cockroachdb/ 301 -/hyperdrive/examples/digital-ocean/ /hyperdrive/examples/connect-to-postgres/digital-ocean/ 301 -/hyperdrive/examples/google-cloud-sql/ /hyperdrive/examples/connect-to-postgres/google-cloud-sql/ 301 -/hyperdrive/examples/materialize/ /hyperdrive/examples/connect-to-postgres/materialize/ 301 -/hyperdrive/examples/neon/ /hyperdrive/examples/connect-to-postgres/neon/ 301 -/hyperdrive/examples/nile/ /hyperdrive/examples/connect-to-postgres/nile/ 301 -/hyperdrive/examples/pgedge/ /hyperdrive/examples/connect-to-postgres/pgedge/ 301 -/hyperdrive/examples/supabase/ /hyperdrive/examples/connect-to-postgres/supabase/ 301 -/hyperdrive/examples/timescale/ /hyperdrive/examples/connect-to-postgres/timescale/ 301 -/hyperdrive/examples/xata/ /hyperdrive/examples/connect-to-postgres/xata/ 301 -/hyperdrive/examples/fly/ /hyperdrive/examples/connect-to-postgres/fly/ 301 + /hyperdrive/examples/aws-rds-aurora/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora/ 301 /hyperdrive/examples/azure/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/azure/ 301 /hyperdrive/examples/cockroachdb/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb/ 301 @@ -1722,6 +1710,7 @@ /hyperdrive/examples/timescale/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale/ 301 /hyperdrive/examples/xata/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/xata/ 301 /hyperdrive/examples/fly/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/fly/ 301 + /hyperdrive/examples/connect-to-mysql/planetscale/ /hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale/ 301 /hyperdrive/examples/connect-to-mysql/azure/ /hyperdrive/examples/connect-to-mysql/mysql-database-providers/azure/ 301 /hyperdrive/examples/connect-to-mysql/google-cloud-sql/ /hyperdrive/examples/connect-to-mysql/mysql-database-providers/google-cloud-sql/ 301 From f1444e2ee78d7cc7cf127e24cac3362dffe013a2 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Fri, 9 May 2025 10:58:47 +0100 Subject: [PATCH 24/24] Adding missing redirects. --- public/__redirects | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/public/__redirects b/public/__redirects index 19afc2851589ef..c245dcc9410022 100644 --- a/public/__redirects +++ b/public/__redirects @@ -1711,6 +1711,20 @@ /hyperdrive/examples/xata/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/xata/ 301 /hyperdrive/examples/fly/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/fly/ 301 +/hyperdrive/examples/connect-to-postgres/aws-rds-aurora/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora/ 301 +/hyperdrive/examples/connect-to-postgres/azure/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/azure/ 301 +/hyperdrive/examples/connect-to-postgres/cockroachdb/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb/ 301 +/hyperdrive/examples/connect-to-postgres/digital-ocean/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/digital-ocean/ 301 +/hyperdrive/examples/connect-to-postgres/fly/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/fly/ 301 +/hyperdrive/examples/connect-to-postgres/google-cloud-sql/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/google-cloud-sql/ 301 +/hyperdrive/examples/connect-to-postgres/materialize/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/materialize/ 301 +/hyperdrive/examples/connect-to-postgres/neon/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon/ 301 +/hyperdrive/examples/connect-to-postgres/nile/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/nile/ 301 +/hyperdrive/examples/connect-to-postgres/pgedge/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/pgedge/ 301 +/hyperdrive/examples/connect-to-postgres/supabase/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase/ 301 +/hyperdrive/examples/connect-to-postgres/timescale/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale/ 301 +/hyperdrive/examples/connect-to-postgres/xata/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/xata/ 301 + /hyperdrive/examples/connect-to-mysql/planetscale/ /hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale/ 301 /hyperdrive/examples/connect-to-mysql/azure/ /hyperdrive/examples/connect-to-mysql/mysql-database-providers/azure/ 301 /hyperdrive/examples/connect-to-mysql/google-cloud-sql/ /hyperdrive/examples/connect-to-mysql/mysql-database-providers/google-cloud-sql/ 301