# Cloudflare::API::D1 #

# NAME #

Cloudflare::API::D1 - manage D1 databases and run REST SQL queries

# SYNOPSIS #

```perl
my $d1=$api->d1();
my $databases=$d1->list_databases();
my $rows=$d1->query_sql($database_id,
    'SELECT * FROM items WHERE id = ?', [$item_id]);
```

# DESCRIPTION #

All methods use the account ID configured on `Cloudflare::API`. The query methods call Cloudflare's D1 REST query endpoint; they do not provide a DBI connection or migration system. SQL parameters remain separate from SQL text.

# METHODS #

* **list_databases(%query)** — List every database, passing named filters as query parameters. The method follows all pages and returns one flat array reference; a large result set can require many requests and substantial memory.
* **list_databases_page(%query)** — Return a lazy `HTTP::API::Core::Pagination` object. Use `next()` to consume one database at a time.
* **list_databases_page_response(%query)** — Make one list request and return the complete decoded Cloudflare response hash, including `result_info` when supplied.
* **get_database($id, %options)** — Retrieve a database by ID and return its `result`.
* **create_database(\%body, %options)** — POST a database definition, normally including `name`. Returns the created `result`.
* **update_database($id, \%body, %options)** — PATCH a database and return its `result`.
* **delete_database($id, %options)** — DELETE a database and return the endpoint's `result`, possibly `undef` for an empty body.
* **query_database($id, \%body, %options)** — POST a D1 query body such as `{ sql => 'SELECT 1', params => [] }`. Returns Cloudflare's `result` without reshaping it.
* **query_sql($id, $sql, \@params, %options)** — Build a single-statement body and call `query_database()`. `\@params` is optional; omit it for a query without bound values. Returns D1's query result array, whose entries can contain `results`, `meta`, and `success`.

For non-list JSON methods, `full_response => 1` returns the complete decoded Cloudflare response. Database IDs are percent-encoded in paths. Body arguments must be hash references; `query_sql()` also requires a non-empty scalar SQL string and, when supplied, an array reference of parameters.

# ERRORS #

Invalid bodies or SQL arguments cause Perl exceptions. HTTP, transport, and Cloudflare response failures follow the rules in `Cloudflare::API`.

# SEE ALSO #

[Cloudflare::API](../API.pm.md)

# AUTHOR #

Andrew Speer <andrew.speer@isolutions.com.au>

# LICENSE and COPYRIGHT #

Copyright (c) 2026 Andrew Speer. This software is free software under the same terms as Perl 5.