manage-CLI-Referenz
Dies ist Rustangos Kommandozeilenwerkzeug. In einem via cargo rustango new
generierten Projekt führt ein einziges Binary jeden Befehl aus („Verb"):
cargo run # runserver (no args = boot the HTTP server)
cargo run -- migrate # any other verb
cargo run -- --help # full subcommand list
Quelle:
rustango::manage(Cli, der Verb-Dispatcher) — hinter demmanage-Feature (standardmäßig aktiviert).Ausführbare Version: jedes Verb hier läuft in einem generierten Projekt; das Beispiel
getting_started_blogwird voncargo run -- migrateund Konsorten angetrieben.
Neu bei einem Begriff hier? scaffold, migration, tenant — siehe das Glossar.
Der Befehls-Router liegt in rustango::manage::Cli;
Ihre src/main.rs verdrahtet ihn so:
#[rustango::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let _ = dotenvy::dotenv();
rustango::manage::Cli::new().api(urls::api()).run().await
}
Multi-Tenant-Projekte fügen der Kette .tenancy() hinzu. Das schaltet den
Router auf rustango::tenancy::manage
um und schaltet die Multi-Tenant-Befehle frei.
Ältere Form — Projekte, die von
manage startapp --with-manage-bin(oder vor v0.16) generiert wurden, liefern weiterhinsrc/bin/manage.rs. Diese verwendencargo run --bin manage -- <verb>. Beide Formen akzeptieren dieselben Verben.
Jeder Befehl gibt auf stdout aus und beendet sich bei Validierungs- oder
E/A-Fehlern mit einem Exit-Code ungleich null. Führen Sie
cargo run -- --help (oder <verb> --help) für die eingebaute
Nutzungshilfe aus.
Inhaltsverzeichnis
- Migrationen
- Datenmigrationen
- Projekt-/App-Scaffolder
- Dateigeneratoren (
make:*) - Datenbank-Werkzeuge
- Systembefehle
- Tenancy-Befehle
- Mehrere Replikas betreiben
- Eigene Unterbefehle
- Häufige Arbeitsabläufe
- Alle Verben
Alle Verben
Die Abschnitte oben erklären die gängigen Verben im Detail. Diese Tabelle ist
die vollständige Liste, aus den beiden Dispatchern
(migrate/manage/mod.rs und tenancy/manage/mod.rs) gezogen statt aus der Prosa —
ein Verb, das im Leitfaden fehlt, ist hier trotzdem auffindbar. Für die Flags
<verb> --help ausführen; der Hilfetext ist maßgeblich, diese Seite nicht.
Mit T markierte Verben brauchen das Feature tenancy und werden über
Cli::tenancy() erreicht.
Migrationen und Schema
| Verb | Was es tut |
|---|---|
makemigrations [name] / --empty <name> | Erzeugt eine Migration aus dem Model-Diff |
migrate [target] / --dry-run / --squash / --fake | Wendet ausstehende Migrationen an (--squash nur Single-Database, --fake nur Tenancy) |
downgrade [N | <target>] | Rollt die letzten N Migrationen zurück, oder die nach <target> (Tenant-Scope) |
showmigrations / status | Listet Migrationen und ihren Anwendungsstand |
sqlmigrate <name> | Gibt das SQL einer Migration aus, ohne es auszuführen |
forget-pending <name> | Löscht eine noch nicht angewendete Migrations-JSON, auf der keine spätere aufbaut |
add-data-op --sql <SQL> [--reverse-sql <SQL>] | Hängt eine handgeschriebene Datenoperation an |
inspectdb [--schema <s>] [--table <t>] | Liest ein bestehendes Schema und erzeugt #[derive(Model)]-Quellcode |
Daten
| Verb | Was es tut |
|---|---|
dumpdata | Exportiert Zeilen als JSON-Fixtures. Gleitkommazahlen bleiben bitgenau; eine JSON-Spalte mit JSON-null wird als {"$json": null} geschrieben, getrennt von SQL NULL (null) |
loaddata <fixture.json> [--fail-fast] | Lädt JSON-Fixtures wieder ein. Ein fehlgeschlagener oder teilweiser Ladevorgang wird nicht zurückgerollt |
flush [--yes] [--app <label>] [--model <name>] | Leert jede Model-Tabelle; die Flags grenzen die Menge ein. Nicht verwaltete Models und Views werden übersprungen. Postgres nutzt TRUNCATE … RESTART IDENTITY und schlägt fehl, wenn eine Tabelle außerhalb des Filters ein Ziel referenziert; MySQL / SQLite löschen die Zeilen in einer Transaktion, Kinder zuerst, und behalten die ID-Zähler. Ein Tenancy-Projekt braucht --tenant <slug> und leert nur diesen Tenant |
prune [--model <name>] [--except <name>] [--pretend] | Streamendes Massenlöschen; --pretend meldet nur, ohne zu löschen |
db:dump / db:restore / db:info | Natives Dump / Restore / Inspect |
dbshell | Führt den nativen Client aus (psql / mysql / sqlite3). Braucht nur DATABASE_URL, keinen funktionierenden Pool — es wird vor dem Pool-Aufbau behandelt und funktioniert daher auch, wenn sqlx nicht verbinden kann |
Scaffolder und Generatoren
| Verb | Was es tut |
|---|---|
startapp <name> | Legt ein App-Modul an |
make:viewset / make:serializer / make:form | Erzeugt ein ViewSet, einen Serializer oder ein Form |
make:job / make:scheduled / make:worker / make:middleware / make:notification / make:test | Erzeugt einen Queue-Job, eine Intervall-Aufgabe, ein Worker-Binary, eine Middleware, eine Notification oder einen Test |
make:api_routes <app> [--tenant] | Erzeugt das API-Routen-Modul einer App |
Cache, Sessions und Mail
| Verb | Was es tut |
|---|---|
createcachetable / create-cache-table [--table <name>] | Legt die Cache-Tabelle an (und die Session-Tabelle, wenn Sessions in die DB gehen) |
clear-cache [--table <name>] / clearsessions | Leert ihn; gibt die Anzahl gelöschter Zeilen zurück. Ohne Tabelle meldet er, dass nichts zu leeren ist |
sendtestemail --to <addr> | Sendet eine feste Test-Mail über das konfigurierte Backend |
Die beiden Cache-Verben brauchen das cache-Feature; ohne es fehlen sie in --help und sagen das beim Aufruf.
Introspektion
| Verb | Was es tut |
|---|---|
showmodels [--format plain|json] [--app <label>] | Jedes registrierte Model, sortiert für deterministische Ausgabe |
showurls [--format plain|json] | Jede benannte Route, sortiert |
check [--deploy] | Health-Checks, Modelländerungen ohne Migration und noch nicht angewandte Migrationen; --deploy ergänzt die Produktions-Audits |
create-admin | Legt eine AdminUser-Zeile für Projekte mit admin::Builder::with_session_auth an. Nicht tenancy-gated — nimmt einen einfachen &Pool und schreibt rustango_admin_users, die Tabelle wird bei Bedarf angelegt. Der einzige Weg zu einem ersten Admin-Login in einem Nicht-Tenancy-Projekt |
reset-password <username> / change-password <username> | Setzt das Passwort eines Admin-Benutzers (eine Datenbank); change-password prüft zuerst das aktuelle. Gleiche Passwort-Flags wie create-admin |
set-admin-active <username> --on|--off | Schaltet einen Admin-Benutzer ab (seine Sitzungen enden) oder wieder an |
reset-admin-totp <username> | Entfernt das Zwei-Faktor-Gerät eines Admin-Benutzers nach Verlust des Telefons. Protokolliert mit Quelle cli |
about / version / --version | Build- und Versionsinformationen |
docs | Öffnet die Dokumentation |
Benutzer und Zugriff T
| Verb | Was es tut |
|---|---|
create-superuser / set-superuser | Legt einen Superuser an oder befördert einen bestehenden Benutzer |
create-user / create-operator | Legt einen Tenant-Benutzer oder einen Operator an |
reset-password / change-password | Passwort-Wiederherstellung für Tenant-Benutzer. change-password nimmt das aktuelle Passwort aus --current-stdin oder, ohne Terminal, aus RUSTANGO_CURRENT_PASSWORD; --current in argv warnt |
set-password-link <slug> <username> | Gibt einen Einmal-Link aus, mit dem der Benutzer sein eigenes Passwort setzt |
reset-operator-password / change-operator-password | Passwort-Wiederherstellung für Operatoren; change-operator-password liest das aktuelle Passwort wie change-password |
set-operator-active | Aktiviert oder deaktiviert einen Operator |
reset-operator-totp <username> | Entfernt das Zwei-Faktor-Gerät eines Operators nach Verlust des Telefons. Im Registry-Audit-Log mit Quelle cli |
create-role / assign-role / revoke-role / list-roles | Rollen |
grant-perm / revoke-perm | Berechtigungen per Codename |
seed-permissions [--slug <s>] | Legt die Standard-Berechtigungszeilen an |
create-api-key | Stellt einen API-Key aus |
revoke-passkey <slug> <username> [--credential <id>] | Löscht einen Passkey eines Tenant-Benutzers oder alle (Feature passkey) |
Tenants T
| Verb | Was es tut |
|---|---|
create-tenant / edit-tenant / list-tenants | Anlegen, bearbeiten, auflisten |
drop-tenant / purge-tenant | Deaktivieren (umkehrbar) / zerstören (nicht) |
rotate-tenant-password <slug> | Neues Passwort für einen Login, den rustango auf einem gespeicherten Server angelegt hat |
migrate-tenants / migrate-registry | Wendet Migrationen über alle Tenants oder auf die Registry an |
migrate-tenant-storage <slug> --to schema|database | Verschiebt einen Tenant zwischen Speichermodi |
add-host / remove-host / list-hosts / set-host-enabled | Host-Routing |
add-db-server / edit-db-server / list-db-servers / test-db-server / remove-db-server | Gespeicherte Datenbankserver |
test-tenant-connection | Prüft, ob die Datenbank eines Tenants erreichbar ist |
reseal-tenant-secrets [--apply] | Versiegelt gespeicherte Tenant-URLs, Server-Passwörter, Operator-TOTP- und SSO-Secrets sowie Cast<EncryptedString>-Spalten neu mit dem aktuellen RUSTANGO_SECRET_KEY; ohne --apply ein Probelauf |
prewarm-pools | Öffnet Tenant-Pools vor dem ersten Request |
run-server / runserver | Startet den Multi-Tenant-Server |
init / init-tenancy / wizard / menu / actions | Setup und interaktive Einstiegspunkte |
Erster Admin. create-tenant <slug> … --admin-email <e> [--admin-username <u>]
legt nach den Migrationen einen Superuser an, bevor der Tenant live geht;
schlägt das fehl, wird der Lauf zurückgerollt. Der Admin bekommt kein Passwort.
Das Verb gibt einmal einen Link zum Setzen des Passworts aus: Er funktioniert
einmal, läuft nach 72 Stunden ab und gilt nur für diesen Tenant. Gib ihn dem
Admin. Er ist mit dem Tenant-Session-Schlüssel des Servers signiert
(RUSTANGO_SESSION_SECRET oder die Dev-Schlüsseldatei), also starte die CLI mit
demselben Schlüssel wie den Server. Außerhalb der Prod-Stufe legt die CLI eine
fehlende ./var/.rustango_tenant_session.key so an, wie der Server es tut; das
klappt also schon vor dem ersten Serverstart. set-password-link <slug> <username>
gibt einen neuen aus.
Audit T
| Verb | Was es tut |
|---|---|
audit-log | Liest den Audit-Trail |
audit-cleanup | Kürzt ihn |
sso-deactivate-idle | Inaktive SSO-Benutzer in jedem Mandanten deaktivieren |
MCP T
Vollständig im MCP-Leitfaden dokumentiert.
| Verb | Was es tut |
|---|---|
create-agent / list-agents / rotate-agent-secret | Agents |
create-skill / list-skills / grant-skill / revoke-skill | Skills |
map-skill-permission / unmap-skill-permission | Bindet einen Skill an eine Berechtigung |
create-user-key / list-user-keys / revoke-user-key | MCP-Zugangsdaten pro Benutzer |
list-runs / show-run | Lauf-Historie |
Migrationen
makemigrations [name]
Generiert eine Migrationsdatei aus Änderungen an Ihren Modellen.
Es vergleicht Ihre registrierten Modelle mit dem letzten
gespeicherten Schema-Snapshot in migrations/ und schreibt eine neue
JSON-Datei mit allen Änderungen.
cargo run -- makemigrations # auto-name (e.g. 0004_add_slug_to_posts)
cargo run -- makemigrations rename_status_to_state # custom suffix
Automatisch erkannte Änderungen:
CreateTable/DropTableAddColumn/DropColumnAlterColumnType/AlterColumnNullable/AlterColumnDefault/AlterColumnMaxLengthAlterColumnUniqueCreateIndex/DropIndexAddCheckConstraint/DropCheckConstraintCreateM2MTable/DropM2MTable
NICHT automatisch erkannt (Umbenennen vs. Löschen+Hinzufügen ist mehrdeutig):
RenameTable,RenameColumn— verwenden Sie--emptyund bearbeiten Sie das JSON.
Eine gelöschte Spalte neben einer neuen Spalte desselben Typs in einer Tabelle
sieht nach einem umbenannten Feld aus, und Löschen+Hinzufügen würde ihre Daten
löschen. makemigrations verweigert das und nennt die Spalten; schreiben Sie
das RenameColumn wie unten, oder übergeben Sie --drop-and-add, um bewusst
zu löschen und hinzuzufügen. Eine gelöschte Tabelle neben einer neuen Tabelle
mit denselben Spalten (ein geändertes table =) wird genauso verweigert;
schreiben Sie stattdessen ein RenameTable. Jedes andere DropColumn oder
DropTable warnt, dass seine Daten verloren gehen.
makemigrations --app <app>
Beschränkt die Migration auf eine einzelne App. Sie schreibt in das eigene
Verzeichnis <project_root>/<app>/migrations/ dieser App und betrachtet nur
Modelle, die zu dieser App gehören.
cargo run -- makemigrations --app blog
cargo run -- makemigrations --app blog backfill_slugs
makemigrations --scope <registry|tenant>
Nur Multi-Tenant. Schreibt eine einzige Migration für nur die Modelle in einem
Scope — jene, deren #[rustango(scope = "...")]-Attribut übereinstimmt.
(„Registry"-Tabellen werden von allen Tenants gemeinsam genutzt;
„Tenant"-Tabellen leben pro Tenant.) Ohne dieses Flag teilt ein einfaches
makemigrations in einem Tenancy-Projekt die Änderungen automatisch in ZWEI
Dateien auf — eine für Registry-Modelle, eine für Tenant-Modelle — damit
gemeinsame Framework-Tabellen (Org, Operator) nicht in die
Per-Tenant-Migrationen durchsickern, die migrate-tenants ausführt.
cargo run -- makemigrations # tenancy: writes 0NN_<auto>.json (registry) + 0MM_<auto>.json (tenant) as needed
cargo run -- makemigrations --scope tenant # explicit single-scope diff
cargo run -- makemigrations --scope registry # explicit single-scope diff
Warum die Aufteilung wichtig ist: vor v0.24.2 bündelte ein einfaches
makemigrations in einem Tenancy-Projekt Operationen auf
rustango_operators (einer Registry-Tabelle) in eine Tenant-Migration. Als
migrate-tenants diese Datei ausführte, wurde rustango_operators über den
search_path auf die Registry-Kopie aufgelöst und kollidierte mit dem dort
bereits vorhandenen Constraint.
makemigrations --empty <name>
Erstellt eine leere Migration (keine forward-Operationen), die Sie von Hand
ausfüllen. Verwenden Sie sie, wenn Sie
Datenoperationen oder Umbenennungsoperationen schreiben müssen, die der
Auto-Detektor nicht generieren kann. Bearbeiten Sie das resultierende JSON
selbst.
cargo run -- makemigrations --empty rename_status_to_state
# Then edit migrations/0005_rename_status_to_state.json:
# "forward": [
# {"schema": {"RenameColumn": {"table": "posts", "old_column": "status", "new_column": "state"}}}
# ]
makemigrations --merge
Repariert eine Migrationshistorie, die sich in zwei Zweige aufgeteilt hat.
Das passiert,
wenn zwei Personen jeweils makemigrations auf ihrem eigenen Feature-Branch
ausführen, sodass beide neuen Dateien auf denselben Elternknoten zeigen.
Nachdem beide Branches gemergt sind, hat die Historie zwei „Blätter"
(Endpunkte), und makemigrations verweigert die Arbeit, bis sie
zusammengeführt sind.
--merge erkennt dies und schreibt eine leere NNNN_merge.json, deren
Elternknoten auf das alphabetisch letzte Blatt zeigt und deren merges die
übrigen nennt; so wird die Historie wieder zu einer einzigen Kette vereint. Ihr
Schema-Snapshot vereint die Snapshots der Zweige, sodass noch nicht migrierte
Modelländerungen im nächsten makemigrations erscheinen.
cargo run -- makemigrations --merge
# wrote migrations/0004_merge.json
# merge node — empty `forward`, anchors the chain after divergent leaves
- Bereits eine einzelne Kette → gibt
no merge neededaus und beendet sich sauber. Sicher auf einer gesunden Historie auszuführen. - Wirklich getrennte Historien (keine Branch-Kollision) → bricht mit einem Fehler ab, statt einen Elternknoten zu erfinden.
- Nicht kombinierbar mit
--empty,--app,--scopeoder einem positionalen Namen.
migrate
Wendet alle ausstehenden Migrationen der Reihe nach auf die Datenbank an. Dies ist der Befehl, den
Sie nach makemigrations ausführen, um Ihr Schema tatsächlich zu ändern.
cargo run -- migrate
cargo run -- migrate --dry-run # print SQL without writing
Jede Datei läuft standardmäßig innerhalb einer Transaktion, sodass ein Fehler
die gesamte Datei zurückrollt. Setzen Sie "atomic": false im JSON, um sich
abzumelden — das brauchen Sie für Anweisungen wie
CREATE INDEX CONCURRENTLY, die nicht in einer Transaktion laufen können.
Im Tenancy-Modus (Cli::tenancy()) ist migrate scope-bewusst: es wendet
zuerst Registry-Migrationen auf die gemeinsame Registry-Datenbank an, dann
Tenant-Migrationen über jeden aktiven Tenant. Für feinere Kontrolle verwenden
Sie migrate-registry /
migrate-tenants. Alle drei wenden auch die <app>/migrations/-Ordner neben
migrations/ an, wie der Server beim Start.
migrate <target>
Migriert zu einem bestimmten Punkt in der Historie, vorwärts oder rückwärts.
Nennen Sie eine Migration, um zu ihr zu
wechseln; das spezielle Ziel zero macht alles rückgängig.
cargo run -- migrate 0003_add_slug # forward to 0003
cargo run -- migrate 0001_initial # roll back to 0001 (unapply 0002+)
cargo run -- migrate zero # unapply EVERY migration
Ein Ziel, das ein angewendeter Squash ersetzt hat, wird verweigert: Der Wechsel dorthin würde den Squash und seine Zeilen rückgängig machen. Wählen Sie den Squash oder eine Migration außerhalb davon als Ziel. Das Zurückrollen verweigert eine Migration, die das Ledger nicht angewendet hat.
migrate --squash
Nur Single-Database. Das
migrateder Mandantenfähigkeit (Cli::tenancy()) lehnt--squashab.
Fasst jede ausstehende (nicht angewendete) Migration in einem frisch generierten Diff zusammen — der Dev-Iterations-Notausgang, wenn ein Stapel halbfertiger Migrationen leichter neu zu generieren als zu reparieren ist. Es weigert sich, an bereits Angewendetem etwas zu ändern.
cargo run -- migrate --squash
Die neu generierte Datei zeichnet die Namen, die sie zusammengefasst hat, in
ihrer replaces-Liste auf. Das ist in dem Moment wichtig, in dem eine andere
Datenbank beteiligt ist: der Checkout Ihres Kollegen, Staging oder CI hat
möglicherweise bereits einige der Dateien angewendet, die Sie gerade gelöscht
haben. Ohne replaces würde das CREATE TABLE der neuen Datei dort
kollidieren; mit ihr versöhnt der Runner stattdessen (siehe unten).
Squash-Versöhnung
Ein Squash stellt den Endzustand der Migrationen wieder her, die er ersetzt, sodass das, was der Runner tun sollte, vollständig davon abhängt, was die Zieldatenbank bereits enthält. Er entscheidet automatisch:
| Datenbankzustand | was passiert |
|---|---|
| frisch — keine Historie, keine Tabellen | der Squash läuft echt |
| jede ersetzte Migration steht im Ledger | verzeichnet, Vorgänger als erledigt markiert, kein DDL |
| Tabellen existieren, aber das Ledger hat keine Historie | verzeichnet, kein DDL — das Ledger wird nachträglich an die vorhandenen Tabellen angeglichen |
| nur einige ersetzte Zeilen / Tabellen vorhanden | verweigert, benennt, was fehlt |
Der partielle Fall ist bewusst ein harter Fehler: keine automatische Wahl ist
dort sicher, also stoppt der Runner und sagt Ihnen, was er gefunden hat, statt
zu raten. Lösen Sie ihn mit migrate --fake (unten).
Migrationen, die von einem angewendeten Squash abgelöst wurden, werden als angewendet behandelt, sodass Sie die alten Dateien für ein oder zwei Releases auf der Platte lassen können — Deployments, die sie nie ausgeführt haben, migrieren trotzdem korrekt vorwärts.
Gewöhnliche (Nicht-Squash-)Migrationen bleiben unberührt: eine einfache Migration, deren Tabelle bereits existiert, scheitert weiterhin lautstark, denn das ist ein echter Konflikt und keine bekannt-äquivalente Historie.
migrate --fake <name>
Nur in Tenancy-Projekten (Cli::tenancy()): das Single-Database-migrate
lehnt --fake als unbekanntes Flag ab.
Stempelt eine Migration als angewendet ohne ihr SQL auszuführen — der Betreiber-Notausgang, wenn die Datenbank bereits im Zielzustand ist, das Ledger es aber nicht weiß (eine außerhalb des Kanals eingerichtete DB, eine gelöschte Ledger-Tabelle, eine teilweise gelungene Migration, ein verweigerter partieller Squash). Wiederholen Sie das Flag, um mehrere Zeilen auf einmal zu reparieren.
cargo run -- migrate --fake 0004_add_indexes
cargo run -- migrate --fake 0004_add_indexes --system # framework's own chain
cargo run -- migrate --fake 0004_add_indexes --all-tenants # every active tenant
Der Name wird zuerst gegen das Migrationsverzeichnis validiert, sodass ein Tippfehler keine unechte Zeile einschleusen kann. Das Stempeln ist idempotent.
--system zielt auf die eigene Migrationskette des Frameworks
(system/migrations/, verzeichnet in __rustango_system_migrations__) statt
auf die Ihres Projekts. --all-tenants fächert den Stempel über jeden aktiven
Tenant auf, berichtet über jeden einzelnen und fährt über Fehler hinweg fort —
die Tabellen des Frameworks leben pro Tenant, ihre Reparatur ist also eine
Per-Tenant-Aufgabe.
downgrade [N | <target>]
<target> geht nur in einem Tenancy-Projekt; das Single-Database-downgrade
nimmt eine Schrittzahl.
Rollt die letzten N angewendeten Migrationen zurück (Standard 1). Jede Migration muss reversibel sein: Schemaänderungen
kehren sich automatisch um, aber Datenoperationen brauchen ein definiertes
reverse_sql, sonst scheitert der Rollback.
cargo run -- downgrade # one step
cargo run -- downgrade 3 # three steps
In einem Tenancy-Projekt rollt downgrade registry-weite Migrationen zurück.
Tenant-Migrationen stehen im Ledger jedes Tenants:
cargo run -- downgrade --tenant acme # ein Tenant
cargo run -- downgrade 2 --all-tenants # jeder aktive Tenant, je zwei Schritte
Tenants können auf unterschiedlichen Versionen stehen. --all-tenants
zeigt den Plan jedes Tenants und ändert nichts; --yes führt ihn aus.
Statt N eine Migration nennen, um alles danach Angewandte zurückzurollen:
cargo run -- downgrade 0001_initial --all-tenants # der Plan
cargo run -- downgrade 0001_initial --all-tenants --yes # ausführen
showmigrations / status
Listet jede Migration und ob sie angewendet wurde. [X] bedeutet angewendet,
[ ] bedeutet noch ausstehend.
cargo run -- showmigrations
cargo run -- status # alias
Ausgabe:
Migrations in ./migrations:
[X] 0001_initial
[X] 0002_add_status
[ ] 0003_add_slug
System migrations in ./system/migrations:
[X] 0001_create_rustango_audit_log_and_rustango_content_types
Eine Zeile, die ein angewendeter Squash ersetzt, zeigt [X] <name> (replaced by a squash).
Datenmigrationen
add-data-op
Fügt einer Migration einen Roh-SQL-Datenschritt hinzu, ohne das JSON von Hand zu bearbeiten. Greifen Sie dazu, wenn Sie vorhandene Zeilen transformieren müssen — eine Spalte nachfüllen, Daten bereinigen — als Teil einer Migration. Das Ergebnis ist eine Datenmigration, die rohes SQL ausführt — für Sie von der Kommandozeile aus generiert.
# New migration with up + down
cargo run -- add-data-op \
--sql "UPDATE posts SET slug = lower(title)" \
--reverse-sql "UPDATE posts SET slug = NULL" \
--name backfill_post_slugs
# Append to an existing migration
cargo run -- add-data-op \
--to 0003_add_slug \
--sql "UPDATE posts SET slug = id::text"
# Irreversible (no rollback)
cargo run -- add-data-op \
--sql "DELETE FROM legacy_data" \
--name purge_legacy
| Flag | Erforderlich | Beschreibung |
|---|---|---|
--sql <SQL> | ja | Vorwärts-SQL, das bei migrate läuft |
--reverse-sql <SQL> | nein | Rollback-SQL bei unapply; weglassen für irreversibel |
--name <name> | nein | Namenssuffix der neuen Migration; Standard ist data_op |
--to <migration> | nein | An eine bestehende Migration anhängen, statt eine neue zu erstellen |
Lassen Sie --reverse-sql weg, und der Schritt wird als reversible: false
markiert — jeder Versuch, ihn zurückzurollen, scheitert sofort.
Projekt-/App-Scaffolder
cargo rustango new <name> (separates Binary)
Erstellt ein brandneues Rustango-Projekt. Dies ist ein separates Werkzeug, installieren Sie es also
zuerst mit cargo install cargo-rustango. Wählen Sie aus drei Vorlagen:
cargo rustango new myblog # default = fullstack (ORM + admin)
cargo rustango new myapi --template api # JSON-only, no admin
cargo rustango new shop --template tenant # multi-tenancy
Schreibt:
<name>/
Cargo.toml
.env.example
.gitignore
rust-toolchain.toml
docker-compose.yml
Dockerfile (deploy image — multi-stage, release, non-root)
Dockerfile.dev (cargo-watch image docker-compose.yml builds)
.dockerignore
README.md
config/default.toml (shared knobs)
config/{dev,staging,prod}_settings.toml (per-tier overrides)
migrations/ (your app's migrations)
system/migrations/ (framework tables, generated — commit them)
src/{lib,main,models,views,urls}.rs
Die config/-Ebene ist die Settings-Quelle: default.toml enthält, was alle
Umgebungen teilen, und je eine <env>_settings.toml überschreibt sie, zur
Laufzeit ausgewählt über RUSTANGO_ENV (Standard dev) — ein frisches
cargo run läuft also ohne jede TOML-Änderung. Zusammen tragen sie das
[database]-Pool-Tuning, [admin], [mcp] und die secure_cookies-Policy —
und sie sind es, was das Settings-Audit von
check --deploy liest. Die Inhalte pro Ebene stehen unter
Scaffolding.
Jede Vorlage liefert einen leeren system/migrations/-Ordner. Die
eigenen Tabellen des Frameworks (rustango_orgs, rustango_users,
Rollen/Berechtigungen, …) werden beim ersten cargo run -- migrate aus den
kompilierten Modellen dorthin generiert — es gibt kein handgeliefertes
Bootstrap-JSON. Siehe migrate /
migrate-registry.
startapp <name> [flags]
Erstellt eine neue App (ein Feature-Modul) unter src/<name>/.
Verwenden Sie es, um Modelle, Views und URLs für einen Teil
Ihres Projekts gruppiert zu halten.
cargo run -- startapp blog
cargo run -- startapp shop --with-manage-bin # also writes src/bin/manage.rs
cargo run -- startapp shop --into apps # write under src/apps/shop/ instead
Erstellt:
src/<name>/
mod.rs
models.rs (a starter model named after the app)
views.rs
urls.rs
tests.rs
Sicher erneut ausführbar — bestehende Dateien bleiben unberührt. Der Befehl
registriert auch das Modul: pub mod <name>; in src/lib.rs (oder
mod <name>; in src/main.rs, wenn es keine lib.rs gibt), dazu eine Zeile
.merge(crate::<name>::urls::api()) im api()-Aggregator von
src/urls.rs. Kann er eine Datei nicht anpassen, gibt er die Zeile zum
Einfügen aus.
Dateigeneratoren (make:*)
Diese erstellen Startdateien für gängige Bausteine. Jeder Generator
schreibt nach src/<snake_name>.rs (oder tests/<snake_name>.rs für
make:test) und:
- Prüft, ob der Name gültig ist (PascalCase, Buchstaben/Ziffern/Unterstrich) —
diese Generatoren erzeugen einen Typ, also ist der Name ein Typname.
make:testist die Ausnahme: Es erzeugt eine Datei mit Testfunktionen, nimmt also jeden Rust-Bezeichner, undmake:test post_smokefunktioniert wie unten gezeigt. - Wandelt ihn für den Dateinamen in snake_case um (
PostViewSet→post_view_set.rs). - Überschreibt keine bestehende Datei.
- Erinnert Sie daran,
pub mod X;zu Ihrerlib.rshinzuzufügen.
make:viewset <Name> [--model <Model>] [--tenant | --no-tenant] [--crate <path>]
Generiert eine vollständige CRUD-REST-Ressource für ein Modell.
Zwei Vorlagen, für Sie ausgewählt. Das #[derive(ViewSet)] mit einem Pool
fängt einen einzigen Pool beim Einbinden ein, was für ein Tenancy-Projekt falsch
ist — der Generator wählt daher zwischen zwei Formen. Auflösungsreihenfolge:
--no-tenant gewinnt, dann --tenant, dann die Auto-Erkennung — tenancy
in der Feature-Liste der rustango-Abhängigkeit in Cargo.toml — und sonst die
Pool-Vorlage. Wenn die Auto-Erkennung den Tenant-Modus wählt, sagt sie das auf
stdout und nennt --no-tenant als Override.
cargo run -- make:viewset PostViewSet --model Post
cargo run -- make:viewset PostViewSet --model Post --no-tenant # Pool-Form erzwingen
Pool-Vorlage — generierte src/post_view_set.rs:
#[derive(ViewSet)]
#[viewset(model = Post, fields = "id, ", filter_fields = "", search_fields = "", page_size = 20, read_only)]
pub struct PostViewSet;
Sie startet als read_only. Sichern Sie Schreibzugriffe vorher ab: mit
tenancy fügen Sie hinter einer Auth-Schicht permissions(create = "...", ...)
hinzu und entfernen read_only; in einer Single-Database-App setzen Sie Ihre
eigene Auth-Schicht davor und ersetzen read_only durch allow_anonymous
(Codenamen verweigern dort das Mounten); Erste Schritte, Schritt 14
zeigt eine solche Schicht. --model Post sucht Post
in src/models.rs oder im models.rs einer App und importiert es von dort;
--model blog::models::Post nennt den Pfad direkt.
In src/main.rs mit dem Pool des Servers einbinden:
.nest_with("/api", |pool| myapp::post_view_set::PostViewSet::router("/posts", pool)). Der Pfad ist die Tabelle des Modells (hier posts); der Snake-Name des Modells, falls es noch nicht einkompiliert ist.
Tenant-Vorlage — kein Derive. Sie erzeugt ein
pub fn router() -> Router<()>, gebaut aus
ViewSet::for_model(Post::SCHEMA, &["id"]), mit aktivem
.permissions_for_model::<Post>() und der restlichen Builder-Kette
(filter_fields / search_fields / ordering / ordering_fields /
page_size / read_only) als auskommentierte Zeilen vorgestubbt, am Ende
.tenant_router("/api/posts"). Die Verbindung wird pro Anfrage über den Tenant-Extractor
aufgelöst statt einmalig beim Einbinden eingefangen — ein router() bedient also
jeden Tenant.
Einbinden mit: .merge(crate::post_view_set::router()) — nicht mit der
PostViewSet::router(path, pool)-Zeile oben.
--crate <path> benennt die Framework-Crate in den generierten use-Zeilen um,
für Projekte, die rustango unter einem anderen Namen importieren.
make:serializer <Name> [--model <Model>]
Generiert eine #[derive(Serializer)]-Struktur — steuert, wie ein Modell nach
und von JSON konvertiert wird.
cargo run -- make:serializer PostSerializer --model Post
make:form <Name>
Generiert eine #[derive(Form)]-Struktur zum Validieren und Verarbeiten von
Formular-Eingaben.
cargo run -- make:form ContactForm
make:job <Name>
Generiert einen jobs::Job — eine Payload-Struktur plus die Trait-Implementierung
mit NAME, MAX_ATTEMPTS und async fn run(&self). Das ist Arbeit, die Sie aus
einem Handler in die Queue stellen und ein Worker später ausführt.
run erhält nur die Payload: keinen Pool, keinen Tenant, keinen
Request-Kontext. Tragen Sie alles Nötige in den Feldern.
cargo run -- make:job SendReceipt
Für Arbeit, die nach Zeitplan statt aus einer Warteschlange läuft, siehe
make:scheduled.
make:scheduled <Name>
Generiert eine Aufgabe mit festem Intervall für scheduler::Scheduler — die Form,
die make:job emittierte, bevor dieser einen echten Job erzeugte.
cargo run -- make:scheduled NightlySweep
Starte ihn aus einem Worker-Binary (make:worker): main.rs hat keinen Pool,
und Code vor Cli::run() liefe bei jedem CLI-Verb.
make:worker <Name>
Generiert ein eigenständiges Worker-Binary für src/bin/ — ein Prozess, der die
Job-Queue abarbeitet und kein HTTP bedient. Betreiben Sie ihn neben dem
Web-Prozess oder als eigenen Container.
Die Form ist kurz und lässt sich so falsch schreiben, dass es erst in Produktion
auffällt: Ein Worker, der auf tokio::signal::ctrl_c() wartet, behandelt SIGINT,
aber nicht SIGTERM — und genau das senden docker stop, Kubernetes und
systemd. Das Abarbeiten läuft dann nie, der Container wird nach seiner Schonfrist
getötet, und laufende Jobs gehen verloren, ohne dass etwas protokolliert wird.
Der generierte Worker wartet auf shutdown::shutdown_signal(), das beide
Signale annimmt.
cargo run -- make:worker JobsWorker
make:notification <Name>
Generiert eine Notification-Struktur, die eine E-Mail aufbaut.
cargo run -- make:notification WelcomeEmail
make:middleware <Name>
Generiert eine Middleware-Funktion — Code, der vor und nach jedem Request läuft (Auth-Prüfungen, Logging und so weiter). „axum" ist das Web-Framework, auf dem Rustango aufbaut, sodass der Stub der Middleware-Form von axum entspricht.
cargo run -- make:middleware AuditLog
make:test <Name>
Generiert einen Integrationstest in tests/, der TestClient verwendet, um
Requests gegen Ihre App zu stellen.
cargo run -- make:test post_smoke
Datenbank-Werkzeuge
db:info
Zeigt, mit welcher Datenbank dieser Build zu sprechen konfiguriert ist, ohne
sich zu verbinden. Es gibt die Framework-Version aus, welche
Datenbanktreiber (postgres/mysql/sqlite Cargo-Features) einkompiliert sind, die
Verbindungs-URL mit verstecktem Passwort und das erkannte Backend. Da es nie
eine Verbindung öffnet, ist es praktisch in CI oder Containern, in denen die
Datenbank noch nicht läuft, Sie aber bestätigen wollen, dass die Einstellungen
stimmen.
cargo run -- db:info
db:dump [--out <path>] [--data-only|--schema-only] [--no-owner]
Sichert Ihre Datenbank, indem pg_dump gegen DATABASE_URL ausgeführt wird.
Standardmäßig geht das SQL nach stdout (damit Sie es
pipen können); übergeben Sie --out <path> (-o), um stattdessen eine Datei
zu schreiben. --data-only und --schema-only bilden direkt auf die Flags von
pg_dump ab, und --no-owner lässt die OWNER-Zeilen weg. Sie brauchen
pg_dump installiert und in Ihrem PATH.
cargo run -- db:dump > backups/before-migrate.sql # stdout → file
cargo run -- db:dump --out backups/before-migrate.sql
Die Statuszeile running: pg_dump … geht auf stderr und bleibt damit
aus der Umleitung und aus einer Pipe heraus. Ältere Versionen
schickten sie auf stdout und landete so in der ersten Zeile der .sql-Datei.
db:restore <path> [--clean --yes]
Lädt eine Dump-Datei zurück in Ihre Datenbank — das Gegenstück zu db:dump. Es
lässt die Datei durch psql gegen DATABASE_URL mit ON_ERROR_STOP=1 in
einer Transaktion laufen, sodass es beim ersten Fehler stoppt und nichts lädt.
Fügen Sie --clean --yes hinzu, um zuerst das bestehende Schema zu löschen (es
stellt DROP SCHEMA IF EXISTS public CASCADE; CREATE SCHEMA public; voran),
damit die Wiederherstellung auf einer leeren Datenbank landet; ein
fehlgeschlagener Import macht das Löschen rückgängig. Mit --clean muss der
Dump eine nicht leere reguläre Datei sein, geprüft bevor etwas läuft; ohne
--clean liest es auch eine Pipe. Ein Tenancy-Projekt lehnt --clean ab, weil
public die Registry enthält. Sie brauchen psql in Ihrem PATH.
cargo run -- db:restore backups/before-migrate.sql
cargo run -- db:restore backups/before-migrate.sql --clean --yes
Systembefehle
version / --version
Gibt die Version des Rustango-Frameworks aus.
$ cargo run -- version
rustango 0.67.0
about
Gibt eine Momentaufnahme Ihrer Umgebung aus: Framework-Version, registrierte Modelle und Apps, ob die Datenbank erreichbar ist, und wichtige Umgebungsvariablen. Legen Sie dies in Support-Tickets, wenn etwas nicht stimmt.
$ cargo run -- about
rustango
version: 0.67.0
models: 3 registered
apps: 1 (blog)
RUSTANGO_ENV: local
DATABASE_URL: postgres://***@localhost:5433/myblog
db_connect: ok
check [--deploy]
Führt Gesundheitsprüfungen an Ihrem Projekt durch. Fügen
Sie --deploy für die strengeren Produktionsreife-Prüfungen hinzu.
Immer aktive Prüfungen:
- ≥ 1 Modell via
inventoryregistriert - DB erreichbar (
SELECT 1) - Modelle registriert, aber keine Migrationen auf der Platte (es vergleicht keine Zahlen — ein vorhandenes
migrations/-Verzeichnis wird unabhängig von der Anzahl als Info gemeldet) - Migrationen, die das Ledger noch nicht angewendet hat. Im Tenancy-Projekt: Registry-Dateien gegen die Registry, Tenant-Dateien gegen das Ledger jedes aktiven Tenants (die zurückliegenden Tenants werden genannt, zehn vollständig),
<app>/migrations/-Ordner eingeschlossen. Acht Tenants werden gleichzeitig gelesen, jeder höchstens 5 s; ein langsamerer gilt als nicht lesbar.check --no-tenantsüberspringt die Tenant-Ledger. Die Schritte des Frameworks insystem/migrations/werden ebenfalls mit dem System-Ledger verglichen (im Tenancy-Projekt die Registry-Schritte mit der Registry)
Mit --deploy:
RUSTANGO_ENVistprododerproductionRUSTANGO_SESSION_SECRETgesetzt und decodiert zu einem Schlüssel von ≥ 32 Byte, dieselbe Prüfung wie zur Laufzeit (der HMAC-Schlüssel für Cookies + JWTs;SECRET_KEYwird vom Framework nie gelesen)DATABASE_URLgesetztRUSTANGO_APEX_DOMAINgesetzt — die Warnung erscheint bei jedem Projekt, wenn unset oderlocalhost, und sagt das auch; Single-Tenant-Projekte können sie ignorierenDATABASE_URLzeigt auflocalhost/127.0.0.1(Warnung — in Produktion meist ein Managed-Hostname)RUSTANGO_BINDbeginnt mit127.0.0.1(Warnung — nur Loopback nimmt keinen externen Traffic an)- Ein Settings-Tier-Audit über dein TOML, das Dev-Defaults in einer Prod-Stufe meldet (braucht das Feature
config) Meta.required_db_vendor/required_db_featuresjedes registrierten Models, geprüft gegen den tatsächlich verbundenen Dialekt
$ cargo run -- check --deploy
running rustango system check (deploy mode)...
[info] 3 models registered via inventory
[info] database reachable
[info] 4 migration(s) on disk
[info] RUSTANGO_ENV is set to a production value
[info] RUSTANGO_SESSION_SECRET decodes to a valid ≥32-byte key
[info] DATABASE_URL set
[info] RUSTANGO_APEX_DOMAIN set to a non-localhost value
all checks passed
Beendet sich mit Exit-Code ungleich null, wenn eine Prüfung auf Fehler-Ebene scheitert. Warnungen allein verursachen kein Scheitern.
check --settings braucht keine Datenbank. Es gibt jeden
Einstellungsschlüssel aus, mit der Herkunft seines Werts (eine eigene
Umgebungsvariable, RUSTANGO__SECTION__KEY, eine Einstellungsdatei oder
der Standard), dem Wert, außer bei Geheimnissen, Schlüsseln, die nichts
liest, und einer fehlenden oder ungültigen Datenbank-URL. Es liest
config/ für die RUSTANGO_ENV-Stufe; das kann von den Einstellungen
abweichen, die die App an with_settings übergibt.
docs
Öffnet die Rustango-Dokumentation (https://docs.rs/rustango) in Ihrem Browser. Es gibt immer auch die URL aus, sodass es auch auf einem Headless-Server funktioniert.
cargo run -- docs
--help / help
Listet jeden Befehl mit einer einzeiligen Beschreibung. Im Tenancy-Modus werden auch die unten aufgeführten Multi-Tenant-Befehle hinzugefügt.
Tenancy-Befehle
Diese Befehle existieren nur in Multi-Tenant-Projekten (eine App, die viele
isolierte Kunden/Orgs bedient). Sie erscheinen nur, wenn das Projekt mit
features = ["tenancy"] gebaut wird UND Cli::new() mit .tenancy()
verkettet ist.
Alles, was die Operator-Konsole kann, können diese Befehle auch — damit eine Aktion in einem Deploy-Hook, in einem Cron-Job oder auf einer Maschine laufen kann, auf der niemand einen Browser öffnen kann.
menu / actions
Es gibt über vierzig Tenancy-Verben. --help sagt Ihnen, dass sie existieren;
das Menü hilft Ihnen, eines auszuführen, das Sie noch nie ausgeführt haben.
cargo run -- menu
rustango manage — pick an action
TENANTS
1) list-tenants every tenant in the registry
2) create-tenant provision a new tenant
3) edit-tenant change routing and display config
…
HOSTNAMES
7) list-hosts every hostname a tenant answers on
…
q quit
? every other verb: cargo run -- --help
Wählen Sie eine Nummer (oder tippen Sie das Verb) und es fragt nur nach dem, wonach das Verb nicht selbst fragt, gibt die Kommandozeile aus, die es gleich ausführt, führt sie aus und kommt für die nächste Aktion zurück. Es läuft durch denselben Dispatcher wie die Flags und kann daher nicht von ihnen abweichen.
Verwandt, aber anders: wizard ist eine einmalige
Einrichtung; menu ist die ständige Liste dessen, was Sie danach tun können.
wizard / init
Führt ein frisches Projekt von „gerade generiert" zu einem funktionierenden
Tenant, einem Operator und einem Tenant-Superuser. Jeder Schritt ist
optional — drücken Sie n, um einen zu überspringen.
cargo run -- wizard
init-tenancy
No-op — aus Kompatibilitätsgründen beibehalten. Das Framework liefert keine
handgebauten Bootstrap-Migrationen mehr. Seine eigenen Tabellen
(rustango_orgs, rustango_operators, rustango_users, Rollen/Berechtigungen,
…) werden aus den kompilierten Modellen in system/migrations/ generiert — der
normale Ablauf (Modelle → makemigrations → migrate) — und von
migrate / migrate-registry angewendet, die
sie bei Bedarf generieren, falls die Dateien fehlen.
cargo run -- init-tenancy # does nothing now; kept so old scripts don't break
Ältere Versionen schrieben hier 0001_rustango_*_initial.json; dieser
hartkodierte Fluss ist verschwunden. Zum Bereitstellen führen Sie einfach
cargo run -- migrate aus. Ein eigenes Benutzermodell
(auf rustango_users deklariert) fließt durch dieselben generierten
system/migrations/ — siehe
Eigenes Benutzermodell.
migrate-registry
Wendet nur die Registry-Migrationen an — die gemeinsamen, tenant-übergreifenden
Tabellen. Die Registry hält rustango_orgs und rustango_operators sowie alle
registry-scoped Tabellen, die Sie definieren. Tenant-Tabellen bleiben unberührt.
cargo run -- migrate-registry
migrate-tenants
Wendet Tenant-Migrationen auf jeden aktiven Tenant nacheinander an. Jeder Tenant verwendet seine eigene Verbindung (sein eigenes Schema oder seine eigene Datenbank), und wenn ein Tenant scheitert, laufen die übrigen trotzdem weiter — der Befehl berichtet am Ende das Ergebnis pro Tenant.
cargo run -- migrate-tenants
Für den häufigen Fall macht ein einfaches migrate bereits zuerst die Registry,
dann die Tenants — greifen Sie zu migrate-tenants nur, wenn Sie diesen Schritt
für sich allein brauchen.
runserver / run-server
Startet den Multi-Tenant-Webserver. In einem
Tenancy-Projekt ist dies dasselbe wie ein nacktes cargo run; die benannte Form
existiert, damit eigene Binaries, die ihre eigenen Argumente parsen, es trotzdem
auslösen können.
cargo run # implicit
cargo run -- runserver # explicit
--bind <addr> schlägt RUSTANGO_BIND und [server] bind; in einem Tenancy-Projekt schlägt --apex <domain> RUSTANGO_APEX_DOMAIN und [tenancy] apex_domain. Jedes andere Flag wird abgelehnt. Der Server loggt die Adresse, auf der er lauscht, auf INFO.
Bei SIGTERM nimmt er keine Verbindungen mehr an und gibt offenen Verbindungen
[server] shutdown_timeout_secs (Standard 20) Zeit, dann schließt er den Rest.
Ein WsHub-WebSocket bekommt Close 1001, ein SSE-Stream in Shutdown::cut
endet; Long-Poll und andere Streams laufen bis zur Frist. Provisionierungs- und Migrationsläufe,
die ein gestoppter Prozess über eine Stunde auf running ließ, werden beim
nächsten Start als fehlgeschlagen markiert; ein Webhook-Retry mit derselben
event_id läuft erneut.
Ein runserver mit einer Datenbank wendet ausstehende Migrationen vor dem Binden
an und löst pre_migrate / post_migrate aus wie migrate. Er wartet bis zu
[server] migrate_lock_timeout_secs (Standard 300) auf die Sperre eines anderen
Laufs und beendet sich dann. Abschalten mit [server] migrate_on_boot = false
(RUSTANGO__SERVER__MIGRATE_ON_BOOT=false) oder Cli::migrate_on_boot(false).
Bei einem Rolling Deploy mit mehreren Replikas abschalten und migrate einmal als
Job vor dem Deploy laufen lassen, damit kein Pod migriert, während alte Pods noch
bedienen. Der Tenancy-Server migriert beim Start nie; migrate selbst ausführen.
create-tenant <slug> [options]
Richtet einen neuen Tenant (Kunde/Org) ein und wendet die Tenant-Migrationen
darauf an. Der <slug> ist sein kurzer Bezeichner. Nicht sicher erneut ausführbar:
ein erneuter Aufruf auf einem
bestehenden Slug wird vorab mit tenant slug `<slug>` already exists
abgelehnt (tenancy::provision::provision_tenant), bevor sonst etwas passiert.
cargo run -- create-tenant acme --display-name "ACME Corp"
cargo run -- create-tenant beta --mode database --database-url postgres://...
cargo run -- create-tenant gamma --mode database --server main
| Flag | Beschreibung |
|---|---|
--display-name <name> | Menschenlesbares Label, das in Admin-Seitenleisten angezeigt wird |
--mode schema | database | Speichermodus (Standard: schema, oder database, wenn --database-url oder --server angegeben ist) |
--database-url <url> | Eine vorhandene Datenbank für den Tenant |
--server <name> | Legt die Datenbank stattdessen auf diesem gespeicherten Server an |
--host-pattern <pattern> | Überschreibt das vom SubdomainResolver verwendete Host-Muster |
--no-migrate | Überspringt das Anwenden tenant-scoped Migrationen nach dem Provisioning |
--backend postgres | mysql | sqlite | Muss das Backend der Registry sein, das auch der Standard ist |
--schema-name <s> | Überschreibt den generierten Schemanamen im Schema-Modus |
--port <n> | Port in den Links des Tenants; allein routet er nichts (siehe unten) |
--path-prefix <s> | Pfad-Präfix, unter dem der Tenant erreichbar ist, fürs Routing |
--admin-email <e> / --admin-username <u> | Legt den ersten Superuser des Tenants an (siehe Erster Admin oben) |
--resume | Schließt einen Tenant ab, den ein früherer Lauf wegen fehlgeschlagener Migrationen inaktiv ließ; dieselben Flags erneut angeben |
Schlagen die Migrationen des Tenants fehl, endet create-tenant mit einem
Fehlercode und der Tenant bleibt inaktiv. Behebe die Migration und führe
denselben Befehl mit --resume erneut aus: er migriert und aktiviert den Tenant.
Jeder Modus prüft seine Rechte, bevor etwas entsteht, und wenn eines fehlt,
nennt er es und gibt die Anweisungen aus, die es beheben: Der Schemamodus braucht
das CREATE des Registry-Logins auf der Registry-Datenbank, --server braucht
die Admin-Rechte unten, --database-url braucht keine. Siehe
Rechte.
Mit --server werden zuerst die Admin-Rechte des Servers geprüft, dann wird eine
Datenbank angelegt, die exakt wie der Slug heißt, mit eigenem Login
(Zufallspasswort, nur auf diese Datenbank berechtigt); SQLite legt
<dir>/<slug>.db an. Eine vorhandene Datenbank dieses Namens wird abgelehnt, nie
wiederverwendet. Der neue Login muss sich dann anmelden (eine pg_hba-Regel oder
ein überdeckendes MySQL-Konto scheitert hier). Auf MySQL übernimmt die Datenbank
die utf8mb4-Collation der Registry. Die Tenant-URL wird versiegelt gespeichert und
die Datenbank in rustango_tenant_databases festgehalten. Scheitert das
Registrieren, Migrieren oder Aktivieren, werden die neue Datenbank, der Login und
die Tenant-Zeile wieder gelöscht, sodass derselbe Befehl einfach erneut laufen
kann. Scheitert dieses Löschen, bleiben der inaktive Tenant und sein Eintrag: Ein
fortsetzender erneuter Versuch (Webhook, create_tenant_if_missing) migriert ihn
an Ort und Stelle. Der Eintrag wird vor dem CREATE geschrieben, sodass ein
mittendrin abgebrochener Lauf eine Datenbank hinterlässt, die rustango finden kann:
Ein erneuter Versuch nach zehn Minuten löscht sie und beginnt neu und lehnt eine
Datenbank ab, von der er nicht beweisen kann, dass er sie angelegt hat.
edit-tenant <slug> [options]
Ändert Routing- und Anzeige-Konfiguration eines Tenants — dieselben Felder, die die Bearbeitungsseite der Operator-Konsole anbietet.
cargo run -- edit-tenant acme --host-pattern shop.example.com
cargo run -- edit-tenant acme --display-name "ACME Inc" --deactivate
cargo run -- edit-tenant acme --clear host-pattern
| Flag | Beschreibung |
|---|---|
--display-name <name> | Menschenlesbares Label |
--host-pattern <host> | Nackter Hostname, unter dem der Tenant antwortet |
--path-prefix <path> | Ein Segment mit führendem Slash, z. B. /acme |
--port <n> | Port in den Links des Tenants |
--database-url <url> | Rotiert die Verbindungs-URL des Tenants |
--activate / --deactivate | Tenant in oder außer Betrieb nehmen |
--clear <field> | Leert host-pattern, path-prefix oder port |
Nur die Felder, die Sie nennen, werden angefasst. „In Ruhe lassen" und
„leeren" sind unterschiedliche Anweisungen — dafür ist --clear da. Es
vermeidet die Abhängigkeit von --host-pattern "", das manche Shells und
CI-Runner verschlucken.
Werte werden so validiert, wie create-tenant sie validiert: ein Host-Muster
mit Port oder ein Pfad-Präfix, das der Resolver nie erzeugen könnte, wird
abgelehnt statt gespeichert, um dann stillschweigend nie zu matchen.
Ein Tenant braucht einen Host oder ein Pfad-Präfix. Der eingebaute Server
routet nicht nach Port, also wird ein Edit abgelehnt, das nur einen Port
übrig lässt, ebenso ein Create nur mit Port, wenn kein Apex gesetzt ist; mit
Apex bekommt das Create den Standard-Host <slug>.<apex>. Um nach Port zu
routen, baue eine eigene Resolver-Kette mit PortResolver und serviere einen
eigenen Router mit einem Listener pro Port (der Server-Builder hat dafür
keinen Hook), dann setze RUSTANGO_TENANT_PORT_ROUTING=1.
Ein Rotieren von --database-url ändert die gespeicherte URL. Jeder Server
wechselt binnen 30 s, wenn sein Tenant-Cache aufgefrischt wird; andere
Änderungen lassen warme Verbindungen unangetastet. Ein Secret, das hinter
derselben Referenz rotiert wird (Vault, Env-Var), ändert nichts
Gespeichertes: Server neu starten oder den Pool des Tenants auf jedem
Server invalidieren.
test-tenant-connection <url> [flags]
Prüft eine Datenbank-URL, bevor Sie sich darauf festlegen — verbindet und schreibt standardmäßig testweise mit Rollback, sodass eine Nur-Lese-Zugangsinformation hier auffällt statt bei der ersten Tenant-Anfrage.
cargo run -- test-tenant-connection postgres://user:pw@host/db
cargo run -- test-tenant-connection "$URL" --no-write-probe --timeout 5
drop-tenant <slug> [--confirm <slug>]
Deaktiviert einen Tenant, indem active = false gesetzt wird. Dies ist die
weiche, umkehrbare Option — die Daten des Tenants bleiben auf der Platte, und
reaktiviere ihn mit edit-tenant <slug> --activate.
Ein erneutes create-tenant funktioniert nicht: die Org-Zeile existiert
weiterhin, der Slug gilt also als Duplikat. Wenn Sie nicht
interaktiv laufen (kein Terminal angehängt), müssen Sie --confirm <slug> mit
dem erneut getippten Slug zur Bestätigung übergeben.
cargo run -- drop-tenant acme --confirm acme
purge-tenant <slug> [--confirm <slug>] [--purge-database]
Löscht einen Tenant dauerhaft. Es löscht das Schema des Tenants und entfernt
seine Zeile aus rustango_orgs, ohne Rückgängig-Machen. Wenn Sie nicht
interaktiv laufen (kein Terminal angehängt), müssen Sie --confirm <slug> mit
dem erneut getippten Slug übergeben. Bei Tenants im database-Modus bleibt die
zugrunde liegende Datenbank an Ort und Stelle, es sei denn, Sie übergeben
zusätzlich --purge-database. Ohne dieses Flag verweigert der Befehl bei
Database-Mode-Tenants komplett — er entfernt nicht die Org-Zeile und lässt die
Datenbank stehen, er tut gar nichts.
cargo run -- purge-tenant acme --confirm acme
cargo run -- purge-tenant beta --confirm beta --purge-database # database-mode: also DROP DATABASE
Bei mehreren Servern erst deaktivieren (drop-tenant) und 30 s warten. Ein
Server, dessen Tenant-Cache noch einen Schema-Mode-Tenant hält, behält
seinen Pool bis zur Cache-Auffrischung; nach dem Löschen des Schemas schlagen
seine Abfragen fehl oder lesen public, wenn eine Extension (etwa citext)
public in seinem search_path hält.
rotate-tenant-password <slug>
Gibt dem Login, den rustango für den Tenant auf einem gespeicherten Server
angelegt hat, ein neues Zufallspasswort: auf dem Server geändert, dann
versiegelt über der alten URL gespeichert, dann öffnen sich die Pools des
Tenants neu. Die Schritte werden ausgegeben, sobald sie enden; der Lauf wird als
rotate_password festgehalten. Andere Pods übernehmen die neue URL innerhalb
eines Fingerprint-Polls; zu diesem Zeitfenster siehe
Tenant-Datenbanken auf einem gespeicherten Server.
cargo run -- rotate-tenant-password acme
list-tenants
Listet jeden Tenant mit seinem Speichermodus und aktiv/inaktiv-Status.
cargo run -- list-tenants
Hostnamen
Ein Tenant ist unter seiner Subdomain erreichbar und optional unter weiteren Hostnamen, die Sie an ihn binden. Ein Hostname führt zu genau einem Tenant.
cargo run -- list-hosts acme
cargo run -- add-host acme shop.example.com
cargo run -- set-host-enabled acme shop.example.com --off # stilllegen
cargo run -- remove-host acme shop.example.com
| Verb | Was es tut |
|---|---|
list-hosts <slug> | Alle Hostnamen des Tenants, Basis-Host zuerst |
add-host <slug> <hostname> | Bindet einen. Abgelehnt, wenn ein anderer Tenant ihn bereits beansprucht |
remove-host <slug> <hostname> | Löst die Bindung |
set-host-enabled <slug> <hostname> --on|--off | Ausliefern oder stilllegen |
Stilllegen (--off) behält die Zeile und nimmt den Host aus dem Betrieb —
nützlich, während DNS propagiert, oder beim Ausmustern einer Domain, die Sie
vielleicht zurückhaben wollen.
Hostnamen werden beim Eingang normalisiert (kleingeschrieben, ohne Schema,
ohne Port, ohne Pfad), denn der gespeicherte Wert wird Byte für Byte gegen
den Host-Header verglichen. Die Verben geben aus, was gespeichert wurde,
nicht, was Sie getippt haben.
Der Basis-Host stammt aus dem host_pattern des Tenants und hat keine
eigene Zeile, kann hier also nicht entfernt werden — ändern Sie ihn mit
edit-tenant --host-pattern. Ein rename-host
gibt es bewusst nicht: entfernen und neu hinzufügen, damit die Änderung auch
andere laufende Pods erreicht.
Datenbankserver
Speichern Sie den Admin-Login eines Datenbankservers einmal, damit Tenant-Datenbanken ohne SQL darauf angelegt werden können. Das Backend ist das der Registry.
cargo run -- add-db-server main --host db.internal --user admin --tls require
cargo run -- test-db-server main
cargo run -- list-db-servers
cargo run -- edit-db-server main --port 6432
cargo run -- remove-db-server main
| Verb | Was es tut |
|---|---|
add-db-server <name> --host <h> [--port <n>] --user <u> [--tls <mode>] [--maintenance-db <db>] | Speichert einen Server. SQLite: stattdessen --sqlite-dir <dir> |
list-db-servers | Alle gespeicherten Server, ohne Geheimnisse |
test-db-server <name> | Meldet sich an und zeigt Version und Rechte des Admin-Logins; schlägt fehl, wenn nicht provisioniert werden kann |
edit-db-server <name> [gleiche Flags] [--prompt-password | --clear-password] [--on|--off] | Ändert einen Server; none leert --tls oder --maintenance-db |
remove-db-server <name> | Löscht ihn; abgelehnt, solange eine Tenant-Datenbank darauf liegt |
Das Passwort wird verdeckt abgefragt oder aus der mit --password-env <VAR>
benannten Variable gelesen; --no-password speichert keines. Es kommt nie aus
argv und wird nie ausgegeben. Es wird versiegelt gespeichert, daher muss
RUSTANGO_SECRET_KEY gesetzt sein.
create-operator <username> --password <pwd>
Erstellt einen Operator — einen globalen Admin, der jeden Tenant von einer tenant-übergreifenden Konsole aus verwalten kann. Operatoren leben in der gemeinsamen Registry, nicht innerhalb eines einzelnen Tenants.
cargo run -- create-operator admin --password correct-horse-42
cargo run -- create-operator admin --generate # stattdessen ein zufälliges ausgeben
Lassen Sie --password auf einem Terminal weg, wird ohne Echo gefragt.
list-operators
Jeder Operator, mit aktiv-Status und Erstellungsdatum, plus eine Zählung, wie viele noch aktiv sind.
cargo run -- list-operators
set-operator-active <username> --on|--off
Schaltet den Zugang eines Operators ab oder wieder an. Die Zeile bleibt in beiden Fällen erhalten, sodass sich „wer war das?" später noch auflösen lässt — und die Konsole liest sie bei jeder Anfrage neu, sodass eine Deaktivierung beim nächsten Klick greift und nicht erst, wenn das Cookie abläuft.
cargo run -- set-operator-active grace --off # Offboarding
cargo run -- set-operator-active grace --on
Zwei Dinge lehnt es ab, aus demselben Grund wie die Konsole:
- Den letzten aktiven Operator deaktivieren. Das sperrt alle aus der Konsole aus, und nur eine Shell auf der Registry könnte es rückgängig machen.
- Sich selbst deaktivieren, wenn die Anfrage aus der Konsole kommt. Die CLI hat keine Session, aus der sie sich aussperren könnte, dort gilt also nur die erste Regel.
Die Richtung ist erforderlich — Raten würde entweder Zugang entziehen oder gewähren, und beides ist falsch, wenn es stillschweigend geschieht. Den bereits vorhandenen Zustand zu setzen wird gemeldet und ist erfolgreich, damit ein erneut laufendes Provisioning-Skript nicht rot wird.
create-user <tenant> <username> --password <pwd> [--superuser]
Erstellt einen Benutzer innerhalb eines Tenants — mit --superuser auch einen
Administrator, aber immer auf einen einzelnen Tenant beschränkt. Statt
--password können Sie --password-stdin oder --generate (gibt ein
zufälliges aus) übergeben; lassen Sie alle drei im Terminal weg, fragt der
Befehl nach. Das Passwort muss dieselben Regeln wie die Web-Formulare
erfüllen: mindestens 12 Zeichen, eine Ziffer oder ein Sonderzeichen, kein
bekannt schwaches Passwort. --skip-validation überspringt sie. Ein
--staff-Flag gibt es nicht.
cargo run -- create-user acme alice --password Hunter2-alice-pw --superuser
--superuser setzt is_superuser = true für diesen Benutzer innerhalb des
Tenants. Das macht ihn zu einem Admin des Tenants (voller Schreibzugriff im
Tenant-Admin), gewährt aber nie Zugang zur tenant-übergreifenden
Operator-Konsole.
--email <e> speichert die E-Mail des Benutzers (braucht das Feature sso).
Mit [auth] login_field = "email" melden sich Benutzer damit an, also geben
Sie jedem Benutzer eine; der Befehl nennt das Feld, mit dem sich der Benutzer
anmeldet.
create-role <tenant> <name>
Erstellt eine Rolle (ein benanntes Bündel von Berechtigungen) innerhalb eines Tenants.
cargo run -- create-role acme editor
list-roles <tenant>
Listet die in einem bestimmten Tenant definierten Rollen.
cargo run -- list-roles acme
assign-role <tenant> <username> <role>
Gibt einem Benutzer eine der Rollen des Tenants.
cargo run -- assign-role acme alice editor
revoke-role <tenant> <username> <role>
Entfernt eine Rolle von einem Benutzer — die Umkehrung von assign-role.
cargo run -- revoke-role acme alice editor
grant-perm <tenant> <role-name|username> <codename> [--role]
Gewährt eine einzelne Berechtigung. Standardmäßig ist das zweite Argument ein
Benutzername, sodass die Berechtigung direkt an diesen Benutzer geht; fügen
Sie --role hinzu, um sie stattdessen einer Rolle zu gewähren.
Modell-Codenames verwenden das Format <table>.<action>
(posts.add, posts.change, posts.delete, posts.view). migrate legt
diese vier für jedes Modell an; mit #[rustango(permissions = false)] nehmen
Sie ein Modell aus.
cargo run -- grant-perm acme alice posts.change # grant to user alice
cargo run -- grant-perm acme editor posts.change --role # grant to role editor
revoke-perm <tenant> <role-name|username> <codename> [--role]
Entfernt eine Berechtigung — die Umkehrung von grant-perm. Zielt standardmäßig
auf einen Benutzer; fügen Sie --role hinzu, um sie stattdessen von einer Rolle
zu entziehen.
cargo run -- revoke-perm acme alice posts.change
cargo run -- revoke-perm acme editor posts.change --role
create-api-key <tenant> <username> [--label <s>]
Stellt einen API-Schlüssel für einen Tenant-Benutzer aus. Das vollständige Token wird einmal ausgegeben und nie wieder — kopieren Sie es jetzt, denn nur sein Präfix und ein Hash werden gespeichert.
cargo run -- create-api-key acme alice --label "ci-bot"
audit-cleanup
Beschneidet alte Einträge aus dem Audit-Log (rustango_audit_log), damit es
nicht ewig wächst. Kürzen Sie nach Alter (--days) oder nach Anzahl
(--keep-last), und optional auf einen Tenant beschränkt. Ohne beide Flags
löscht es Einträge, die älter als [audit] retention_days sind, und schlägt
fehl, wenn das nicht gesetzt ist.
cargo run -- audit-cleanup # älter als [audit] retention_days
cargo run -- audit-cleanup --days 90 # delete > 90 days old
cargo run -- audit-cleanup --keep-last 50 # keep most recent 50 per row
cargo run -- audit-cleanup --keep-last 50 --tenant acme # scoped
cargo run -- audit-cleanup --registry --days 90 # nur das Log der Registry
Standardmäßig räumt es das eigene Log der Registry und das jedes aktiven
Tenants auf. Im Registry-Log hält die Operator-Konsole fest, was Operatoren
getan haben — es wächst also mit der Nutzung der Konsole. Nennen Sie einen
Tenant (--tenant), fragen Sie nach diesem Tenant und lassen die Registry in
Ruhe. Ein defekter Tenant wird gemeldet und gezählt, statt den Durchlauf zu
beenden.
Ein Projekt mit einer Datenbank hat dasselbe Verb mit --days, --keep-last und
--yes; es kürzt das eine Audit-Log.
Nachsehen, was passiert ist
Drei Nur-Lese-Verben, die ausgeben, was die Konsole rendert — die Antworten, die Sie während eines Vorfalls brauchen, ohne Browser und ohne SQL-Client.
cargo run -- list-runs # letzte Provisioning- und Migrationsläufe
cargo run -- list-runs --kind migrate --limit 50
cargo run -- show-run 42 # die Schritte eines Laufs
cargo run -- audit-log # wer was wann geändert hat
cargo run -- audit-log --pk acme --limit 100
| Verb | Flags |
|---|---|
list-runs | --limit <n>, --kind provision|migrate|purge|rotate_password, --state pending|running|succeeded|failed |
show-run <id> | — |
audit-log | --limit <n>, --table <t>, --pk <v>, --operation <o>, --source <s> |
list-runs zeigt Neuestes zuerst, und seine Filter laufen in der Abfrage —
die Suche nach einem migrate-Lauf findet also einen, selbst wenn die
jüngsten Läufe alle Provisionings sind. show-run gibt den Kopf des Laufs
und jeden aufgezeichneten Schritt aus, und das sagt Ihnen, wo ein Fehler
auftrat.
Über die CLI angelegte Tenants werden ebenfalls aufgezeichnet, markiert mit
requested_by = cli, sodass die Historie beide Oberflächen abdeckt.
prewarm-pools
Öffnet im Voraus eine Verbindung für jeden aktiven Tenant im database-Modus. Lohnt sich nach einem Deploy, einem Registry-Neustart oder einer Rotation von Zugangsdaten: es verwandelt „die erste Anfrage an jeden Tenant zahlt den Verbindungsaufbau" in eine einzige bewusste Wartezeit und bringt einen nicht erreichbaren Tenant ans Licht, bevor ein Benutzer ihn findet.
cargo run -- prewarm-pools
Die Operator-Konsole hat dafür ebenfalls einen Button, auf der Tenant-Liste.
Eigenes Benutzermodell (zusätzliche Spalten auf rustango_users)
So fügen Sie der Benutzertabelle Ihre eigenen Felder hinzu. Der eingebaute Tenant-User hat
neun feste Spalten: id, username, password_hash, is_superuser,
active, created_at, password_changed_at, sessions_revoked_at, plus eine
data-JSONB-Spalte (ein flexibler JSON-Blob) für beliebige zusätzliche
Metadaten pro Benutzer. Mit dem Feature sso hat er außerdem eine eindeutige
email. Für die meisten Apps ist
diese JSONB-Spalte alles, was Sie brauchen — keine Migration, kein Override,
keine Überraschungen.
Wenn Sie stattdessen typisierte, indexierbare Spalten auf rustango_users
wollen, gibt es zwei Ansätze. Sie sind nicht austauschbar; wählen Sie den, der
dazu passt, wo Ihr Projekt in seinem Leben steht.
Option 1 — Geschwister-Profilmodell mit FK (funktioniert bei jedem Projekt)
Am besten, wenn das Projekt bereits existiert, oder wenn Sie die User-Tabelle
des Frameworks lieber als einzige Quelle der Wahrheit belassen möchten.
#[derive(rustango::Model)]
pub struct UserProfile {
#[rustango(primary_key)] pub id: rustango::sql::Auto<i64>,
#[rustango(fk = "rustango_users")] pub user_id: i64,
#[rustango(max_length = 128, default = "''")] pub display_name: String,
#[rustango(max_length = 64, default = "'UTC'")] pub timezone: String,
}
Führen Sie cargo run -- makemigrations dann cargo run -- migrate aus, und
Sie haben eine typisierte Extra-Tabelle, die per Fremdschlüssel mit dem Benutzer
verknüpft ist. Lesen Sie sie mit dem ORM:
let profile = UserProfile::objects()
.where_(UserProfile::user_id.eq(user.id.get().copied().unwrap()))
.first(&pool).await?; // Option<UserProfile>
Kompromiss: eine zusätzliche Zeile und ein JOIN bei jedem Zugriff. Vorteil: null Risiko, die Framework-Auth zu brechen.
Option 2 — Cli::user_model::<AppUser>() (nur auf der grünen Wiese)
Verwenden Sie dies nur auf einem frischen Projekt, bei dem Sie die
zusätzlichen Felder direkt auf der rustango_users-Tabelle selbst wollen. Da
AppUser das rustango_users-Modell ist, fließen seine Spalten durch die
gewöhnliche makemigrations → migrate-Engine: die Tabellen des Frameworks
werden in system/migrations/ generiert, sodass die Spalten von AppUser im
generierten CREATE TABLE rustango_users landen.
Schritt 1. Definieren Sie Ihr Modell. Es muss jede vom Framework geforderte
Spalte exakt deklarieren (id, username, password_hash, is_superuser,
active, created_at, data,
password_changed_at, sessions_revoked_at), plus Ihre Extras. Jede zusätzliche Spalte muss
entweder NULL erlauben oder einen default = "…" haben.
use rustango::sql::Auto;
#[derive(rustango::Model, Debug, Clone)]
#[rustango(table = "rustango_users")]
pub struct AppUser {
#[rustango(primary_key)] pub id: Auto<i64>,
#[rustango(max_length = 64, unique)] pub username: String,
#[rustango(max_length = 255)] pub password_hash: String,
pub is_superuser: bool,
pub active: bool,
pub created_at: chrono::DateTime<chrono::Utc>,
#[rustango(default = "'{}'")] pub data: serde_json::Value,
pub password_changed_at: Option<chrono::DateTime<chrono::Utc>>,
pub sessions_revoked_at: Option<chrono::DateTime<chrono::Utc>>,
// extras —
#[rustango(max_length = 128, default = "''")] pub display_name: String,
#[rustango(max_length = 64, default = "'UTC'")] pub timezone: String,
}
impl rustango::tenancy::TenantUserModel for AppUser {}
Schritt 2. Verdrahten Sie den Override in main.rs:
#[rustango::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
rustango::manage::Cli::new()
.api(my_app::urls::api())
.tenancy()
.user_model::<AppUser>()
.run().await
}
user_model prüft das Modell beim Start und bricht ab, wenn eine Pflichtspalte
fehlt; ausgewählt wird es dadurch, dass es auf rustango_users deklariert ist.
Schritt 3. Registrieren Sie AppUser anstelle des Framework-User —
nur ein Modell darf table = "rustango_users" beanspruchen. Der Scaffolder
liefert kein statisches Bootstrap-JSON (nur ein leeres system/migrations/),
es gibt also nichts zu löschen; registrieren Sie einfach nicht auch den
Framework-User.
Schritt 4. Generieren + anwenden:
cargo run -- makemigrations # generates system/migrations/ with AppUser's columns
cargo run -- migrate # creates rustango_users with your extras
Vorbehalte:
AppUserspäter zu ändern ist eine normale Schemaänderung: führen Siemakemigrationserneut aus, um dieAddColumn-Migration zu emittieren, dannmigrate.- Nur ein Modell darf auf
rustango_usersabbilden. Das Registrieren beider, des Framework-Userund IhresAppUser, machtmakemigrationsmehrdeutig — registrieren SieAppUserallein. Das ist der Hauptgrund, warum Option 2 nur für frische Projekte ist; bei einem bestehenden Projekt vermeidet Option 1 das Problem. - Framework-Auth- und Admin-Code liest die neun Kernspalten namentlich; Ihre
zusätzlichen Spalten sind nur über
AppUser::objects().fetch(...)erreichbar.
Builder::user_model::<AppUser>() macht dasselbe für Code, der den
Server-Builder direkt baut, ohne über Cli zu gehen.
Mehrere Replikas betreiben
Mancher Zustand lebt in einem Prozess. Hinter einem Load Balancer mit zwei oder mehr Replikas hält jeder Pod seine eigene Kopie:
- Cache. Der Standard
[cache] backend = "memory"ist eine Map pro Prozess. Nutzen Sie Redis oder den Datenbank-Cache (Caching), damit Zähler, Sperren und Einmal-Marken geteilt werden. - Rate Limits.
RateLimitLayerzählt pro Prozess; das echte Limit ist also das Limit mal die Zahl der Replikas. Nutzen SieCacheRateLimitLayermit einem geteilten Cache. - Login-Drossel und Sperre. Die Login-Limits pro IP und global und die
Benutzernamen-Sperre zählen pro Prozess, bis Sie geteilte mit
login_throttle::configure_sharedundaccount_lockout::configure_sharedinstallieren (Sicherheit). - Sperren. Ein
DistributedLockauf dem In-Memory-Cache sperrt nur einen Prozess. - JWT-Widerruf. Der Standard
InMemoryJtiStoremeldet anderen Replikas kein widerrufenes Token. Installieren Sie einen geteilten Store mitwith_jti_store. - i18n-Overrides. Jeder Prozess hält eine eigene Kopie. Andere Replikas sehen
eine Änderung, nachdem sie
refresh_overrides_poolaufrufen (i18n). - MCP. Der Benachrichtigungsbus und die Abbruch-Registry leben in einem
Prozess. Ein
list_changed- oder Fortschritts-Frame erreicht nur SSE-Clients auf demselben Pod, und einnotifications/cancelled, das auf einem anderen Pod ankommt, wird ignoriert (MCP). - Session-Schlüssel. Außerhalb von prod und ohne
RUSTANGO_SESSION_SECRETlegt der Tenancy-Server seine Tenant- und Operator-Session-Schlüssel auf jedem Pod in./var/ab. Eine Session von einem Pod wird dann auf einem anderen abgelehnt. Setzen SieRUSTANGO_SESSION_SECRETauf jeder Stufe mit mehr als einem Pod. - Brand-Dateien. Die Operator-Konsole speichert Logos standardmäßig in einem lokalen Verzeichnis (Operator-Konsole).
Herunterfahren
Bei SIGTERM:
- Nimmt der Server sofort keine Verbindungen mehr an. Der Listener schließt, neue Verbindungen zu diesem Pod werden abgewiesen.
- Bittet er jede offene Verbindung, nach ihrer laufenden Anfrage zu schließen.
- Sendet er jedem
WsHub-WebSocket Close 1001 und beendet jeden SSE-Stream, der inShutdown::cutsteckt, etwa den MCP-Stream (WebSockets). - Wartet er auf offene Verbindungen bis zu
[server] shutdown_timeout_secs(Standard 20; im Codeserver::Builder::drain_timeout), loggt dann eine Warnung und schließt den Rest.
Kubernetes nimmt einen stoppenden Pod erst kurz nach dem SIGTERM aus seinem
Service. Ein paar neue Verbindungen kommen also noch an und werden abgewiesen.
Fügen Sie einen kurzen preStop-Sleep hinzu, damit der Pod bedient, bis er
entfernt ist. Setzen Sie terminationGracePeriodSeconds über Sleep plus
shutdown_timeout_secs:
spec:
terminationGracePeriodSeconds: 30
containers:
- name: web
lifecycle:
preStop:
sleep:
seconds: 5 # Kubernetes 1.30+; älter: exec: { command: ["sleep", "5"] }
/ready pingt die Datenbank mit SELECT 1. Ist jede Pool-Verbindung innerhalb
von 30 Sekunden nach einem erfolgreichen Ping belegt, meldet es die Datenbank
ohne Ping als bereit, damit eine Lastspitze nicht alle Replikas zugleich
scheitern lässt. Nach 30 Sekunden pingt es wieder; eine hängende Datenbank gibt
also weiter 503. Jeder Prozess merkt sich seinen eigenen letzten Ping.
Eine /ready-Antwort wird 1 Sekunde wiederverwendet, sodass eine Flut von Probes
die Checks einmal pro Sekunde ausführt; HealthRouter::ready_cache(d) ändert das.
Der Server hält höchstens RUSTANGO_MAX_CONNECTIONS (10 000) Verbindungen; die
nächste wartet im Backlog.
Bei einer App mit einer Datenbank migrate_on_boot abschalten und migrate
einmal als Job vor dem Deploy laufen lassen (siehe runserver oben).
Eigene Unterbefehle
Ein Crate kann eigene Verben hinzufügen, die App ebenso. Sie stehen in
--help unter dem Crate, das sie registriert hat, und laufen wie die
eingebauten.
Aus einem Crate — register_command! registriert das Verb beim Linken,
die Host-App ändert main nicht:
use std::io::Write as _;
use rustango::manage::CommandContext;
// In any crate the binary links, e.g. a CMS library.
rustango::register_command!(
"reset-link",
"Print a password-reset link for a user",
|mut ctx: CommandContext, args: Vec<String>| async move {
let user = args.first().ok_or("usage: reset-link --tenant <slug> <user>")?;
let pool = ctx.tenant_pool().ok_or("pass --tenant <slug>")?.clone();
// ... look the user up on `pool` with the ORM ...
writeln!(ctx.stdout(), "link for {user}")?;
Ok(())
},
);
Aus der App — die Builder-Methode Cli::command:
rustango::manage::Cli::new()
.tenancy()
.command("import-csv", "Import a CSV file", |ctx, args| async move {
my_csv_importer::run(ctx.pool(), &args).await?;
Ok(())
})
.run()
.await
Der Handler bekommt einen CommandContext und die Argumente nach dem Verb:
ctx.pool()— die Datenbank der App; in einem Tenancy-Projekt die Registry.ctx.tenant_pool()/ctx.tenant()— mitCli::tenancy()wird--tenant <slug>aus den Argumenten genommen und öffnet den Pool dieses Mandanten (Schema- oder Datenbank-Modus, jedes Backend).ctx.tenant_by_slug(slug)öffnet jeden anderen.ctx.settings()— die anCli::with_settings*übergebenen Einstellungen.ctx.stdout()— wohin die Ausgabe geht.
cargo run -- reset-link --tenant acme alice
Ein Name, der mit einem eingebauten Verb kollidiert oder doppelt
registriert ist, lässt Cli::run beim Start mit beiden Namen im Fehler
scheitern.
Cli::run_with_args(args) führt die CLI mit den übergebenen Argumenten (ohne
Programmnamen) statt mit denen des Prozesses aus, etwa aus einem Test.
Datenbankverbindung. Alle Verben, der Server und eigene Befehle lesen
die Datenbank aus DATABASE_URL oder aus DB_DRIVER, DB_HOST,
DB_PORT, DB_USER, DB_PASSWORD (oder DB_PASSWORD_FILE, einer Datei
mit dem Passwort), DB_NAME und DB_PARAMS. Für SQLite DB_DRIVER=sqlite
und DB_NAME als Dateipfad setzen. DB_PASSWORD und DB_PASSWORD_FILE
zusammen zu setzen ist ein Fehler. Sind beide Varianten gesetzt, gewinnt
DATABASE_URL, eine einzige Warnung (Passwort verborgen) sagt es, und
check --deploy listet es auf; bleib also bei einer Variante.
Häufige Arbeitsabläufe
Erstmalige Projekteinrichtung (single-tenant)
cargo rustango new myapp
cd myapp
cp .env.example .env # edit DATABASE_URL
docker compose up -d
cargo run -- migrate
cargo run # serve at :8080
Erstmalige Projekteinrichtung (tenancy)
cargo rustango new myapp --template tenant
cd myapp
cp .env.example .env # edit DATABASE_URL + RUSTANGO_APEX_DOMAIN
docker compose up -d
cargo run -- makemigrations # files for your models
cargo run -- migrate # registry + tenants
cargo run -- create-operator admin --password correct-horse-42
cargo run -- create-tenant acme --display-name "ACME Inc" \
--host-pattern acme.localhost
cargo run -- create-user acme alice --password Tenant-pw-2026 --superuser
cargo run # serve at :8080
Tenants hinzufügen, nachdem die App bereits läuft
Eine echte Tenancy-App baut in der Regel lange vor der Anmeldung ihres ersten Tenants Modelle und Migrationen auf. Dieser Ablauf funktioniert zu jedem Zeitpunkt im Leben des Projekts:
# 1. (any time) develop user models — define structs with #[derive(Model)],
# add `pub mod ...;` to src/lib.rs.
# 2. Generate scope-aware migrations. In a tenancy project this writes
# up to TWO files: one tagged registry-scope (touches Org/Operator),
# one tagged tenant-scope (touches User + your models). Pre-v0.24.2
# this used to dump everything into one tenant-scoped file and
# crash on `create-tenant` — see the changelog.
cargo run -- makemigrations
# 3. Apply migrations. `migrate` is scope-aware: it runs registry-
# scoped files once against the registry pool first, then fans
# tenant-scoped files across every active tenant.
cargo run -- migrate
# 4. Provision a NEW tenant whenever (could be days, weeks, many
# migrations later). The tenancy code applies every accumulated
# tenant-scoped migration to the new tenant's schema in one pass —
# the new tenant arrives at the same schema state as existing ones.
cargo run -- create-tenant acme --display-name "ACME Inc" \
--host-pattern acme.localhost
cargo run -- create-user acme alice --password Tenant-pw-2026 --superuser
Warum das sicher ist:
#[rustango(scope = "registry")]aufOrg/Operatorhält Änderungen an gemeinsamen Tabellen aus den Per-Tenant-Migrationen heraus.migrate-tenantsbesucht jeden aktiven Tenant und wendet nur die Tenant-Migrationen an — Registry-Dateien werden übersprungen.create-tenantführt denselbenmigrate-tenants-Durchlauf gegen das Schema des neuen Tenants aus, sodass er vollständig auf dem neuesten Stand startet, ohne manuelle Nachbesserung.
Ein Modell hinzufügen
cargo run -- startapp blog # if not done yet
# Edit src/blog/models.rs — rename the starter `Blog` to `Post`
# (table = "posts") and add its fields
# (startapp already added `pub mod blog;` to src/lib.rs)
cargo run -- makemigrations
cargo run -- migrate
Eine JSON-API für dieses Modell hinzufügen
cargo run -- make:viewset PostViewSet --model Post
# Edit src/post_view_set.rs — fill in field lists
# Add `pub mod post_view_set;` to src/lib.rs
# Mount it in src/main.rs, as the end of src/post_view_set.rs shows:
# .nest_with("/api", |pool| myapp::post_view_set::PostViewSet::router("/posts", pool))
cargo run # GET /api/posts now works
Ein Daten-Backfill hinzufügen
cargo run -- add-data-op \
--sql "UPDATE posts SET slug = lower(title) WHERE slug IS NULL" \
--reverse-sql "UPDATE posts SET slug = NULL" \
--name backfill_post_slugs
cargo run -- migrate
Pre-Deploy-Audit
cargo run --release -- check --deploy
Die letzte Migration zurückrollen
cargo run -- downgrade 1
Eine Tenancy-Migration auf einen bestimmten Scope anwenden
cargo run -- migrate-registry # registry-scoped only
cargo run -- migrate-tenants # tenant-scoped, fan-out across orgs
Einen Tenant außer Betrieb nehmen
cargo run -- drop-tenant acme # soft (reversible)
cargo run -- purge-tenant acme # hard (drops schema/db)
Tenant-Pool-Feinabstimmung (v0.27.7+)
Tenants im database-Modus erhalten ihren eigenen Verbindungspool (einen
PgPool — eine Menge wiederverwendeter Datenbankverbindungen), zwischengespeichert
nach Slug in TenantPools.
Standardmäßig wird ein Pool faul, beim ersten Request des Tenants gebaut, es
sei denn, Sie schalten das Pre-Warming ein. Die Einstellungen leben auf
TenantPoolsConfig:
| Feld | Standard | Zweck |
|---|---|---|
max_cached_database_pools | 64 | Obergrenze für den Pool-Cache. Ist er voll, wird der am längsten nicht genutzte Tenant-Pool geschlossen. |
database_pool_max_connections | 16 | max_connections pro Pool. Halten Sie es klein, damit ein Tenant-Fan-out PGs max_connections nicht erschöpft. |
database_pool_min_connections | 0 | Hält jederzeit N Verbindungen warm. ≥1 senkt die Latenz des ersten Requests, indem der TCP/TLS/Auth-Roundtrip beim Boot bezahlt wird. |
database_pool_acquire_timeout | 30s | Wie lange pool.acquire() wartet, bevor es mit PoolTimedOut scheitert. |
database_pool_idle_timeout | 10 min | Schließt untätige Verbindungen nach dieser Dauer. Wehrt Kappungen durch Load-Balancer / idle_in_transaction_session_timeout ab. |
database_pool_max_lifetime | 30 min | Erzwingt das Rotieren von Verbindungen, damit vault-geleaste Anmeldedaten aufgefrischt werden. |
prewarm_active_tenants | false | Wenn true, ruft Server::Builder::serve beim Boot prewarm_database_tenants() auf. |
max_cached_scoped_pools | 16 | Obergrenze für die gecachten Pools pro Tenant bei Tenants im schema-Modus. |
scoped_pool_max_connections | 3 | max_connections des Abfrage-Pools eines Tenants im schema-Modus (t.pool()). |
scoped_held_pool_max_connections | 1 | max_connections des Halte-Pools eines Tenants im schema-Modus (Tenant::conn). Darüber wartet eine Anfrage bis database_pool_acquire_timeout und erhält dann 503 (TenancyError::TenantConnBusy). |
max_concurrent_pool_builds | 16 | Gleichzeitige Pool-Aufbauten im Datenbank-Modus; ein Aufbau wartet bis database_pool_acquire_timeout, dann 503. 0 = keine Grenze. |
max_pool_builds_per_minute | 600 | Pool-Aufbauten im Datenbank-Modus pro Minute; darüber 503. 0 = keine Grenze. |
Tenants im schema-Modus können max_cached_scoped_pools × (scoped_pool_max_connections + scoped_held_pool_max_connections)
Verbindungen zum Registry-Server öffnen (standardmäßig 64), bemessen mit dem Registry-Pool
für ein Standard-Postgres (max_connections = 100); der Start warnt, wenn der Server nach
seinen reservierten Plätzen weniger erlaubt, auch vor dem ersten Tenant. Erhöhen Sie sie auf einem größeren Server oder hinter PgBouncer.
Mit Cli übergeben Sie die Konfiguration über Cli::with_tenant_pools(config).
Beim Boot vorwärmen
Zwei Wege zum Auslösen:
-
Automatisch — setzen Sie
prewarm_active_tenants = trueauf derTenantPoolsConfig, die SieTenantPools::new(...).config(...)übergeben.Server::Builder::serveführt das Pre-Warming vor dem Binden aus. -
CLI-Verb —
cargo run -- prewarm-poolsbaut Pools für jeden aktiven Tenant im database-Modus und beendet sich. Nützlich als Post-Deploy-Hook (z. B. nach einer Anmeldedaten-Rotation) oder um zu validieren, dass jeder Tenant erreichbar ist, bevor ein Load-Balancer umgeschaltet wird.
Das Pre-Warming durchläuft Org::objects().where(active = true, storage_mode = "database") und bricht kurz, wenn die Cache-Obergrenze erreicht ist (gemeldet
als skipped_cap im [PrewarmReport]). Per-Tenant-Build-Fehler loggen ein
tracing::warn!, brechen die Schleife aber nicht ab.
Tracing
tenant_pool_init ist ein tracing::info_span!, der den
Cold-Path-Pool-Build umschließt; die Events darin tragen das Target
rustango::tenancy::pools. Abonnieren Sie es, um die
Per-Tenant-Build-Latenz zu sehen:
INFO rustango::tenancy::pools: tenant pool connected (database mode)
slug=acme elapsed_ms=42 min_conn=1 max_conn=4
Einschalten mit RUST_LOG=rustango::tenancy::pools=info. Ein Filter auf
crate::tenancy::pools passt auf nichts — ein Target ist ein String und
kein Pfad, siehe Logging.
Einrichtungs-Falle — macOS .local-TLDs
Wenn Sie den Tenant-Admin über http://acme.local:8080/admin/ auf macOS
erreichen und bei jedem Request eine 5-Sekunden-Pause sehen: das ist
Bonjour / mDNS, nicht Rustango. Der Resolver von macOS behandelt
.local speziell und wartet den vollen mDNS-Timeout ab, bevor er auf
/etc/hosts zurückfällt. Zwei Lösungen:
- Verwenden Sie eine andere TLD:
127.0.0.1 acme.localhostfunktioniert ohne Verzögerung.localhostist reserviert (RFC 6761) und überspringt mDNS. - Betreiben Sie dnsmasq mit einer
.local-Zone, die auf 127.0.0.1 zeigt, damit das OS eine sofortige Antwort erhält.
Bestätigen Sie mit curl -w "%{time_connect}\n": wenn time_connect ~5s zeigt,
aber mit --resolve acme.local:8080:127.0.0.1 auf Millisekunden fällt, treffen
Sie auf mDNS.
