tablestudioapp/plugins

---

name: database-workflow description: Como ler e alterar com segurança o banco de dados de um projeto através do TableStudio. Use para qualquer tarefa que envolva um banco de dados real: consultar ou inspecionar dados, investigar um bug de dados, corrigir ou preencher linhas, semear, adicionar ou alterar tabelas, colunas, índices ou restrições, escrever ou revisar uma migração, ou executar SQL. Use também sempre que você normalmente usaria psql, mysql, sqlite3, wrangler d1 execute, um DATABASE_URL ou um script avulso que abre sua própria conexão.

Trabalhando com bancos de dados através do TableStudio

O TableStudio é o aplicativo de banco de dados do usuário no Mac. Suas ferramentas MCP alcançam as conexões salvas sem credenciais e vêm com redes de segurança que uma sessão psql pura não possui: uma execução de teste exata de uma gravação nas linhas reais, cópias sandbox descartáveis e uma caixa de entrada de revisão onde o usuário aprova alterações. Use-as para trabalho com banco de dados em vez de psql, mysql, sqlite3 ou um script que abre sua própria conexão.

Os nomes das ferramentas abaixo são do TableStudio. Seu cliente pode mostrá-los com um prefixo (no Claude Code: mcp__plugin_tablestudio_tablestudio__list_connections). Se estiverem adiadas, carregue-as pelo nome antes da primeira chamada.

1. Encontre o banco de dados correto antes de fazer qualquer coisa

A nota de contexto do banco de dados da sessão, do plugin TableStudio, geralmente nomeia a conexão do TableStudio por trás de cada configuração de banco de dados do repositório, com seu id e ambiente. Use esse id como connection_id. A nota também diz quando as ferramentas do TableStudio não estão disponíveis e o que o usuário deve fazer a respeito.

Sem a nota, ou para um banco de dados que ela não nomeia:

1. Chame list_connections. Cada conexão pode conter o que o usuário disse ao TableStudio sobre ela:
   • project: o projeto ao qual pertence. Prefira conexões cujo projeto corresponde ao repositório em que você está trabalhando.
   • environment: development, staging ou production. Ausente significa não marcado, não development.
   • read_only: o TableStudio recusa gravações nela. Staging ainda funciona.
   • location: local (este Mac), remote ou sandbox (uma cópia descartável, segura para experimentar).
   • agent_writes: direct significa que execute_query pode escrever lá (quando as gravações estão ativadas); review significa que toda alteração passa por stage_migration para o usuário aplicar. O TableStudio decide isso, não você: produção e qualquer banco de dados remoto que o usuário não marcou como development ou staging são review.
   • notes: as notas do usuário sobre as convenções do banco de dados (soft deletes, dinheiro em centavos, nomenclatura). Siga-as.
2. Combine o projeto primeiro, depois confirme com host, port e database em relação às próprias configurações do projeto (.env, config).
3. Se duas conexões puderem ser a que o usuário quer, ou você não conseguir dizer se uma é produção, pergunte. Não adivinhe.

Então:

• Chame describe_capabilities uma vez antes de planejar qualquer coisa além de uma leitura. Ele diz se gravações diretas, staging e sandboxes são permitidos agora, e nomeia a configuração por trás de cada um. Planeje em torno disso em vez de descobrir um limite sendo recusado.
• agent_writes: review (produção, ou remoto e não marcado) significa nunca escrever diretamente: prepare as alterações para revisão. O TableStudio recusa uma gravação direta de qualquer forma, então planeje para staging desde o início.
• Verifique engine (postgres, mysql, sqlite, d1, clickhouse) antes de escrever SQL, e escreva nesse dialeto.
• Um banco de dados que não está salvo no TableStudio não pode ser acessado através de suas ferramentas. Peça ao usuário para adicioná-lo no TableStudio. Nunca peça uma senha no chat.
• Se uma chamada falhar porque o banco de dados está inacessível, chame connection_status. Quando ele disser que um servidor local está parado, chame start_local_database com o instance_id que ele fornecer.

2. Leitura e investigação

• Pesquise em vez de adivinhar nomes: search_schema encontra tabelas e colunas por fragmento de nome, e get_table_ddl fornece a estrutura completa, índices, chaves estrangeiras e referenced_by.
• Execute leituras com execute_query. Selecione as colunas que você precisa, filtre, agregue e LIMIT. Os resultados são limitados (max_rows, padrão 200), então um resultado truncated não é a resposta completa.
• As leituras são executadas em uma transação somente leitura com limite de 30 segundos, mesmo em produção, então uma leitura não pode alterar dados, mesmo através de uma função. Mantenha-as leves de qualquer forma: em uma tabela grande de produção, filtre em uma coluna indexada ou use estimativas de linhas database_overview em vez de count(*).
• Um bug de dados: reproduza-o nos dados primeiro. Encontre as linhas ruins, conte-as e descubra quando começaram (min(created_at)). Então leia o código que as escreve. Mostre ao usuário a consulta que prova isso. Corrija o código e, se as linhas precisarem de reparo, isso é uma alteração de dados (seção 3).
• Nunca cole segredos, senhas ou strings de conexão em SQL, código, docs ou chat. O único lugar onde uma string de conexão pertence é no arquivo env ignorado pelo git do projeto, para um banco de dados local (a habilidade de bancos de dados locais cobre get_connection_url).

3. Alterando dados (INSERT, UPDATE, DELETE)

No PostgreSQL:

1. Escreva a declaração, depois chame preflight_statement com ela. Você recebe um verdict (looks_fine, review ou would_fail), dry_run.rows (exatamente quantas linhas alteraria, somente leitura), cascatas para outras tabelas e o que a faria falhar.
2. Diga ao usuário em palavras simples o que ela fará: "Isso atualiza 142 linhas em invoices; nada em cascata." Se o veredito for would_fail, corrija a declaração primeiro. Se for review, explique o porquê.
3. Então, ou:
   • agent_writes: direct e gravações diretas são permitidas: execute_query com expected_rows definido como dry_run.rows. Ele confirma apenas se exatamente esse número de linhas for alterado e reverte caso contrário. Em um banco de dados PostgreSQL remoto, o TableStudio recusa uma alteração de dados sem expected_rows.
   • agent_writes: review, gravações não permitidas ou qualquer coisa que o usuário deve ver primeiro: stage_migration com um title claro, o SQL e uma rationale que inclui a contagem de dry-run ("Anula as 142 faturas duplicadas encontradas por …"). Ele vai para a fila de revisão do usuário no Agent Center do TableStudio e não é executado.

Em outros motores não há dry run: primeiro execute um SELECT count(*) com o mesmo WHERE, relate a contagem, depois siga a mesma regra de executar ou preparar.

Antes de qualquer coisa destrutiva em um banco de dados que importa (um grande DELETE, um DROP, um TRUNCATE), chame create_restore_point quando sandboxes estiverem ativados e informe ao usuário que você fez isso.

4. Alterando o esquema

Se o repositório usa uma ferramenta de migração (Prisma, Drizzle, Rails, Django, Alembic, Laravel, Supabase, Knex, Ecto, TypeORM, Wrangler D1 ou arquivos SQL numerados simples; o contexto da sessão nomeia quando o plugin detectou um), a alteração pertence a essa ferramenta:

1. Faça a alteração da maneira da ferramenta: edite o esquema e gere uma migração, ou escreva o arquivo de migração.
2. Aplique-a ao banco de dados de desenvolvimento local com o comando de desenvolvimento da ferramenta.
3. Verifique-a contra dados reais (abaixo).
4. Deixe a aplicação em qualquer outro lugar para o processo de deploy normal do usuário. Nunca execute o comando de deploy da ferramenta contra produção você mesmo.

Executar ALTER TABLE diretamente quando uma ferramenta de migração possui o esquema deixa o histórico da ferramenta dessincronizado com o banco de dados, o que quebra o próximo deploy.

Se não houver ferramenta de migração, ou o usuário pedir uma alteração avulsa em um banco de dados existente:

1. Leia a tabela primeiro com get_table_ddl. Verifique referenced_by antes de descartar ou renomear qualquer coisa.
2. Teste em uma cópia: create_sandbox (data: none para apenas esquema, sample para uma fatia de linhas reais), execute o DDL na conexão do sandbox com execute_query e verifique se faz o que você pretendia.
3. Mostre a diferença com compare_schemas (sandbox como source_connection_id, o banco de dados real como target_connection_id).
4. Proponha com stage_migration na conexão real. O usuário aplica do TableStudio.

Verifique uma migração contra dados reais

Uma migração que passa no banco de dados local ainda pode falhar, ou travar o aplicativo, onde as linhas reais estão. Antes de considerar uma migração concluída, verifique-a somente leitura contra o banco de dados para o qual será implantada (geralmente staging ou produção, da nota da sessão ou list_connections):

1. get_table_ddl para cada tabela que ela altera: quantas linhas, seus índices e o que a referencia.

2. Para cada restrição que ela adiciona, execute_query o SELECT que encontra linhas que a quebrariam:

   • NOT NULL: SELECT count(*) FROM t WHERE col IS NULL
   • UNIQUE: SELECT col, count(*) FROM t GROUP BY col HAVING count(*) > 1 LIMIT 20
   • uma chave estrangeira: linhas filhas cujo pai não existe (LEFT JOIN … WHERE parent.id IS NULL)
   • uma CHECK, ou um tipo ou comprimento mais restrito: linhas fora do novo intervalo

   Qualquer linha significa que o deploy falharia. Adicione uma etapa de backfill ou limpeza à migração e informe.

3. No PostgreSQL, sinalize etapas que bloqueiam ou reescrevem uma tabela grande (veja abaixo) e mude para o padrão seguro.

4. Quando a alteração for complicada, execute-a de verdade em uma cópia: create_sandbox a partir dessa conexão com data: "sample", execute_query o SQL da migração no sandbox, depois compare_schemas.

Diga ao usuário o que você verificou e o que encontrou ("orders.status tem 0 NULLs em 1,2M linhas, então SET NOT NULL é seguro"). Tudo isso é somente leitura: nunca aplique a migração em nenhum lugar além do banco de dados de desenvolvimento local.

Locks no PostgreSQL

• Construir um índice em uma tabela grande e movimentada: use CREATE INDEX CONCURRENTLY. Não pode ser executado dentro de uma transação, então não envolva essa declaração em BEGIN … COMMIT.
• Adicionar uma coluna NOT NULL com um padrão volátil, alterar o tipo de uma coluna ou adicionar uma chave estrangeira pode reescrever ou bloquear a tabela. Informe na justificativa e considere dividir em etapas seguras (adicione a coluna nullable, backfill em lotes, depois SET NOT NULL; adicione uma chave estrangeira NOT VALID, depois VALIDATE CONSTRAINT).
• schema_issues retorna SQL de correção com um lock_impact para cada problema. Leia antes de propor uma correção.

5. Depois de preparar algo

• Informe ao usuário que está aguardando revisão no TableStudio e não foi executadoe forneça o review_url do resultado como um link. Ele abre a revisão com o impacto da alteração (linhas que toca, locks, o que falharia), um diagrama do esquema depois dela e um plano de desfazer. Nunca diga que uma alteração preparada foi aplicada.
• Se o usuário pedir alterações, list_staged_migrations mostra status: changes_requested com a nota em review_feedback. Revise com update_staged_migration (mesmo migration_id) em vez de preparar uma segunda cópia, depois informe que está pronta para ser revisada novamente. Para retirá-la, use remove_staged_migration.
• list_staged_migrations também mostra se o usuário aplicou, ignorou ou falhou.

Quando o usuário perguntar o que está esperando ("o que você preparou?", "minha migração rodou?"), chame list_staged_migrations para as conexões deste repositório. Relate as pendentes primeiro, da mais nova para a mais antiga: o título, a conexão, quando foi preparada, seu review_url e uma linha sobre o que faz e quão arriscada é (bloqueia ou reescreve uma tabela grande, exclui dados ou carece de um WHERE?). Depois, quaisquer com changes requested, com a nota do usuário, e quaisquer que falharam, com o erro. Diga claramente que o usuário aplica, envia de volta ou ignora no Agent Center do TableStudio; você não pode aplicá-las você mesmo.

6. Quando o TableStudio diz não

• Uma recusa que nomeia uma configuração (por exemplo, gravações estão desligadas) é uma escolha do usuário. Diga qual configuração permitiria, ofereça preparar a alteração e pare. Não contorne.
• Se as ferramentas do TableStudio não estiverem disponíveis, a nota da sessão explica o porquê: o aplicativo está fechado, seu servidor MCP está desligado (Settings → MCP) ou o cliente ainda não está conectado. Repasse a correção que ela fornece. No Claude Code, o usuário pode reconectar com /mcp assim que o TableStudio estiver aberto.
• Uma recusa com blocked: production_review_required ou review_required significa que essa conexão só aceita alterações através de revisão: prepare. dry_run_required significa executar preflight_statement primeiro e passar expected_rows. side_effect_function significa que a declaração chama algo que atua fora de uma transação; mostre o SQL ao usuário.
• O shell guard do plugin bloqueia comandos de shell que gravam em produção. Trate um bloqueio como um sinal para usar as etapas acima, não como algo a contornar.
• Tudo o que você fizer através do TableStudio é mostrado ao usuário no Agent Center, agrupado por esta conversa.