Cloud SQL

Nos apps do App Maker, os dados geralmente são armazenados no Cloud SQL, um serviço do Google Cloud Platform (GCP) com bancos de dados SQL totalmente gerenciados na nuvem. Saiba mais sobre os benefícios do Cloud SQL.

Como desenvolvedor de aplicativos, escolha entre dois tipos de instâncias do Cloud SQL:

  • Padrão: um administrador do G Suite pode configurar uma instância do Cloud SQL compartilhada entre aplicativos do App Maker em uma organização. Quando a instância padrão é configurada, um banco de dados é criado automaticamente para o aplicativo quando você adiciona pelo menos um modelo de dados do Cloud SQL. Escolha essa opção se o aplicativo precisar de um banco de dados fácil de usar e que não precise de configuração. Normalmente, as organizações usam uma instância padrão, enquanto os desenvolvedores criam protótipos e testam um aplicativo. Em seguida, o aplicativo é transferido para uma instância personalizada quando está pronto para implantação como aplicativo de produção.

  • Personalizado: depois que o administrador configurar uma instância padrão do Cloud SQL, você também pode configurar a própria instância. Escolha essa opção quando:

    • o aplicativo atende a um grande número de usuários ou armazena uma grande quantidade de dados;
    • o banco de dados precisa ser compartilhado com outros aplicativos;
    • você precisa gerenciar o banco de dados ou manter o controle da instância do Cloud SQL.

Segurança do Cloud SQL

Independentemente do aplicativo usar a instância padrão ou personalizada do Cloud SQL, as credenciais são sempre criptografadas em trânsito e em repouso:

  • Cloud SQL padrão: as credenciais são armazenadas no servidor do App Maker. Elas nunca ficam acessíveis para desenvolvedores de aplicativos ou usuários finais.

  • Cloud SQL personalizado: uma vez que um desenvolvedor envia credenciais do Cloud SQL para o App Maker, elas nunca mais ficam visíveis para os desenvolvedores do aplicativo. O App Maker armazena as credenciais no navegador enquanto um desenvolvedor trabalha em um aplicativo no editor. As credenciais são removidas quando o desenvolvedor atualiza ou fecha a guia do navegador.

    Quando um desenvolvedor implanta um aplicativo com um modelo do Cloud SQL personalizado, as credenciais são armazenadas nos servidores do Google com o aplicativo implantado. Elas nunca ficam acessíveis para os usuários finais.

Antes de começar

Antes de usar o Cloud SQL com o App Maker, avalie as seguintes considerações de segurança e custo:

  • Os dados armazenados no GCP ficam fora da sua organização do G Suite: algumas organizações, especialmente as agências governamentais, têm requisitos rígidos para o armazenamento de dados confidenciais. Tanto o GCP quanto o G Suite atendem a rigorosos padrões de privacidade e segurança, mas o uso de cada um desses serviços pode estar sujeito a termos diferentes. Saiba mais sobre como cumprimos os padrões de privacidade e segurança:

  • O Cloud SQL faz parte do GCP: você tem a opção de iniciar uma avaliação gratuita se quiser testar uma instância personalizada. No entanto, o uso continuado gera despesas para a organização. Saiba mais sobre preços. O preço mensal típico da maioria dos aplicativos do App Maker é insignificante.

Usar uma nova instância personalizada do Cloud SQL para seu aplicativo

Se você não quiser usar a instância padrão do Cloud SQL, pode usar uma instância personalizada do serviço. Para que você use uma instância personalizada do Cloud SQL, um administrador do G Suite ainda precisa configurar uma instância padrão primeiro. Para o aplicativo, é possível usar um banco de dados personalizado atual ou criar um. Se você criar uma instância personalizada, levará algum tempo para configurá-la e integrá-la ao App Maker.

Observação: não é possível conectar o aplicativo a um banco de dados em uma instância personalizada do Cloud SQL a menos que o administrador do G Suite configure uma instância padrão do Cloud SQL.

Recomendamos que você use uma instância do Cloud SQL de segunda geração se estiver configurando uma nova. O App Maker também é compatível com instâncias de primeira geração. As características de preço e desempenho variam dependendo do tipo de instância. Portanto, revise os recursos antes de criar uma instância.

Para as instruções a seguir, é necessário ter:

  • acesso ao Console do GCP;
  • permissões para criar instâncias e usuários do Cloud SQL.

Segunda geração

  1. Se você ainda não tiver feito isso, crie uma instância de segunda geração do Cloud SQL para MySQL na região us-central.
  2. No Console do GCP, crie uma conta de usuário do MySQL para permitir o acesso do aplicativo ao banco de dados.

    Registre o nome de usuário e a senha para que você possa inseri-los quando conectar o aplicativo ao banco de dados. Para impedir o acesso não autorizado por meio de contas de usuários, recomendamos que você defina senhas fortes para todas as contas da instância.

  3. No Console do GCP, crie um banco de dados.
  4. O App Maker é executado no App Engine. Para configurar uma conexão com o App Engine, adicione uma conta de serviço ao projeto do Cloud:
    1. Acesse a página de projetos do IAM e administrador (no Console do GCP, clique em Menu IAM e administrador).
    2. Selecione o projeto que contém a instância do Cloud SQL.
    3. Clique em Adicionar.
    4. Na caixa de diálogo Novos membros, digite:
      appmaker-maestro@appspot.gserviceaccount.com
      Escolha Cloud SQLCliente do Cloud SQL como papel.
    5. Clique em Salvar.
    6. Se outros desenvolvedores forem editar ou implantar esse aplicativo, adicione as Contas do Google deles como novos membros e atribua a elas o papel de Cliente do Cloud SQL.
  5. Copie os detalhes da sua instância:
    1. Abra a página de instâncias do Cloud SQL (no Console do GCP, clique em Menu SQL).
    2. Clique na sua instância e procure pelo campo Nome da conexão da instância.
    3. Na caixa Nome da conexão da instância, clique em Copiar .
  6. Configure o aplicativo para usar o banco de dados personalizado do Cloud SQL:
    1. No App Maker, abra o aplicativo e clique em Configurações Banco de dados.
    2. Clique em Alternar para um banco de dados personalizado do Cloud SQL.
    3. Cole os detalhes da instância e adicione o nome do banco de dados criado no passo 3. Use o seguinte formato:
      projectName:regionName:instanceName/databaseName
    4. Digite o nome de usuário e a senha da conta de usuário do banco de dados e clique em Continuar.

Primeira geração

O App Maker é compatível com instâncias de primeira geração. No entanto, se você criar uma instância, recomendamos criar uma de segunda geração em vez disso.

  1. Se você ainda não tiver feito isso, crie uma instância de primeira geração.
  2. Configure contas de usuário para essa instância:
    • Altere a senha da conta raiz. Para impedir o acesso não autorizado por meio da conexão do App Engine (criada nos passos a seguir), recomendamos que você defina uma senha forte para a conta.
    • Crie uma conta de usuário que possa ser usada pelo aplicativo para acessar o banco de dados. Ao criar o usuário do banco de dados:
      • especifique localhost como o Nome do host;
      • defina uma senha forte para a conta, de modo a impedir o acesso não autorizado.

      Registre o nome de usuário e a senha para que você possa inseri-los quando conectar o aplicativo ao banco de dados.

  3. No Console do GCP, crie um banco de dados.
  4. O App Maker é executado no App Engine. Para configurar uma conexão com o App Engine, adicione o ID do aplicativo do App Maker à instância do Cloud SQL:
    1. Acesse a página de instâncias do Cloud SQL (no Console do GCP, clique em Menu SQL).
    2. Clique no nome da instância para abrir a página Visão geral e acesse a guia Autorização.
    3. Clique em Adicionar código do projeto e insira:
      appmaker-maestro
    4. Clique em Concluído para sair do modo de edição.
    5. Clique em Salvar para atualizar a instância.
  5. Adicione a instância personalizada do Cloud SQL ao aplicativo.
    1. Abra o aplicativo e clique em Configurações Banco de dados.
    2. Clique em Alternar para um banco de dados personalizado do Cloud SQL.
    3. Digite o endereço no seguinte formato:
      projectName:instanceName/databaseName
    4. Digite o nome de usuário e a senha da conta de usuário do banco de dados e clique em Continuar.

Usar um banco de dados atual do Cloud SQL para seu aplicativo

Se você já tem dados no Cloud SQL, pode criar um modelo no aplicativo para usar esses dados:

  1. Adicione os detalhes da instância ao aplicativo:
    1. Abra a página de instâncias do Cloud SQL (no Console do GCP, clique em Menu SQL).
    2. Clique na sua instância e procure pelo campo Nome da conexão da instância.
    3. Na caixa Nome da conexão da instância, clique em Copiar .
    4. No App Maker, abra o aplicativo e clique em Configurações Banco de dados.
    5. Clique em Alternar para um banco de dados personalizado do Cloud SQL.
    6. Cole os detalhes da instância e adicione o nome do banco de dados atual. Use o seguinte formato: projectName:regionName:instanceName/databaseName
    7. Digite o nome de usuário e a senha da conta de usuário do banco de dados e clique em Continuar.
  2. Na IU do App Maker, ao lado de Dados, clique em Adicionar
  3. Selecione Google Cloud SQL (atual).
  4. Digite o endereço no seguinte formato:

    • Primeira geração: projectName:instanceName/databaseName
    • Segunda geração: projectName:regionName:instanceName/databaseName
  5. Digite o nome de usuário e a senha da conta de usuário do banco de dados.

  6. Selecione uma tabela da lista e clique em Importar. É possível importar qualquer tabela que não seja mesclada.

As relações são criadas automaticamente quando você importa as tabelas envolvidas nelas. As relações de um banco de dados do Cloud SQL são reconhecidas por meio de tabelas mescladas ou restrições de chave estrangeira de tabelas importadas. Por exemplo, se a tabela A tiver uma chave estrangeira para uma tabela B, será criada automaticamente uma relação de muitos para um de A para B.

Se o esquema no banco de dados do Cloud SQL mudar, é possível atualizar os modelos:

  1. Clique em Configurações Banco de dados.
  2. Em Compatibilidade de modelo e relações, clique no botão Verificar. Você tem a opção de atualizar todos os modelos do Cloud SQL para corresponderem ao banco de dados ou atualizar o banco de dados para corresponder aos modelos.

Se você atualizar os modelos, as alterações em nomes de campos, propriedades de validação e eventos serão preservadas. No entanto, se um campo for excluído do Cloud SQL, o campo correspondente também será excluído do modelo.

Atualizar as configurações do Cloud SQL para seu aplicativo

Acesse Configurações Banco de dados para:

  • alternar para a instância padrão do SQL;
  • atualizar o endereço da instância;
  • verificar a compatibilidade entre modelo e relação.

Alternar entre bancos de dados padrão e personalizados do Cloud SQL

No caso das organizações que configuraram uma instância padrão do Cloud SQL, essa instância é usada pelos novos modelos. O banco de dados padrão do Cloud SQL é ideal para aplicativos que precisam de um banco de dados sem necessidade de configuração e fácil de usar.

Se você notar que o banco de dados padrão não atende às suas necessidades, poderá convertê-lo em um banco de dados personalizado:

  1. Se ainda não o fez, configure uma instância personalizada do Cloud SQL. Escolha us-central como a região da nova instância.
  2. Abra seu aplicativo e clique em Configurações Banco de dados.
  3. Clique no botão Verificar para ver a compatibilidade entre modelo e relação. Se forem relatadas incompatibilidades, pode ser necessário excluir dados para continuar.
  4. Quando você estiver pronto para prosseguir, clique no botão Alternar para um banco de dados personalizado do Cloud SQL.
  5. Digite o endereço no seguinte formato:

    • Primeira geração: projectName:instanceName/databaseName
    • Segunda geração: projectName:regionName:instanceName/databaseName
  6. Digite o nome de usuário e a senha da conta de usuário do banco de dados e clique em Continuar.

Depois de alternar para um banco de dados personalizado, você tem a opção de alternar de volta para um banco de dados padrão.

Trabalhar com registros do Cloud SQL

Cada registro em um modelo do Cloud SQL representa uma linha em uma tabela. Se você criar um registro do App Maker, uma linha será adicionada à tabela correspondente da instância do Cloud SQL.

No App Maker, a coluna da chave primária da tabela geralmente é usada como chave para os registros, e não é possível alterar as chaves-valor primárias após a criação do registro. Em alguns casos, as chaves não correspondem:

  • Os registros criados no servidor por newRecord() têm chave nula até serem salvos, mesmo que a coluna de chave primária seja atribuída.

  • Os registros de rascunho no cliente têm chaves sintéticas que não correspondem à coluna da chave primária até serem salvas.

  • Os registros criados no cliente em uma fonte de dados de modo de salvamento manual têm chaves sintéticas que não correspondem à coluna da chave primária mesmo depois de salvas.

Você tem várias opções para lidar com chaves primárias no App Maker:

Chaves primárias do Cloud SQL
Chaves primárias naturais Quando chaves primárias naturais são usadas pela tabela do Cloud SQL, o campo no modelo do aplicativo que corresponde a essa chave é obrigatório, e é necessário especificar um valor antes de salvar um registro. Para saber mais informações sobre o tratamento de campos obrigatórios, acesse Validar dados.
Chaves primárias alternativas Quando chaves primárias alternativas são usadas pela tabela do Cloud SQL, é possível definir a chave primária antes da chave do registro. Como alternativa, se a chave primária puder ser informada pelo banco de dados, é possível deixar a chave do registro nula para que ela seja atualizada automaticamente pelo App Maker. Esse método não funciona com registros criados no cliente com fontes de dados de modo de salvamento manual.
Chaves primárias de incremento automático

Para chaves primárias inteiras, um número de sequência pode ser atribuído automaticamente como valor da chave primária quando o registro é criado. Nesse caso, o valor do campo da chave primária não precisa ser preenchido pelo usuário ou pelo aplicativo.

Para definir essa opção no App Maker:

  1. na seção Dados do painel de navegação, clique no modelo de dados;
  2. na guia Campos, clique no campo numérico que você quer incrementar automaticamente;
  3. clique em Avançado e selecione Incrementar automaticamente.
Chaves primárias de código exclusivo

No App Maker, é possível configurar um código exclusivo para um campo de chave primária quando um registro é criado. O código exclusivo tem 12 caracteres e é gerado aleatoriamente. Ele não é preenchido pelo usuário nem pelo aplicativo.

Use chaves primárias de código exclusivo quando você não quiser que a chave dê informações sobre o pedido ou o número total de registros de uma tabela, como quando os usuários têm acesso a apenas alguns registros.

Para criar uma chave primária de código exclusivo em um modelo do App Maker que já tenha uma chave primária numérica:

  1. na seção Dados do painel de navegação, clique no modelo de dados ou crie um modelo;
  2. na guia Campos, clique no campo Código;
  3. clique em Avançado e desmarque a caixa de seleção Incrementar automaticamente;
  4. clique em Adicionar campoString;
  5. clique em Definir como chave primária;
  6. digite um nome para o campo, como "uniqueID";
  7. clique em Avançado e selecione Auto identificador exclusivo;
  8. (opcional) exclua o campo Código.

Relações

Campos que correspondem a campos de chave estrangeira podem ser lidos diretamente por scripts do servidor. No cliente, os valores dos campos de chave estrangeira e suas associações correspondentes podem ser modificados como relações. Saiba mais sobre como modificar relações.

Visualizações

Importe visualizações do Cloud SQL como modelos de dados somente leitura. Modelos baseados em visualizações podem tirar proveito de consultas SQL que envolvem mesclas, agregações e subseleções. Por exemplo, no esquema a seguir, uma visualização é usada para agregar dados de uma tabela e facilitar a exibição no App Maker:

CREATE TABLE Orders (FruitName varchar(128), int Amount);
CREATE VIEW FruitOrders AS SELECT FruitName, sum(Amount) AS Amount FROM
    Orders GROUP BY FruitName ORDER BY FruitName;

Modelos SQL calculados

Em um modelo SQL calculado, uma consulta do Cloud SQL é usada para recuperar dados. Assim como em outras fontes de dados calculadas, não é possível criar, excluir ou atualizar registros com uma fonte de dados SQL.

Para criar um modelo SQL calculado:

  1. no App Maker, ao lado de Dados, clique em Adicionar ;
  2. selecione SQL calculado e clique em Próximo;
  3. dê um nome ao modelo e clique em Criar;
  4. acesse a guia Fontes de dados. Adicione a fonte de dados SQL (ou use uma fonte padrão) e insira uma consulta no campo Consulta SQL.

    A consulta SQL precisa ter as seguintes propriedades:

    • A consulta não pode ter uma cláusula LIMIT ou OFFSET. Essas cláusulas são adicionadas pelo App Maker de acordo com pageSize e pageIndex da fonte de dados.
    • Os nomes e tipos de coluna de saída da consulta SQL precisam corresponder aos nomes e tipos do modelo calculado.
    • A consulta SQL só pode conter parâmetros precedidos por dois pontos, como :Param. Esses parâmetros precisam corresponder ao nome e ao tipo de uma propriedade personalizada da fonte de dados.

Por exemplo, um aplicativo de RH precisa exibir o número de funcionários de cada departamento acima de determinada idade. Ele tem um modelo do Cloud SQL Employee com os campos Age e Dept.

Para exibir os dados filtrados, um modelo calculado EmployeeCount com dois campos, DeptName e Count, é usado. O modelo calculado tem uma fonte de dados SQL com uma propriedade personalizada number chamada MinAge, e a seguinte consulta é usada:

SELECT Dept AS DeptName, COUNT(*) AS Count FROM Employee WHERE Age > :MinAge GROUP BY Dept

Os parâmetros da lista são traduzidos em uma lista de parâmetros entre parênteses no SQL. Por exemplo, para selecionar os códigos dos departamentos com nomes correspondentes a um elemento em uma lista de parâmetros, escreva uma consulta como esta:

SELECT id from Departments WHERE Name in :PossibleNames

O parâmetro PossibleNames é convertido em (?, ?, ?, ...), e os elementos do valor do parâmetro são usados para os marcadores de posição do SQL.

Para parâmetros baseados em tempo, você precisa definir o fuso horário.

Filtragem de relações

O Cloud SQL é o único tipo de modelo que pode ser filtrado por um campo em um modelo relacionado em Vinculação de dados e Script do Servidor.

Saiba mais sobre a filtragem de relações.

Fusos horários

Em algumas situações, uma instância do Cloud SQL e o App Maker estão em fusos horários diferentes. Isso pode fazer com que datas e horas indesejadas sejam gravadas no banco de dados. Revise a tabela a seguir e defina os tipos de campo de data apropriadamente.

Tratamento de fuso horário para tipos de campo de data
Modelos do Cloud SQL

Defina o tipo de campo de data conforme necessário:

  1. Abra a guia Campos de um modelo.
  2. Clique em um campo de data e acesse Avançado para definir o tipo de data:
    • DATE ou DATETIME: para campos que não têm fuso horário. A hora é convertida para o fuso horário do servidor do App Maker, conforme definido nas configurações do aplicativo, antes de ser gravada no banco de dados.
    • TIMESTAMP: para campos com fuso horário. O fuso horário do usuário é salvo, e a data é gravada no Cloud SQL em relação à época Unix.

A data dos dois tipos é convertida para o fuso horário do navegador quando exibida pelo App Maker.

Modelos SQL calculados Quando você adiciona um campo de tipo de data a um modelo SQL calculado, ele é adicionado como um tipo DATETIME.
Parâmetros de consulta da fonte de dados SQL calculada

Defina o tipo de campo de data conforme necessário:

  1. Abra a guia Fontes de dados do modelo SQL calculado.
  2. Clique na fonte de dados e em Adicionar parâmetro.
  3. Para parâmetros de data, clique na lista suspensa Tipo de data SQL e selecione um tipo:
    • DATE ou DATETIME: para parâmetros que não têm fuso horário. Quando um campo DATE ou DATETIME é usado pela consulta, o valor é convertido do fuso horário do usuário do aplicativo para o fuso horário do servidor antes de ser usado.

      Por exemplo, se um usuário em PST (UTC-8) consultar registros criados antes de 1º de janeiro de 2018 às 9h00, e o servidor do App Maker estiver em CT (UTC-6), serão consultados registros criados antes de 1º de janeiro de 2018 às 11h00.

    • TIMESTAMP: para parâmetros com fuso horário. A hora é convertida em UTC antes de ser usada na consulta. Não recomendamos o uso de parâmetros de consulta do tipo TIMESTAMP porque a data só é tratada corretamente se o aplicativo e o banco de dados estiverem no mesmo fuso horário.

Restrições e limitações

  • Se suas tabelas do Cloud SQL tiverem zero ou várias colunas de chave primária, não será possível para o App Maker modificar ou criar relações para elas.

  • O App Maker representa valores BIGINT como strings porque o intervalo de números representado por BIGINT é grande demais para ser representado com números JavaScript.

  • Não é possível importar para o App Maker alguns tipos de coluna do Cloud SQL, como BLOB, CLOB e outros tipos binários. Ainda é possível importar modelos com esses tipos de coluna, mas essas colunas não serão legíveis ou graváveis. Se elas forem marcadas como não nulas, todas as outras colunas do modelo de dados serão somente leitura.

  • No App Maker, não é possível expressar consultas a modelos do Cloud SQL que envolvam mesclas, agregações ou subseleções. Em vez disso, importe uma visualização SQL como modelo ou use uma fonte de dados SQL em um modelo calculado.

  • Não há suporte para pesquisas por palavras-chave. Como solução alternativa, crie uma consulta personalizada que simule uma pesquisa de texto completo com os operadores contains. Por exemplo, para um modelo Employee com os campos Name e Department, use a consulta: (Name contains? :Keywords) OR (Department contains? :Keywords) e vincule o parâmetro Keywords à propriedade value de um campo de texto.