> ## Documentation Index
> Fetch the complete documentation index at: https://tinycloudlabs-skgbafa-app-kit-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# DuckDB

> Query and manage DuckDB databases from the TinyCloud CLI

<Badge>Beta</Badge>

The `tc duckdb` commands manage DuckDB databases in the active TinyCloud space. Use them for analytical workloads that fit DuckDB's columnar query model. The command family currently supports query, execute, schema describe, export, and import workflows.

## Commands

### tc duckdb query

Run a read-only query.

```bash theme={null}
tc duckdb query <sql>
```

| Option            | Description                                        | Default   |
| ----------------- | -------------------------------------------------- | --------- |
| `--db <name>`     | DuckDB database name                               | `default` |
| `--params <json>` | JSON array of bind parameters for `?` placeholders | None      |

```bash theme={null}
tc duckdb query "SELECT type, count(*) AS total FROM events GROUP BY type" --db analytics
```

### tc duckdb execute

Run a write or schema statement.

```bash theme={null}
tc duckdb execute <sql>
```

| Option            | Description                                        | Default   |
| ----------------- | -------------------------------------------------- | --------- |
| `--db <name>`     | DuckDB database name                               | `default` |
| `--params <json>` | JSON array of bind parameters for `?` placeholders | None      |

```bash theme={null}
tc duckdb execute "CREATE TABLE IF NOT EXISTS events (type VARCHAR, created_at TIMESTAMP)" --db analytics
```

### tc duckdb describe

Show tables, columns, and views.

```bash theme={null}
tc duckdb describe --db analytics
```

### tc duckdb export

Download the raw DuckDB database file.

```bash theme={null}
tc duckdb export --db analytics --output analytics.duckdb
```

| Option                | Description          | Default         |
| --------------------- | -------------------- | --------------- |
| `--db <name>`         | DuckDB database name | `default`       |
| `-o, --output <file>` | Output file path     | `export.duckdb` |

### tc duckdb import

Upload a local DuckDB database file.

```bash theme={null}
tc duckdb import analytics.duckdb --db analytics
```

| Option        | Description          | Default   |
| ------------- | -------------------- | --------- |
| `--db <name>` | DuckDB database name | `default` |

## Scripting

Use `--json` for machine-readable output when querying or describing databases.

```bash theme={null}
tc duckdb query "SELECT count(*) AS total FROM events" --db analytics --json | jq '.rows[0][0]'
```

<Note>
  DuckDB support is beta. Prefer SQLite via `tc sql` for operational app data unless you specifically need DuckDB query behavior.
</Note>