solrctl

CLI-Tool und Python-Library zur Verwaltung von Apache Solr 9.x – Cores tauschen, Snapshots erstellen, Status abfragen, Konfiguration einsehen.

Installation

uv tool install solrctl

Oder aus dem Checkout:

uv pip install -e .

Nutzung als CLI

# Solr erreichbar?
solrctl ping

# Cores anzeigen
solrctl core list

# Core-Infos (Pfade, Dokumentanzahl, Größe)
solrctl core info <name>

# solrconfig.xml abrufen
solrctl core config <name>

# Schema als XML abrufen
solrctl core schema <name>

# Core-Swap (unterbrechungsfrei)
solrctl core swap --source <neuer_core> --target <aktiver_core>

# Core erstellen
solrctl core create <name> [--config-set CONFIG_SET]

# Core löschen
solrctl core delete <name> [--delete-index]

# Core neu laden
solrctl core reload <name>

# Snapshots (Backup/Restore via Replication Handler)
solrctl core snapshot create <core>
solrctl core snapshot list <core>
solrctl core snapshot restore <core> --name <snapshot_name> [--wait]
solrctl core snapshot delete <core> --name <snapshot_name>

# Replication-Polling auf einem Follower an-/ausschalten
solrctl core replication enable-poll <core>
solrctl core replication disable-poll <core>
solrctl core replication status <core>

# Havarie-Sync: Follower sofort vom Leader synchronisieren (z. B. nach Leader-Restore + core reload)
solrctl core replication fetch <core> [--wait] [--leader-url <url>]
solrctl core replication abort-fetch <core>

# Cores für Traffic freigeben/sperren (Healthcheck-File im Ping-Handler, z. B. für Traefik-Failover)
solrctl core health-file enable <core>... [--force]
solrctl core health-file disable <core>...
solrctl core health-file status <core>...

# Alias-Operationen (SolrCloud ⚠️ nicht getestet)
solrctl alias list
solrctl alias swap --alias <name> --collection <ziel>
solrctl alias delete <name>

Alle Befehle akzeptieren globale Optionen:

--solr-url   Basis-URL der Solr-Instanz (Default: http://localhost:8983, Env: SOLR_URL)
--user       Basic-Auth Benutzername (Env: SOLR_USER)
--password   Basic-Auth Passwort (Env: SOLR_PASSWORD)
-v, --verbose  Ausführliche Debug-Ausgabe aktivieren (Default: INFO)

Nutzung als Python-Library

solrctl kann direkt im Python-Code verwendet werden – ohne CLI.

Einfache Funktionen (auto-Client)

Jede Funktion erstellt automatisch einen SolrClient und schließt ihn nach dem Aufruf:

from solrctl import swap, list_cores, ping, get_core_info

# Solr erreichbar?
if ping("http://localhost:8983"):
    print("Solr ist da!")

# Alle Cores auflisten
cores = list_cores("http://localhost:8983")

# Core-Swap (unterbrechungsfrei)
swap("http://localhost:8983", source="core_new", target="core_active")

# Core-Infos abfragen
info = get_core_info("core1", solr_url="http://localhost:8983")
print(info["index"]["numDocs"])

SolrClient für mehrere Operationen

Für mehrere Operationen in einer Session eigenen SolrClient als Kontext-Manager verwenden:

from solrctl import SolrClient

with SolrClient("http://localhost:8983", auth=("user", "pass")) as client:
    if client.ping():
        cores = client.list_cores()
        for core_name in cores:
            info = client.get_core_info(core_name)
            print(f"{core_name}: {info['index']['numDocs']} docs")

    client.swap_cores("core_active", "core_new")
    config_xml = client.get_core_config("core_active")
    schema_xml = client.get_core_schema("core_active")

Verfügbare Funktionen

Funktion	Beschreibung
ping(solr_url)	Erreichbarkeit prüfen
list_cores(solr_url)	Alle Cores auflisten
get_core_info(core, solr_url)	Core-Details abfragen
swap(source, target, solr_url)	Zwei Cores tauschen
delete_core(core, delete_index, solr_url)	Core löschen
create_core(core, config_set, solr_url)	Neuen Core erstellen
reload_core(core, solr_url)	Core neu laden
get_core_config(core, solr_url)	solrconfig.xml abrufen
get_core_schema(core, solr_url)	Schema als XML abrufen
create_snapshot(core, solr_url)	Snapshot erstellen (Name + Location auto-generiert)
restore_snapshot(core, name, wait, solr_url)	Snapshot wiederherstellen
list_snapshots(core, solr_url)	Snapshots auflisten
delete_snapshot(core, name, solr_url)	Snapshot löschen
enable_replication_polling(core, solr_url)	Replication-Polling auf einem Follower aktivieren
disable_replication_polling(core, solr_url)	Replication-Polling auf einem Follower deaktivieren
get_replication_status(core, solr_url)	Replication-Status eines Cores abfragen
fetch_index(core, wait, leader_url, solr_url)	Follower sofort vom Leader synchronisieren (Havarie-Sync)
abort_fetch(core, solr_url)	Laufenden Fetch auf einem Follower abbrechen
enable_healthcheck(core, solr_url, allow_empty)	Core für Traffic freigeben (Healthcheck-File anlegen)
disable_healthcheck(core, solr_url)	Core für Traffic sperren (Healthcheck-File entfernen)
get_healthcheck_status(core, solr_url)	Freigabe-Status: enabled/disabled/not configured
list_aliases(solr_url)	Alle Aliases auflisten ⚠️
swap_alias(alias, collection, solr_url)	Alias umsetzen ⚠️
delete_alias(alias, solr_url)	Alias löschen ⚠️

⚠️ = SolrCloud-Funktionen – Code vorhanden, aber nicht gegen SolrCloud getestet.

Alle Core-Funktionen akzeptieren solr_url (default: http://localhost:8983) und auth (optional: (user, password)-Tupel).

Voraussetzungen

• Python 3.11+
• Zugriff auf eine Solr 9.x Instanz (Standalone für Core-Befehle, SolrCloud für Alias-Befehle)

Lokale Entwicklung

# Abhängigkeiten inkl. Dev- und Prefect-Extras installieren
uv sync --all-extras

# Tests ausführen
uv run pytest

# CLI lokal ausführen
uv run solrctl --help

Docker-basiertes Test-Setup

docker compose up -d
solrctl --solr-url http://localhost:8983 ping

# Live-Tests (Replication-Polling gegen echten Leader/Follower-Core, Healthcheck-File, opt-in):
uv run pytest -m live

Prefect-Integration

solrctl enthält optionale Prefect-Tasks und -Flows. Diese befinden sich im Verzeichnis prefect_flows/ und sind nicht Teil des PyPI-Pakets – sie werden beim Build ausgeschlossen.

Um sie zu nutzen, müssen solrctl und prefect installiert sein:

uv pip install -e ".[prefect]"

Verfügbare Tasks und Flows (in prefect_flows/):

Modul	Beschreibung
prefect_flows.tasks.core_swap	Task: Core-Swap mit Retries
prefect_flows.tasks.alias_swap	Task: Alias-Swap mit Retries ⚠️
prefect_flows.tasks.cleanup	Task: Optionales Löschen alter Cores/Collections
prefect_flows.flows.swap_flow	Flow: Kompletter Swap inkl. optionalem Cleanup

⚠️ Alias-Swap-Task ist für SolrCloud und nicht getestet.

Lokaler Testlauf:

uv run python -m prefect_flows.flows.swap_flow

Projektstruktur

src/
  solrctl/
    __init__.py         # Public API (Funktionen + SolrClient)
    api.py              # High-Level-Komfort-Funktionen
    cli.py              # Click-CLI
    client.py           # SolrClient (HTTP-API-Wrapper)
prefect_flows/          # Prefect-Integration (nicht im PyPI-Paket)
  tasks/
    core_swap.py
    alias_swap.py        # ⚠️ SolrCloud – nicht getestet
    cleanup.py
  flows/
    swap_flow.py
tests/
docs/
  idea.md
  plan.md
  technical.md

Weitere Dokumentation

• docs/plan.md – Ausführungsplan und aktueller Status
• docs/technical.md – Architekturentscheidungen
• docs/usage.md – Deployment-Nutzung und Flow-Integration

KI-Unterstützung

Dieses Projekt wurde mit Unterstützung von KI-Tools (Large Language Models) entwickelt. Code-Struktur, Implementierung und Dokumentation wurden dabei unterstützt durch automatiserte Vorschläge. Alle Entscheidungen wurden vom Entwickler geprüft und bestätigt. Transparenz über den Entwicklungsprozess ist uns wichtig.

---

English

solrctl is a CLI tool and Python library for managing Apache Solr 9.x – swap cores without downtime, create snapshots, query status, inspect configuration.

CLI Usage

solrctl ping                          # Check if Solr is reachable
solrctl core list                     # List all cores
solrctl core info <name>              # Show core details
solrctl core config <name>            # Get solrconfig.xml
solrctl core schema <name>            # Get schema as XML
solrctl core swap --source NEW --target ACTIVE  # Zero-downtime core swap
solrctl core create <name>                      # Create a new core
solrctl core delete <name>                      # Delete a core
solrctl core reload <name>                      # Reload a core
# Snapshots (backup/restore via Replication Handler)
solrctl core snapshot create <core>   # Create a snapshot
solrctl core snapshot list <core>     # List snapshots
solrctl core snapshot restore <core> --name <name> [--wait]  # Restore a snapshot
solrctl core snapshot delete <core> --name <name>   # Delete a snapshot
# Enable/disable replication polling on a follower core
solrctl core replication enable-poll <core>
solrctl core replication disable-poll <core>
solrctl core replication status <core>
# Disaster-recovery sync: force a follower to fetch from its leader
solrctl core replication fetch <core> [--wait] [--leader-url <url>]
solrctl core replication abort-fetch <core>
# Enable/disable cores for traffic (ping handler healthcheck file, e.g. Traefik failover)
solrctl core health-file enable <core>... [--force]
solrctl core health-file disable <core>...
solrctl core health-file status <core>...

Solr 9.10 Quirks (geprüft 2026-09-11, ergänzt 2026-09-18)

• restore-Name ohne snapshot.-Präfix angeben — wird der volle Name übergeben, antwortet der Replication Handler mit status:OK, QTime:0, ohne tatsächlich zu restoren (silent no-op). solrctl strippt den Präfix automatisch, analog zu delete_snapshot.
• **deletebackup-Name ebenfalls ohne snapshot.-Präfix** — gleiche Eigenheit, solrctl` handhabt das ebenfalls automatisch.
• Cross-Core-Restore ist in Solr 9.10.1 kaputt — auch mit korrektem --location schlägt der Wechsel auf den restored Index mit IndexNotFoundException: no segments* file found fehl. Workaround: Snapshot-Dateien manuell in data/index/ des Ziel-Cores kopieren und Core neu laden.
• fetchindex hat keinen HTTP-Parameter, um Solrs Sync-Prüfung zu erzwingen — meist irrelevant, da die Prüfung eine exakte Timestamp-Gleichheit ist, kein „nur wenn Leader neuer". Nach einem Leader-Restore muss aber vor core replication fetch zwingend core reload <leader_core> ausgeführt werden, sonst kann Solrs interner Versions-Cache den alten Stand melden.

```bash
# SolrCloud (⚠️ untested – code exists but not verified against SolrCloud)
solrctl alias list                    # List all aliases
solrctl alias swap --alias NAME --collection TARGET

Python Library

from solrctl import swap, list_cores, SolrClient

# Quick one-shot calls (auto-creates and closes client)
swap("http://localhost:8983", source="new", target="active")
cores = list_cores("http://localhost:8983")

# Session with multiple operations
with SolrClient("http://localhost:8983") as client:
    client.swap_cores("active", "new")
    info = client.get_core_info("active")

Install

uv tool install solrctl

Requires Python 3.11+, Apache Solr 9.x. MIT License.