quickbase-extract 0.2.0__tar.gz → 0.3.0__tar.gz

{quickbase_extract-0.2.0 → quickbase_extract-0.3.0}/.editorconfig

@@ -20,14 +20,6 @@ indent_style = space
 indent_size = 4
 max_line_length = 120
 
-# ============================================================
-# JavaScript / TypeScript
-# ============================================================
-[*.{js,jsx,ts,tsx}]
-indent_style = space
-indent_size = 2
-max_line_length = 120
-
 # ============================================================
 # JSON
 # ============================================================

{quickbase_extract-0.2.0 → quickbase_extract-0.3.0}/.gitignore

@@ -48,15 +48,6 @@ src/*.egg-info/
 *.log
 logs/
 
-# Database files
-*.db
-*.sqlite
-*.sqlite3
-
-# Node modules
-node_modules/
-npm-debug.log
-
 # IDE caches
 .idea/
 *.swp

{quickbase_extract-0.2.0 → quickbase_extract-0.3.0}/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-04-27
+
+### Added
+
+- `complete_cache_refresh()` function in `cache_sync` module for selective cache refresh in development
+- Support for granular cache refresh control:
+  - `force_all=True`: Refresh both metadata and data caches
+  - `force_metadata=True`: Refresh only metadata cache
+  - `force_data=True`: Refresh only data cache
+- Cache refresh workflow: clear /tmp → fetch fresh from Quickbase → update S3 → re-sync to /tmp
+- Manual development toggles in Lambda handlers for testing cache refresh without API changes
+- Comprehensive test suite for complete cache refresh functionality
+
+### Changed
+
+- Lambda workers can now force complete cache refresh for development/debugging by toggling code variables
+- Cache refresh strategy clarified: selective refresh based on what changed (metadata vs data)
+
+### Fixed
+
+- Dev workflow now supports forcing cache refresh without modifying Lambda event API
+- Ensures /tmp and S3 are synchronized after cache refresh operations
+
+## [0.2.1] - 2026-04-25
+
+### Fixed
+
+- `sync_from_s3()` now preserves S3 `LastModified` timestamps via `os.utime()`, so `get_cache_age_hours()` returns accurate ages after S3 restore (previously always returned ~0 on Lambda cold start)
+- Renamed misleading `should_sync` variable to `already_synced` in `sync_from_s3_once()` for clarity
+
+### Removed
+
+- `FORCE_CACHE_REFRESH` environment variable support from `sync_from_s3_once()` — use `force=True` parameter instead
+
 ## [0.2.0] - 2026-04-22
 
 ### Added

{quickbase_extract-0.2.0 → quickbase_extract-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickbase-extract
-Version: 0.2.0
+Version: 0.3.0
 Summary: Extract and cache Quickbase report data with built-in error handling and S3 support
 Project-URL: Homepage, https://github.com/tbrezler/quickbase-extract
 Project-URL: Repository, https://github.com/tbrezler/quickbase-extract.git
@@ -882,7 +882,6 @@ s3://mit-bio-quickbase/my_project/dev/cache/report_metadata/...
 | `CACHE_BUCKET` | S3 bucket for Lambda cache | - |
 | `METADATA_STALE_HOURS` | Threshold (hours) for metadata cache staleness | `168` (7 days) |
 | `DATA_STALE_HOURS` | Threshold (hours) for data cache staleness | `24` (1 day) |
-| `FORCE_CACHE_REFRESH` | If set to "true", forces cache refresh on next sync | - |
 
 ### Custom Cache Location
 
@@ -956,10 +955,30 @@ def lambda_handler(event, context):
     - Cold start: Syncs cache from S3
     - Cache freshness: Auto-refreshes if stale
     - Data fetching: Queries Quickbase and caches results
+    - Development: Supports forcing complete cache refresh for testing
     """
     client = get_client()
     cache_mgr = get_cache_manager()
 
+    # OPTIONAL: Set to True to force cache refresh (for development/debugging only)
+    # Only one should be True at a time. force_all overrides the others.
+    FORCE_COMPLETE_CACHE_REFRESH_ALL = False
+    FORCE_COMPLETE_CACHE_REFRESH_METADATA = False
+    FORCE_COMPLETE_CACHE_REFRESH_DATA = False
+
+    # Force complete cache refresh if needed (dev/debugging only)
+    if (FORCE_COMPLETE_CACHE_REFRESH_ALL or FORCE_COMPLETE_CACHE_REFRESH_METADATA
+            or FORCE_COMPLETE_CACHE_REFRESH_DATA):
+        from quickbase_extract import complete_cache_refresh
+        complete_cache_refresh(
+            cache_manager=cache_mgr,
+            client=client,
+            report_configs=get_all_reports(),
+            force_all=FORCE_COMPLETE_CACHE_REFRESH_ALL,
+            force_metadata=FORCE_COMPLETE_CACHE_REFRESH_METADATA,
+            force_data=FORCE_COMPLETE_CACHE_REFRESH_DATA,
+        )
+
     # Step 1: Sync cache from S3 on cold start (only on first invocation)
     sync_from_s3_once(cache_mgr)
 
@@ -1265,7 +1284,6 @@ Checks metadata and data caches independently. Refreshes only the caches that ar
 **Environment Variables:**
 - `METADATA_STALE_HOURS`: Override default metadata staleness threshold (in hours)
 - `DATA_STALE_HOURS`: Override default data staleness threshold (in hours)
-- `FORCE_ALL_CACHE_REFRESH`: Set to "true" to force refresh regardless of cache state
 
 **Returns:** None
 
@@ -1565,6 +1583,48 @@ def lambda_handler(event, context):
     metadata = load_report_metadata_batch(cache_mgr, config)
 ```
 
+#### `complete_cache_refresh(cache_manager, client, report_configs, force_all=False, force_metadata=False, force_data=False)`
+
+Completely refresh cache for development/debugging: clear /tmp, fetch fresh from Quickbase, update S3, re-sync to /tmp.
+
+This is a development utility for forcing a complete cache refresh when report metadata or configurations change. Clears local /tmp cache, fetches fresh data from Quickbase, writes to S3, and re-syncs to /tmp.
+
+**Parameters:**
+- `cache_manager` (CacheManager): Cache manager instance
+- `client`: Quickbase API client for fetching fresh data
+- `report_configs` (list[ReportConfig]): List of all ReportConfig instances to refresh
+- `force_all` (bool): If True, refresh both metadata and data. Defaults to False.
+- `force_metadata` (bool): If True (and `force_all` is False), refresh only metadata. Defaults to False.
+- `force_data` (bool): If True (and `force_all` is False), refresh only data. Defaults to False.
+
+**Returns:** None
+
+**Raises:**
+- `Exception`: If cache clearing or refresh operations fail
+
+**Example:**
+```python
+from quickbase_extract import complete_cache_refresh
+
+# Refresh only metadata (after changing report configurations)
+complete_cache_refresh(
+    cache_manager=cache_mgr,
+    client=qb_client,
+    report_configs=get_all_reports(),
+    force_metadata=True
+)
+
+# Refresh all (metadata + data)
+complete_cache_refresh(
+    cache_manager=cache_mgr,
+    client=qb_client,
+    report_configs=get_all_reports(),
+    force_all=True
+)
+```
+
+**Note:** This function is designed for development/debugging. To use in Lambda, add toggles to your handler (see "Development/Debug Mode" section below).
+
 ### Query Execution with Retry Logic
 
 #### `handle_query(client, table_id, *, select=None, where=None, sort_by=None, group_by=None, options=None, description="", max_retries=3)`
@@ -2108,43 +2168,6 @@ fields = info["fields"]
 
 ---
 
-### Issue: "FORCE_CACHE_REFRESH not working"
-
-**Symptom:** Set `FORCE_CACHE_REFRESH=true` but cache still not refreshing.
-
-**Cause:** Environment variable case-sensitive or not set correctly.
-
-**Solution:**
-
-1. **Verify env var is set (case-sensitive):**
-   ```bash
-   # Must be exactly this (uppercase)
-   export FORCE_ALL_CACHE_REFRESH=true
-
-   # Not these (wrong):
-   export force_cache_refresh=true
-   export Force_Cache_Refresh=true
-   ```
-
-2. **Verify it's being read:**
-   ```python
-   import os
-   print(os.environ.get("FORCE_ALL_CACHE_REFRESH"))  # Should print "true"
-   ```
-
-3. **Use programmatic force instead:**
-   ```python
-   ensure_cache_freshness(
-       client=client,
-       cache_manager=cache_mgr,
-       report_configs_all=get_all_reports(),
-       report_configs_to_cache=get_reports_to_cache(),
-       force_all=True  # Programmatic force (always works)
-   )
-   ```
-
----
-
 ### Issue: Data fetch returns empty or different results
 
 **Symptom:** `get_data()` returns empty list or fewer records than expected.
@@ -2282,6 +2305,47 @@ ask_values = {"ask1": "value"}    # No underscores
 
 ---
 
+### Issue: Lambda has old cached data after I changed report metadata
+
+**Symptom:** You updated a Quickbase report's fields, filters, or configuration, but your Lambda returns stale data.
+
+**Cause:** Cache was loaded before your changes, and it hasn't become "stale" enough to auto-refresh yet.
+
+**Solutions:**
+
+1. **Quick fix: Use force refresh toggle (development only)**
+
+   In your Lambda handler, temporarily set:
+   ```python
+   FORCE_COMPLETE_CACHE_REFRESH_METADATA = True
+   ```
+
+   Upload new build, invoke Lambda, check logs for refresh. Then revert flag to `False`.
+
+2. **For immediate production fix:**
+
+   Manually delete files from S3:
+   ```bash
+   aws s3 rm s3://my-quickbase-cache-bucket/prod/cache/report_metadata/ --recursive
+   ```
+
+   Next Lambda cold start will re-fetch fresh metadata.
+
+3. **To prevent in future:**
+
+   Reduce `metadata_stale_hours` threshold:
+   ```python
+   ensure_cache_freshness(
+       client=client,
+       cache_manager=cache_mgr,
+       report_configs_all=get_all_reports(),
+       report_configs_to_cache=get_reports_to_cache(),
+       metadata_stale_hours=24  # Check daily instead of 30 days
+   )
+   ```
+
+---
+
 ### Issue: Performance degradation over time
 
 **Symptom:** First request fast, subsequent requests slow.
@@ -2453,23 +2517,6 @@ ensure_cache_freshness(
 )
 ```
 
-#### Environment Variable Force
-
-Set `FORCE_ALL_CACHE_REFRESH=true` before invoking:
-
-```bash
-# In Lambda environment variables or shell
-export FORCE_ALL_CACHE_REFRESH=true
-
-# Then call normally (will force refresh automatically)
-ensure_cache_freshness(
-    client=client,
-    cache_manager=cache_mgr,
-    report_configs_all=get_all_reports(),
-    report_configs_to_cache=get_reports_to_cache()
-)
-```
-
 ### Cache-All-Data Mode
 
 For production, cache data for all reports instead of a subset:
@@ -2678,6 +2725,95 @@ def scheduled_cache_refresh(event, context):
     return {"statusCode": 200, "message": "Cache refreshed"}
 ```
 
+### Development/Debug Mode: Forcing Complete Cache Refresh
+
+When you modify report metadata or configurations in Quickbase, your Lambda may still use stale cached data. Use the force refresh toggles to clear everything and fetch fresh data.
+
+#### When to Use
+
+- You changed a report's filters or fields in Quickbase
+- You added/removed fields from a report
+- You renamed a report or table
+- You need to verify fresh data is being fetched
+
+#### How to Use
+
+1. Open your Lambda handler code
+2. Set one of the toggle flags to `True`:
+
+```python
+# In lambda_handler, find these lines:
+FORCE_COMPLETE_CACHE_REFRESH_ALL = False
+FORCE_COMPLETE_CACHE_REFRESH_METADATA = False
+FORCE_COMPLETE_CACHE_REFRESH_DATA = False
+
+# Change to (example: refresh only metadata):
+FORCE_COMPLETE_CACHE_REFRESH_METADATA = True
+```
+
+3. Upload new Lambda build
+4. Invoke your Lambda (via API or CloudWatch event)
+5. Check CloudWatch logs for cache refresh messages
+6. **Revert the flag back to `False`** for normal operation
+
+#### Flag Options
+
+| Flag | What Gets Refreshed | Use When |
+|------|---------------------|----------|
+| `force_all=True` | Both metadata + data | Complete cache overhaul needed |
+| `force_metadata=True` | Only metadata | Report configuration changed |
+| `force_data=True` | Only data | Data needs fresh pull |
+
+#### What Happens
+
+When you trigger a force refresh:
+
+1. ✓ `/tmp` cache directories are deleted
+2. ✓ Fresh data fetched from Quickbase API
+3. ✓ Data written to S3
+4. ✓ `/tmp` re-synced from updated S3
+
+Your Lambda now has fresh data from Quickbase.
+
+#### Example
+
+```python
+def lambda_handler(event, context):
+    client = get_client()
+    cache_mgr = get_cache_manager()
+
+    # Metadata changed in Quickbase? Force refresh it:
+    FORCE_COMPLETE_CACHE_REFRESH_METADATA = True  # ← Toggle this
+
+    if (FORCE_COMPLETE_CACHE_REFRESH_ALL or FORCE_COMPLETE_CACHE_REFRESH_METADATA
+            or FORCE_COMPLETE_CACHE_REFRESH_DATA):
+        from quickbase_extract import complete_cache_refresh
+        complete_cache_refresh(
+            cache_manager=cache_mgr,
+            client=client,
+            report_configs=get_all_reports(),
+            force_metadata=FORCE_COMPLETE_CACHE_REFRESH_METADATA,
+        )
+
+    # Rest of handler...
+```
+
+**CloudWatch logs will show:**
+```
+WARNING: Starting complete cache refresh for: metadata (clearing /tmp, refreshing from Quickbase, updating S3...)
+DEBUG: Reset cache sync flag
+INFO: Fetching fresh data from Quickbase...
+INFO: Re-syncing /tmp from S3...
+WARNING: Complete cache refresh finished for metadata: /tmp and S3 now have fresh data from Quickbase
+```
+
+#### Important Notes
+
+- **Don't leave toggles set to `True`** — revert to `False` after testing
+- **Only for development** — not a production workflow
+- Logs will show exactly what was refreshed
+- Safe to use — doesn't affect running processes, only next Lambda invocation
+
 ## Advanced Usage
 
 ### Custom Report Configurations

{quickbase_extract-0.2.0 → quickbase_extract-0.3.0}/README.md

@@ -855,7 +855,6 @@ s3://mit-bio-quickbase/my_project/dev/cache/report_metadata/...
 | `CACHE_BUCKET` | S3 bucket for Lambda cache | - |
 | `METADATA_STALE_HOURS` | Threshold (hours) for metadata cache staleness | `168` (7 days) |
 | `DATA_STALE_HOURS` | Threshold (hours) for data cache staleness | `24` (1 day) |
-| `FORCE_CACHE_REFRESH` | If set to "true", forces cache refresh on next sync | - |
 
 ### Custom Cache Location
 
@@ -929,10 +928,30 @@ def lambda_handler(event, context):
     - Cold start: Syncs cache from S3
     - Cache freshness: Auto-refreshes if stale
     - Data fetching: Queries Quickbase and caches results
+    - Development: Supports forcing complete cache refresh for testing
     """
     client = get_client()
     cache_mgr = get_cache_manager()
 
+    # OPTIONAL: Set to True to force cache refresh (for development/debugging only)
+    # Only one should be True at a time. force_all overrides the others.
+    FORCE_COMPLETE_CACHE_REFRESH_ALL = False
+    FORCE_COMPLETE_CACHE_REFRESH_METADATA = False
+    FORCE_COMPLETE_CACHE_REFRESH_DATA = False
+
+    # Force complete cache refresh if needed (dev/debugging only)
+    if (FORCE_COMPLETE_CACHE_REFRESH_ALL or FORCE_COMPLETE_CACHE_REFRESH_METADATA
+            or FORCE_COMPLETE_CACHE_REFRESH_DATA):
+        from quickbase_extract import complete_cache_refresh
+        complete_cache_refresh(
+            cache_manager=cache_mgr,
+            client=client,
+            report_configs=get_all_reports(),
+            force_all=FORCE_COMPLETE_CACHE_REFRESH_ALL,
+            force_metadata=FORCE_COMPLETE_CACHE_REFRESH_METADATA,
+            force_data=FORCE_COMPLETE_CACHE_REFRESH_DATA,
+        )
+
     # Step 1: Sync cache from S3 on cold start (only on first invocation)
     sync_from_s3_once(cache_mgr)
 
@@ -1238,7 +1257,6 @@ Checks metadata and data caches independently. Refreshes only the caches that ar
 **Environment Variables:**
 - `METADATA_STALE_HOURS`: Override default metadata staleness threshold (in hours)
 - `DATA_STALE_HOURS`: Override default data staleness threshold (in hours)
-- `FORCE_ALL_CACHE_REFRESH`: Set to "true" to force refresh regardless of cache state
 
 **Returns:** None
 
@@ -1538,6 +1556,48 @@ def lambda_handler(event, context):
     metadata = load_report_metadata_batch(cache_mgr, config)
 ```
 
+#### `complete_cache_refresh(cache_manager, client, report_configs, force_all=False, force_metadata=False, force_data=False)`
+
+Completely refresh cache for development/debugging: clear /tmp, fetch fresh from Quickbase, update S3, re-sync to /tmp.
+
+This is a development utility for forcing a complete cache refresh when report metadata or configurations change. Clears local /tmp cache, fetches fresh data from Quickbase, writes to S3, and re-syncs to /tmp.
+
+**Parameters:**
+- `cache_manager` (CacheManager): Cache manager instance
+- `client`: Quickbase API client for fetching fresh data
+- `report_configs` (list[ReportConfig]): List of all ReportConfig instances to refresh
+- `force_all` (bool): If True, refresh both metadata and data. Defaults to False.
+- `force_metadata` (bool): If True (and `force_all` is False), refresh only metadata. Defaults to False.
+- `force_data` (bool): If True (and `force_all` is False), refresh only data. Defaults to False.
+
+**Returns:** None
+
+**Raises:**
+- `Exception`: If cache clearing or refresh operations fail
+
+**Example:**
+```python
+from quickbase_extract import complete_cache_refresh
+
+# Refresh only metadata (after changing report configurations)
+complete_cache_refresh(
+    cache_manager=cache_mgr,
+    client=qb_client,
+    report_configs=get_all_reports(),
+    force_metadata=True
+)
+
+# Refresh all (metadata + data)
+complete_cache_refresh(
+    cache_manager=cache_mgr,
+    client=qb_client,
+    report_configs=get_all_reports(),
+    force_all=True
+)
+```
+
+**Note:** This function is designed for development/debugging. To use in Lambda, add toggles to your handler (see "Development/Debug Mode" section below).
+
 ### Query Execution with Retry Logic
 
 #### `handle_query(client, table_id, *, select=None, where=None, sort_by=None, group_by=None, options=None, description="", max_retries=3)`
@@ -2081,43 +2141,6 @@ fields = info["fields"]
 
 ---
 
-### Issue: "FORCE_CACHE_REFRESH not working"
-
-**Symptom:** Set `FORCE_CACHE_REFRESH=true` but cache still not refreshing.
-
-**Cause:** Environment variable case-sensitive or not set correctly.
-
-**Solution:**
-
-1. **Verify env var is set (case-sensitive):**
-   ```bash
-   # Must be exactly this (uppercase)
-   export FORCE_ALL_CACHE_REFRESH=true
-
-   # Not these (wrong):
-   export force_cache_refresh=true
-   export Force_Cache_Refresh=true
-   ```
-
-2. **Verify it's being read:**
-   ```python
-   import os
-   print(os.environ.get("FORCE_ALL_CACHE_REFRESH"))  # Should print "true"
-   ```
-
-3. **Use programmatic force instead:**
-   ```python
-   ensure_cache_freshness(
-       client=client,
-       cache_manager=cache_mgr,
-       report_configs_all=get_all_reports(),
-       report_configs_to_cache=get_reports_to_cache(),
-       force_all=True  # Programmatic force (always works)
-   )
-   ```
-
----
-
 ### Issue: Data fetch returns empty or different results
 
 **Symptom:** `get_data()` returns empty list or fewer records than expected.
@@ -2255,6 +2278,47 @@ ask_values = {"ask1": "value"}    # No underscores
 
 ---
 
+### Issue: Lambda has old cached data after I changed report metadata
+
+**Symptom:** You updated a Quickbase report's fields, filters, or configuration, but your Lambda returns stale data.
+
+**Cause:** Cache was loaded before your changes, and it hasn't become "stale" enough to auto-refresh yet.
+
+**Solutions:**
+
+1. **Quick fix: Use force refresh toggle (development only)**
+
+   In your Lambda handler, temporarily set:
+   ```python
+   FORCE_COMPLETE_CACHE_REFRESH_METADATA = True
+   ```
+
+   Upload new build, invoke Lambda, check logs for refresh. Then revert flag to `False`.
+
+2. **For immediate production fix:**
+
+   Manually delete files from S3:
+   ```bash
+   aws s3 rm s3://my-quickbase-cache-bucket/prod/cache/report_metadata/ --recursive
+   ```
+
+   Next Lambda cold start will re-fetch fresh metadata.
+
+3. **To prevent in future:**
+
+   Reduce `metadata_stale_hours` threshold:
+   ```python
+   ensure_cache_freshness(
+       client=client,
+       cache_manager=cache_mgr,
+       report_configs_all=get_all_reports(),
+       report_configs_to_cache=get_reports_to_cache(),
+       metadata_stale_hours=24  # Check daily instead of 30 days
+   )
+   ```
+
+---
+
 ### Issue: Performance degradation over time
 
 **Symptom:** First request fast, subsequent requests slow.
@@ -2426,23 +2490,6 @@ ensure_cache_freshness(
 )
 ```
 
-#### Environment Variable Force
-
-Set `FORCE_ALL_CACHE_REFRESH=true` before invoking:
-
-```bash
-# In Lambda environment variables or shell
-export FORCE_ALL_CACHE_REFRESH=true
-
-# Then call normally (will force refresh automatically)
-ensure_cache_freshness(
-    client=client,
-    cache_manager=cache_mgr,
-    report_configs_all=get_all_reports(),
-    report_configs_to_cache=get_reports_to_cache()
-)
-```
-
 ### Cache-All-Data Mode
 
 For production, cache data for all reports instead of a subset:
@@ -2651,6 +2698,95 @@ def scheduled_cache_refresh(event, context):
     return {"statusCode": 200, "message": "Cache refreshed"}
 ```
 
+### Development/Debug Mode: Forcing Complete Cache Refresh
+
+When you modify report metadata or configurations in Quickbase, your Lambda may still use stale cached data. Use the force refresh toggles to clear everything and fetch fresh data.
+
+#### When to Use
+
+- You changed a report's filters or fields in Quickbase
+- You added/removed fields from a report
+- You renamed a report or table
+- You need to verify fresh data is being fetched
+
+#### How to Use
+
+1. Open your Lambda handler code
+2. Set one of the toggle flags to `True`:
+
+```python
+# In lambda_handler, find these lines:
+FORCE_COMPLETE_CACHE_REFRESH_ALL = False
+FORCE_COMPLETE_CACHE_REFRESH_METADATA = False
+FORCE_COMPLETE_CACHE_REFRESH_DATA = False
+
+# Change to (example: refresh only metadata):
+FORCE_COMPLETE_CACHE_REFRESH_METADATA = True
+```
+
+3. Upload new Lambda build
+4. Invoke your Lambda (via API or CloudWatch event)
+5. Check CloudWatch logs for cache refresh messages
+6. **Revert the flag back to `False`** for normal operation
+
+#### Flag Options
+
+| Flag | What Gets Refreshed | Use When |
+|------|---------------------|----------|
+| `force_all=True` | Both metadata + data | Complete cache overhaul needed |
+| `force_metadata=True` | Only metadata | Report configuration changed |
+| `force_data=True` | Only data | Data needs fresh pull |
+
+#### What Happens
+
+When you trigger a force refresh:
+
+1. ✓ `/tmp` cache directories are deleted
+2. ✓ Fresh data fetched from Quickbase API
+3. ✓ Data written to S3
+4. ✓ `/tmp` re-synced from updated S3
+
+Your Lambda now has fresh data from Quickbase.
+
+#### Example
+
+```python
+def lambda_handler(event, context):
+    client = get_client()
+    cache_mgr = get_cache_manager()
+
+    # Metadata changed in Quickbase? Force refresh it:
+    FORCE_COMPLETE_CACHE_REFRESH_METADATA = True  # ← Toggle this
+
+    if (FORCE_COMPLETE_CACHE_REFRESH_ALL or FORCE_COMPLETE_CACHE_REFRESH_METADATA
+            or FORCE_COMPLETE_CACHE_REFRESH_DATA):
+        from quickbase_extract import complete_cache_refresh
+        complete_cache_refresh(
+            cache_manager=cache_mgr,
+            client=client,
+            report_configs=get_all_reports(),
+            force_metadata=FORCE_COMPLETE_CACHE_REFRESH_METADATA,
+        )
+
+    # Rest of handler...
+```
+
+**CloudWatch logs will show:**
+```
+WARNING: Starting complete cache refresh for: metadata (clearing /tmp, refreshing from Quickbase, updating S3...)
+DEBUG: Reset cache sync flag
+INFO: Fetching fresh data from Quickbase...
+INFO: Re-syncing /tmp from S3...
+WARNING: Complete cache refresh finished for metadata: /tmp and S3 now have fresh data from Quickbase
+```
+
+#### Important Notes
+
+- **Don't leave toggles set to `True`** — revert to `False` after testing
+- **Only for development** — not a production workflow
+- Logs will show exactly what was refreshed
+- Safe to use — doesn't affect running processes, only next Lambda invocation
+
 ## Advanced Usage
 
 ### Custom Report Configurations

{quickbase_extract-0.2.0 → quickbase_extract-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickbase-extract"
-version = "0.2.0"
+version = "0.3.0"
 description = "Extract and cache Quickbase report data with built-in error handling and S3 support"
 readme = "README.md"
 requires-python = ">=3.12"