---
title: "Databases hooks"
description: "React hooks for databases. Standard CRUD (`useListDatabases`,
`useRetrieveDatabase`, `useCreateDatabase`, `useUpdateDatabase`,
`useDeleteDatabase`, `useRestoreDatabase`) is generated; see
./databases.gen. Hooks for SQL execution and D1 introspection (list
tables, describe table, browse rows) are hand-written below."
section: "Libraries"
group: "React hooks"
order: 411
---

## Hooks

### `useBrowseTable` `composite`

Browse rows in a table with pagination.

```ts
useBrowseTable(id: string, tableName: string, params?: { limit?: number; offset?: number; }, options?: QueryOpts<BrowseTableResponse>)
```

**Types:** [BrowseTableResponse](/types/browse-table-response)

```ts
const { data } = useBrowseTable("dbs_abc123", "users", {
  limit: 50,
  offset: 0,
});
```

### `useCreateDatabase` `mutation`

Create a new database.

```ts
useCreateDatabase(options?: MutationOpts<Database, CreateDatabaseParams>)
```

**Types:** [Database](/types/database) · [CreateDatabaseParams](/types/create-database-params)

### `useDeleteDatabase` `mutation`

Soft-delete a database. The underlying D1 instance stays live until purge.

```ts
useDeleteDatabase(options?: MutationOpts<SuccessResponse, string>)
```

**Types:** [SuccessResponse](/types/success-response)

### `useDescribeTable` `composite`

Describe a single table (columns + row count).

```ts
useDescribeTable(id: string, tableName: string, options?: QueryOpts<DescribeTableResponse>)
```

**Types:** [DescribeTableResponse](/types/describe-table-response)

```ts
const { data } = useDescribeTable("dbs_abc123", "users");
```

### `useExecuteSql` `composite`

Execute a SQL statement against a database. Returns rows, columns,
and stats. Does not invalidate any query cache — queries are
side-effect-free.

**Mutation, not a query.** TanStack Query's mutation shape — args
pass to `.mutate(...)` / `.mutateAsync(...)`, not to the hook itself.
Calling it like a query silently no-ops: no network call, `data`
stays `undefined`, no error. The "args were ignored" failure mode is
the #1 deployed-element bug here because both forms typecheck.

```ts
useExecuteSql(options?: MutationOpts<SqlResult, QueryDatabaseParams>)
```

**Types:** [SqlResult](/types/sql-result) · [QueryDatabaseParams](/types/query-database-params)

```ts
// ✅ Correct — args via mutate / mutateAsync
const { mutateAsync } = useExecuteSql();
const result = await mutateAsync({ id: "dbs_abc123", query: "SELECT ..." });
result.rows;

// ❌ Wrong — args to the hook are silently dropped, no network call
const { data } = useExecuteSql({ id: "dbs_abc123", query: "SELECT ..." });
data?.rows; // always undefined
```

For SELECT reads on mount, fire from `useEffect` and store rows in
state.

````

### `useListDatabases` `query`

List databases with pagination.

```ts
useListDatabases(params?: Omit<ListDatabasesParams, | > & { filter?: DatabaseFilter; orderBy?: DatabaseOrderBy[]; } & DatabaseShorthands, options?: QueryOpts<Page<Database>>)
````

**Types:** [ListDatabasesParams](/types/list-databases-params) · [DatabaseFilter](/types/database-filter) · [DatabaseOrderBy](/types/database-order-by) · [DatabaseShorthands](/types/database-shorthands) · [Page](/types/page) · [Database](/types/database)

### `useListTables` `query`

List tables in a database.

```ts
useListTables(id: string, options?: QueryOpts<ListTablesResponse>)
```

**Types:** [ListTablesResponse](/types/list-tables-response)

```ts
const { data } = useListTables("dbs_abc123");
```

### `usePurgeDatabase` `composite`

Permanently delete a soft-deleted database.

```ts
usePurgeDatabase(options?: MutationOpts<SuccessResponse, PurgeDatabaseParams>)
```

**Types:** [SuccessResponse](/types/success-response) · [PurgeDatabaseParams](/types/purge-database-params)

### `useRestoreDatabase` `composite`

Restore a soft-deleted database.

```ts
useRestoreDatabase(options?: MutationOpts<Database, string>)
```

**Types:** [Database](/types/database)

### `useRetrieveDatabase` `query`

Get a database by ID.

```ts
useRetrieveDatabase(id: string, options?: QueryOpts<Database>)
```

**Types:** [Database](/types/database)

### `useUpdateDatabase` `mutation`

Update a database (rename / change description).

```ts
useUpdateDatabase(options?: MutationOpts<Database, UpdateDatabaseParams>)
```

**Types:** [Database](/types/database) · [UpdateDatabaseParams](/types/update-database-params)