db: document isDbError() (#7491)

* feat: document isDbError()

* edit: forgot this ain't .astro

Co-authored-by: Sarah Rainsberger <[email protected]>

* edit: be expressive

Co-authored-by: Sarah Rainsberger <[email protected]>

---------

Co-authored-by: Sarah Rainsberger <[email protected]>

src/content/docs/en/guides/integrations-guide/db.mdx

@@ -221,3 +221,30 @@ Execute a `.ts` or `.js` file to read or write to your database. This accepts a
 - `--remote` Run against your Studio project database. Omit to run against your development server.
 
 Execute a raw SQL query against your database. Use the `--remote` flag to run against your Studio project database, or omit the flag to run against your development server.
+
+## Astro DB utility reference
+
+### `isDbError()`
+
+The `isDbError()` function checks if an error is a libSQL database exception. This may include a foreign key constraint error when using references, or missing fields when inserting data. You can combine `isDbError()` with a try / catch block to handle database errors in your application:
+
+```ts title="src/pages/api/comment/[id].ts" "idDbError"
+import { db, Comment, isDbError } from 'astro:db';
+import type { APIRoute } from 'astro';
+
+export const POST: APIRoute = (ctx) => {
+  try {
+    await db.insert(Comment).values({
+      id: ctx.params.id,
+      content: 'Hello, world!'
+    });
+  } catch (e) {
+    if (isDbError(e)) {
+      return new Response(`Cannot insert comment with id ${id}\n\n${e.message}`, { status: 400 });
+    }
+    return new Response('An unexpected error occurred', { status: 500 });
+  }
+
+  return new Response(null, { status: 201 });
+};
+```