Table of Contents

*A autora selecionou a Electronic Frontier Foundation para receber uma doação como parte do programa Write for DOnations.*

Introdução

O Prisma é uma camada de dados que substitui as ferramentas tradicionais de mapeamento relacional de objeto (ORMs) em sua aplicação. Oferecendo suporte tanto para a construção de servidores GraphQL, bem como REST APIs, o Prisma simplifica o acesso ao banco de dados com foco em *segurança de tipo* e permite *migrações de banco de dados declarativas*. A segurança de tipo ajuda a reduzir possíveis erros e inconsistências de código, enquanto as migrações de banco de dados declarativas permitem armazenar seu modelo de dados no controle de versão. Esses recursos ajudam os desenvolvedores a reduzir o tempo gasto na configuração de acesso a bancos de dados, migrações e fluxos de trabalho de gerenciamento de dados.

Você pode fazer o deploy do servidor Prisma, que atua como um proxy para seu banco de dados, de várias maneiras e hospedá-lo remotamente ou localmente. Através do serviço do Prisma, você pode acessar seus dados e se conectar ao seu banco de dados com a API GraphQL, que permite operações em tempo real e a capacidade de criar, atualizar e excluir dados. O GraphQL é uma linguagem de consulta para APIs que permite aos usuários enviar consultas para acessar os dados exatos que eles precisam de seu servidor. O servidor Prisma é um componente independente que fica acima do seu banco de dados.

Neste tutorial, você irá instalar manualmente um servidor Prisma no Ubuntu 18.04 e executará uma consulta de teste GraphQL no GraphQL Playground. Você hospedará seu código de configuração e desenvolvimento Prisma localmente — onde você constrói de fato a sua aplicação — enquanto executa o Prisma no seu servidor remoto. Ao realizar a instalação manualmente, você terá uma compreensão e uma personalização mais detalhadas da infraestrutura subjacente de sua configuração.

Embora este tutorial aborde as etapas manuais para implantar o Prisma em um servidor Ubuntu 18.04, você também pode realizar isso de uma forma mais automatizada com a Docker Machine, seguindo este tutorial no site do Prisma.

Note: A configuração descrita nesta seção não inclui recursos que você normalmente esperaria em servidores prontos para produção, como backups automatizados e failover ativo.

Pré-requisitos

prisma illustration for: Pré-requisitos

Para completar este tutorial, você vai precisar de:

  • Node.js instalado em seu servidor. Você pode conseguir isso indo até a seção PPA do tutorial Installing Node.js.

O Prisma CLI é a principal ferramenta usada para fazer o deploy e gerenciar seus serviços Prisma. Para iniciar os serviços, você precisa configurar a infraestrutura necessária, que inclui o servidor Prisma e um banco de dados para conexão.

O Docker Compose lhe permite gerenciar e executar aplicações multi-container. Você o utilizará para configurar a infraestrutura necessária para o serviço Prisma.

Você começará criando o arquivo docker-compose.yml para armazenar a configuração do serviço Prisma em seu servidor. Você usará esse arquivo para ativar automaticamente o Prisma, um banco de dados associado, e configurar os detalhes necessários, tudo em uma única etapa. Uma vez que o arquivo é executado com o Docker Compose, ele irá configurar as senhas para seus bancos de dados, portanto, certifique-se de substituir as senhas para managementAPIsecret e MYSQL_ROOT_PASSWORD por algo seguro. Execute o seguinte comando para criar e editar o arquivo docker-compose.yml:

				
					
sudo nano docker-compose.yml

Adicione o seguinte conteúdo ao arquivo para definir os serviços e volumes para a configuração do Prisma:

				
					
[label docker-compose.yml]



version: "3"

services:

 prisma:

 image: prismagraphql/prisma:<^>1.20<^>

 restart: always

 ports:

 - "4466:4466"

 environment:

 PRISMA_CONFIG: |

 port: 4466

 managementApiSecret: <^>my-secret<^>

 databases:

 default:

 connector: mysql

 host: mysql

 port: 3306

 user: root

 password: <^>prisma<^>

 migrations: true

 mysql:

 image: mysql:5.7

 restart: always

 environment:

 MYSQL_ROOT_PASSWORD: <^>prisma<^>

 volumes:

 - mysql:/var/lib/mysql

volumes:

 mysql:

Essa configuração faz o seguinte:

  • Lança dois serviços: prisma-db e db.
  • Baixa a última versão do Prisma. No momento da escrita desse artigo, ela é o Prisma 1.20.
  • Define as portas em que o Prisma estará disponível e especifica todas as credenciais para se conectar ao banco de dados MySQL na seção databases.

O arquivo docker-compose.yml configura o managementApiSecret, que impede que outras pessoas acessem seus dados com conhecimento do seu endpoint. Se você estiver usando este tutorial apenas algo que não seja um deployment de teste, altere o managementAPIsecret para algo mais seguro. Quando fizer isso, guarde isso para que você possa inseri-lo mais tarde durante o processo prisma init.

Esse arquivo também extrai a imagem Docker do MySQL e define essas credenciais também. Para os propósitos deste tutorial, este arquivo Docker Compose cria uma imagem MySQL, mas você também pode usar o PostgreSQL com o Prisma. Ambas as imagens Docker estão disponíveis no Docker Hub:

Salve e saia do arquivo.

Agora que você salvou todos os detalhes, você pode iniciar os containers do Docker. O comando -d diz aos containers para serem executados no modo detached, o que significa que eles serão executados em segundo plano:

				
					
sudo docker-compose up -d

Isso irá buscar as imagens do Docker para prisma e mysql. Você pode verificar se os containers do Docker estão sendo executados com o seguinte comando:

				
					
sudo docker ps

Você verá uma saída semelhante a esta:

				
					
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES

24f4dd6222b1 prismagraphql/prisma:<^>1.12<^> <^>"/bin/sh -c /app/sta…"<^> <^>15<^> seconds ago Up 1 second <^>0.0.0.0:4466<^>-><^>4466<^>/tcp root_prisma_1

d8cc3a393a9f mysql:<^>5.7 <^> <^>"docker-entrypoint.s…"<^> <^>15<^> seconds ago Up 13 seconds <^>3306<^>/tcp root_mysql_1

Com seu servidor Prisma e o banco de dados configurados, agora você está pronto para trabalhar localmente para fazer o deploy do serviço Prisma.

Passo 2 — Instalando o Prisma Localmente

O servidor Prisma fornece os ambientes de runtime para seus serviços Prisma. Agora que você tem seu servidor Prisma iniciado, você pode fazer o deploy do seu serviço Prisma. Você executará estas etapas localmente, não no seu servidor.

Para começar, crie uma pasta separada que irá conter todos os arquivos do Prisma:

				
					
[environment local]

mkdir prisma

Mova-se pra essa pasta:

				
					
[environment local]

cd prisma

Você pode instalar o Prisma com o Homebrew se você estiver usando o MacOS. Para fazer isso, execute o seguinte comando para adicionar o repositório do Prisma:

				
					
[environment local]

brew tap prisma/prisma

Você pode então instalar o Prisma com o seguinte comando:

				
					
[environment local]

brew install prisma

Ou, alternativamente com o npm:

				
					
[environment local]

npm install -g prisma

Com o Prisma instalado localmente, você está pronto para iniciar o novo serviço Prisma.

Passo 3 — Criando a Configuração para um Novo Serviço Prisma

Após a instalação, você pode usar o prisma init para criar a estrutura de arquivos para uma nova API de banco de dados Prisma, que gera os arquivos necessários para construir sua aplicação com o Prisma. Seu endpoint estará automaticamente no arquivo prisma.yml, e o datamodel.prisma já conterá um modelo de dados de amostra que você pode consultar na próxima etapa. O modelo de dados serve como base para sua API Prisma e especifica o modelo para sua aplicação. Neste ponto, você está criando apenas os arquivos e o modelo de dados de amostra. Você não está fazendo nenhuma alteração no banco de dados até executar o prisma deploy posteriormente nesta etapa.

Agora você pode executar o seguinte comando localmente para criar a nova estrutura de arquivos:

				
					
[environment local]

prisma init hello-world

Depois de executar este comando, você verá um prompt interativo. Quando perguntado, selecione, Use other server e pressione ENTER:

				
					
[secondary_label Output]

[environment local]

 Set up a new Prisma server or deploy to an existing server?



 You can set up Prisma for local development (based on docker-compose)

 Use existing database Connect to existing database

 Create new database Set up a local database using Docker



 Or deploy to an existing Prisma server:

 Demo server Hosted demo environment incl. database (requires login)

❯ Use other server Manually provide endpoint of a running Prisma server

Em seguida, você fornecerá o endpoint do seu servidor que está atuando como servidor Prisma. Será algo parecido com: http://<^>IP_DO_SERVIDOR<^>:4466. É importante que o endpoint comece com http (ou https) e tenha o número da porta indicado.

				
					
[secondary_label Output]

[environment local]

Enter the endpoint of your Prisma server &lt;^&gt;http://&lt;^&gt;IP_DO_SERVIDOR:&lt;^&gt;4466&lt;^&gt;

Para o segredo da API de gerenciamento, insira a frase ou senha que você indicou anteriormente no arquivo de configuração:

				
					
[secondary_label Output]

[environment local]

Enter the management API secret &lt;^&gt;my-secret&lt;^&gt;

Para as opções subseqüentes, você pode escolher as variáveis padrão pressionando ENTER para o service name e service stage:

				
					
[secondary_label Output]

[environment local]

Choose a name for your service &lt;^&gt;hello-world&lt;^&gt;

Choose a name for your stage &lt;^&gt;dev&lt;^&gt;

Você também terá a opção de escolher uma linguagem de programação para o cliente Prisma. Nesse caso, você pode escolher sua linguagem preferida. Você pode ler mais sobre o cliente aqui.

				
					
[secondary_label Output]

[environment local]

 Select the programming language for the generated Prisma client (Use arrow keys)

❯ Prisma TypeScript Client

 Prisma Flow Client

 Prisma JavaScript Client

 Prisma Go Client

 Don't generate

Depois de terminar o prompt, você verá a seguinte saída que confirma as seleções que você fez:

				
					
[secondary_label Output]

[environment local] 

Created 3 new files:



 prisma.yml Prisma service definition

 datamodel.prisma GraphQL SDL-based datamodel (foundation for database)

 .env Env file including PRISMA_API_MANAGEMENT_SECRET



Next steps:



 1. Open folder: cd hello-world

 2. Deploy your Prisma service: prisma deploy

 3. Read more about deploying services:

 http://bit.ly/prisma-deploy-services

Vá para o diretório <^>hello-world<^>:

				
					
[environment local]

cd hello-world

Sincronize estas mudanças com o seu servidor usando prisma deploy. Isso envia as informações para o servidor Prisma a partir da sua máquina local e cria o serviço Prisma no servidor Prisma:

				
					
[environment local]

prisma deploy

Nota: A execução do prisma deploy novamente atualizará seu serviço Prisma.

Sua saída será algo como:

				
					
[secondary_label Output]

[environment local]

Creating stage dev for service hello-world ✔

Deploying service `hello-world` to stage 'dev' to server 'default' 468ms



Changes:



 User (Type)

 + Created type `User`

 + Created field `id` of type `GraphQLID!`

 + Created field `name` of type `String!`

 + Created field `updatedAt` of type `DateTime!`

 + Created field `createdAt` of type `DateTime!`



Applying changes 716ms



Your Prisma GraphQL database endpoint is live:



 HTTP: http://&lt;^&gt;IP_DO_SERVIDOR&lt;^&gt;:4466/&lt;^&gt;hello-world&lt;^&gt;/&lt;^&gt;dev&lt;^&gt;

 WS: ws://&lt;^&gt;IP_DO_SERVIDOR&lt;^&gt;:4466/&lt;^&gt;hello-world&lt;^&gt;/&lt;^&gt;dev&lt;^&gt;

A saída mostra que o Prisma atualizou seu banco de dados de acordo com o seu modelo de dados (criado na etapa prisma init) com um *tipo* User. Tipos são uma parte essencial de um modelo de dados; eles representam um item da sua aplicação, e cada tipo contém vários campos. Para o seu modelo de dados, os campos associados que descrevem o usuário são: o ID do usuário, o nome, a hora em que foram criados e o horário em que foram atualizados.

Se você encontrar problemas nesse estágio e obtiver uma saída diferente, verifique novamente se digitou todos os campos corretamente durante o prompt interativo. Você pode fazer isso revisando o conteúdo do arquivo prisma.yml.

Com seu serviço Prisma em execução, você pode se conectar a dois endpoints diferentes:

  • A interface de gerenciamento, disponível em http://<^>IP_DO_SERVIDOR<^>:4466/management, onde você pode gerenciar e fazer deployment de serviços Prisma.
  • A API GraphQL para o seu serviço Prisma, disponível em http://<^>IP_DO_SERVIDOR<^>:4466/<^>hello-world<^>/<^>dev<^>.

Você configurou e fez o deployment com sucesso do seu servidor Prisma. Agora você pode explorar consultas e mutações no GraphQL.

Passo 4 — Executando uma Consulta de Exemplo

Para explorar outro caso de uso do Prisma, você pode experimentar em seu servidor a ferramenta GraphQL playground, que é um ambiente de desenvolvimento integrado open-source (IDE). Para acessá-lo, visite seu endpoint em seu navegador, da etapa anterior:

				
					
http://&lt;^&gt;IP_DO_SERVIDOR&lt;^&gt;:4466/&lt;^&gt;hello-world&lt;^&gt;/&lt;^&gt;dev&lt;^&gt;

Uma *mutação* é um termo do GraphQL que descreve uma maneira de modificar — criar, atualizar ou excluir (CRUD) — dados no backend via GraphQL. Você pode enviar uma mutação para criar um novo usuário e explorar a funcionalidade. Para fazer isso, execute a seguinte mutação no lado esquerdo da página:

				
					
mutation {

 createUser(data: { name: "Alice" }) {

 id

 name

 }

}

Depois de pressionar o botão play, você verá os resultados no lado direito da página.

Posteriormente, se você quiser procurar um usuário usando a coluna ID no banco de dados, poderá executar a seguinte consulta:

				
					
query {

 user(where: { id: "cjkar2d62000k0847xuh4g70o" }) {

 id

 name

 }

}

Agora você tem um servidor Prisma e o serviço em funcionamento no servidor, e você executou consultas de teste no IDE do GraphQL.

Conclusão

Você tem uma configuração Prisma em funcionamento no seu servidor. Você pode ver alguns casos de uso adicionais do Prisma e os próximos passos no Guia de primeiros passos ou explorar o conjunto de recursos do Prisma no Prisma Docs. Depois de concluir todas as etapas deste tutorial, você tem várias opções para verificar sua conexão com o banco de dados, sendo que uma possibilidade é a utilização do Prisma Client.

*Por Etel Sverdlov*