diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/planetscale-postgres.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/planetscale-postgres.mdx new file mode 100644 index 000000000000000..e4c557410e84572 --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/planetscale-postgres.mdx @@ -0,0 +1,42 @@ +--- +type: example +summary: Connect Hyperdrive to a PlanetScale PostgreSQL database. +pcx_content_type: example +title: PlanetScale +sidebar: + order: 8 +description: Connect Hyperdrive to a PlanetScale PostgreSQL database. +--- + +import { Render } from "~/components"; + +This example shows you how to connect Hyperdrive to a [PlanetScale](https://planetscale.com/) PostgreSQL database. + +## 1. Allow Hyperdrive access + +You can connect Hyperdrive to any existing PlanetScale PostgreSQL database by creating a new role (optional) and retrieving a connection string to your database. + +### PlanetScale Dashboard + +1. Go to the [**PlanetScale dashboard**](https://app.planetscale.com/) and select the database you wish to connect to. +2. Click **Connect**. +3. Create a new role for your Hyperdrive configuration (recommended): + 1. Ensure the minimum required permissions for Hyperdrive to read and write data to your tables: + - **pg_read_all_data**: Read data from all tables, views, and sequences + - **pg_write_all_data**: Write data to all tables, views, and sequences + 2. Click **Create role**. +4. Note the user, the password, the database host, and the database name (or `postgres` as the default database). You will need these to create a database configuration in Hyperdrive. + +With the host, database name, username and password, you can now create a Hyperdrive database configuration. + +## 2. Create a database configuration + + + +:::note + +When connecting to a PlanetScale PostgreSQL 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/reference/supported-databases-and-features.mdx b/src/content/docs/hyperdrive/reference/supported-databases-and-features.mdx index 1f86026ee9b4b07..8c757b75675bf4a 100644 --- a/src/content/docs/hyperdrive/reference/supported-databases-and-features.mdx +++ b/src/content/docs/hyperdrive/reference/supported-databases-and-features.mdx @@ -30,7 +30,7 @@ Hyperdrive also supports databases that are compatible with the Postgres or MySQ | 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 | +| Planetscale | ✅ | All | PlanetScale provides MySQL-compatible and PostgreSQL databases | | MariaDB | ✅ | All | MySQL-compatible. | ## Supported TLS (SSL) modes diff --git a/src/content/docs/workers/databases/connecting-to-databases.mdx b/src/content/docs/workers/databases/connecting-to-databases.mdx index e42cc1a1f35bcd5..436708df548cc51 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/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/), +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 (either [MySQL](/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale/) or [PostgreSQL](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/planetscale-postgres/)), 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 | @@ -45,22 +45,21 @@ Since a connection must be re-established on every Worker invocation, this adds ### Serverless databases -Serverless databases may provide direct connection to the underlying database, or provide HTTP-based proxies and drivers (also known as serverless drivers). +Serverless databases may provide direct connection to the underlying database, or provide HTTP-based proxies and drivers (also known as serverless drivers). -For PostgreSQL and MySQL serverless databases, you can connect to the underlying database directly using the native database drivers and ORMs you are familiar with, using Hyperdrive (recommended) to speed up connectivity and pool database connections. When you use Hyperdrive, your connection pool is managed across all of Cloudflare regions and optimized for usage from Workers. +For PostgreSQL and MySQL serverless databases, you can connect to the underlying database directly using the native database drivers and ORMs you are familiar with, using Hyperdrive (recommended) to speed up connectivity and pool database connections. When you use Hyperdrive, your connection pool is managed across all of Cloudflare regions and optimized for usage from Workers. -You can also use serverless driver libraries to connect to the HTTP-based proxies managed by the database provider. These may also provide connection pooling for traditional SQL databases and reduce the amount of roundtrips needed to establish a secure connection, similarly to Hyperdrive. - -| Database | Library or Driver | Connection Method | -| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------- | -| [PlanetScale](https://planetscale.com/blog/introducing-the-planetscale-serverless-driver-for-javascript) | [Hyperdrive](/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale), [@planetscale/database](https://github.com/planetscale/database-js) | [mysql2](/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql2/) or [mysql](/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql/), or API via client library | -| [Supabase](https://github.com/supabase/supabase/tree/master/examples/with-cloudflare-workers) | [Hyperdrive](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase/), [@supabase/supabase-js](https://github.com/supabase/supabase-js) | [node-postgres](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/),[Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/), or API via client library | -| [Prisma](https://www.prisma.io/docs/guides/deployment/deployment-guides/deploying-to-cloudflare-workers) | [prisma](https://github.com/prisma/prisma) | API via client library | -| [Neon](https://blog.cloudflare.com/neon-postgres-database-from-workers/) | [Hyperdrive](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon/), [@neondatabase/serverless](https://neon.tech/blog/serverless-driver-for-postgres/) | [node-postgres](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/),[Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/), or API via client library | -| [Hasura](https://hasura.io/blog/building-applications-with-cloudflare-workers-and-hasura-graphql-engine/) | API | GraphQL API via fetch() | -| [Upstash Redis](https://blog.cloudflare.com/cloudflare-workers-database-integration-with-upstash/) | [@upstash/redis](https://github.com/upstash/upstash-redis) | API via client library | -| [TiDB Cloud](https://docs.pingcap.com/tidbcloud/integrate-tidbcloud-with-cloudflare) | [@tidbcloud/serverless](https://github.com/tidbcloud/serverless-js) | API via client library | +You can also use serverless driver libraries to connect to the HTTP-based proxies managed by the database provider. These may also provide connection pooling for traditional SQL databases and reduce the amount of roundtrips needed to establish a secure connection, similarly to Hyperdrive. +| Database | Library or Driver | Connection Method | +| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [PlanetScale](https://planetscale.com/blog/introducing-the-planetscale-serverless-driver-for-javascript) | [Hyperdrive (MySQL)](/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale), [Hyperdrive (PostgreSQL)](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/planetscale-postgres/), [@planetscale/database](https://github.com/planetscale/database-js) | [mysql2](/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql2/), [mysql](/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql/), [node-postgres](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/), [Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/), or API via client library | +| [Supabase](https://github.com/supabase/supabase/tree/master/examples/with-cloudflare-workers) | [Hyperdrive](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase/), [@supabase/supabase-js](https://github.com/supabase/supabase-js) | [node-postgres](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/),[Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/), or API via client library | +| [Prisma](https://www.prisma.io/docs/guides/deployment/deployment-guides/deploying-to-cloudflare-workers) | [prisma](https://github.com/prisma/prisma) | API via client library | +| [Neon](https://blog.cloudflare.com/neon-postgres-database-from-workers/) | [Hyperdrive](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon/), [@neondatabase/serverless](https://neon.tech/blog/serverless-driver-for-postgres/) | [node-postgres](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/),[Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/), or API via client library | +| [Hasura](https://hasura.io/blog/building-applications-with-cloudflare-workers-and-hasura-graphql-engine/) | API | GraphQL API via fetch() | +| [Upstash Redis](https://blog.cloudflare.com/cloudflare-workers-database-integration-with-upstash/) | [@upstash/redis](https://github.com/upstash/upstash-redis) | API via client library | +| [TiDB Cloud](https://docs.pingcap.com/tidbcloud/integrate-tidbcloud-with-cloudflare) | [@tidbcloud/serverless](https://github.com/tidbcloud/serverless-js) | API via client library | Once you have installed the necessary packages, use the APIs provided by these packages to connect to your database and perform operations on it. Refer to detailed links for service-specific instructions. diff --git a/src/content/docs/workers/databases/third-party-integrations/planetscale.mdx b/src/content/docs/workers/databases/third-party-integrations/planetscale.mdx index 72d3b15a142e1b6..07ac435297b3d23 100644 --- a/src/content/docs/workers/databases/third-party-integrations/planetscale.mdx +++ b/src/content/docs/workers/databases/third-party-integrations/planetscale.mdx @@ -5,7 +5,7 @@ title: PlanetScale import { Render, PackageManagers, Tabs, TabItem } from "~/components"; -[PlanetScale](https://planetscale.com/) is a MySQL-compatible platform that makes databases infinitely scalable, easier and safer to manage. +[PlanetScale](https://planetscale.com/) is a database platform that provides MySQL-compatible and PostgreSQL databases, making them more scalable, easier and safer to manage. :::note diff --git a/src/content/partials/hyperdrive/planetscale-partial.mdx b/src/content/partials/hyperdrive/planetscale-partial.mdx index d7d1e505f699519..bed84899102c7e0 100644 --- a/src/content/partials/hyperdrive/planetscale-partial.mdx +++ b/src/content/partials/hyperdrive/planetscale-partial.mdx @@ -6,7 +6,7 @@ import { Render } from "~/components"; ## 1. Allow Hyperdrive access -You can connect Hyperdrive to any existing PlanetScale database by creating a new user and fetching your database connection string. +You can connect Hyperdrive to any existing PlanetScale MySQL-compatible database by creating a new user and fetching your database connection string. ### Planetscale Dashboard