Cloud SQL

应用制作工具应用通常将数据存储在 Cloud SQL 中，后者是一种 Google Cloud Platform (GCP) 服务，可以在云端提供完全托管的 SQL 数据库。详细了解 Cloud SQL 的优势。

作为应用开发者，您可以选择两种类型的 Cloud SQL 实例：

• 默认 - G Suite 管理员可以设置一个在组织中的应用制作工具应用之间共享的 Cloud SQL 实例。设置默认实例以后，您在添加至少一个 Cloud SQL 数据模型时，系统会自动为您的应用创建一个新的数据库。如果您的应用需要一个易于使用且无需设置的数据库，请选择此选项。在开发者对某个应用进行原型设计和测试时，组织通常会使用默认实例；随后，在该应用已准备好作为正式版应用部署时，再让该应用改用自定义实例。

• 自定义 - 一旦您的管理员设置了默认的 Cloud SQL 实例，您还可以设置自己的 Cloud SQL 实例。在以下情况下，请选择此选项：

  • 应用为大量用户提供服务，或者存储大量数据。
  • 该数据库必须与其他应用共享。
  • 您需要管理数据库或保留对 Cloud SQL 实例的控制。

注意：只有在 G Suite 管理员为您的组织设置了默认的 Cloud SQL 实例以后，您才能添加自定义 Cloud SQL 实例。

Cloud SQL 安全性

无论您的应用使用默认 Cloud SQL 实例还是自定义 Cloud SQL 实例，系统始终会在传输以及静态时对凭据进行加密：

• 默认 Cloud SQL - 凭据存储在应用制作工具服务器上。应用开发者或最终用户无法访问这些凭据。

• 自定义 Cloud SQL - 一旦某个开发者将 Cloud SQL 凭据提交到应用制作工具，该应用的所有开发者就再也看不到这些凭据了。某个开发者在编辑器中开发应用时，应用制作工具会将这些凭据存储在浏览器中。该开发者重新加载或关闭浏览器标签页时，系统会移除这些凭据。

  开发者使用自定义 Cloud SQL 模型部署应用时，这些凭据会与部署的应用一起存储在 Google 服务器上。最终用户无法访问这些凭据。

前期准备

在将 Cloud SQL 用于应用制作工具之前，请查看以下有关安全和费用的注意事项：

• 存储在 GCP 中的数据位于您的 G Suite 组织之外 - 某些组织（尤其是政府机构）对存储敏感数据有严格的要求。GCP 和 G Suite 都符合严格的保密和安全标准，但您在使用这些服务时可能会受到不同条款的约束。请详细了解我们的产品是如何遵循保密和安全标准的：

  • Google Cloud Platform
  • G Suite

• Cloud SQL 是 GCP 的一部分 - 如果您想试用自定义实例，可以开始免费试用。不过，如果您在免费试用结束以后继续使用自定义实例，则您的组织将承担相应的费用。详细了解价格。大多数应用制作工具应用的典型月度价格极低。

将新的自定义 Cloud SQL 实例用于您的应用

如果您不想使用默认的 Cloud SQL 实例，可以改用自定义 Cloud SQL 实例。如需使用自定义 Cloud SQL 实例，G Suite 管理员仍然必须先设置默认实例。您的应用可以使用现有的自定义数据库，您也可以创建新的自定义数据库。如果您要创建新的自定义实例，则需要花一些时间设置该实例并将其与应用制作工具进行集成。

注意：只有在 G Suite 管理员设置了默认的 Cloud SQL 实例以后，您才能将自己的应用连接到自定义 Cloud SQL 实例中的数据库。

如果您要设置新的 Cloud SQL 实例，我们建议您使用第二代 Cloud SQL 实例。应用制作工具也支持第一代实例。由于价格和性能特征会因实例的类型而异，因此在创建实例之前，请查看功能。

注意：应用制作工具仅支持 MySQL 数据库。您无法使用 PostgreSQL。

如需按照以下说明操作，您必须拥有下列权限：

• 访问 GCP Console 的权限。
• 创建 Cloud SQL 实例和用户的权限。

第二代

1. 如果您还没有创建第二代 Cloud SQL for MySQL 实例，请在 us-central 区域中创建一个。
   
   注意：配置实例时，请注意以下内容：

   • 您必须选择 MySQL 作为数据库类型。
   • 无论您的地理位置如何，我们都建议您将 us-central1 区域用于新实例。您可以选择其他区域，但应用性能可能不太理想，因为应用是在 us-central 区域中运行的。
2. 在 GCP Console 中，为您的应用创建一个 MySQL 用户帐号，用于访问该数据库。

   请记录用户名和密码，以便在将自己的应用连接到该数据库时输入用户名和密码。为了防止别人通过用户帐号进行未经授权的访问，我们建议您为该实例上的所有帐号设置安全系数高的密码。

3. 在 GCP Console 中，创建一个新的数据库。
4. 应用制作工具会在 App Engine 上运行。请将服务帐号添加到您的 Cloud 项目，以设置与 App Engine 的连接：
   1. 转到 IAM 和管理项目页面（在 GCP Console 中，点击 “Menu”IAM & Admin）。
   2. 选择包含您的 Cloud SQL 实例的项目。
   3. 点击 Add。
   4. 在“New members”对话框中，输入：
      [e-mail] 选择 Cloud SQLCloud SQL Client 作为角色。
   5. 点击 Save。
   6. 如果其他开发者会修改或部署此应用，请添加其 Google 帐号作为新成员并分配 Cloud SQL Client 角色。
5. 复制您实例的详细信息：
   1. 打开 Cloud SQL 实例页面（在 GCP Console 中，点击 “Menu”SQL）。
   2. 点击您的实例，然后查找 Instance connection name 字段。
   3. 在 Instance connection name 框中，点击“Copy”。
6. 将您的应用设置为使用自定义 Cloud SQL 数据库：
   
   1. 在应用制作工具中，打开您的应用，然后点击 “Settings”Database。
   2. 点击 Switch to a custom Cloud SQL database。
   3. 粘贴实例详细信息，然后添加步骤 3 中创建的数据库的名称。请使用以下格式：
      projectName:regionName:instanceName/databaseName
      
   4. 输入数据库用户帐号的用户名和密码，然后点击 Continue。

第一代

应用制作工具支持第一代实例。不过，如果您要创建新实例，我们建议您改为创建第二代实例。

1. 如果您还没有创建第一代实例，请创建一个。
   
   注意：配置实例时，请注意以下内容：

   • 您必须选择 MySQL 作为数据库类型。
   • 无论您的地理位置如何，我们都建议您将 us-central1 区域用于新实例。您可以选择其他区域，但应用性能可能不太理想，因为应用是在 us-central 区域中运行的。
2. 为此实例配置用户帐号：
   • 更改根帐号的密码。为了防止别人通过（以下步骤中创建的）App Engine 连接进行未经授权的访问，我们建议您为该帐号设置安全系数高的密码。
   • 创建一个您的应用可以用来访问该数据库的用户帐号。创建数据库用户时，请注意以下两点：
     • 将 localhost 指定为 主机名。
     • 为该帐号设置安全系数高的密码，以防止别人进行未经授权的访问。

     请记录用户名和密码，以便在将自己的应用连接到该数据库时输入用户名和密码。

3. 在 GCP Console 中，创建一个新的数据库。
4. 应用制作工具会在 App Engine 上运行。请将应用制作工具的应用 ID 添加到您的 Cloud SQL 实例，来设置与 App Engine 的连接：
   1. 转到 Cloud SQL 实例页面（在 GCP Console 中，点击 “Menu”SQL。
   2. 点击实例名称以打开其 Overview 页面，然后点击 Authorization 标签页。
   3. 点击 Add project ID 并输入以下内容：
      appmaker-maestro
   4. 点击 Done 以退出修改模式。
   5. 点击 Save 以更新实例。
5. 将自定义 Cloud SQL 实例添加到您的应用。
   
   1. 打开您的应用，然后点击 “Settings” Database。
   2. 点击 Switch to a custom Cloud SQL database。
   3. 输入地址的格式如下：
      projectName:instanceName/databaseName
   4. 输入数据库用户帐号的用户名和密码，然后点击 Continue。

将现有的 Cloud SQL 数据库用于您的应用

如果您在 Cloud SQL 中已经有数据，则可以在自己的应用中创建一个使用这些数据的模型：

1. 将实例详细信息添加到您的应用：
   1. 打开 Cloud SQL 实例页面（在 GCP Console 中，点击 “Menu”SQL）。
   2. 点击您的实例，然后查找 Instance connection name 字段。
   3. 在 Instance connection name 框中，点击“Copy”。
   4. 在应用制作工具中，打开您的应用，然后点击 “Settings”Database。
   5. 点击 Switch to a custom Cloud SQL database。
   6. 粘贴实例详细信息，然后添加现有数据库的名称。请使用以下格式：projectName:regionName:instanceName/databaseName
   7. 输入数据库用户帐号的用户名和密码，然后点击 Continue。
2. 在应用制作工具界面中的 Data 旁边，点击 “Add”。
3. 选择 Google Cloud SQL (existing)。

4. 按以下格式输入地址：

   • 第一代 - projectName:instanceName/databaseName
   • 第二代 - projectName:regionName:instanceName/databaseName

5. 输入数据库用户帐号的用户名和密码。

6. 从列表中选择一个表，然后点击导入。您可以导入任何不属于联接表的表。

导入某个关系中涉及的两个表以后，应用制作工具会自动创建关系。应用制作工具使用联接表或者使用导入表中的外键约束来识别 Cloud SQL 数据库中的关系。例如，如果表 A 有表 B 的外键，则应用制作工具会自动创建从 A 到 B 的多对一关系。

如果 Cloud SQL 数据库中的架构发生变化，您可以更新自己的模型：

1. 点击 “Settings” Database。
2. 在 Model and relation compatibility 下，点击 Check 按钮。您可以选择更新所有 Cloud SQL 模型以匹配该数据库，或者更新该数据库以匹配模型。

如果更新模型，则应用制作工具会保留对模型所做的更改，例如已修改的字段名称、验证属性和事件。不过，如果从 Cloud SQL 中删除了某个字段，则相应的字段也会从模型中删除。

更新应用的 Cloud SQL 设置

您可以转到 “Settings” Database 来执行以下操作：

• 切换到默认的 SQL 实例。
• 更新实例地址。
• 检查模型和关系兼容性。

在默认的 Cloud SQL 数据库和自定义 Cloud SQL 数据库之间进行切换

对于已设置默认 Cloud SQL 实例的组织，新模型会使用此实例。如果您的应用需要一个无需设置且易于使用的数据库，则默认的 Cloud SQL 数据库就是理想的选择。

如果您发现默认的数据库无法满足您的需求，可以将其转换为自定义数据库：

1. 如果您还没有设置自定义 Cloud SQL 实例，请设置一个。选择 us-central 作为新实例的区域。
2. 打开您的应用，然后点击 “Settings” Database。
3. 点击 Check 按钮以验证模型和关系兼容性。如果应用制作工具报告不兼容，在删除数据库中数据前，您可能无法继续执行后续步骤。
4. 准备好继续执行后续步骤以后，点击切换到自定义 Cloud SQL 数据库按钮。

5. 按以下格式输入地址：

   • 第一代 - projectName:instanceName/databaseName
   • 第二代 - projectName:regionName:instanceName/databaseName

6. 输入数据库用户帐号的用户名和密码，然后点击 Continue。

切换到自定义数据库以后，您可以选择切换回默认数据库。

使用 Cloud SQL 记录

Cloud SQL 模型中的每条记录代表表中的一行。如果您创建应用制作工具记录，则您的 Cloud SQL 实例会在相应的表中添加一行。

应用制作工具通常使用表的主键列作为其记录的键，且在创建记录以后无法更改主键值。在某些情况下，这些键并不匹配：

• 使用 newRecord() 在服务器上创建的记录在保存之前具有 null 键，即使分配了主键列也是如此。

• 客户端上的草稿记录具有一些合成键，这些合成键只有在草稿记录保存以后才会与主键列相匹配。

• 在客户端上的手动保存模式数据源中创建的记录具有一些合成键，这些合成键即使在记录保存了以后也与主键列不匹配。

您可以通过多种方式在应用制作工具中处理主键：

Cloud SQL 主键
自然主键	当 Cloud SQL 表使用自然主键时，应用模型中与该键对应的字段是必填字段，在保存记录之前必须为其指定值。如需详细了解必填字段，请转至验证数据。
代理主键	如果 Cloud SQL 表使用代理键，则您可以在设置记录键之前设置主键。或者，如果该数据库可以提供主键，则您可以将记录键保留为 null，并让应用制作工具自动更新记录键。此方法不适用于使用手动保存模式数据源在客户端上创建的记录。
自动递增主键	对于整数主键，Cloud SQL 可以在创建记录时自动分配序列号作为主键值。在这种情况下，主键字段值不必由用户或应用提供。 如需在应用制作工具中设置此选项，请执行以下操作： 在导航窗格的 Data 部分中，点击数据模型。 在 Fields 标签页中，点击要自动递增的数字字段。 点击 Advanced，然后选择 Auto Increment。
唯一 ID 主键	创建记录时，应用制作工具可以为主键字段设置唯一 ID。唯一 ID 的长度是 12 个字符，由制作工具随机生成，而不是由用户或应用提供。 如果您不希望主键透露有关表中记录的顺序或总记录数的信息（例如在用户只拥有某些记录的访问权限时），请使用唯一 ID 主键。 如需在已经有数字主键的应用制作工具模型中创建唯一 ID 主键，请执行以下操作： 在导航窗格的 Data 部分中，点击数据模型或者创建一个新的模型。 在 Fields 标签页中，点击 Id 字段。 点击 Advanced 并清除 Auto increment 复选框。 点击 Add fieldString。 点击 Set as primary key。 输入字段的名称，例如“uniqueID”。 点击 Advanced，然后选择 Auto unique identifier。 （可选）删除 Id 字段。

关系

可以使用服务器脚本直接读取与外键字段对应的字段。在客户端上，可以将外键字段的值及其对应关联修改为关系。详细了解如何修改关系。

视图

您可以将 Cloud SQL 视图导入为只读数据模型。基于视图的模型可以利用涉及联接、聚合和子选择的 SQL 查询。例如，以下架构使用视图聚合表中的数据，以方便在应用制作工具中显示：

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;
    

SQL 计算模型

SQL 计算模型使用 Cloud SQL 查询检索数据。与其他计算数据源一样，SQL 数据源无法创建、删除或更新记录。

如需创建 SQL 计算模型，请执行以下操作：

1. 在应用制作工具中的 Data 旁边，点击“Add”。
2. 选择 Calculated SQL，然后点击 Next。
3. 为模型命名，然后点击创建。

4. 转到数据源标签。添加 SQL 数据源（或使用默认数据源），然后在 SQL Query 字段中输入单个查询。

   该 SQL 查询必须具有以下属性：

   • 该查询不能带有 limit 或 offset 子句。应用制作工具会根据数据源的 pageSize 和 pageIndex 添加 limit 和 offset 子句。
   • 该 SQL 查询输出列名称和类型必须与该计算模型的名称和类型匹配。
   • 该 SQL 查询只能包含以英文冒号开头的参数，例如 :Param。这些参数必须与数据源上的自定义属性的名称和类型匹配。

例如，某个 HR 应用需要显示每个部门中超过给定年龄的员工数量。该应用有一个 Cloud SQL 模型 Employee，其中有 Age 和 Dept 字段。

为了显示过滤后的数据，该应用使用带有 DeptName 和 Count 这两个字段的计算模型 EmployeeCount。该计算模型有一个 SQL 数据源（该数据源具有一个名为 MinAge 的 number 自定义属性），并使用以下查询：

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

在 SQL 中，列表参数会转换为带有英文括号的参数列表。例如，要选择名称与参数列表中的元素匹配的部门的 ID，您可以编写如下查询：

SELECT id from Departments WHERE Name in :PossibleNames
    

PossibleNames 参数会转换为 (?, ?, ?, ...)，并且参数值的元素会用于 SQL 占位符。

对于基于时间的参数，您需要设置时区。

注意：SQL 计算模型不会继承或遵循为查询模型设置的安全限制。请在 Security 标签页中为 SQL 计算模型本身设置安全限制。

关系过滤

Cloud SQL 是唯一可以由数据绑定和服务器脚本编写中相关模型的字段过滤的模型类型。

详细了解关系过滤。

时区

在某些情况下，Cloud SQL 实例和应用制作工具位于不同的时区。这可能会导致系统将不适宜的日期和时间写入到数据库。请查看下表并确保正确设置日期字段类型。

日期字段类型的时区处理
Cloud SQL 模型	根据需要设置日期字段类型： 打开模型的 Fields 标签页。 点击日期字段，然后点击 Advanced 以设置日期类型： DATE 或 DATETIME - 用于没有时区的字段。在将数据写入到数据库之前，应用制作工具会将时间转换为应用制作工具服务器所在时区的时间（在“应用设置”中进行设置）。 时间戳 - 用于有时区的字段。应用制作工具会保存用户的时区，并且会在 Cloud SQL 中以相对于 Unix Epoch 时间的日期写入相应日期。 对于这两种日期类型，应用制作工具在显示数据时会将日期转换为浏览器所在时区的日期。
SQL 计算模型	将日期类型字段添加到 SQL 计算模型时，该字段会作为“DATETIME”类型添加进去。 注意：我们建议您，不要将数据源设置为在常规 Cloud SQL 模型中查询“时间戳”字段来获取日期值。只有在应用和数据库位于同一时区时，系统才能正确读取日期。
SQL 计算数据源查询参数	根据需要设置日期字段类型： 打开 SQL 计算模型的 Datasources 标签页。 点击数据源，然后点击 Add Parameter。 对于日期参数，点击 Data SQL Type 下拉列表，然后选择类型： DATE 或 DATETIME - 用于没有时区的参数。当查询操作使用“DATE”或“DATETIME”字段时，应用制作工具服务器会将相应字段的值从应用用户所在时区的值转换为该服务器所在时区的值，然后再在查询中使用转换后的值。 例如，如果某个位于 PST (UTC-8) 时区的用户查询 2018 年 1 月 1 日上午 9 点之前创建的记录，而应用制作工具服务器位于 CT (UTC-6) 时区，则查询操作将搜索 2018 年 1 月 1 日上午 11 点之前创建的记录。 时间戳 - 用于有时区的参数。应用制作工具会将时间转换为 UTC 时间，然后再在查询中使用转换后的时间。我们建议您不要使用“时间戳”类型的查询参数，因为只有在应用和数据库位于同一时区时，系统才能正确处理日期。

限制和局限

• 如果您的 Cloud SQL 表没有主键列或者有多个主键列，则应用制作工具无法修改或创建它们的关系。

• 应用制作工具会将 BIGINT 值表示为字符串，因为 BIGINT 表示的数字范围太大而无法用 JavaScript 数字表示。

• 应用制作工具无法导入某些 Cloud SQL 列类型，例如 BLOB、CLOB 和其他二进制类型。您仍然可以导入具有这些列类型的模型，但系统将无法读取或写入这些列。如果这些列标记为非 null，则整个数据模型中的其他所有列都将是只读的。

• 应用制作工具无法针对涉及联接、聚合或子选择的 Cloud SQL 模型表达查询。如果要针对上述情况执行查询，请导入 SQL 视图作为模型或者在计算模型中使用 SQL 数据源。

• 应用不支持按关键字进行搜索。突破该限制的一种解决方法是，创建一个使用 contains 运算符模拟全文搜索的自定义查询。例如，对于具有 Name 和 Department 字段的模型 Employee，请使用查询 (Name contains? :Keywords) OR (Department contains? :Keywords)，并将 Keywords 参数绑定到文本字段的 value 属性。