ntanduy/cloudflare-d1-database

Easy configuration and setup for D1 Database connections in Laravel.

v0.2.8 2025-12-04 09:37 UTC

Requires

• php: ^8.2
• doctrine/dbal: ^3.0|^4.0
• illuminate/cache: ^10.0|^11.0|^12.0
• illuminate/contracts: ^10.0|^11.0|^12.0
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0
• saloonphp/laravel-plugin: ^3.5
• saloonphp/saloon: ^3.10

Requires (Dev)

• mockery/mockery: ^1.6
• orchestra/testbench: ^8.0|^9.0|^10.0
• pestphp/pest: ^2.35|^3.0

Suggests

• ext-pdo: Extending the PDO driver for Cloudflare D1 is requireds.

MIT

• TanDuy03

• database
• laravel
• cloudflare
• d1
• TanDuy03

README

Integrate Cloudflare bindings into your PHP/Laravel application.

🎯 Requirements

• PHP: >= 8.2
• Laravel: 10.x, 11.x, or 12.x

✨ Features

This package offers support for:

• Cloudflare D1

🚀 Installation

composer require ntanduy/cloudflare-d1-database

👏 Usage

Integrate Cloudflare D1 with Laravel

Add a new connection in your config/database.php file:

'connections' => [
    'd1' => [
        'driver' => 'd1',
        'prefix' => '',
        'database' => env('CLOUDFLARE_D1_DATABASE_ID', ''),
        'api' => 'https://api.cloudflare.com/client/v4',
        'auth' => [
            'token' => env('CLOUDFLARE_TOKEN', ''),
            'account_id' => env('CLOUDFLARE_ACCOUNT_ID', ''),
        ],
        'timeout' => env('D1_TIMEOUT', 10),
        'connect_timeout' => env('D1_CONNECT_TIMEOUT', 5),
        'retries' => env('D1_RETRIES', 2),
        'retry_delay' => env('D1_RETRY_DELAY', 100),
    ],
]

Next, configure your Cloudflare credentials in the .env file:

CLOUDFLARE_TOKEN=your_api_token
CLOUDFLARE_ACCOUNT_ID=your_account_id
CLOUDFLARE_D1_DATABASE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Configuration Options

Option	Default	Description
timeout	10	Request timeout in seconds
connect_timeout	5	Connection timeout in seconds
retries	2	Max retry attempts on 5xx/429 errors
retry_delay	100	Base delay between retries (ms)

For production, you can tune these via .env:

D1_TIMEOUT=10
D1_CONNECT_TIMEOUT=5
D1_RETRIES=2
D1_RETRY_DELAY=100

The d1 driver will forward PDO queries to the Cloudflare D1 API to execute them.

⚠️ Limitations

• No real transactions: D1 doesn't support BEGIN/COMMIT/ROLLBACK. The driver simulates transaction state for Laravel compatibility, but queries are executed immediately.
• REST API latency: Each query is an HTTP request (~100-500ms). For low-latency needs, consider using Cloudflare Workers with native D1 bindings.

🌱 Testing

Start the built-in Worker to simulate the Cloudflare API:

cd tests/worker
npm ci
npm run start

In a separate terminal, run the tests:

vendor/bin/pest

🤝 Contributing

Please see CONTRIBUTING for details.

🔒 Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

🎉 Credits

• TanDuy03
• All Contributors