mt5cli 1.0.2__tar.gz → 1.1.0__tar.gz

{mt5cli-1.0.2 → mt5cli-1.1.0}/.agents/skills/local-qa/scripts/qa.sh

@@ -10,7 +10,7 @@ uv run pyright .
 uv run pytest
 
 # Markdown
-npx -y prettier --write './**/*.md'
+npx -y prettier --write './**/*.{md,json}'
 
 # GitHub Actions
 case "${OSTYPE}" in

{mt5cli-1.0.2 → mt5cli-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 1.0.2
+Version: 1.1.0
 Summary: Generic MT5 data and execution infrastructure for Python applications
 Project-URL: Repository, https://github.com/dceoy/mt5cli.git
 Author-email: dceoy <dceoy@users.noreply.github.com>
@@ -19,6 +19,10 @@ Requires-Python: <3.14,>=3.11
 Requires-Dist: click>=8.1.0
 Requires-Dist: pdmt5>=1.0.0
 Requires-Dist: typer>=0.15.0
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http; extra == 'otel'
+Requires-Dist: opentelemetry-sdk; extra == 'otel'
 Provides-Extra: parquet
 Requires-Dist: pyarrow>=19.0.0; extra == 'parquet'
 Description-Content-Type: text/markdown
@@ -182,34 +186,36 @@ python -m mt5cli -o account.csv account-info
 
 ## Commands
 
-| Command                | Description                                                                                                  |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `rates-from`           | Export rates from a start date                                                                               |
-| `rates-from-pos`       | Export rates from a start position                                                                           |
-| `latest-rates`         | Export latest rates from a start position                                                                    |
-| `rates-range`          | Export rates for a date range                                                                                |
-| `ticks-from`           | Export ticks from a start date                                                                               |
-| `ticks-range`          | Export ticks for a date range                                                                                |
-| `ticks-recent`         | Export ticks from a recent trailing window                                                                   |
-| `account-info`         | Export account information                                                                                   |
-| `terminal-info`        | Export terminal information                                                                                  |
-| `version`              | Export MetaTrader 5 version information                                                                      |
-| `last-error`           | Export the last error information                                                                            |
-| `symbols`              | Export symbol list                                                                                           |
-| `symbol-info`          | Export symbol details                                                                                        |
-| `symbol-info-tick`     | Export the last tick for a symbol                                                                            |
-| `minimum-margins`      | Export minimum-volume buy and sell margin requirements                                                       |
-| `market-book`          | Export market depth (order book)                                                                             |
-| `orders`               | Export active orders                                                                                         |
-| `positions`            | Export open positions                                                                                        |
-| `history-orders`       | Export historical orders                                                                                     |
-| `history-deals`        | Export historical deals                                                                                      |
-| `recent-history-deals` | Export historical deals from a recent trailing window                                                        |
-| `mt5-summary`          | Export terminal/account status summary                                                                       |
-| `order-check`          | Check funds sufficiency for a trade request                                                                  |
-| `order-send`           | Send a raw trade request to the trade server (`--yes` required; expert path)                                 |
-| `close-positions`      | Close open positions by `--symbol` or `--ticket` (`--yes` required for live; `--dry-run` available)          |
+| Command                | Description                                                                                                                                 |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rates-from`           | Export rates from a start date                                                                                                              |
+| `rates-from-pos`       | Export rates from a start position                                                                                                          |
+| `latest-rates`         | Export latest rates from a start position                                                                                                   |
+| `rates-range`          | Export rates for a date range                                                                                                               |
+| `ticks-from`           | Export ticks from a start date                                                                                                              |
+| `ticks-range`          | Export ticks for a date range                                                                                                               |
+| `ticks-recent`         | Export ticks from a recent trailing window                                                                                                  |
+| `account-info`         | Export account information                                                                                                                  |
+| `terminal-info`        | Export terminal information                                                                                                                 |
+| `version`              | Export MetaTrader 5 version information                                                                                                     |
+| `last-error`           | Export the last error information                                                                                                           |
+| `symbols`              | Export symbol list                                                                                                                          |
+| `symbol-info`          | Export symbol details                                                                                                                       |
+| `symbol-info-tick`     | Export the last tick for a symbol                                                                                                           |
+| `minimum-margins`      | Export minimum-volume buy and sell margin requirements                                                                                      |
+| `market-book`          | Export market depth (order book)                                                                                                            |
+| `orders`               | Export active orders                                                                                                                        |
+| `positions`            | Export open positions                                                                                                                       |
+| `history-orders`       | Export historical orders                                                                                                                    |
+| `history-deals`        | Export historical deals                                                                                                                     |
+| `recent-history-deals` | Export historical deals from a recent trailing window                                                                                       |
+| `mt5-summary`          | Export terminal/account status summary                                                                                                      |
+| `order-check`          | Check funds sufficiency for a trade request                                                                                                 |
+| `order-send`           | Send a raw trade request to the trade server (`--yes` required; expert path)                                                                |
+| `close-positions`      | Close open positions by `--symbol` or `--ticket` (`--yes` required for live; `--dry-run` available)                                         |
 | `collect-history`      | Collect rates, history-orders, and history-deals for one or more symbols into a single SQLite database (ticks opt-in via `--dataset ticks`) |
+| `grafana-schema`       | Create or refresh Grafana-ready views and indexes in an existing SQLite database (idempotent, no MT5 connection)                            |
+| `snapshot`             | Snapshot current account, position, order, and terminal state into SQLite for live Grafana dashboards                                       |
 
 Use `order-check` to validate a request payload before running `order-send --yes`.
 `close-positions` is the safer high-level alternative that builds correct close
@@ -229,6 +235,104 @@ mt5cli -o history.db collect-history \
 
 History orders and deals are fetched per symbol and concatenated, so the symbol filter is applied consistently across all datasets. The `cash_events` view is derived from symbol-filtered `history_deals`, so account-level cash events with empty or non-matching symbols may be excluded. The `rates` table records the requested `timeframe` so appended runs at different timeframes remain distinguishable. The `positions_reconstructed` view aggregates trade deals by `position_id`, excludes positions without closing-side entries, and uses volume-weighted open/close prices; reversal deals (`DEAL_ENTRY_INOUT`) are reported via `volume_reversal` / `reversal_count` columns.
 
+### Grafana-ready SQLite dashboards
+
+mt5cli can prepare a SQLite database for use as a Grafana datasource (via the [SQLite plugin](https://grafana.com/grafana/plugins/frser-sqlite-datasource/) or similar). Most `grafana_*` views expose an integer epoch-second `time` column for use in Grafana time-series panels. Two views (`grafana_realized_pnl`, `grafana_trade_stats`) are static symbol-level summaries with no `time` column — use them in table or stat panels.
+
+#### Prepare the schema (idempotent, no MT5 connection needed)
+
+```bash
+mt5cli -o history.db grafana-schema
+```
+
+This creates snapshot tables (`account_snapshots`, `position_snapshots`, `order_snapshots`, `terminal_snapshots`, `snapshot_runs`) and all `grafana_*` views and indexes in the SQLite database. Safe to run repeatedly — all operations are idempotent.
+
+#### Snapshot current account state
+
+```bash
+mt5cli -o history.db snapshot \
+  --symbol JP225 --symbol HK50 --symbol NL25 \
+  --with-account --with-positions --with-orders --with-terminal \
+  --with-grafana-schema
+```
+
+Appends one timestamped row per data type. Never places orders or modifies trading state. Run periodically (e.g. from a cron job or a loop) to build a time-series account history.
+
+#### SDK usage
+
+```python
+from pdmt5 import Mt5DataClient, Mt5Config
+from mt5cli import update_observability, update_observability_with_config
+
+# Reuse an already-connected client
+client = Mt5DataClient(config=Mt5Config(login=12345))
+client.initialize_and_login_mt5()
+try:
+    update_observability(
+        client=client,
+        output="history.db",
+        symbols=["EURUSD", "GBPUSD"],  # optional position/order filter
+        include_account=True,
+        include_positions=True,
+        include_orders=True,
+        include_terminal=True,
+        with_grafana_schema=True,
+    )
+finally:
+    client.shutdown()
+
+# Standalone wrapper that opens/closes MT5 automatically
+update_observability_with_config(
+    output="history.db",
+    config=Mt5Config(login=12345),
+)
+```
+
+#### Available Grafana views
+
+**Time-series views** (integer epoch-second `time` column; snapshot views also expose `run_id`):
+
+| View                         | Source               | Description                                                |
+| ---------------------------- | -------------------- | ---------------------------------------------------------- |
+| `grafana_rates`              | `rates`              | OHLCV bars with integer epoch `time`                       |
+| `grafana_ticks`              | `ticks`              | Tick data with integer epoch `time`                        |
+| `grafana_history_deals`      | `history_deals`      | All deals with epoch `time`                                |
+| `grafana_history_orders`     | `history_orders`     | All historical orders; adds epoch `time` from `time_setup` |
+| `grafana_trade_deals`        | `history_deals`      | Trade deals only (`type IN (0,1)`)                         |
+| `grafana_cash_events`        | `history_deals`      | Non-trade deals (deposits, dividends, etc.)                |
+| `grafana_symbol_pnl`         | `history_deals`      | Per-close-deal profit/loss per symbol                      |
+| `grafana_account_snapshots`  | `account_snapshots`  | Account balance/equity/margin time series                  |
+| `grafana_position_snapshots` | `position_snapshots` | Open position snapshots over time                          |
+| `grafana_order_snapshots`    | `order_snapshots`    | Active order snapshots over time                           |
+| `grafana_terminal_snapshots` | `terminal_snapshots` | Terminal connectivity snapshots                            |
+
+**Static summary views** (no `time` column; use in table or stat panels, not time-series):
+
+| View                   | Source          | Description                           |
+| ---------------------- | --------------- | ------------------------------------- |
+| `grafana_realized_pnl` | `history_deals` | Cumulative realized PnL per symbol    |
+| `grafana_trade_stats`  | `history_deals` | Win/loss counts and profit per symbol |
+
+#### Example Grafana queries
+
+```sql
+-- Equity curve over time
+SELECT time, equity FROM grafana_account_snapshots ORDER BY time;
+
+-- Rolling balance by account login
+SELECT time, login, balance FROM grafana_account_snapshots
+WHERE login = $login ORDER BY time;
+
+-- Open positions at latest successful snapshot
+SELECT symbol, volume, profit FROM grafana_position_snapshots
+WHERE run_id = (SELECT MAX(run_id) FROM snapshot_runs WHERE status = 'ok');
+
+-- Realized PnL by symbol
+SELECT symbol, total_profit FROM grafana_trade_stats ORDER BY total_profit DESC;
+```
+
+> **Note**: OpenTelemetry integration is intentionally not part of this release and is tracked separately.
+
 ### Incremental history SDK
 
 For automated pipelines, use the importable incremental API instead of re-fetching fixed date ranges:

{mt5cli-1.0.2 → mt5cli-1.1.0}/README.md

@@ -157,34 +157,36 @@ python -m mt5cli -o account.csv account-info
 
 ## Commands
 
-| Command                | Description                                                                                                  |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `rates-from`           | Export rates from a start date                                                                               |
-| `rates-from-pos`       | Export rates from a start position                                                                           |
-| `latest-rates`         | Export latest rates from a start position                                                                    |
-| `rates-range`          | Export rates for a date range                                                                                |
-| `ticks-from`           | Export ticks from a start date                                                                               |
-| `ticks-range`          | Export ticks for a date range                                                                                |
-| `ticks-recent`         | Export ticks from a recent trailing window                                                                   |
-| `account-info`         | Export account information                                                                                   |
-| `terminal-info`        | Export terminal information                                                                                  |
-| `version`              | Export MetaTrader 5 version information                                                                      |
-| `last-error`           | Export the last error information                                                                            |
-| `symbols`              | Export symbol list                                                                                           |
-| `symbol-info`          | Export symbol details                                                                                        |
-| `symbol-info-tick`     | Export the last tick for a symbol                                                                            |
-| `minimum-margins`      | Export minimum-volume buy and sell margin requirements                                                       |
-| `market-book`          | Export market depth (order book)                                                                             |
-| `orders`               | Export active orders                                                                                         |
-| `positions`            | Export open positions                                                                                        |
-| `history-orders`       | Export historical orders                                                                                     |
-| `history-deals`        | Export historical deals                                                                                      |
-| `recent-history-deals` | Export historical deals from a recent trailing window                                                        |
-| `mt5-summary`          | Export terminal/account status summary                                                                       |
-| `order-check`          | Check funds sufficiency for a trade request                                                                  |
-| `order-send`           | Send a raw trade request to the trade server (`--yes` required; expert path)                                 |
-| `close-positions`      | Close open positions by `--symbol` or `--ticket` (`--yes` required for live; `--dry-run` available)          |
+| Command                | Description                                                                                                                                 |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rates-from`           | Export rates from a start date                                                                                                              |
+| `rates-from-pos`       | Export rates from a start position                                                                                                          |
+| `latest-rates`         | Export latest rates from a start position                                                                                                   |
+| `rates-range`          | Export rates for a date range                                                                                                               |
+| `ticks-from`           | Export ticks from a start date                                                                                                              |
+| `ticks-range`          | Export ticks for a date range                                                                                                               |
+| `ticks-recent`         | Export ticks from a recent trailing window                                                                                                  |
+| `account-info`         | Export account information                                                                                                                  |
+| `terminal-info`        | Export terminal information                                                                                                                 |
+| `version`              | Export MetaTrader 5 version information                                                                                                     |
+| `last-error`           | Export the last error information                                                                                                           |
+| `symbols`              | Export symbol list                                                                                                                          |
+| `symbol-info`          | Export symbol details                                                                                                                       |
+| `symbol-info-tick`     | Export the last tick for a symbol                                                                                                           |
+| `minimum-margins`      | Export minimum-volume buy and sell margin requirements                                                                                      |
+| `market-book`          | Export market depth (order book)                                                                                                            |
+| `orders`               | Export active orders                                                                                                                        |
+| `positions`            | Export open positions                                                                                                                       |
+| `history-orders`       | Export historical orders                                                                                                                    |
+| `history-deals`        | Export historical deals                                                                                                                     |
+| `recent-history-deals` | Export historical deals from a recent trailing window                                                                                       |
+| `mt5-summary`          | Export terminal/account status summary                                                                                                      |
+| `order-check`          | Check funds sufficiency for a trade request                                                                                                 |
+| `order-send`           | Send a raw trade request to the trade server (`--yes` required; expert path)                                                                |
+| `close-positions`      | Close open positions by `--symbol` or `--ticket` (`--yes` required for live; `--dry-run` available)                                         |
 | `collect-history`      | Collect rates, history-orders, and history-deals for one or more symbols into a single SQLite database (ticks opt-in via `--dataset ticks`) |
+| `grafana-schema`       | Create or refresh Grafana-ready views and indexes in an existing SQLite database (idempotent, no MT5 connection)                            |
+| `snapshot`             | Snapshot current account, position, order, and terminal state into SQLite for live Grafana dashboards                                       |
 
 Use `order-check` to validate a request payload before running `order-send --yes`.
 `close-positions` is the safer high-level alternative that builds correct close
@@ -204,6 +206,104 @@ mt5cli -o history.db collect-history \
 
 History orders and deals are fetched per symbol and concatenated, so the symbol filter is applied consistently across all datasets. The `cash_events` view is derived from symbol-filtered `history_deals`, so account-level cash events with empty or non-matching symbols may be excluded. The `rates` table records the requested `timeframe` so appended runs at different timeframes remain distinguishable. The `positions_reconstructed` view aggregates trade deals by `position_id`, excludes positions without closing-side entries, and uses volume-weighted open/close prices; reversal deals (`DEAL_ENTRY_INOUT`) are reported via `volume_reversal` / `reversal_count` columns.
 
+### Grafana-ready SQLite dashboards
+
+mt5cli can prepare a SQLite database for use as a Grafana datasource (via the [SQLite plugin](https://grafana.com/grafana/plugins/frser-sqlite-datasource/) or similar). Most `grafana_*` views expose an integer epoch-second `time` column for use in Grafana time-series panels. Two views (`grafana_realized_pnl`, `grafana_trade_stats`) are static symbol-level summaries with no `time` column — use them in table or stat panels.
+
+#### Prepare the schema (idempotent, no MT5 connection needed)
+
+```bash
+mt5cli -o history.db grafana-schema
+```
+
+This creates snapshot tables (`account_snapshots`, `position_snapshots`, `order_snapshots`, `terminal_snapshots`, `snapshot_runs`) and all `grafana_*` views and indexes in the SQLite database. Safe to run repeatedly — all operations are idempotent.
+
+#### Snapshot current account state
+
+```bash
+mt5cli -o history.db snapshot \
+  --symbol JP225 --symbol HK50 --symbol NL25 \
+  --with-account --with-positions --with-orders --with-terminal \
+  --with-grafana-schema
+```
+
+Appends one timestamped row per data type. Never places orders or modifies trading state. Run periodically (e.g. from a cron job or a loop) to build a time-series account history.
+
+#### SDK usage
+
+```python
+from pdmt5 import Mt5DataClient, Mt5Config
+from mt5cli import update_observability, update_observability_with_config
+
+# Reuse an already-connected client
+client = Mt5DataClient(config=Mt5Config(login=12345))
+client.initialize_and_login_mt5()
+try:
+    update_observability(
+        client=client,
+        output="history.db",
+        symbols=["EURUSD", "GBPUSD"],  # optional position/order filter
+        include_account=True,
+        include_positions=True,
+        include_orders=True,
+        include_terminal=True,
+        with_grafana_schema=True,
+    )
+finally:
+    client.shutdown()
+
+# Standalone wrapper that opens/closes MT5 automatically
+update_observability_with_config(
+    output="history.db",
+    config=Mt5Config(login=12345),
+)
+```
+
+#### Available Grafana views
+
+**Time-series views** (integer epoch-second `time` column; snapshot views also expose `run_id`):
+
+| View                         | Source               | Description                                                |
+| ---------------------------- | -------------------- | ---------------------------------------------------------- |
+| `grafana_rates`              | `rates`              | OHLCV bars with integer epoch `time`                       |
+| `grafana_ticks`              | `ticks`              | Tick data with integer epoch `time`                        |
+| `grafana_history_deals`      | `history_deals`      | All deals with epoch `time`                                |
+| `grafana_history_orders`     | `history_orders`     | All historical orders; adds epoch `time` from `time_setup` |
+| `grafana_trade_deals`        | `history_deals`      | Trade deals only (`type IN (0,1)`)                         |
+| `grafana_cash_events`        | `history_deals`      | Non-trade deals (deposits, dividends, etc.)                |
+| `grafana_symbol_pnl`         | `history_deals`      | Per-close-deal profit/loss per symbol                      |
+| `grafana_account_snapshots`  | `account_snapshots`  | Account balance/equity/margin time series                  |
+| `grafana_position_snapshots` | `position_snapshots` | Open position snapshots over time                          |
+| `grafana_order_snapshots`    | `order_snapshots`    | Active order snapshots over time                           |
+| `grafana_terminal_snapshots` | `terminal_snapshots` | Terminal connectivity snapshots                            |
+
+**Static summary views** (no `time` column; use in table or stat panels, not time-series):
+
+| View                   | Source          | Description                           |
+| ---------------------- | --------------- | ------------------------------------- |
+| `grafana_realized_pnl` | `history_deals` | Cumulative realized PnL per symbol    |
+| `grafana_trade_stats`  | `history_deals` | Win/loss counts and profit per symbol |
+
+#### Example Grafana queries
+
+```sql
+-- Equity curve over time
+SELECT time, equity FROM grafana_account_snapshots ORDER BY time;
+
+-- Rolling balance by account login
+SELECT time, login, balance FROM grafana_account_snapshots
+WHERE login = $login ORDER BY time;
+
+-- Open positions at latest successful snapshot
+SELECT symbol, volume, profit FROM grafana_position_snapshots
+WHERE run_id = (SELECT MAX(run_id) FROM snapshot_runs WHERE status = 'ok');
+
+-- Realized PnL by symbol
+SELECT symbol, total_profit FROM grafana_trade_stats ORDER BY total_profit DESC;
+```
+
+> **Note**: OpenTelemetry integration is intentionally not part of this release and is tracked separately.
+
 ### Incremental history SDK
 
 For automated pipelines, use the importable incremental API instead of re-fetching fixed date ranges:

{mt5cli-1.0.2 → mt5cli-1.1.0}/docs/api/public-contract.md

@@ -124,6 +124,63 @@ sending requests. Failed, malformed, or unknown broker retcodes are fail-closed
 and returned as `status="failed"` with normalized `request` / `response` details;
 `dry_run=True` never calls `ensure_symbol_selected()` or `order_send()`.
 
+### Grafana observability (SQLite read model)
+
+These helpers prepare a SQLite database as a Grafana datasource. All DDL is
+idempotent (`CREATE TABLE IF NOT EXISTS`, `DROP VIEW IF EXISTS` + `CREATE
+VIEW`, `CREATE INDEX IF NOT EXISTS`). Missing source tables are skipped with a
+warning rather than raising an error.
+
+| Symbol                             | Role                                                                                            |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `update_observability`             | Append one timestamped snapshot row per data type; accepts an already-connected `Mt5DataClient` |
+| `update_observability_with_config` | Standalone wrapper: opens/closes MT5 connection automatically around `update_observability`     |
+
+Both functions write to the SQLite path given by `output=`. The optional
+`symbols` parameter filters `positions_get` / `orders_get` by symbol.
+`with_grafana_schema=False` (default) skips Grafana view/index setup; run
+`grafana-schema` once to set up the schema, then call `snapshot` repeatedly
+without this flag.
+
+**Snapshot tables** (created by `create_snapshot_tables` in `mt5cli.grafana`):
+
+| Table                | Content                                   |
+| -------------------- | ----------------------------------------- |
+| `account_snapshots`  | Balance, equity, margin, free-margin, P&L |
+| `position_snapshots` | Open positions: symbol, volume, profit, … |
+| `order_snapshots`    | Active orders: symbol, type, price, …     |
+| `terminal_snapshots` | Terminal connectivity and build info      |
+| `snapshot_runs`      | Per-run status (`ok` / `error`) timestamp |
+
+**Grafana time-series views** (integer epoch-second `time` column; snapshot views also expose `run_id`):
+
+| View                         | Source                           |
+| ---------------------------- | -------------------------------- |
+| `grafana_rates`              | `rates` table                    |
+| `grafana_ticks`              | `ticks` table                    |
+| `grafana_history_deals`      | `history_deals`                  |
+| `grafana_history_orders`     | `history_orders`                 |
+| `grafana_trade_deals`        | `history_deals` trade types only |
+| `grafana_cash_events`        | `history_deals` non-trade events |
+| `grafana_symbol_pnl`         | Per-close-deal P&L per symbol    |
+| `grafana_account_snapshots`  | `account_snapshots`              |
+| `grafana_position_snapshots` | `position_snapshots`             |
+| `grafana_order_snapshots`    | `order_snapshots`                |
+| `grafana_terminal_snapshots` | `terminal_snapshots`             |
+
+**Grafana static summary views** (no `time` column; use for table/stat panels, not time-series):
+
+| View                   | Source                                |
+| ---------------------- | ------------------------------------- |
+| `grafana_realized_pnl` | Cumulative realized PnL per symbol    |
+| `grafana_trade_stats`  | Win/loss counts and profit per symbol |
+
+Lower-level helpers (`ensure_grafana_schema`, `create_grafana_views`,
+`create_grafana_indexes`, `create_snapshot_tables`, `start_snapshot_run`,
+`insert_account_snapshot`, `insert_position_snapshots`, `insert_order_snapshots`,
+`insert_terminal_snapshot`, `record_snapshot_run`) are available directly from
+`mt5cli.grafana` and are not part of the package-root stable surface.
+
 ### Errors
 
 | Symbol                                                                     | Role                          |
@@ -135,14 +192,15 @@ and returned as `status="failed"` with normalized `request` / `response` details
 Lower-level helpers are available from their owning modules and are not part
 of the package-root stable surface. Import them directly when needed:
 
-| Module              | Examples                                                                                       |
-| ------------------- | ---------------------------------------------------------------------------------------------- |
-| `mt5cli.history`    | `resolve_rate_view_name`, `resolve_rate_tables`, `load_rate_data`, `build_rate_view_name`      |
-| `mt5cli.sdk`        | `copy_rates_from`, `copy_ticks_from`, `account_info`, `symbols`, `mt5_summary`, `latest_rates` |
-| `mt5cli.schemas`    | `DataKind`, `normalize_dataframe`, `validate_schema`, `DEDUP_KEYS`                             |
-| `mt5cli.utils`      | `Dataset`, `IfExists`, `detect_format`, `export_dataframe`, `export_dataframe_to_sqlite`       |
-| `mt5cli.converters` | `normalize_symbol`, `ensure_utc`, `parse_date_range`, `granularity_name`                       |
-| `mt5cli.exceptions` | `normalize_mt5_exception`, `call_with_normalized_errors`, `is_recoverable_mt5_error`           |
+| Module              | Examples                                                                                                                                                                    |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mt5cli.grafana`    | `ensure_grafana_schema`, `create_grafana_views`, `create_grafana_indexes`, `create_snapshot_tables`, `start_snapshot_run`, `insert_account_snapshot`, `record_snapshot_run` |
+| `mt5cli.history`    | `resolve_rate_view_name`, `resolve_rate_tables`, `load_rate_data`, `build_rate_view_name`                                                                                   |
+| `mt5cli.sdk`        | `copy_rates_from`, `copy_ticks_from`, `account_info`, `symbols`, `mt5_summary`, `latest_rates`                                                                              |
+| `mt5cli.schemas`    | `DataKind`, `normalize_dataframe`, `validate_schema`, `DEDUP_KEYS`                                                                                                          |
+| `mt5cli.utils`      | `Dataset`, `IfExists`, `detect_format`, `export_dataframe`, `export_dataframe_to_sqlite`                                                                                    |
+| `mt5cli.converters` | `normalize_symbol`, `ensure_utc`, `parse_date_range`, `granularity_name`                                                                                                    |
+| `mt5cli.exceptions` | `normalize_mt5_exception`, `call_with_normalized_errors`, `is_recoverable_mt5_error`                                                                                        |
 
 ## CLI commands
 
@@ -155,6 +213,15 @@ The Typer application in `mt5cli.cli` exposes file-export commands documented in
 - Delegate to the same Python APIs described here; they are not duplicated
   business logic.
 
+`grafana-schema` initializes Grafana views, indexes, and snapshot tables in the
+target SQLite database without connecting to MT5. It is idempotent and safe to
+run repeatedly.
+
+`snapshot` appends one timestamped row per enabled data type
+(`--with-account`, `--with-positions`, `--with-orders`, `--with-terminal`) and
+never places orders or modifies trading state. Both commands require
+`-o/--output` to point at a `.db` / SQLite file.
+
 `order-send` is the expert raw-request path; it requires `--yes` and a fully
 constructed request payload. `close-positions` is the safer high-level helper
 that closes open positions by `--symbol` or `--ticket` using

mt5cli-1.1.0/examples/grafana/README.md

@@ -0,0 +1,95 @@
+# Grafana Integration for mt5cli
+
+This directory contains example configuration and dashboard files for visualising
+mt5cli SQLite data in [Grafana](https://grafana.com/) using the
+[Grafana SQLite datasource plugin](https://grafana.com/grafana/plugins/frser-sqlite-datasource/).
+
+## Prerequisites
+
+- mt5cli installed and able to connect to MetaTrader 5
+- Grafana 10+ with the `frser-sqlite-datasource` plugin installed
+- (Optional) Docker and Docker Compose for the containerised setup
+
+## Generating the SQLite database
+
+Collect historical data and snapshot current account state:
+
+```sh
+# Collect OHLCV history
+mt5cli -o history.db collect-history --symbol EURUSD --date-from 2024-01-01 --date-to 2024-12-31
+
+# Create Grafana-ready views and indexes
+mt5cli -o history.db grafana-schema
+
+# Snapshot current account, positions, and orders
+mt5cli -o history.db snapshot --with-grafana-schema
+```
+
+## Publishing a Grafana-readable copy
+
+Grafana reads the SQLite file directly. To avoid read/write conflicts, publish
+a consistent copy after each update:
+
+```sh
+mt5cli -o history.db grafana-schema --publish-copy history.mt5cli.db
+mt5cli -o history.db snapshot --publish-copy history.mt5cli.db
+```
+
+The `--publish-copy` option uses the SQLite online backup API, which is safe
+even when the source database uses WAL journal mode.
+
+## Configuring the datasource path
+
+Edit `provisioning/datasources/mt5cli-sqlite.yml` and set the `path` field
+to the absolute path of your published `.db` file:
+
+```yaml
+jsonData:
+  path: /absolute/path/to/history.mt5cli.db
+```
+
+## Running Grafana on Windows (native)
+
+1. Download and install Grafana from <https://grafana.com/grafana/download/>.
+2. Install the SQLite plugin: `grafana-cli plugins install frser-sqlite-datasource`.
+3. Copy `provisioning/datasources/mt5cli-sqlite.yml` into
+   `%ProgramFiles%\GrafanaLabs\grafana\conf\provisioning\datasources\`.
+   Do not copy `provisioning/dashboards/mt5cli.yml` — it contains a
+   Docker-specific dashboard path that is not valid on Windows.
+4. Import the dashboards from `dashboards/` via the Grafana UI
+   (Dashboards → Import → Upload JSON file).
+
+## Running with Docker Compose
+
+Set `MT5CLI_DB_PATH` to the absolute path of your published `.db` file, then
+start the stack:
+
+```sh
+# From the examples/grafana directory
+MT5CLI_DB_PATH=/absolute/path/to/history.mt5cli.db docker compose up -d
+```
+
+Alternatively, create a `.env` file in `examples/grafana/` containing
+`MT5CLI_DB_PATH=/absolute/path/to/history.mt5cli.db` and run
+`docker compose up -d`. Compose refuses to start if the variable is unset or
+empty.
+
+Then open <http://localhost:3000> (default credentials: admin / admin).
+
+## Dashboard overview
+
+| Dashboard              | Description                                             |
+| ---------------------- | ------------------------------------------------------- |
+| `mt5cli-overview.json` | Account balance, equity, margin, and snapshot freshness |
+| `mt5cli-trades.json`   | Trade P/L, win rate, symbol breakdown                   |
+| `mt5cli-market.json`   | OHLCV rates, spreads, and tick volume                   |
+
+All panel queries use the `grafana_*` views; they do not read internal storage
+tables directly.
+
+## Importing dashboards
+
+1. Open Grafana and navigate to **Dashboards → Import**.
+2. Click **Upload JSON file** and select one of the files in `dashboards/`.
+3. Select the `mt5cli-SQLite` datasource when prompted.
+4. Click **Import**.

mt5cli-1.1.0/examples/grafana/compose.yml

@@ -0,0 +1,26 @@
+# Docker Compose for Grafana with mt5cli SQLite datasource.
+#
+# MT5CLI_DB_PATH must be set to the absolute host path of your published .db
+# file before running `docker compose up -d`. Compose will refuse to start if
+# the variable is missing or empty.
+#
+# Example:
+#   MT5CLI_DB_PATH=/home/user/history.mt5cli.db docker compose up -d
+
+services:
+  grafana:
+    image: grafana/grafana:latest
+    ports:
+      - "3000:3000"
+    environment:
+      GF_PATHS_PROVISIONING: /etc/grafana/provisioning
+      GF_INSTALL_PLUGINS: frser-sqlite-datasource
+    volumes:
+      - ./provisioning:/etc/grafana/provisioning:ro
+      - ./dashboards:/var/lib/grafana/dashboards:ro
+      - grafana-storage:/var/lib/grafana
+      - ${MT5CLI_DB_PATH:?Set MT5CLI_DB_PATH to the path of your published mt5cli SQLite DB}:/data/mt5cli.db:ro
+    user: "472"
+
+volumes:
+  grafana-storage: