Hyperdrive

The Hyperdrive component lets you add a Cloudflare Hyperdrive to your app.

Hyperdrive can connect Workers to PostgreSQL and MySQL databases. Set origin.scheme to "postgres" or "mysql".

PostgreSQL example

sst.config.ts

const hyperdrive = new sst.cloudflare.Hyperdrive("PostgresDatabase", {
  origin: {
    database: "app",
    host: "db.example.com",
    password: "secret",
    scheme: "postgres",
    user: "postgres",
  },
})

Check out the PlanetScale or the AWS RDS Postgres examples for a complete guide.

MySQL example

sst.config.ts

const hyperdrive = new sst.cloudflare.Hyperdrive("MySQLDatabase", {
  origin: {
    database: "app",
    host: "db.example.com",
    password: "secret",
    scheme: "mysql",
    user: "root",
  },
})

Link to a worker

You can link Hyperdrive to a worker.

sst.config.ts

new sst.cloudflare.Worker("MyWorker", {
  handler: "./index.ts",
  link: [hyperdrive],
  url: true,
})

Once linked, you can use the SDK to access the Hyperdrive binding in your worker.

index.ts

import postgres from "postgres"
import { Resource } from "sst/resource"

const sql = postgres(Resource.PostgresDatabase.connectionString)

It also works with MySQL:

index.ts

import mysql from "mysql2/promise"
import { Resource } from "sst/resource"

const db = await mysql.createConnection(Resource.MySQLDatabase.connectionString)

---

Constructor

new Hyperdrive(name, args, opts?)

Parameters

• name string

• args HyperdriveArgs

• opts? ComponentResourceOptions

HyperdriveArgs

caching?

Type Input<false | Object>

• maxAge?

• staleWhileRevalidate?

Configure caching for SQL queries sent through Hyperdrive.

Tip

Caching is enabled by default. Pass false to disable it.

Disable caching.

{
  caching: false
}

Customize cache durations.

{
  caching: {
    maxAge: "30 minutes",
    staleWhileRevalidate: "30 seconds"
  }
}

caching.maxAge?

Type Input<${number} minute | ${number} minutes | ${number} hour | ${number} hours | ${number} second | ${number} seconds> | undefined

Default “60 seconds”

The maximum duration items should persist in the cache. Can be up to 1 hour.

{
  caching: {
    maxAge: "30 minutes"
  }
}

caching.staleWhileRevalidate?

Type Input<${number} minute | ${number} minutes | ${number} hour | ${number} hours | ${number} second | ${number} seconds> | undefined

Default “15 seconds”

The duration the cache may serve a stale response while it’s being revalidated.

{
  caching: {
    staleWhileRevalidate: "30 seconds"
  }
}

connectionLimit?

Type Input<number>

The (soft) maximum number of connections the Hyperdrive is allowed to make to the origin database.

mtls?

Type Input<Object>

• caCertificateId?

• mtlsCertificateId?

• sslmode?

Configure mTLS authentication when connecting to the origin database.

mtls.caCertificateId?

Type Input<string> | undefined

Define CA certificate ID obtained after uploading CA cert.

mtls.mtlsCertificateId?

Type Input<string> | undefined

Define mTLS certificate ID obtained after uploading client cert.

mtls.sslmode?

Type Input<string> | undefined

Set SSL mode to ‘require’, ‘verify-ca’, or ‘verify-full’ to verify the CA.

origin

Type Input<Object>

• accessClientId?

• accessClientSecret?

• database

• host

• password

• port?

• scheme

• user

The connection details for the origin database Hyperdrive connects to.

origin.accessClientId?

Type Input<string>

Defines the Client ID of the Access token to use when connecting to the origin database.

origin.accessClientSecret?

Type Input<string>

Defines the Client Secret of the Access Token to use when connecting to the origin database. The API never returns this write-only value.

origin.database

Type Input<string>

Set the name of your origin database.

origin.host

Type Input<string>

Defines the host (hostname or IP) of your origin database.

origin.password

Type Input<string>

Set the password needed to access your origin database. The API never returns this write-only value.

origin.port?

Type Input<number>

Defines the port of your origin database. Defaults to 5432 for PostgreSQL or 3306 for MySQL if not specified.

origin.scheme

Type Input<“postgres” | “mysql”>

Specifies the URL scheme used to connect to your origin database.

origin.user

Type Input<string>

Set the user of your origin database.

transform?

Type Object

• hyperdrive?

Transform how this component creates its underlying resources.

transform.hyperdrive?

Type HyperdriveConfigArgs | (args: HyperdriveConfigArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Hyperdrive config resource.

Properties

id

Type Output<string>

The generated ID of the Hyperdrive config.

name

Type Output<string>

The generated name of the Hyperdrive config.

nodes

Type Object

• hyperdrive

The underlying resources this component creates.

nodes.hyperdrive

Type HyperdriveConfig

The Cloudflare Hyperdrive config.

SDK

Use the SDK in your runtime to interact with your infrastructure.

---

Links

This is accessible through the Resource object in the SDK.

• id string

  The generated ID of the Hyperdrive config.

Bindings

When you link Hyperdrive to a worker, the Hyperdrive binding will be available in the worker and you can use its connectionString to connect with a PostgreSQL or MySQL client.

index.ts

import postgres from "postgres"
import { Resource } from "sst"

const sql = postgres(Resource.PostgresDatabase.connectionString)

For MySQL:

index.ts

import mysql from "mysql2/promise"
import { Resource } from "sst"

const db = await mysql.createConnection(Resource.MySQLDatabase.connectionString)