Skip to content
Cloudflare Docs

Xata

Xata ↗ is a PostgreSQL database platform designed to help developers operate and scale databases with enhanced productivity and performance. Xata provides features like instant copy-on-write database branches, zero-downtime schema changes, data anonymization, AI-powered performance monitoring, and BYOC.

Refer to the full Xata documentation ↗.

To connect to Xata using Hyperdrive, follow these steps:

1. Allow Hyperdrive access

You can connect Hyperdrive to any existing Xata PostgreSQL database with the connection string provided by Xata.

Xata dashboard

To retrieve your connection string from the Xata dashboard:

  1. Go to the Xata dashboard ↗.
  2. Select the database you want to connect to.
  3. Copy the PostgreSQL connection string.

Refer to the full Xata documentation ↗.

2. Create a database configuration

To configure Hyperdrive, you will need:

  • The IP address (or hostname) and port of your database.
  • The database username (for example, hyperdrive-demo) you configured in a previous step.
  • The password associated with that username.
  • The name of the database you want Hyperdrive to connect to. For example, postgres.

Hyperdrive accepts the combination of these parameters in the common connection string format used by database drivers:

postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name

Most database providers will provide a connection string you can directly copy-and-paste directly into Hyperdrive.

To create a Hyperdrive configuration with the Cloudflare dashboard:

  1. In the Cloudflare dashboard, go to the Hyperdrive page.

    Go to Hyperdrive

  2. Select Create Configuration.

  3. Fill out the form, including the connection string.

  4. Select Create.

3. Use Hyperdrive from your Worker

Install the node-postgres driver:

Terminal window
npm i pg@>8.16.3

If using TypeScript, install the types package:

Terminal window
npm i -D @types/pg

Add the required Node.js compatibility flags and Hyperdrive binding to your wrangler.jsonc file:

{
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "compatibility_date": "2024-09-23",
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<your-hyperdrive-id-here>"
    }
  ]
}

Create a new Client instance and pass the Hyperdrive connectionString:

TypeScript
// filepath: src/index.ts
import { Client } from "pg";


export default {
  async fetch(
    request: Request,
    env: Env,
    ctx: ExecutionContext,
  ): Promise<Response> {
    // 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");


      return Response.json({
        success: true,
        result: result.rows,
      });
    } catch (error: any) {
      console.error("Database error:", error.message);


      new Response("Internal error occurred", { status: 500 });
    }
  },
};

Next steps