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

# Beancount

> Open Beancount ledgers with TablePro

# Beancount

TablePro opens `.beancount` ledgers as read-only, file-based connections. If the Beancount plugin is not installed yet, TablePro prompts you to download it before opening the ledger. The driver projects transactions, postings, accounts, prices, computed balances, balance assertions, and source files into SQL tables for browsing and exports.

The plugin uses either `rledger` or Python Beancount to parse ledgers. Install one of those backends separately. When both are available, TablePro uses `rledger`; Python Beancount is used as a fallback for browsing projected SQL tables.

The plugin also supports BQL queries through `rledger`. BQL requires the `rledger` executable even when the ledger was opened through Python Beancount.

## Backend requirements

TablePro does not bundle a Beancount parser. It discovers backends in this order:

1. `rledger` from `TABLEPRO_RUSTLEDGER_BINARY`, `PATH`, or standard Homebrew locations.
2. Python Beancount from `TABLEPRO_BEANCOUNT_PYTHON`, `PATH`, or standard Python locations.

Other Beancount-compatible parsers are not discovered unless they expose one of these supported interfaces.

To verify `rledger`:

```bash theme={null}
rledger --version
```

To verify Python Beancount:

```bash theme={null}
python3 -c "import beancount"
```

If TablePro cannot find a supported backend, set the executable path before launching the app:

```bash theme={null}
launchctl setenv TABLEPRO_RUSTLEDGER_BINARY /opt/homebrew/bin/rledger
launchctl setenv TABLEPRO_BEANCOUNT_PYTHON /opt/homebrew/bin/python3
```

To force a backend:

```bash theme={null}
launchctl setenv TABLEPRO_BEANCOUNT_BACKEND python
```

## Connecting to a Beancount ledger

<Steps>
  <Step title="Create a new connection">
    Open TablePro and click **New Connection** or press <kbd>⌘N</kbd>.
  </Step>

  <Step title="Select Beancount">
    Choose **Beancount** from the database type list.
  </Step>

  <Step title="Choose your ledger file">
    Click **Browse** and select a `.beancount` file.
  </Step>

  <Step title="Connect">
    Click **Connect** to open the ledger.
  </Step>
</Steps>

## Connection URL

```text theme={null}
beancount:///path/to/main.beancount
```

See [Connection URL Reference](/databases/connection-urls) for all parameters.

## Tables

| Table                | Contents                                                                                     |
| -------------------- | -------------------------------------------------------------------------------------------- |
| `transactions`       | Transaction date, flag, payee, and narration                                                 |
| `postings`           | Posting account, amount, commodity, and resolved cost basis (`cost_number`, `cost_currency`) |
| `accounts`           | Opened accounts and declared currencies                                                      |
| `prices`             | Price directives                                                                             |
| `balances`           | Computed account balances by commodity                                                       |
| `balance_assertions` | Beancount balance directives                                                                 |
| `source_files`       | Parsed ledger and include files                                                              |

Amounts are read straight from `rledger`, so thousands separators, arithmetic, cost (`{}`), and price (`@`/`@@`) annotations are resolved to their booked values.

## Includes

The parser follows Beancount `include` directives. Literal includes and glob patterns such as `include "imports/*.beancount"` and `include "imports/**/*.beancount"` are supported.

## BQL

Prefix a query with `BQL:` to run it through your configured `rledger` executable:

```sql theme={null}
BQL: SELECT account FROM accounts ORDER BY account
```

Table browsing, row counts, and pagination work for BQL results. BQL queries do not support SQL parameters.

## Limitations

* Beancount connections are read-only.
* Schema editing, imports, SSH, SSL, and database switching are not available for ledgers.
* The SQL projection covers common ledger directives; unsupported directives remain available in the original source files.