docs: add best practice section to contribution guide

website/docs/development.md

@@ -140,3 +140,61 @@ The Grafana VS Code extension allows you to open Grafana dashboards as JSON file
 - From the editor UI, save the updated dashboard back to the original JSON file
 
 see: [grafana-vs-code-extension](https://github.com/grafana/grafana-vs-code-extension)
+
+## Best Practices
+
+### Queries involving timestamp columns
+
+Datetime values are currently stored in columns of type `timestamp`. [This is NOT recommended](https://wiki.postgresql.org/wiki/Don't_Do_This#Don.27t_use_timestamp_.28without_time_zone.29_to_store_UTC_times).
+
+While [Grafana macros](https://grafana.com/docs/grafana/latest/datasources/postgres/#macros) like `$__timeFilter` & `$__timeGroup` are working PostgreSQL functions like `DATE_TRUNC()` require additional treatment.
+
+```sql
+DATE_TRUNC('day', TIMEZONE('UTC', date))
+```
+
+In addition ensure to compare either values with or without time zone.
+
+### Streaming API data / positions table usage in dashboard queries
+
+When Streaming API is enabled roughly 1 GB of data is gathered per car and 30.000km. Most of that data (95+ percent) is stored in positions table. For optimal dashboard performance these recommendations should be followed:
+
+- only query positions table when really needed
+- if data in 15 second intervals is sufficient consider excluding streaming data by adding `ideal_battery_range_km IS NOT NULL and car_id = $car_id` as WHERE conditions
+
+Before opening pull requests please diagnose index usage & query performance by making use of `EXPLAIN ANALYZE`.
+
+### Enable _pg_stat_statements_ to collect query statistics
+
+To quickly identify performance bottlenecks we encourage all contributors to enable the pg_stat_statements extension in their instance. For docker based installs you can follow these steps:
+
+- Enable the pg_stat_statements module
+
+  ```yml
+  services:
+    database:
+      image: postgres:17
+      ...
+      command: postgres -c shared_preload_libraries=pg_stat_statements
+      ...
+  ```
+
+- Create Extension to enable `pg_stat_statements` view
+
+  ```sql
+  CREATE EXTENSION IF NOT EXISTS `pg_stat_statements`;
+  ```
+
+- Identify potentially slow queries (mean_exec_time)
+
+  ```sql
+  SELECT query, calls, mean_exec_time, total_exec_time FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;
+  ```
+
+- Identify frequently executed queries (calls)
+
+  ```sql
+  SELECT query, calls, mean_exec_time, total_exec_time FROM pg_stat_statements ORDER BY calls DESC LIMIT 10;
+  ```
+
+Additional details about pg_stat_statements can be found here: https://www.postgresql.org/docs/current/pgstatstatements.html