CloudflareD1.NET 1.0.1

CloudflareD1.NET

A complete .NET adapter for Cloudflare D1 - the serverless SQL database running on Cloudflare's edge network. This library provides seamless integration with Cloudflare's D1 database, supporting both local SQLite development and remote D1 production deployments.

✨ Features

• 🚀 Full D1 API Support - Complete implementation of Cloudflare D1 REST API
• 🏠 Local Development Mode - Use local SQLite for development without any setup
• 🔄 Seamless Switching - Easy toggle between local and remote modes
• 📦 Batch Operations - Execute multiple queries as a single transaction
• ⏱️ Time Travel Queries - Query historical data (D1 feature)
• 🛠️ Database Management - Create, list, and delete D1 databases programmatically
• 💉 Dependency Injection - Full ASP.NET Core DI integration
• 🔐 Flexible Authentication - Support for API Token and API Key authentication
• 📝 Comprehensive Logging - Built-in logging with ILogger support
• 🎯 Type-Safe - Strongly typed with full XML documentation
• ⚡ Async/Await - Modern async patterns throughout
• 🧪 Well Tested - Comprehensive test coverage

📦 Installation

Install via NuGet Package Manager:

dotnet add package CloudflareD1.NET

Or via Package Manager Console:

Install-Package CloudflareD1.NET

🚀 Quick Start

Local Development Mode (Default)

Perfect for development and testing without needing Cloudflare credentials:

using CloudflareD1.NET;
using CloudflareD1.NET.Configuration;
using Microsoft.Extensions.Options;
using Microsoft.Extensions.Logging;

// Configure for local SQLite mode
var options = Options.Create(new D1Options
{
    UseLocalMode = true,
    LocalDatabasePath = "myapp.db"
});

var logger = loggerFactory.CreateLogger<D1Client>();

// Create client
using var client = new D1Client(options, logger);

// Create table
await client.ExecuteAsync(@"
    CREATE TABLE users (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        name TEXT NOT NULL,
        email TEXT UNIQUE NOT NULL
    )
");

// Insert data
await client.ExecuteAsync(
    "INSERT INTO users (name, email) VALUES (@name, @email)",
    new { name = "John Doe", email = "john@example.com" }
);

// Query data
var result = await client.QueryAsync("SELECT * FROM users");
foreach (var row in result.Results)
{
    Console.WriteLine($"{row["name"]}: {row["email"]}");
}

Remote Cloudflare D1 Mode

For production with actual Cloudflare D1 databases:

var options = Options.Create(new D1Options
{
    UseLocalMode = false,
    AccountId = "your-cloudflare-account-id",
    DatabaseId = "your-d1-database-id",
    ApiToken = "your-cloudflare-api-token"
});

using var client = new D1Client(options, logger);

// Same API as local mode!
var result = await client.QueryAsync("SELECT * FROM users WHERE name = @name", 
    new { name = "John" });

🔧 ASP.NET Core Integration

With Configuration

In appsettings.json:

{
  "CloudflareD1": {
    "UseLocalMode": true,
    "LocalDatabasePath": "myapp.db"
  }
}

In Program.cs or Startup.cs:

using CloudflareD1.NET.Extensions;

// Add D1 services
builder.Services.AddCloudflareD1(builder.Configuration.GetSection("CloudflareD1"));

// Or configure directly
builder.Services.AddCloudflareD1(options =>
{
    options.UseLocalMode = true;
    options.LocalDatabasePath = "myapp.db";
});

Using in Controllers

using CloudflareD1.NET;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
    private readonly ID1Client _d1Client;

    public UsersController(ID1Client d1Client)
    {
        _d1Client = d1Client;
    }

    [HttpGet]
    public async Task<IActionResult> GetUsers()
    {
        var result = await _d1Client.QueryAsync("SELECT * FROM users");
        return Ok(result.Results);
    }

    [HttpPost]
    public async Task<IActionResult> CreateUser([FromBody] User user)
    {
        var result = await _d1Client.ExecuteAsync(
            "INSERT INTO users (name, email) VALUES (@name, @email)",
            user
        );
        
        return CreatedAtAction(nameof(GetUsers), new { id = result.Meta?.LastRowId });
    }
}

📚 Advanced Usage

Batch Operations (Transactions)

Execute multiple statements as a single atomic transaction:

using CloudflareD1.NET.Models;

var statements = new List<D1Statement>
{
    new() { 
        Sql = "INSERT INTO users (name, email) VALUES (@name, @email)", 
        Params = new { name = "Alice", email = "alice@example.com" } 
    },
    new() { 
        Sql = "INSERT INTO orders (user_id, total) VALUES (@userId, @total)", 
        Params = new { userId = 1, total = 99.99 } 
    },
    new() { 
        Sql = "UPDATE stats SET user_count = user_count + 1" 
    }
};

var results = await client.BatchAsync(statements);
// All succeed or all fail together

Time Travel Queries (Cloudflare D1 Only)

Query your database at a specific point in time:

using CloudflareD1.NET;

var managementClient = (ID1ManagementClient)client;

// Query data as it was 24 hours ago
var timestamp = DateTime.UtcNow.AddDays(-1).ToString("o");
var historicalData = await managementClient.QueryAtTimestampAsync(
    "SELECT * FROM users",
    timestamp
);

Database Management

using CloudflareD1.NET;

var managementClient = (ID1ManagementClient)client;

// List all databases
var databases = await managementClient.ListDatabasesAsync();

// Create a new database
var newDb = await managementClient.CreateDatabaseAsync("my-new-database");

// Get database info
var dbInfo = await managementClient.GetDatabaseAsync("database-id");

// Delete a database
await managementClient.DeleteDatabaseAsync("database-id");

🎯 Configuration Options

🔐 Authentication

API Token (Recommended)

1. Go to Cloudflare Dashboard
2. Create API Token with D1 Edit permissions
3. Use in configuration:

options.ApiToken = "your-api-token";

API Key (Legacy)

options.ApiKey = "your-api-key";
options.Email = "your-email@example.com";

📖 Documentation

Full documentation is available at https://your-docs-site.com (coming soon)

🧪 Testing

The library includes a comprehensive test suite. Run tests with:

dotnet test

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Cloudflare for the amazing D1 database platform
• The .NET community for excellent tooling and support

📮 Support

• 📫 Open an issue on GitHub Issues
• 💬 Start a discussion on GitHub Discussions

🔗 Links

• Cloudflare D1 Documentation
• Cloudflare D1 API Reference
• NuGet Package

Made with ❤️ by the .NET and Cloudflare communities