# Open DuckDB Files

VisiGrid opens local DuckDB (`.duckdb`) databases in the desktop app and the `vgrid` CLI, starting in **VisiGrid 0.45.0**. The database is opened **read-only** and is never modified; the tables you choose are copied into sheets.

## Open a database

Open the `.duckdb` file with `Ctrl+O`. Before anything is copied, a picker lists the database's tables with their exact row counts and previews the first eight rows of the highlighted one. Choose one or more tables and **Import**; each becomes a sheet. **Cancel** leaves the workbook as it was.

| Key | In the picker |
|-----|---------------|
| `↑` `↓` | Highlight a table and preview it |
| `Space` | Select or clear the highlighted table |
| `Ctrl+F` | Search table names |
| `Tab` | Move between search, select all, the list and the buttons |
| `Ctrl+Enter` | Import the selected tables |
| `Esc` | Cancel |

Only base tables are listed; views are not imported. Column types come through the same way as [Parquet](https://docs.visigrid.app/guide/parquet/#how-column-types-come-through): numbers stay numbers, text stays text (including `007` and values starting with `=`), and dates, times and timestamps keep their types.

A selection must fit in sheets (1,048,576 rows and 16,384 columns each) and within **10 million cells** in total. The picker says so before importing; filter or split the table in DuckDB first.

DuckDB is opened without network access and without installing or loading extensions, so a database can't reach out to anything when you open it.

## Refresh a table into a sheet

An [import recipe](https://docs.visigrid.app/guide/import-recipes/) can read one DuckDB table, apply steps such as keeping, renaming and filtering columns, and refresh the result into a Table whenever the database changes (0.47.0 and later).

## From the command line

`vgrid peek` and `vgrid convert` read DuckDB through the same importer:

```bash
# Browse a table in the terminal
vgrid peek warehouse.duckdb --sheet main.orders

# One table to CSV or Excel
vgrid convert warehouse.duckdb --sheet main.orders -t csv -o orders.csv
vgrid convert warehouse.duckdb --sheet main.orders -t xlsx -o orders.xlsx
```

### Write Parquet or DuckDB

`vgrid convert` writes one worksheet as typed Parquet, or as a **new** DuckDB database holding it as `main.data`. An existing database is never replaced.

```bash
# See the column types and any conflicts first, as JSON, without writing
vgrid convert orders.csv --headers -t parquet --parquet-plan

vgrid convert orders.csv --headers -t parquet -o orders.parquet
vgrid convert orders.csv --headers -t duckdb -o orders.duckdb

# A column mixing numbers and text (A-1, 7) must be exported as text
vgrid convert orders.csv --headers -t parquet --text-column Reference -o orders.parquet
```

Exports carry calculated values, not formulas or formatting. A column whose values mix types (numbers and text, say) stops the export until you choose `--text-column` for it. DuckDB column names must also be unique ignoring case.

See [`vgrid convert`](https://docs.visigrid.app/cli/convert/) and [`vgrid peek`](https://docs.visigrid.app/cli/peek/) for every option.