MySQL gerenciado

Visão geral

Cada MySQL gerenciado roda numa instância própria dentro do seu ambiente, com disco persistente e backup lógico diário conforme o plano. A plataforma cria a conta que os seus serviços usam, guarda a credencial e a entrega nas variáveis do serviço do banco.

Criar um banco

Pelo canvas do projeto ou pela CLI. O banco fica pronto em cerca de três minutos; quando aparece como running, a conta já existe e o login já funciona.

Conectar um serviço

O serviço do banco expõe as variáveis abaixo. Use-as por referência no serviço que consome o banco: a referência é resolvida a cada deploy, então uma troca de senha chega ao serviço no deploy seguinte.

# No serviço que consome o banco (o banco aqui se chama "mysql")
$ upuai variables set 'DATABASE_URL=${{mysql.DATABASE_URL}}' -s api
✓ Set DATABASE_URL [service]
ℹ Takes effect on the service's next deploy — run `upuai redeploy -s api` to apply it now.

$ upuai deploy -s api --wait --yes
✓ Deployment success

Para apontar um serviço para outro banco criado por você na mesma instância, monte a URL com as referências:

# Outro banco criado por você dentro do mesmo MySQL
DATABASE_URL=mysql://${{mysql.MYSQL_USER}}:${{mysql.MYSQL_PASSWORD}}@${{mysql.HOST}}:3306/inkprint_master

Conectar do seu computador

O acesso público abre o banco num endereço próprio, <slug>.db.upuai.cloud, numa porta exclusiva dele, com certificado TLS válido (Let's Encrypt). Fica desligado por padrão.

• Ligue em: serviço do banco → aba Conectar → Acesso público (dono ou admin do workspace), ou pela CLI com upuai db public enable.
• Cada banco tem a sua porta. Ela não muda se você desligar e religar o acesso; só some quando o banco é apagado.
• Use verificação completa de identidade: --ssl-mode=VERIFY_IDENTITY no cliente mysql; no DBeaver, aba SSL → Use SSL + Verify server certificate; no MySQL Workbench, SSL → Require and Verify Identity; em JDBC, sslMode=VERIFY_IDENTITY.
• O usuário é a conta de aplicação (MYSQL_USER) e a senha é a mesma das variáveis. A aba Conectar mostra host, porta, usuário, senha e banco em campos separados para clientes gráficos.
• Restrinja quem pode conectar com a lista de IPs permitidos da mesma aba; fora dela a conexão é recusada antes de chegar ao banco.

# Host e porta: painel → serviço do banco → aba Conectar (ou `upuai db public status`)
# macOS: --ssl-ca=/etc/ssl/cert.pem · Debian/Ubuntu: /etc/ssl/certs/ca-certificates.crt
$ mysql --host=xq7zk3pm.db.upuai.cloud --port=23310 --user=app --password \
    --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/cert.pem app

# Backup completo (rotinas, eventos, triggers e views)
$ mysqldump --host=xq7zk3pm.db.upuai.cloud --port=23310 --user=app --password \
    --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/cert.pem \
    --single-transaction --routines --events --triggers --set-gtid-purged=OFF --no-tablespaces \
    app > backup.sql

# Restaurar
$ mysql --host=xq7zk3pm.db.upuai.cloud --port=23310 --user=app --password \
    --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/cert.pem app < backup.sql

A conta de aplicação

A conta entregue em MYSQL_USER é a administradora dos seus dados naquela instância. Um app com um banco por cliente, por exemplo, cria os bancos com ela mesma.

O que a conta pode fazer

• Criar, alterar e remover bancos, tabelas, índices e views.
• Criar triggers, funções, procedures e eventos.
• Criar outras contas e conceder a elas os privilégios que ela mesma tem — por exemplo uma conta só de leitura para BI.
• Ler o estado do servidor (processos, status de replicação).

-- Conectado com a DATABASE_URL do serviço
SELECT CURRENT_USER(), VERSION();
-- app@%   8.4.6

CREATE DATABASE tenant_000001;
CREATE TABLE tenant_000001.orders (id INT PRIMARY KEY AUTO_INCREMENT, note VARCHAR(40));
CREATE TRIGGER tenant_000001.orders_bi BEFORE INSERT ON tenant_000001.orders
  FOR EACH ROW SET NEW.note = UPPER(NEW.note);
CREATE FUNCTION tenant_000001.one() RETURNS INT DETERMINISTIC RETURN 1;

-- Uma conta só de leitura para uma ferramenta de BI
CREATE USER 'bi_ro'@'%' IDENTIFIED BY '<senha>';
GRANT SELECT ON tenant_000001.* TO 'bi_ro'@'%';

O que fica com a plataforma

• Não existe conta root. Privilégios de administração do servidor (variáveis globais, desligar, arquivos) não são entregues.
• O schema de sistema mysql é somente leitura para a conta.
• As contas com prefixo moco- são da plataforma (replicação, backup, monitoração). Não as altere nem remova: isso para o backup e a operação do seu banco.
• A autenticação é caching_sha2_password, o padrão do MySQL 8. Use um driver atual (mysql2 no Node, mysqlclient/PyMySQL recentes, Connector/J 8+).

Senha: reparo e rotação

A credencial em uso fica guardada na plataforma, e as variáveis do serviço do banco são um espelho dela. Por isso elas são somente leitura: editar o texto de MYSQL_PASSWORD não mudaria a senha no banco.

• Reparar: confere se a conta consegue logar e a reaplica se o banco a recusar (conta alterada por fora, por exemplo). Não troca a senha.
• Rotacionar: gera uma senha nova. A senha atual deixa de abrir conexões na hora; conexões já abertas continuam até fecharem.
• Depois de uma rotação, faça o deploy dos serviços listados no resultado: eles seguem com a senha antiga até lá.
• No painel: serviço do banco → aba Database → Credenciais. Rotacionar exige dono ou admin do workspace.
• Marcar uma variável do banco como segredo continua possível (ícone de cadeado na aba Variables), mas pense antes: o valor deixa de ser exibido no painel e na CLI, e para desmarcar é preciso informar o valor atual. Os serviços continuam recebendo a credencial por referência.

# Confere o login; reaplica a conta se o banco a recusar. Não troca a senha.
$ upuai db credentials repair -s mysql
✓ credentials are working — nothing to change

# Senha nova. A atual deixa de abrir conexões na hora.
$ upuai db credentials rotate -s mysql --yes
✓ password rotated — the previous one no longer opens connections
ℹ redeploy to pick up the current credential: api
ℹ read the new value with 'upuai variables list -s <database>'

$ upuai deploy -s api --wait --yes
✓ Deployment success

Tentar editar ou apagar uma variável de conexão do banco é recusado, com a indicação do caminho certo:

$ upuai variables set 'MYSQL_PASSWORD=outra-senha' -s mysql
✗ failed to set variables: API error 409: Connection variables of a managed database are set by
  the platform and cannot be edited or deleted. To change the password, rotate the database
  credentials. To use another database name or user, create it inside the database and reference
  it from the consuming service. (keys: MYSQL_PASSWORD; reason: databaseCredentialsReadOnly)

Para agentes de IA

Receita determinística para Claude Code, Cursor e outros agentes que operam a CLI.

# 1. Ligar um serviço ao banco: sempre por referência, nunca colando a URL
upuai variables set 'DATABASE_URL=${{<db>.DATABASE_URL}}' -s <service>
upuai deploy -s <service> --wait --yes

# 2. "Access denied" num MySQL gerenciado
upuai db credentials repair -s <db>      # reaplica a conta se o banco a recusar
upuai deploy -s <service> --wait --yes   # só se o comando listar o serviço

# 3. Trocar a senha (dono ou admin)
upuai db credentials rotate -s <db> --yes
upuai deploy -s <service> --wait --yes   # cada serviço listado

# Nunca: apagar e recriar o banco, editar as variáveis dele,
# ou trocar por uma imagem Docker do MySQL para "resolver" um erro de acesso.

Erros e o que fazer

Códigos estáveis devolvidos pela API e pela CLI.

Perguntas frequentes

Recursos