tablestudioapp/plugins

Arbeiten mit Datenbanken über TableStudio

TableStudio ist die Datenbank-App des Benutzers auf seinem Mac. Seine MCP-Tools erreichen die gespeicherten Verbindungen ohne Anmeldeinformationen und verfügen über Sicherheitsnetze, die eine rohe psql-Sitzung nicht bietet: einen exakten Trockenlauf eines Schreibvorgangs gegen die echten Zeilen, Wegwerf-Sandbox-Kopien und einen Überprüfungs-Posteingang, in dem der Benutzer Änderungen genehmigt. Verwenden Sie sie für Datenbankarbeit anstelle von psql, mysql, sqlite3 oder einem Skript, das eine eigene Verbindung öffnet.

Die folgenden Toolnamen stammen von TableStudio. Ihr Client zeigt sie möglicherweise mit einem Präfix an (in Claude Code: mcp__plugin_tablestudio_tablestudio__list_connections). Wenn sie zurückgestellt sind, laden Sie sie vor dem ersten Aufruf unter diesem Namen.

1. Die richtige Datenbank finden, bevor Sie etwas tun

Der Hinweis zum Datenbankkontext der Sitzung aus dem TableStudio-Plugin nennt normalerweise die TableStudio-Verbindung hinter den einzelnen Datenbankeinstellungen des Repositorys, mit ihrer ID und Umgebung. Verwenden Sie diese ID als connection_id. Der Hinweis sagt auch, wann die Tools von TableStudio nicht verfügbar sind und was der Benutzer dagegen tun soll.

Ohne den Hinweis oder für eine Datenbank, die er nicht nennt:

1. Rufen Sie list_connections auf. Jede Verbindung kann enthalten, was der Benutzer TableStudio über sie mitgeteilt hat:
   • project: das Projekt, zu dem sie gehört. Bevorzugen Sie Verbindungen, deren Projekt mit dem Repository übereinstimmt, in dem Sie arbeiten.
   • environment: development, staging oder production. Fehlt, bedeutet nicht getaggt, nicht development.
   • read_only: TableStudio verweigert Schreibvorgänge darauf. Staging funktioniert trotzdem.
   • location: local (dieser Mac), remote oder sandbox (eine Wegwerfkopie, sicher zum Experimentieren).
   • agent_writes: direct bedeutet, dass execute_query dort schreiben darf (wenn Schreibvorgänge eingeschaltet sind); review bedeutet, dass jede Änderung über stage_migration geht, damit der Benutzer sie anwendet. TableStudio entscheidet dies, nicht Sie: Produktion und jede entfernte Datenbank, die der Benutzer nicht als Entwicklung oder Staging getaggt hat, sind review.
   • notes: die Notizen des Benutzers zu den Konventionen der Datenbank (Soft Deletes, Geld in Cent, Benennung). Befolgen Sie sie.
2. Gleichen Sie zuerst das Projekt ab, dann bestätigen Sie mit host, port und database gegen die eigenen Einstellungen des Projekts (.env, config).
3. Wenn zwei Verbindungen die vom Benutzer gemeinte sein könnten oder Sie nicht sagen können, ob eine Produktion ist, fragen Sie. Raten Sie nicht.

Dann:

• Rufen Sie describe_capabilities einmal auf, bevor Sie etwas über eine reine Leseoperation hinaus planen. Es sagt, ob direkte Schreibvorgänge, Staging und Sandboxes gerade erlaubt sind, und nennt die jeweilige Einstellung. Planen Sie entsprechend, anstatt an eine Grenze zu stoßen, weil sie verweigert wird.
• agent_writes: review (Produktion oder entfernt und nicht getaggt) bedeutet, niemals direkt darauf zu schreiben: Änderungen zur Überprüfung bereitstellen. TableStudio verweigert dort ohnehin einen direkten Schreibvorgang, also planen Sie von Anfang an mit Staging.
• Überprüfen Sie engine (postgres, mysql, sqlite, d1, clickhouse), bevor Sie SQL schreiben, und schreiben Sie diesen Dialekt.
• Eine Datenbank, die nicht in TableStudio gespeichert ist, kann über seine Tools nicht erreicht werden. Bitten Sie den Benutzer, sie in TableStudio hinzuzufügen. Fragen Sie niemals nach einem Passwort im Chat.
• Wenn ein Aufruf fehlschlägt, weil die Datenbank nicht erreichbar ist, rufen Sie connection_status auf. Wenn es sagt, dass ein lokaler Server gestoppt ist, rufen Sie start_local_database mit der instance_id auf, die es Ihnen gibt.

2. Lesen und Untersuchen

• Schlagen Sie Dinge nach, anstatt Namen zu raten: search_schema findet Tabellen und Spalten anhand von Namensfragmenten, und get_table_ddl gibt die vollständige Struktur, Indizes, Fremdschlüssel und referenced_by.
• Führen Sie Lesevorgänge mit execute_query aus. Wählen Sie die benötigten Spalten aus, filtern, aggregieren und LIMIT. Ergebnisse sind begrenzt (max_rows, Standard 200), also ist ein truncated-Ergebnis nicht die vollständige Antwort.
• Lesevorgänge laufen in einer schreibgeschützten Transaktion mit einem 30-Sekunden-Limit, auch in der Produktion, sodass ein Lesevorgang selbst über eine Funktion keine Daten ändern kann. Halten Sie sie trotzdem günstig: Filtern Sie bei einer großen Produktionstabelle auf einer indizierten Spalte oder verwenden Sie Zeilenschätzungen aus database_overview anstelle von count(*).
• Ein Datenfehler: Reproduzieren Sie ihn zuerst in den Daten. Finden Sie die fehlerhaften Zeilen, zählen Sie sie und finden Sie heraus, wann sie begonnen haben (min(created_at)). Lesen Sie dann den Code, der sie schreibt. Zeigen Sie dem Benutzer die Abfrage, die es beweist. Beheben Sie den Code. Wenn Zeilen repariert werden müssen, ist das eine Datenänderung (Abschnitt 3).
• Geben Sie niemals Geheimnisse, Passwörter oder Verbindungszeichenfolgen in SQL, Code, Dokumente oder Chat ein. Der einzige Ort, an den eine Verbindungszeichenfolge gehört, ist die git-ignorierte Umgebungsdatei des Projekts für eine lokale Datenbank (die Skill-Anleitung für lokale Datenbanken behandelt get_connection_url).

3. Daten ändern (INSERT, UPDATE, DELETE)

Auf PostgreSQL:

1. Schreiben Sie die Anweisung und rufen Sie dann preflight_statement damit auf. Sie erhalten ein verdict (looks_fine, review oder would_fail), dry_run.rows (genau, wie viele Zeilen es ändern würde, schreibgeschützt), Kaskaden in andere Tabellen und was zum Fehlschlagen führen würde.
2. Teilen Sie dem Benutzer in einfachen Worten mit, was es tun wird: „Dies aktualisiert 142 Zeilen in invoices; nichts kaskadiert.“ Wenn das Urteil would_fail ist, korrigieren Sie die Anweisung zuerst. Wenn es review ist, erklären Sie warum.
3. Dann entweder:
   • agent_writes: direct und direkte Schreibvorgänge sind erlaubt: execute_query mit expected_rows gesetzt auf dry_run.rows. Es committed nur, wenn sich genau diese Anzahl von Zeilen ändert, und macht andernfalls einen Rollback. Bei einer entfernten PostgreSQL-Datenbank verweigert TableStudio eine Datenänderung ohne expected_rows.
   • agent_writes: review, Schreibvorgänge nicht erlaubt oder alles, was der Benutzer zuerst sehen sollte: stage_migration mit einem klaren title, dem SQL und einer rationale, die die Trockenlaufanzahl enthält („Entfernt die 142 doppelten Rechnungen, gefunden durch …“). Es geht in die Überprüfungswarteschlange des Benutzers im TableStudio Agent Center und wird nicht ausgeführt.

Bei anderen Engines gibt es keinen Trockenlauf: Führen Sie zuerst ein SELECT count(*) mit dem gleichen WHERE aus, melden Sie die Anzahl und befolgen Sie dann die gleiche Ausführen-oder-Staging-Regel.

Führen Sie vor etwas Destruktivem an einer wichtigen Datenbank (einem großen DELETE, einem DROP, einem TRUNCATE) create_restore_point aus, wenn Sandboxes aktiviert sind, und teilen Sie dem Benutzer mit, dass Sie dies getan haben.

4. Das Schema ändern

Wenn das Repository ein Migrationstool verwendet (Prisma, Drizzle, Rails, Django, Alembic, Laravel, Supabase, Knex, Ecto, TypeORM, Wrangler D1 oder einfache nummerierte SQL-Dateien; der Sitzungskontext nennt es, wenn das Plugin eines erkannt hat), gehört die Änderung in dieses Tool:

1. Nehmen Sie die Änderung auf die Weise des Tools vor: Bearbeiten Sie das Schema und generieren Sie eine Migration oder schreiben Sie die Migrationsdatei.
2. Wenden Sie sie auf die lokale Entwicklungsdatenbank mit dem Entwicklungsbefehl des Tools an.
3. Überprüfen Sie sie gegen echte Daten (unten).
4. Überlassen Sie das Anwenden an anderer Stelle dem normalen Bereitstellungsprozess des Benutzers. Führen Sie niemals den Bereitstellungsbefehl des Tools selbst gegen die Produktion aus.

Die direkte Ausführung von ALTER TABLE, wenn ein Migrationstool das Schema besitzt, bringt den Verlauf des Tools mit der Datenbank außer Sync, was die nächste Bereitstellung unterbricht.

Wenn es kein Migrationstool gibt oder der Benutzer eine einmalige Änderung an einer vorhandenen Datenbank wünscht:

1. Lesen Sie die Tabelle zuerst mit get_table_ddl. Überprüfen Sie referenced_by, bevor Sie etwas löschen oder umbenennen.
2. Probieren Sie es an einer Kopie aus: create_sandbox (data: none nur für das Schema, sample für einen Ausschnitt echter Zeilen), führen Sie das DDL auf der Sandbox-Verbindung mit execute_query aus und überprüfen Sie, ob es das tut, was Sie beabsichtigt haben.
3. Zeigen Sie den Unterschied mit compare_schemas (Sandbox als source_connection_id, die echte Datenbank als target_connection_id).
4. Schlagen Sie es mit stage_migration auf der echten Verbindung vor. Der Benutzer wendet es von TableStudio aus an.

Überprüfen einer Migration gegen echte Daten

Eine Migration, die auf der lokalen Datenbank erfolgreich ist, kann immer noch fehlschlagen oder die App sperren, wo die echten Zeilen sind. Bevor Sie eine Migration als abgeschlossen bezeichnen, überprüfen Sie sie schreibgeschützt gegen die Datenbank, in die sie bereitgestellt wird (normalerweise Staging oder Produktion, aus dem Sitzungshinweis oder list_connections):

1. get_table_ddl für jede Tabelle, die sie ändert: wie viele Zeilen, ihre Indizes und was darauf verweist.

2. Für jedes Constraint, das sie hinzufügt, führen Sie execute_query mit dem SELECT aus, das Zeilen findet, die es brechen würden:

   • NOT NULL: SELECT count(*) FROM t WHERE col IS NULL
   • UNIQUE: SELECT col, count(*) FROM t GROUP BY col HAVING count(*) > 1 LIMIT 20
   • einen Fremdschlüssel: untergeordnete Zeilen, deren übergeordnete Zeile nicht existiert (LEFT JOIN … WHERE parent.id IS NULL)
   • eine CHECK- oder eine engere Typ- oder Längenbeschränkung: Zeilen außerhalb des neuen Bereichs

   Alle Zeilen bedeuten, dass die Bereitstellung fehlschlagen würde. Fügen Sie einen Backfill- oder Bereinigungsschritt zur Migration hinzu und sagen Sie es.

3. Markieren Sie bei PostgreSQL Schritte, die eine große Tabelle sperren oder neu schreiben (siehe unten), und wechseln Sie zum sicheren Muster.

4. Wenn die Änderung knifflig ist, führen Sie sie auf einer Kopie aus: create_sandbox von dieser Verbindung mit data: "sample", execute_query mit dem SQL der Migration auf der Sandbox, dann compare_schemas.

Teilen Sie dem Benutzer mit, was Sie überprüft und was Sie gefunden haben („orders.status hat 0 NULLs bei 1,2 Millionen Zeilen, also ist SET NOT NULL sicher“). All dies ist schreibgeschützt: Wenden Sie die Migration niemals anderswo als auf der lokalen Entwicklungsdatenbank an.

Sperren bei PostgreSQL

• Das Erstellen eines Indexes auf einer großen, stark genutzten Tabelle: Verwenden Sie CREATE INDEX CONCURRENTLY. Es kann nicht innerhalb einer Transaktion ausgeführt werden, also umschließen Sie diese Anweisung nicht mit BEGIN … COMMIT.
• Das Hinzufügen einer NOT NULL-Spalte mit einem flüchtigen Standardwert, das Ändern eines Spaltentyps oder das Hinzufügen eines Fremdschlüssels kann die Tabelle neu schreiben oder sperren. Sagen Sie dies in der Begründung und erwägen Sie, es in sichere Schritte aufzuteilen (Spalte nullable hinzufügen, in Batches backfillen, dann SET NOT NULL; einen Fremdschlüssel NOT VALID hinzufügen, dann VALIDATE CONSTRAINT).
• schema_issues gibt SQL zur Behebung mit einem lock_impact für jedes Problem zurück. Lesen Sie es, bevor Sie eine Korrektur vorschlagen.

5. Nachdem Sie etwas bereitgestellt haben

• Teilen Sie dem Benutzer mit, dass es auf seine Überprüfung in TableStudio wartet und nicht ausgeführt wurde, und geben Sie ihm die review_url aus dem Ergebnis als Link. Sie öffnet die Überprüfung mit den Auswirkungen der Änderung (betroffene Zeilen, Sperren, mögliche Fehlschläge), einem Diagramm des Schemas danach und einem Rückgängig-Plan. Sagen Sie niemals, dass eine bereitgestellte Änderung angewendet wurde.
• Wenn der Benutzer Änderungen wünscht, zeigt list_staged_migrations status: changes_requested mit seiner Notiz in review_feedback. Überarbeiten Sie sie mit update_staged_migration (gleiche migration_id), anstatt eine zweite Kopie bereitzustellen, und teilen Sie ihm dann mit, dass sie wieder zur Ansicht bereit ist. Um sie zurückzuziehen, verwenden Sie remove_staged_migration.
• list_staged_migrations zeigt auch, ob der Benutzer sie angewendet, ignoriert oder fehlgeschlagen ist.

Wenn der Benutzer fragt, was auf ihn wartet („Was hast du bereitgestellt?“, „Ist meine Migration gelaufen?“), rufen Sie list_staged_migrations für die Verbindungen dieses Repositorys auf. Melden Sie zuerst die ausstehenden, die neuesten zuerst: den Titel, die Verbindung, wann sie bereitgestellt wurde, die review_url und eine Zeile darüber, was sie tut und wie riskant sie ist (sperrt oder schreibt sie eine große Tabelle neu, löscht sie Daten oder fehlt ihr ein WHERE?). Dann alle mit angeforderten Änderungen mit der Notiz des Benutzers und alle, die fehlgeschlagen sind, mit dem Fehler. Sagen Sie klar, dass der Benutzer sie im TableStudio Agent Center anwendet, zurücksendet oder ignoriert; Sie können sie nicht selbst anwenden.

6. Wenn TableStudio Nein sagt

• Eine Ablehnung, die eine Einstellung nennt (zum Beispiel, dass Schreibvorgänge ausgeschaltet sind), ist die Wahl des Benutzers. Sagen Sie ihm, welche Einstellung es erlauben würde, bieten Sie an, die Änderung stattdessen bereitzustellen, und hören Sie auf. Umgehen Sie es nicht.
• Wenn die Tools von TableStudio überhaupt nicht verfügbar sind, sagt der Sitzungshinweis, warum: Die App ist geschlossen, ihr MCP-Server ist ausgeschaltet (Einstellungen → MCP) oder der Client ist noch nicht damit verbunden. Geben Sie die Korrektur weiter, die er angibt. In Claude Code kann der Benutzer mit /mcp neu verbinden, sobald TableStudio geöffnet ist.
• Eine Ablehnung mit blocked: production_review_required oder review_required bedeutet, dass diese Verbindung Änderungen nur über die Überprüfung annimmt: Stellen Sie sie bereit. dry_run_required bedeutet, führen Sie zuerst preflight_statement aus und übergeben Sie expected_rows. side_effect_function bedeutet, dass die Anweisung etwas aufruft, das außerhalb einer Transaktion wirkt; zeigen Sie dem Benutzer stattdessen das SQL.
• Die Shell-Sperre des Plugins blockiert Shell-Befehle, die in die Produktion schreiben. Behandeln Sie eine Blockade als Signal, die obigen Schritte zu verwenden, nicht als etwas, das umgangen werden muss.
• Alles, was Sie über TableStudio tun, wird dem Benutzer in seinem Agent Center angezeigt, gruppiert nach dieser Unterhaltung.