From e708e418ba19b43bfd8b5d2421939b08faa776d6 Mon Sep 17 00:00:00 2001
From: Danny Groenewegen <danny@ecommons.space>
Date: Thu, 29 Oct 2026 10:43:08 +0100
Subject: [PATCH] feat: opt-in Loki index store migration from deprecated
 boltdb-shipper to TSDB

boltdb-shipper is deprecated and will be removed in Loki 4.0.
Setting LOKI_TSDB_FROM_DATE adds a second schema_config period (store:
tsdb) from that date onward, alongside the existing boltdb-shipper
period, so logs before the cutover stay queryable under the old store
while new logs are indexed with TSDB.
---
 .env.sample      |  6 ++++++
 README.md        | 12 ++++++++++++
 abra.sh          |  2 +-
 compose.loki.yml |  1 +
 loki.yml.tmpl    | 30 +++++++++++++++++++++++++++++-
 release/next     |  1 +
 6 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100644 release/next

diff --git a/.env.sample b/.env.sample
index 6da93e3..6cbf978 100644
--- a/.env.sample
+++ b/.env.sample
@@ -79,6 +79,12 @@ SECRET_BASIC_AUTH_VERSION=v1
 # LOKI_RETENTION_PERIOD=744h
 # LOKI_STORAGE_FILESYSTEM=1
 #
+# Opt in to migrating the deprecated boltdb-shipper index store to TSDB, from this date
+# onward (YYYY-MM-DD). MUST be a FUTURE date, e.g. the day after you deploy this: a past
+# or same-day date makes both stores claim that day's data, breaking queries for it.
+# Logs from before this date are still ingested and queried from boltdb-shipper.
+# LOKI_TSDB_FROM_DATE=2026-11-01
+#
 ## S3 Storage
 # LOKI_STORAGE_S3=1
 # LOKI_AWS_ENDPOINT=https://minio.autonomic.zone
diff --git a/README.md b/README.md
index 93d9b97..8e59814 100644
--- a/README.md
+++ b/README.md
@@ -130,6 +130,18 @@ $ echo '{
 $ systemctl restart docker.service
 ```
 
+### Upgrading: Loki TSDB migration
+
+Loki's index store defaults to `boltdb-shipper`, which is deprecated upstream in favour of
+TSDB. To migrate an existing deployment without losing access to already-ingested logs, set
+`LOKI_TSDB_FROM_DATE` in your `.env` (see `.env.sample`) to a date on or after the day after
+your deploy, then `abra app deploy`. Logs from before that date stay on boltdb-shipper and
+remain queryable as before; only logs from that date onward are indexed with TSDB.
+
+**The date must be in the future when you deploy it, never today or earlier**: both stores share the same
+per-day table, so a past or same-day date makes them collide over that day's data and
+breaks querying it.
+
 ### Setup Push Gateway
 
 1. Enable in the env file by uncommenting the following lines:
diff --git a/abra.sh b/abra.sh
index 2bf76f2..d067d49 100644
--- a/abra.sh
+++ b/abra.sh
@@ -5,7 +5,7 @@ export GF_STACKS_DASH_VERSION=v3
 export GF_TRAEFIK_DASH_VERSION=v3
 export GF_BACKUP_DASH_VERSION=v1
 export GF_CUSTOM_INI_VERSION=v4
-export LOKI_YML_VERSION=v3
+export LOKI_YML_VERSION=v4
 export PROMETHEUS_YML_VERSION=v2
 export MATRIX_ALERTMANAGER_CONFIG_VERSION=v1
 export MATRIX_ALERTMANAGER_ENTRYPOINT_VERSION=v1
diff --git a/compose.loki.yml b/compose.loki.yml
index 8c2aa66..5ee915f 100644
--- a/compose.loki.yml
+++ b/compose.loki.yml
@@ -22,6 +22,7 @@ services:
       - STACK_NAME
       - LOKI_STORAGE_FILESYSTEM
       - LOKI_STORAGE_S3
+      - LOKI_TSDB_FROM_DATE
     deploy:
       restart_policy:
         condition: on-failure
diff --git a/loki.yml.tmpl b/loki.yml.tmpl
index e399700..6000f76 100644
--- a/loki.yml.tmpl
+++ b/loki.yml.tmpl
@@ -56,12 +56,26 @@ schema_config:
       index:
         prefix: index_
         period: 24h
+{{ if env "LOKI_TSDB_FROM_DATE" }}
+    - from: {{ env "LOKI_TSDB_FROM_DATE" }}
+      store: tsdb
+      object_store: filesystem
+      schema: v13
+      index:
+        prefix: index_
+        period: 24h
+{{ end }}
 
 storage_config:
   boltdb_shipper:
     active_index_directory: /loki/boltdb-shipper-active
     cache_location: /loki/boltdb-shipper-cache
     cache_ttl: 24h         # Can be increased for faster performance over longer query periods, uses more disk space
+{{ if env "LOKI_TSDB_FROM_DATE" }}
+  tsdb_shipper:
+    active_index_directory: /loki/tsdb-index
+    cache_location: /loki/tsdb-cache
+{{ end }}
   filesystem:
     directory: /loki/chunks
 {{ end }}
@@ -74,6 +88,15 @@ schema_config:
     index:
       prefix: index_
       period: 24h
+{{ if env "LOKI_TSDB_FROM_DATE" }}
+  - from: {{ env "LOKI_TSDB_FROM_DATE" }}
+    store: tsdb
+    object_store: aws
+    schema: v13
+    index:
+      prefix: index_
+      period: 24h
+{{ end }}
 
 storage_config:
  boltdb_shipper:
@@ -81,6 +104,11 @@ storage_config:
    cache_location: /loki/index_cache
    resync_interval: 5s
    shared_store: aws
+{{ if env "LOKI_TSDB_FROM_DATE" }}
+ tsdb_shipper:
+   active_index_directory: /loki/tsdb-index
+   cache_location: /loki/tsdb-cache
+{{ end }}
 
  aws:
    endpoint: {{ env "LOKI_AWS_ENDPOINT" }}
@@ -99,7 +127,7 @@ storage_config:
 
 
 compactor:
-  working_directory: /loki/boltdb-shipper-compactor
+  working_directory: /loki/compactor
   compaction_interval: 10m
   retention_enabled: true
   retention_delete_delay: 2h
diff --git a/release/next b/release/next
new file mode 100644
index 0000000..39a8fcb
--- /dev/null
+++ b/release/next
@@ -0,0 +1 @@
+- opt-in migration of Loki's index store from deprecated boltdb-shipper to TSDB via LOKI_TSDB_FROM_DATE
-- 
2.54.0