External Databases

External Databases

Connect your agents to any database, anywhere, instantly. Cloudflare Hyperdrive accelerates queries to your existing databases by intelligently caching connections and data at the edge. Perfect for agents that need to access PostgreSQL, MySQL, and other external databases with dramatically reduced latency.

Key Features

  • Zero-Configuration Acceleration: Automatic query optimization and connection pooling
  • Universal Compatibility: Works with PostgreSQL, MySQL, and any database with connection strings
  • Geographic Distribution: Smart caching across Cloudflare's global network
  • Connection Pooling: Efficient database connection management at scale
  • Query Caching: Intelligent caching of frequently accessed data

Getting Started

Wrangler Configuration

First, add Hyperdrive configuration in your wrangler.json:

json

Hello World Database Query

Create a simple agent that queries an external PostgreSQL database:

typescript

Agent Integration

Access external databases from your agent:

typescript

MCP Integration

External databases are powerful tools for MCP servers to access enterprise data.

typescript

TypeScript API Reference

You can access the external database via the env of the Agent or MCP Tool

typescript

Database Connection

EXTERNAL_DB.prepare(query: string): PreparedStatement
Creates a prepared statement for secure parameterized queries. Always use prepared statements to prevent SQL injection attacks.

preparedStatement.bind(...params: any[]): PreparedStatement
Binds parameters to the prepared statement placeholders (?). Parameters are automatically escaped for security.

preparedStatement.first(): Promise<Record<string, any> | null>
Executes the query and returns the first row, or null if no results found.

preparedStatement.all(): Promise<{ results: Record<string, any>[], meta: QueryMeta }>
Executes the query and returns all matching rows with metadata about the query execution.

preparedStatement.run(): Promise<{ success: boolean, meta: QueryMeta }>
Executes INSERT, UPDATE, or DELETE queries and returns execution metadata including affected row count.

Transaction Support

EXTERNAL_DB.batch(statements: PreparedStatement[]): Promise<BatchResult[]>
Executes multiple prepared statements as a single atomic transaction. All statements succeed or all fail together.

EXTERNAL_DB.exec(sql: string): Promise<ExecResult>
Executes raw SQL for DDL operations like CREATE TABLE. Use sparingly and never with user input.

Examples

Customer Relationship Management Agent

typescript

Best Practices

Query Optimization

Use prepared statements and efficient queries to maximize Hyperdrive's caching benefits:

typescript

Connection Management

Leverage Hyperdrive's automatic connection pooling and caching:

typescript

Limitations & Considerations

  • Database Compatibility: Supports PostgreSQL, MySQL, and any database with standard connection strings
  • Query Limits: Individual queries limited to 1MB result size
  • Connection Pooling: Automatic pooling with configurable limits
  • Caching: Intelligent caching of frequently accessed data
  • Geographic Distribution: Best performance when database and edge locations are geographically close

Related Services

  • Databases - Serverless SQL databases for primary storage
  • Memory Store (KV) - Cache frequently accessed external database results
  • Analytics Storage - Track external database query performance
  • Queues - Queue external database operations for batch processing

Official Documentation