7552cdfd57
- test_db_connection.py: 5-stage DB connection test (TCP, auth, schema, data, db.py integration) - read_candles.py: Read 1m candles with --all, --[symbol], --timestamp support - README.md: Usage instructions for testing scripts - .env.example: Template for connection configuration Default symbols updated to match LiveCandleFetcher subscriptions (BNB, ETH, xyz:GOLD, etc.) Colon-containing symbols handled via db.sanitize_table_name()
144 lines
4.0 KiB
Markdown
144 lines
4.0 KiB
Markdown
# Candle Reader - Testing Instructions
|
|
|
|
## Overview
|
|
|
|
`read_candles.py` is a test script that reads 1m candle data from the PostgreSQL database running in Docker on the Synology NAS (`20.20.20.20`).
|
|
|
|
## Prerequisites
|
|
|
|
1. **Python 3.11+** with `psycopg2-binary` installed:
|
|
```bash
|
|
pip install psycopg2-binary
|
|
```
|
|
|
|
2. **Network access** to the NAS at `20.20.20.20` on port `5433`.
|
|
|
|
3. **Docker containers running** on the NAS:
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Connection parameters are loaded from `testing/.env` (git-ignored). Copy from the example if needed:
|
|
|
|
```bash
|
|
cp testing/.env.example testing/.env
|
|
```
|
|
|
|
Edit `testing/.env` to match your NAS setup:
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `PG_HOST` | `20.20.20.20` | NAS IP address |
|
|
| `PG_PORT` | `5433` | PostgreSQL port (host) |
|
|
| `PG_DB` | `hyper` | Database name |
|
|
| `PG_USER` | `hyper` | Database user |
|
|
| `PG_PASSWORD` | `kaqpaaoi0` | Database password |
|
|
| `PG_TIMEOUT` | `10` | Connection timeout (seconds) |
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
python testing/read_candles.py [OPTIONS] [--SYMBOL ...]
|
|
```
|
|
|
|
### Options
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--all` | List last candles for **all** symbols (411+ tables) |
|
|
| `--timestamp DD-MM-YY` | List nearest candle to the given date (start of day) |
|
|
| `--timestamp "DD-MM-YY HH:mm"` | List nearest candle to the given date and time |
|
|
| `-h, --help` | Show help message |
|
|
|
|
### Dynamic Symbol Flags
|
|
|
|
Any `--SYMBOL` flag filters to that specific symbol(s). Multiple symbols can be combined.
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--BTC` | Only BTC candles |
|
|
| `--BTC --ETH` | BTC and ETH candles only |
|
|
| `--xyz:GOLD` | Only xyz:GOLD candles (colon symbols supported) |
|
|
| `--xyz:BRENTOIL` | Only xyz:BRENTOIL candles |
|
|
|
|
### Default Behavior
|
|
|
|
With no flags, the script reads the last 1m candle for 12 default symbols:
|
|
`BNB`, `ETH`, `xyz:GOLD`, `xyz:SILVER`, `SUI`, `xyz:BRENTOIL`, `mkts:USTECH`, `xyz:CL`, `xyz:XYZ100`, `HYPE`, `SOL`, `BTC`
|
|
|
|
Symbols containing colons (e.g., `xyz:GOLD`) are automatically sanitized to PostgreSQL-safe table names (e.g., `xyz_GOLD_1m`).
|
|
|
|
## Examples
|
|
|
|
### 1. Last candles for 12 default symbols
|
|
```bash
|
|
python testing/read_candles.py
|
|
```
|
|
|
|
### 2. Last candles for all symbols
|
|
```bash
|
|
python testing/read_candles.py --all
|
|
```
|
|
|
|
### 3. Last candle for a single symbol
|
|
```bash
|
|
python testing/read_candles.py --BTC
|
|
```
|
|
|
|
### 4. Last candles for multiple symbols
|
|
```bash
|
|
python testing/read_candles.py --BTC --ETH --SOL
|
|
```
|
|
|
|
### 5. Last candles for colon-containing symbols
|
|
```bash
|
|
python testing/read_candles.py --xyz:GOLD --xyz:BRENTOIL
|
|
```
|
|
|
|
### 5. Nearest candle to a date (start of day)
|
|
```bash
|
|
python testing/read_candles.py --BTC --timestamp 05-08-26
|
|
```
|
|
|
|
### 6. Nearest candle to a date and time
|
|
```bash
|
|
python testing/read_candles.py --BTC --timestamp "05-08-26 13:30"
|
|
```
|
|
|
|
### 7. Combine --all with --timestamp
|
|
```bash
|
|
python testing/read_candles.py --all --timestamp "05-08-26 13:15"
|
|
```
|
|
|
|
## Output Format
|
|
|
|
```
|
|
======================================================================
|
|
Last 1m Candles - default 12 symbols
|
|
======================================================================
|
|
BTC | 2026-08-05 13:15:00 | 1785935700000 | O=64116.00 H=64116.00 L=64096.00 C=64104.00 | Vol=2.19
|
|
ETH | 2026-08-05 13:15:00 | 1785935700000 | O=1868.00 H=1868.00 L=1867.50 C=1867.60 | Vol=32.26
|
|
...
|
|
======================================================================
|
|
```
|
|
|
|
Columns: `Symbol | datetime_utc | timestamp_ms | O(open) H(high) L(low) C(close) | Vol(volume)`
|
|
|
|
## Troubleshooting
|
|
|
|
### Connection refused
|
|
- Ensure Docker containers are running: `docker-compose up -d`
|
|
- Check NAS firewall allows port 5433
|
|
- Verify `PG_HOST` in `testing/.env`
|
|
|
|
### No data for a symbol
|
|
- The symbol may not have a table (e.g., `MATIC_1m` may not exist)
|
|
- Use `--all` to see which tables are available
|
|
- Ensure the symbol name matches exactly (case-sensitive, colons included)
|
|
|
|
### Invalid timestamp format
|
|
- Use `DD-MM-YY` (e.g., `05-08-26`)
|
|
- Or `"DD-MM-YY HH:mm"` (e.g., `"05-08-26 13:30"`)
|