Prisma的命令行界面(CLI)是部署和管理你的Prisma services的主要工具。

Prisma CLI可以在以下地方帮助你:

  • 为新services生成服务配置文件
  • 部署services到Prisma的服务器
  • 生成认证令牌token
  • 导入种子数据,导入和导出数据
  • ...云服务等更多

获取有关所有的CLI命令的相关详细信息,请参阅下文命令参考

Prisma CLI可从[NPM]安装(https://docs.npmjs.com/misc/registry)。


cnpm install -g prisma

yarn global add prisma

# PRISMA
# 
# GraphQL Database Gateway (https://www.prisma.io)
# 
# Usage: prisma COMMAND
# 
# Service:
#   init            Initialize a new service
#   deploy          Deploy service changes (or new service)
#   introspect      Introspect database schema(s) of service
#   info            Display service information (endpoints, cluster, ...)
#   token           Create a new service token
#   list            List all deployed services
#   delete          Delete an existing service
# 
# Data workflows:
#   playground      Open service endpoints in GraphQL Playground
#   seed            Seed a service with data specified in the prisma.yml
#   import          Import data into a service
#   export          Export service data to local file
#   reset           Reset the stage data
# 
# Cloud:
#   login           Login or signup to the Prisma Cloud
#   logout          Logout from Prisma Cloud
#   console         Open Prisma Console in browser
#   account         Display account information
# 
# Use prisma help [command] for more information about a command.
# Docs can be found here: https://bit.ly/prisma-cli-commands
# 
# Examples:
# 
# - Initialize files for a new Prisma service
#   prisma init
# 
# - Deploy service changes (or new service)
#   prisma deploy

一旦安装,执行下面的命令,让你的Prisma API跑起来,并开始发送Query和Mutation给它:


prisma init hello-world
# 按part1示例
cd hello-world
prisma deploy
prisma playground

Prisma CLI与[graphql-config]集成(https://github.com/prismagraphql/graphql-config)。如果你的项目使用了.graphqlconfig文件,你可以使用prisma扩展,它指向你的prisma.yml:


projects:
  prisma:
    schemaPath: prisma.graphql
    extensions:
      prisma: prisma.yml

Prisma CLI支持[定制HTTP代理(https://github.com/graphcool/prisma/issues/618)。在企业防火墙后面时,这一点尤为重要。

要激活代理,所提供的环境变量HTTP_PROXYHTTPS_PROXY。该行为非常类似于如何npm handles this

可以提供以下环境变量:

  • HTTP_PROXYhttp_proxy:HTTP流量代理URL,例如通过http://localhost:8080
  • HTTPS_PROXYhttps_proxy:为HTTPS流量代理URL,例如的https://localhost:8080
  • NO_PROXYno_proxy:要禁用某些URL的代理,请为'NO_PROXY提供glob,例如*`。

为了得到一个简单的本地代理,则可以使用proxy模块:


npm install -g proxy
DEBUG="*" proxy -p 8080
HTTP_PROXY=http://localhost:8080 HTTPS_PROXY=https://localhost:8080 prisma deploy

起新Prisma services的服务配置。该命令将通过默认启动交互式CLI向导,帮助你决定在何处部署(即哪个Prisma服务器)。

如果你已经知道端点,则可以使用该--endpointflags传递它并跳过交互式向导。

生成的文件有:

  • prisma.yml
  • datamodel.prisma
  • docker-compose.yml(可选)

如果你提供一个目录名作为参数传递给命令,生成的文件将被放置在该名称的新目录中。


-e, --endpoint         The endpoint to be written into prisma.yml

prisma init DIRNAME

在一个叫做'myapp`的目录使用向导创建Prisma services服务配置


prisma init myapp

跳过向导,并在一个叫myapp目录创建Prisma services服务配置


prisma init myapp --endpoint http://localhost:4466/myapp/dev

部署服务配置到服务器。

每当你改变服务配置的时候,你需要将这些变化与运行的Prisma services同步。

在第一次部署服务时,如果提供prisma.yml的seed属性,命令将执行初始数据导入。你可以通过传递--no-seed选项防止这一点。

如果endpoint在prisma.yml中未指定任何属性,则该命令将提示你以交互方式选择Prisma服务器作为服务的部署目标。选择Prisma服务器后,CLI会将endpointprisma.yml 写入未来部署的默认设置。要再次调出交互式提示,只需endpoint手动从prisma.yml中删除该属性或传递--new参数。


prisma deploy [flags]
-d,--dry                 干跑执行部署 -e,--env-file ENV-FILE   注入ENV的.ENV文件路径 -f,--force               强制deploy,接受由数据更改造成的数据丢失 -j,--json                JSON输出 -n,--new                 强制交互模式来选择集群 -w,--watch               监视更改 --no-seed                 禁止种子数据导入 `}

部署当前目录服务配置


prisma deploy

部署服务和交互式选择Prisma服务器作为部署目标:


prisma deploy --new

.env.prod指定的环境变量部署服务


prisma deploy --env-file .env.prod

在调用prisma.yml指定的generators。可用生成器是:

以下生成器内置到Prisma CLI:

  • Prisma client in JavaScript: javascript-client
  • Prisma client in TypeScript: typescript-client
  • Prisma client in Flow: flow-client
  • Prisma client in Go: go-client
  • GraphQL schema of the Prisma API: graphql-schema

prisma generate [flags]
-e, --env-file ENV-FILE    Path to .env file to inject env vars `}

生成TypeScript client并将生成的文件存储在./generated/prisma

prisma.yml:


generate:
    - generator: typescript-client
      output: ./generated/prisma

prisma generate

Go client和GraphQL schema并存储生成的文件在./generated/prisma

prisma.yml:


generate:
    - generator: go-client
      output: ./generated/prisma
    - generator: graphql-schema
      output: ./generated/prisma

prisma generate

由现有数据库的模式introspecting创建一个数据模型。

该命令启动交互式向导,要求你提供你的数据库连接的详细信息:

  • Host: The host of your Database server, e.g. localhost.
  • Port: The port where your Database server listens, e.g. 5432.
  • User & Password: The credentials for your Database server.
  • Name of existing database: The name of the Database database.
  • Use SSL (Yes/No): If your database connection is using SSL, you need to select Yes, otherwise No.
  • Name of existing schema: The name of the Database schema, e.g. public.

prisma introspect

Introspect现有的数据库


prisma introspect

这里是通过向导提供的数据库连接细节:


#  ? What kind of database do you want to introspect? Postgres
#  ? Enter database host localhost
#  ? Enter database port 5432
#  ? Enter database user prisma
#  ? Enter database password ****
#  ? Enter name of existing database prisma-db
#  ? Enter name of existing schema public
#  
#  Introspecting database 402ms
#  Created datamodel mapping based on 7 database tables.
#  
#  Created 1 new file:               
#  
#    datamodel-[TIMESTAMP].graphql    GraphQL SDL-based datamodel (derived from existing database)

所生成的数据模型文件将包含时间戳的名称,以避免重写现有的datamodel.prisma文件。

显示服务信息:

  • 服务名称
  • 服务版本
  • API端点(HTTP和的WebSocket)

prisma info

 -e, --env-file ENV-FILE    Path to .env file to inject env vars
 -j, --json                 JSON Output
 -s, --secret               Print secret in JSON output (requires --json option)

打印关于当前服务的信息


prisma info

打印有关JSON当前服务信息


prisma info --json

打印有关JSON当前服务信息,包括服务密码


prisma info --json --secret

提供两个--json--secretflags的时,服务密码才会打印。

生成一个新的service token。service token是用JWT与service token签名加密的。


prisma token [flags]

-c, --copy                 Copy token to clipboard
-e, --env-file ENV-FILE    Path to .env file to inject env vars

打印service toke


prisma token

复制service toke到剪贴板


prisma token --copy

列出所有部署的服务。


prisma list

列出所有部署的服务


prisma list

从Prisma服务器删除的其上运行现有服务。

这个命令需要在Prisma services的根目录中执行。


prisma delete [flags]

 -e, --env-file ENV-FILE    Path to .env file to inject env vars
 -f, --force                Force delete, without confirmation

删除现有的服务(与确认提示)


prisma delete

删除现有的服务(没有确认提示)


prisma delete --force

打开一个GraphQL Playground用于当前的服务。

默认情况下,这将打开Playground的Desktop version(如果已安装)。基于浏览器的Playground可以通过传递--webflags被打开。

Playground运行在3000端口上。


prisma playground [flags]

--dotenv DOTENV          Path to .env file to inject env vars
-w, --web                Open browser-based Playground

打开Playground(桌面版本,如果已安装)


prisma playground

打开Playground(基于浏览器的版本)


prisma playground --web

服务的种子数据。

此命令需要在prisma.yml中[seed]属性已设置。


prisma seed [flags]

-e, --env-file ENV-FILE    Path to .env file to inject env vars
-r, --reset                Reset the service before seeding

与初始数据种子


prisma seed

删除所有服务的数据后先初始数据种子


prisma seed --reset

将数据导入到你的Prisma services的数据库。

数据需要根据归一化数据格式进行格式化。欲了解更多信息,请阅读[数据导入和导出]


prisma import [flags]

-d, --data PATH            (required) Path to zip or directory with import data (NDF)
-e, --env-file ENV-FILE    Path to .env file to inject env vars

导出你的业务数据到本地的zip目录。欲了解更多信息,请阅读[数据导入和导出]


prisma export [flags]

-e, --env-file ENV-FILE    Path to .env file to inject env vars
-p, --path PATH            Path to export .zip file

导出数据到默认名称(export-<timestamp>.zip)文件


prisma export

数据导出到文件称为mydata.zip


prisma export --path mydata.zip

删除所有业务数据。


prisma reset

 -e, --env-file ENV-FILE    Path to .env file to inject env vars
 -f, --force                Force reset data without confirmation

删除所有服务的数据(确认提示)。


prisma reset

删除所有服务的数据(没有确认提示)。


prisma reset --force

Prisma cloud进行认证。

该命令打开Prisma cloud端控制台,你需要注册或登录。

在浏览器中成功认证后,CLI写入cloudSessionKey〜/.prisma/config.yml。从那里,它被用于通过对Prisma cloud CLI所做的所有后续请求。

请注意,不仅是通过--keyflags提供你的云会话密钥,你还可以设置PRISMA_CLOUD_SESSION_KEY环境变量,这在CI的环境中尤其有用。


prisma login [flags]

-k, --key KEY    Cloud session key

与Prisma cloud验证(打开浏览器)


prisma login

通过手动传递云会话密钥与Prisma cloud验证


prisma login --key KEY

在上面的命令中,KEY需要与你的有效的云会话密钥的值来代替。你可以在〜/.prisma/config.ymlcloudSessionKey

Prisma cloud注销。

这个命令只是从〜/.prisma/config.yml删除cloudSessionKey


prisma logout

登录Prisma cloud出


prisma logout

在浏览器中打开Prisma cloud端控制台


prisma console

打开Prisma cloud端控制台在浏览器


prisma console

显示当前帐户Prisma cloud(基于〜/.prisma/config.ymlcloudSessionKey)的信息。

显示的信息包括:

  • 用户名
  • 电子邮件地址

prisma account

Prisma cloud用户显示帐户信息


prisma account

prisma.yml为Prisma services的配置文件。每个Prisma services由一个prisma.yml定义。你可以认为prisma.yml是一个Prisma services的地基

prisma.yml指定了许多有关Prisma services的属性,例如:

  • 服务的endpoint(包括namestage)
  • 如何以及在何处生成Prisma client
  • Service secret用于验证服务的API的请求
  • datamodel文件的位置(一个或多个)
  • hooks指定shell命令在deployment过程中哪些点要被执行

有效的prisma.yml至少包含两个属性:

  • datamodel
  • endpoint

为了能够指定一个endpoint,你需要访问Prisma服务器。如果你没有Prisma服务器,在这种情况下,CLI向导将引导你完成创建本地Prisma服务器的过程或可以部署Prisma cloud的Demo Servers。然后为你提供的服务被部署之前将endpoint写入到prisma.yml:


datamodel: datamodel.prisma
/

在prisma.yml最常用的属性是:

  • datamodel
  • endpoint
  • secret
  • hooks
  • generate

下面是具有这些特性的标准prisma.yml:


datamodel: datamodel.prisma
endpoint: http://localhost:4466/myservice/dev
secret: mysecret42
generate:
    - generator: javascript-client
      output: ./generated/prisma
hooks:
  post-deploy:
    - prisma generate

这里就是展示prisma.yml所有属性的例子:


#该服务是基于这两个文件类型定义
#databasetypes.graphql和database/enums.graphql
datamodel:
  - database/types.graphql
  - database/enums.graphql
#endpoint代表了你的Prisma API的HTTP endpoint。
#它表示了几条信息:
#-*Prisma服务器('localhost:4466'在这个例子中)
#-*服务名称('myservice'在这个例子中)
#-*阶段('dev'在这个例子中)
#注:服务名称和阶段被设置为'default'时,他们可被省略。
#http://myserver.com/default/default可以写成http://myserver.com。
endpoint: http://localhost:4466/myservice/dev
#密码用于创建JSON Web Token(JWTs)。这些令牌需要在Prisma的endpoint发出的HTTP请求加上'Authorization'头。
#警告:如果不提供密码,在Prisma API可以无需验证访问!
secret: mysecret123
#生成一个JavaScript Prisma client并储存在output指定的目录
generate:
    - generator: javascript-client
      output: ./generated/prisma
#在部署时执行命令生成Prisma client
hooks:
  post-deploy:
    - prisma generate
#这个服务有一个事件Subscriptions配置。相应的Subscriptions查询位于'database/subscriptions/welcomeEmail.graphql'。
#当Subscriptions被触发,指定'webhook'经由HTTP调用。
subscriptions:
  sendWelcomeEmail:
    query: database/subscriptions/sendWelcomeEmail.graphql
    webhook:
      url: https://${self:custom.serverlessEndpoint}/sendWelcomeEmail
      headers:
        Authorization: ${env:MY_ENDPOINT_SECRET}
#初次部署时会用该文件中的数据导入种子数据
seed:
  import: database/seed.graphql
#此服务只定义了一个自定义变量,是'subscription'的'webhook'引用地址
custom:
  serverlessEndpoint: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev

该prisma.yml定义的目录结构:


.
│ .graphqlconfig
├── prisma.yml
└── database
    ├── subscriptions
    │   └── welcomeEmail.graphql
    ├── types.graphql
    └── enums.graphql

变量允许你动态地更换你的prisma.yml配置值。当为你服务设置secrets时特别有用的,或者在多个开发人员共同开发时。

要使用prisma.yml变量,需要引用括在'${}'括号内的值:


yamlKeyXYZ: ${variableSource}

一个variable source可以是以下两种:

  • 自引用值
  • 环境变量

你只能在属性值中使用变量- 而不是在属性键中。因此,你无法使用变量来例如在自定义资源部分中生成动态逻辑ID。

你可以递归引用同一prisma.yml文件中的其他属性值。

使用递归自引用作为变量时,放入括号中的值由以下内容组成:

  • 前缀 self:
  • (可选)引用属性的路径 ; 如果未指定路径,则变量的值将是整个YAML文件。

subscriptions:
  sendWelcomeEmail:
    query: database/subscriptions/sendWelcomeEmail.graphql
    webhook:
      url: https://${self:custom.serverlessEndpoint}/sendWelcomeEmail
custom:
  serverlessEndpoint: example.org
/

这适用于prisma.yml内任何属性,不只是custom

你可以在prisma.yml中引用环境变量

使用环境变量时,放入括号中的值由以下内容组成:

  • 前缀 env:
  • 环境变量的name

在以下示例中,引用了一个环境变量来指定webhook的URL和身份验证令牌:


subscriptions:
  sendWelcomeEmail:
    query: database/subscriptions/sendWelcomeEmail.graphql
    webhook:
      url: https://example.org/sendWelcomeEmail
      headers:
        Authorization: ${env:MY_TOKEN}

服务定义文件prisma.yml具有以下根属性:

  • datamodel(必需):数据库模型,关系,枚举和其他类型的类型定义。
  • endpoint:HTTP endpoint的Prisma API。可以省略CLI部署向导。
  • secret:用于固定API endpoint的服务密码。
  • hooks:定义CLI命令之前/Prisma CLI的特定动作之后执行。
  • subscriptions:订阅webhooks的配置。
  • seed:指向包含种子数据的Mutation文件。
  • custom:用于提供可在其他地方被prisma.yml引用的变量。

prisma.yml的确切结构是使用JSON模式定义的。你可以找到相应的模式定义这里。JSON schem定义还允许提升你的工具,让你的代码编辑器和IDE帮助你完成prisma.yml的正确结构。

datamodel指向.graphql包含用GraphQL SDL编写的模型定义的一个或多个文件的点。如果提供了多个文件,CLI只会在部署时连接其内容。

该datamodel属性需要一个字符串或一个字符串列表。

数据模型是在一个名为'types.graphql`文件中定义。


datamodel: types.graphql

数据模型在称为types.graphqlenums.graphl的两个文件定义。当服务被部署时,这两个文件的内容将通过CLI进行关联。


datamodel:
  - types.graphql
  - enums.graphql

你Prisma API的HTTP端点由以下几部分组成:

  • Prisma server:将承载你的Prisma services的服务器。
  • Workspace(仅适用于Prisma cloudDemo Servers):你通过Prisma cloud配置的工作区的名称。
  • Service name:你Prisma的SERVICE中的描述性名称。
  • Service stage:你集群的版本(比如'devstagingprod`)。

请注意,部署Prisma服务时endpoint实际上是必填的。但是,如果在运行prisma deploy之前未在prisma.yml中指定它,CLI会提示你使用向导来帮助你确定Prisma服务器作为部署目标,然后将endpoint写入prisma.yml。

endpoint属性需要一个字符串。

下面的示例端点编码以下信息:

  • Prisma server:HTTP://localhost:4466意味着你的机器上运行的服务器Prisma在本地(例如,使用docker)。
  • Service name: default
  • Stage: default

当服务名称和阶段都被设置为'default,它们可以被省略。这意味着本实施例中的端点是相当于:http://localhost:4466/`


endpoint: http://localhost:4466/default/default

下面的示例端点编码以下信息:

  • Prisma server:https://eu1.prisma.sh意味着你使用的是Prisma的Demo Servers作为你的Prisma services部署目标。
  • Workspace:jane-doe是Prisma Cloud工作区的名称。
  • Service name:myservice
  • Stage:dev

终点:https://eu1.prisma.sh/jane-doe/myservice/dev

下面的示例端点编码以下信息:

  • Prisma server: http://my-pr-Publi-1GXX8QUZU3T89-413349553.us-east-1.elb.amazonaws.com 表示你正在使用AWS上的Prisma服务器来部署你的Prisma服务。
  • Service name: cat-pictures
  • Stage: prod

endpoint: http://my-pr-Publi-1GXX8QUZU3T89-413349553.us-east-1.elb.amazonaws.com/cat-pictures/prod

所述服务密码被用于生成(或sign)认证令牌(JWT)。token需要附加到服务公开的针对Prisma API的HTTP请求(在Authorization头字段中)。

密码必须遵循以下要求:

  • 必须是UTF8编码
  • 不能包含空格
  • 最多256个字符

注意

如果Prisma services部署没有secret,其API不需要验证。这意味着每个人都可以访问到endpoint发送Query和Mutation API,因此可以任意读取和写入数据库!

secret属性需要一个字符串(不是字符串列表)。如果要指定多个密码,你需要为他们提供一个逗号分隔列表(空格被忽略),但仍然作为一个字符串值。

定义一个密码moo4ahn3ahb4phein1eingaep


secret: moo4ahn3ahb4phein1eingaep

定义三个密码的值myFirstSecretSECRET_NUMBER_23-secret。需要注意的是第二个密码之前的空格将被忽略。


secret: myFirstSecret,    SECRET_NUMBER_2,3rd-secret

使用环境变量MY_SECRET的密码(一个或多个)的值。


secret: ${env:MY_SECRET}

generate属性用于指定如何以及在何处应该生成Prisma client(或其他文件)。

以下生成器内置到Prisma CLI:

  • Prisma client in JavaScript: javascript-client
  • Prisma client in TypeScript: typescript-client
  • Prisma client in Flow: flow-client
  • Prisma client in Go: go-client
  • GraphQL schema of the Prisma API: graphql-schema

generate属性需要一个对象列表。这些对象有两个属性:

  • generator:从上面的列表中提供的生成器中的其中一个。
  • output:指定生成的文件应在哪个位置。

generate:
    - generator: javascript-client
      output: ./generated/prisma
    - generator: graphql-schema
      output: ./generated/prisma

hooks属性用于定义终端命令,这些命令将由Prisma CLI在某些命令之前或之后执行。

目前提供以下钩子:

  • post-deploy:将在命令后调用prisma deploy

hooks属性需要一个对象。该对象的属性与当前可用挂钩的名称匹配。

以下是执行prisma deploy后先执行三个命令的例子:

1.打印"Deployment finished" 1.下载在.graphqlconfig指定的db项目的GraphQL schema 1.调用代码生成


hooks:
  post-deploy:
    - echo "Deployment finished"
    - graphql get-schema --project db
    - graphql codegen

请注意,此设置假设的.graphqlconfig类似这样:


projects:
  db:
    schemaPath: generated/prisma.graphql
    extensions:
      prisma: prisma.yml
      codegen:
        - generator: prisma-binding
          language: typescript
          output:
            binding: src/generated/prisma.ts

subscriptions属性用于定义Prisma服务的所有订阅webhook。订阅需要(至少)两条信息:

  • 一个subscription query定义在哪个事件的函数被调用,Payload的样子
  • 一旦事件发生,其通过HTTP调用的webhook的网址
  • (任选)要附加到发送到URL的请求的多个HTTP header

subscriptions属性需要一个具有以下属性的对象:

  • query(必需):该文件路径的subscription query(存储在一个.graphql文件)。
  • webhook(必需):有关要调用的webhook的信息(URL和可选的HTTP header)。如果没有header,你可以直接向此属性提供URL(请参阅下面的第一个示例)。否则,webhook需要另一个对象的url和headers(见下文第二示例)。

没有指定的HTTP头的一个Subscriptions。


subscriptions:
  sendWelcomeEmail:
    query: database/subscriptions/sendWelcomeEmail.graphql
    webhook: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev/sendWelcomeEmail

`

指定一个Subscriptions事件有两个HTTP header。


subscriptions:
  sendWelcomeEmail:
    query: database/subscriptions/sendWelcomeEmail.graphql
    webhook:
      url: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev/sendWelcomeEmail
      headers:
        Authorization: ${env:MY_SECRET}
        Content-Type: application/json

填充数据库初始数据,测试数据的标准方法。

seed属性需要一个对象,具有以下两个子属性之一:

  • import:导入数据的说明。你可以参考两种文件中的任何一种:

    • .graphql 具有GraphQL操作的文件的路径。
    • .zip 包含规范化数据格式(NDF)中的数据集的文件的路径
  • run:导入时将要执行的Shell命令。这适用于未涵盖的更复杂的seed设置的import。

首次部署服务时(除非使用上PRISMA deploy--no-seedflags明确禁用)seed被隐式执行。

含有Mutation的.graphql文件:


seed:
  import: database/seed.graphql

与NDF数据集的.zip文件:


seed:
  import: database/backup.zip

seed时运行节点脚本:


seed:
  run: node script.js

custom属性用于指定你想在你的prisma.yml其他地方重用值的任何种类。因此,它没有一个预定义的结构。可以参考使用与[self可变源]的变量,例如:${self:custom.myVariable}

custom属性需要一个对象。没有关于物体的形状假设。

定义两个自定义值,并在事件Subscriptions的定义中重用他们。


custom:
  serverlessEndpoint: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev
  subscriptionQueries: database/subscriptions/
subscriptions:
  sendWelcomeEmail:
    query: ${self:custom.subscriptionQueries}/sendWelcomeEmail.graphql
    webhook: https://${self:custom.serverlessEndpoint}/sendWelcomeEmail

要导入的数据需要遵循规范化数据格式(NDF)。截至今天,必须手动执行从任何具体数据源(如MySQL,MongoDB或Firebase)到NDF的转换。在未来,该Prisma的CLI将支持直接从这些数据源导入。

下面是数据导入过程的概述:


+--------------+                    +----------------+                       +------------+
| +--------------+                  |                |                       |            |
| |            | |                  |                |                       |            |
| | SQL        | |  (1) transform   |      NDF       |  (2) chunked upload   |   Prisma   |
| | MongoDB    | | +--------------> |                | +-------------------> |            |
| | JSON       | |                  |                |                       |            |
| |            | |                  |                |                       |            |
+--------------+ |                  +----------------+                       +------------+
  +--------------+

如上所述,步骤1必须手动执行。然后,可以使用原始导入API或prisma importCLI中的命令来完成步骤2 。

要在CLI中查看支持的转换的当前状态并提交所需的转换,你可以查看这个GitHub的讨论。

当用NDF格式上传文件,你需要将导入数据拆分提供三个不同种类的文件:

  • nodes:数据单个节点(即数据库记录)
  • lists:数据节点的列表
  • relations:数据的关系节点

你可以为每种类型上传无限数量的文件,但建议每个文件最多1 MB。否则你可能会遇到超时。

导入数据时,所述id字段最多25个字符。

请注意,导入操作不是幂等的。这意味着运行导入始终会向你的服务添加数据。它永远不会更新现有节点。这意味着多次导入相同的数据集将导致未知的错误。

例如,导入节点具有相同id多次将导致不确定的行为,并有可能弄挂掉你的服务!

[导入API]不执行对数据的任何验证检查。当使用[CLI]导入数据时,将执行基本验证检查。

导入无效的数据会导致不确定的行为,并可能会破坏你服务!作为服务的维护者,你有责任确保导入数据的有效性。

提示:导入时确保有效数据的一种好方法是检查具有相同数据模型的服务上先前导出的数据。

Prisma CLI提供了PRISMA import命令。它接受一个选项:

  • --data(简写:-d):包含要导入数据的目录的文件路径(可以是常规文件或压缩文件)

在底层,CLI使用下一节中描述的导入API。但是,使用CLI提供了一些主要好处:

  • 一次上传多个文件(而不是必须单独上传每个文件)
  • 利用CLI的身份验证机制(即你无需手动发送身份验证令牌)
  • 能够暂停和恢复正在进行的导入
  • 从 MySQL,MongoDB或Firebase等各种数据源导入(尚不可用)

使用CLI导入数据时,包含NDF中数据的文件需要位于其类型后调用的目录中:nodes,lists和relations。

NDF文件是遵循特定结构的JSON文件,因此每个包含导入数据的文件都需要后缀.json。当放置在各自的目录(nodes,lists或relations)中时,.json-files需要逐步编号,从1开始,例如1.json。文件名可以添加任意数量的零,例如01.json或0000001.json。

考虑定义一个Prisma services下列文件结构:


.
├── data
│   ├── lists
│   │   ├── 0001.json
│   │   ├── 0002.json
│   │   └── 0003.json
│   ├── nodes
│   │   ├── 0001.json
│   │   └── 0002.json
│   └── relations
│       └── 0001.json
├── datamodel.prisma
└── prisma.yml

data包含文件中要导入的数据。此外,在.json结尾的文件都秉承NDF。从这些文件中导入数据,你可以简单地在终端运行下面的命令:


prisma import --data data

原始导入API在HTTP端点的/import路径下公开。例如:

  • http://localhost:4466/my-app/dev/import
  • https://eu1.prisma.sh/my-app/prod/import

一个请求可以上传最多10 MB大小的JSON数据(在NDF中)。请注意,你需要在请求的HTTP 标头中提供Authorization身份验证令牌!

下面是一个例子curl命令上传一些JSON数据(NDF类型的nodes):


curl 'http://localhost:4466/my-app/dev/import' -H 'Content-Type: application/json' -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJPbmxpbmUgSldUIEJ1aWxkZXIiLCJpYXQiOjE1MTM1OTQzMTEsImV4cCI6MTU0NTEzMDMxMSwiYXVkIjasd3d3LmV4YW1wbGUuY29tIiwic3ViIjoianJvY2tldEBleGFtcGxlLmNvbSIsIkdpdmVuTmFtZSI6IkpvaG5ueSIsIlN1cm5hbWUiOiJSb2NrZXQiLCJFbWFpbCI6Impyb2NrZXRAZXhhbXBsZS5jb20iLCJSb2xlIjpbIk1hbmFnZXIiLCJQcm9qZWN0IEFkbWluaXN0cmF0b3IiXX0.L7DwH7vIfTSmuwfxBI82D64DlgoLBLXOwR5iMjZ_7nI' -d '{"valueType":"nodes","values":[{"_typeName":"Model0","id":"0","a":"test","b":0,"createdAt":"2017-11-29 14:35:13"},{"_typeName":"Model1","id":"1","a":"test","b":1},{"_typeName":"Model2","id":"2","a":"test","b":2,"createdAt":"2017-11-29 14:35:13"},{"_typeName":"Model0","id":"3","a":"test","b":3},{"_typeName":"Model3","id":"4","a":"test","b":4,"createdAt":"2017-11-29 14:35:13","updatedAt":"2017-11-29 14:35:13"},{"_typeName":"Model3","id":"5","a":"test","b":5},{"_typeName":"Model3","id":"6","a":"test","b":6},{"_typeName":"Model4","id":"7"},{"_typeName":"Model4","id":"8","string":"test","int":4,"boolean":true,"dateTime":"1015-11-29 14:35:13","float":13.333,"createdAt":"2017-11-29 14:35:13","updatedAt":"2017-11-29 14:35:13"},{"_typeName":"Model5","id":"9","string":"test","int":4,"boolean":true,"dateTime":"1015-11-29 14:35:13","float":13.333,"createdAt":"2017-11-29 14:35:13","updatedAt":"2017-11-29 14:35:13"}]}' -sSv

对于curl(使用占位符)的通用版本将如下所示:


curl '__SERVICE_ENDPOINT__/import' -H 'Content-Type: application/json' -H 'Authorization: Bearer __JWT_AUTH_TOKEN__' -d '{"valueType":"__NDF_TYPE__","values": __DATA__ }' -sSv

可以使用CLI或原始导出API导出数据。在这两种情况下,下载的数据都以JSON格式化,并遵循规范化数据格式(NDF)。由于导出的数据位于NDF中,因此可以直接将其导入具有相同模式的服务。当服务需要测试数据时,例如在dev阶段中,这可能是有用的。

Prisma CLI提供了prisma export命令。它接受两个选项:

  • --env-file(简写:-e):导出环境变量

  • --path(简写: -p):指向.zip目录的文件路径,该目录将由CLI创建并存储导出的数据

在底层,CLI使用下一节中描述的导出API。但是,使用CLI提供了一些主要好处:

  • CLI的身份验证机制(即你不需要手动发送你的token)
  • 直接下载数据到文件系统
  • 光标管理以防需要多个请求来导出所有应用程序数据(手动这样做时你需要发送多个请求,并调整记录位置)

以NDF格式执行数据导出,将被放置在被不同类型的NDF格式命名的三个目录:nodeslistsrelations

原始导出API在服务的HTTP端点的路径/export下公开。例如:

  • http://localhost:4466/my-app/dev/export
  • https://database.prisma.sh/my-app/prod/export

一个请求可以下载最大10 MB的JSON数据(在NDF中)。请注意,你需要在请求的HTTP header 的Authorization中提供身份验证令牌!

端点需要一个POST请求,其中正文为JSON,其中包含以下内容:


{
  "fileType": "nodes",
  "cursor": {
    "table": 0,
    "row": 0,
    "field": 0,
    "array": 0
  }
}

cursor描述了数据库中应从何处导出数据的偏移量。请注意,导出请求的每个响应都将返回一个具有以下两种状态之一的新游标:

  • Terminated (not full): 如果table所有的值,rowfieldarray返回为-1这意味着出口已完成。
  • Non-terminated (_full): 如果对于任何tablerowfieldarray是与-1不同的值的,这意味着10个MB用于该响应的最大尺寸已经到达。如果发生这种情况,你可以使用返回cursor值作为输入你的下一个export的参数。

下面是一个curl命令上传一些JSON数据(NDF类型nodes)的例子:


curl 'http://localhost:4466/my-app/dev/export' -H 'Content-Type: application/json' -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJPbmxpbmUgSldUIEJ1aWxkZXIiLCJpYXQiOjE1MTM1OTQzMTEsImV4cCI6MTU0NTEzMDMxMSwiYXVkIjasd3d3LmV4YW1wbGUuY29tIiwic3ViIjoianJvY2tldEBleGFtcGxlLmNvbSIsIkdpdmVuTmFtZSI6IkpvaG5ueSIsIlN1cm5hbWUiOiJSb2NrZXQiLCJFbWFpbCI6Impyb2NrZXRAZXhhbXBsZS5jb20iLCJSb2xlIjpbIk1hbmFnZXIiLCJQcm9qZWN0IEFkbWluaXN0cmF0b3IiXX0.L7DwH7vIfTSmuwfxBI82D64DlgoLBLXOwR5iMjZ_7nI' -d '{"fileType":"nodes","cursor":{"table":0,"row":0,"field":0,"array":0}}' -sSv

curl(使用占位符)的通用版本将如下所示:


curl '__SERVICE_ENDPOINT__/export' -H 'Content-Type: application/json' -H 'Authorization: Bearer __JWT_AUTH_TOKEN__' -d '{"fileType":"__NDF_TYPE__","cursor": {"table":__TABLE__,"row":__ROW__,"field":__FIELD__,"array":__ARRAY__}} }' -sSv

规范化数据格式(NDF)用作Prisma服务中导入和导出的中间数据格式。NDF描述了JSON的特定结构。

当使用NDF,数据会拆分三个不同的"值类型":

  • Nodes: Contains data for the scalar fields of nodes
  • Lists: Contains data for list fields of nodes
  • Relations: Contains data to connect two nodes via a relation by their relation fields

在NDF JSON文档的结构是具有以下两个键的对象:

  • valueType:表示文档中数据的值类型(可以是"nodes","lists"或者"relations")
  • values:包含作为数组的实际数据(遵循值类型)

在下面的例子都是基于这个数据模型:


type User {
  id: String! @unique
  firstName: String!
  lastName: String!
  hobbies: [String!]! @scalarList(strategy: RELATION)
  partner: User
}

如果valueType是"nodes",则values数组内对象的结构如下:


{
  "valueType": "nodes",
  "values": [
    { "_typeName": STRING, "id": STRING, "<scalarField1>": ANY, "<scalarField2>": ANY, ..., "<scalarFieldN>": ANY },
    ...
  ]
}

该符号表示的字段_typeNameid都是字符串类型的。_typeName是指从你的数据模型的SDL类型的名称。在<scalarFieldX>-placeholders将是SDL类型的字段的名称。

例如,下面的JSON文档可用于导入两个User节点的标量值:


{
  "valueType": "nodes",
  "values": [
    {"_typeName": "User", "id": "johndoe", "firstName": "John", "lastName": "Doe"},
    {"_typeName": "User", "id": "sarahdoe", "firstName": "Sarah", "lastName": "Doe"}
  ]
}

如果valueType是"lists",则values数组内对象的结构如下:


{
  "valueType": "lists",
  "values": [
    { "_typeName": STRING, "id": STRING, "<scalarListField>": [ANY] },
    ...
  ]
}

该符号表示的字段_typeNameid都是字符串类型的。_typeName是指你的数据模型的SDL类型的名称。在<scalarListField>-placeholder是那个SDL类型的列表中的字段名称。需要注意的是对比的是标量list字段,每个对象只能有一个字段。

例如,下面的JSON文档可以用于导入值两个User节点的hobbies列表字段:


{
  "valueType": "lists",
  "values": [
    {"_typeName": "User", "id": "johndoe", "hobbies": ["Fishing", "Cooking"]},
    {"_typeName": "User", "id": "sarahdoe", "hobbies": ["Biking", "Coding"]}
  ]
}

如果valueType是"relations",则values数组内对象的结构如下:


{
  "valueType": "relations",
  "values": [
    [
      { "_typeName": STRING, "id": STRING, "fieldName": STRING },
      { "_typeName": STRING, "id": STRING, "fieldName": STRING }
    ],
    ...
  ]
}

该符号表示的字段_typeNameidfieldName都是字符串类型的。

_typeName是指从你的数据模型的SDL类型的名称。在<relationField>-placeholder是那个SDL类型的关系字段的名称。由于关系数据的目标是通过关系连接两个节点,因此values数组中的每个元素本身都是一对(写成一个总是包含两个元素的数组),而不是像"nodes"和的情况那样的单个对象"lists"。

例如,以下JSON文档可用于User通过partner关系字段在两个节点之间创建关系:


{
  "valueType": "relations",
  "values": [
    [
      { "_typeName": "User", "id": "johndoe", "fieldName": "partner" },
      { "_typeName": "User", "id": "sarahdoe", "fieldName": "partner" }
    ]
  ]
}

下一节来学习Prisma Server部署

Prisma Server部署