hxdb-react
v0.1.2
Published
React client library for HxDB - Query your database with React components
Maintainers
beee-devopsReadme
hxdb-react
React client library for HxDB — query your database with React hooks and components.
Install
npm install hxdb-reactQuick Start
1. Wrap your app with the provider
The baseUrl defaults to https://hxdb-test.kubo.hexabase.io, so you only need to provide your API key:
// app/providers.tsx (Next.js App Router)
"use client";
import { HxDBProvider } from "hxdb-react";
export function Providers({ children }: { children: React.ReactNode }) {
return (
<HxDBProvider config={{ apiKey: "your-api-key" }}>
{children}
</HxDBProvider>
);
}To connect to a different HxDB instance, override baseUrl:
<HxDBProvider config={{ baseUrl: "http://localhost:5213", apiKey: "your-api-key" }}>
{children}
</HxDBProvider>2. Wire up the layout
// app/layout.tsx
import { Providers } from "./providers";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}3. Query with the useHxDB hook
"use client";
import { useHxDB } from "hxdb-react";
interface User {
id: number;
name: string;
email: string;
}
export default function UserList() {
const { data, columns, loading, error, executionTimeMs } = useHxDB<User>(
"SELECT * FROM users LIMIT 10"
);
if (loading) return <p>Loading...</p>;
if (error) return <p>Error: {error}</p>;
return (
<div>
<p>Fetched in {executionTimeMs}ms</p>
<table>
<thead>
<tr>
{columns.map((col) => (
<th key={col}>{col}</th>
))}
</tr>
</thead>
<tbody>
{data.map((user) => (
<tr key={user.id}>
<td>{user.id}</td>
<td>{user.name}</td>
<td>{user.email}</td>
</tr>
))}
</tbody>
</table>
</div>
);
}4. Or use the declarative <HxDB> component
"use client";
import { HxDB } from "hxdb-react";
export default function OrdersTable() {
return (
<HxDB query="SELECT * FROM orders ORDER BY created_at DESC LIMIT 20">
{({ data, loading, error, columns, refetch }) => {
if (loading) return <p>Loading...</p>;
if (error) return <p>Error: {error}</p>;
return (
<div>
<button onClick={refetch}>Refresh</button>
<table>
<thead>
<tr>
{columns.map((c) => (
<th key={c}>{c}</th>
))}
</tr>
</thead>
<tbody>
{data.map((row, i) => (
<tr key={i}>
{columns.map((c) => (
<td key={c}>{String(row[c] ?? "")}</td>
))}
</tr>
))}
</tbody>
</table>
</div>
);
}}
</HxDB>
);
}API Reference
<HxDBProvider>
Wraps your app and provides the HxDB client to all child components.
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| config.baseUrl | string | No | HxDB server URL (default: https://hxdb-test.kubo.hexabase.io) |
| config.apiKey | string | Yes | API key for authentication (from Settings page) |
| config.headers | Record<string, string> | No | Custom request headers |
useHxDB<T>(query, options?)
React hook for executing SQL queries.
const { data, columns, loading, error, executionTimeMs, rowsAffected, refetch } = useHxDB<User>(
"SELECT * FROM users",
{ enabled: true } // set false to defer execution
);Returns HxDBQueryState<T>:
| Field | Type | Description |
|-------|------|-------------|
| data | T[] | Query result rows |
| columns | string[] | Column names |
| loading | boolean | Loading state |
| error | string \| null | Error message |
| executionTimeMs | number \| null | Query execution time |
| rowsAffected | number | Rows affected (INSERT/UPDATE/DELETE) |
| refetch | () => Promise<void> | Re-execute the query |
<HxDB>
Declarative component using render props pattern.
<HxDB query="SELECT * FROM products" enabled={true}>
{({ data, loading, error }) => {
// render your UI
}}
</HxDB>HxDBClient
Standalone client for use outside React components (API routes, scripts, etc).
import { createHxDBClient } from "hxdb-react";
// Uses default URL (https://hxdb-test.kubo.hexabase.io)
const client = createHxDBClient({ apiKey: "your-api-key" });
// Or specify a custom URL
// const client = createHxDBClient({ baseUrl: "http://localhost:5213", apiKey: "your-api-key" });
// Query
const { data, columns } = await client.query("SELECT * FROM users LIMIT 5");
// List datasets
const datasets = await client.datasets();cURL Examples
The same API works with any HTTP client:
# Query with API key
curl -X POST https://hxdb-test.kubo.hexabase.io/api/query \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key" \
-d '{"sql": "SELECT * FROM users LIMIT 5"}'
# List datasets
curl https://hxdb-test.kubo.hexabase.io/api/datasets \
-H "Authorization: Bearer your-api-key"
# Get dataset schema
curl https://hxdb-test.kubo.hexabase.io/api/datasets/users/schema \
-H "Authorization: Bearer your-api-key"
# Insert a row
curl -X POST https://hxdb-test.kubo.hexabase.io/api/datasets/users \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key" \
-d '{"name": "Alice", "email": "[email protected]"}'License
MIT