Metadata-Version: 2.4
Name: solrctl
Version: 1.1.0
Summary: CLI-Tool zur Verwaltung von Apache Solr 9.x – Cores, Aliases und Snapshots verwalten
Author-email: Thomas Baer <thomas.baer@slub-dresden.de>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: click>=8.1
Requires-Dist: loguru>=0.7
Provides-Extra: prefect
Requires-Dist: prefect==3.6.19; extra == "prefect"
Requires-Dist: python-dotenv>=1.0; extra == "prefect"
Provides-Extra: deploy
Requires-Dist: python-on-whales>=0.70; extra == "deploy"
Provides-Extra: dev
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: pytest-env>=1.1; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Dynamic: license-file

# solrctl

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

## Installation

```bash
uv tool install solrctl
```

Oder aus dem Checkout:

```bash
uv pip install -e .
```

## Nutzung als CLI

```bash
# 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]

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

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

Alle Befehle akzeptieren globale Optionen:

```bash
--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:

```python
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:

```python
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 |
| `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, solr_url)` | Snapshot wiederherstellen |
| `list_snapshots(core, solr_url)` | Snapshots auflisten |
| `delete_snapshot(core, name, solr_url)` | Snapshot löschen |
| `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

```bash
# 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

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

## 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:

```bash
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:

```bash
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`](docs/plan.md) – Ausführungsplan und aktueller Status
- [`docs/technical.md`](docs/technical.md) – Architekturentscheidungen
- [`docs/usage.md`](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

```bash
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
# 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>  # Restore a snapshot
solrctl core snapshot delete <core> --name <name>   # Delete a snapshot
# SolrCloud (⚠️ untested – code exists but not verified against SolrCloud)
solrctl alias list                    # List all aliases
solrctl alias swap --alias NAME --collection TARGET
```

### Python Library

```python
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

```bash
uv tool install solrctl
```

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