Malla文档
首页快速入门打开 Malla

连接你的数据库

连接 Postgres，用参数查询，并通过实时搜索显示数据行。

用户指南
中级25 分钟

你将构建： 一个从你自己的 Postgres 数据库读取的产品列表，带有一个随输入实时筛选的搜索框

请先阅读： 显示 API 数据

在本教程中，你将连接一个 Postgres 数据库（例如 Neon 或 Supabase 上的数据库），编写带参数的 SQL 查询，并用搜索框为这个参数提供值，让列表随访客输入实时筛选。你需要一个可以从互联网访问的 Postgres 数据库，以及一个有读取权限的用户。

连接你的数据库视频即将推出。下面的文字步骤已涵盖全部内容。
连接你的数据库· 8 分钟

准备一张表

  1. 创建示例数据

    如果你还没有要展示的表，打开数据库服务商的 SQL 编辑器并运行：

    sql
    create table products (id serial primary key, name text not null, price numeric(8, 2) not null);
insert into products (name, price) values
  ('Canvas tote', 24.00), ('Ceramic mug', 14.50), ('Linen apron', 32.00),
  ('Notebook', 9.90), ('Oak coaster set', 18.00), ('Wool blanket', 89.00);

  2. 找到连接信息

    在服务商的仪表盘中，打开数据库的连接信息（在 Neon 和 Supabase 中，点击项目上的 Connect）。复制主机、端口、数据库名、用户名和密码。它们就是 postgresql://user:password@host:5432/database 这类连接字符串的各个部分。

连接数据库

  1. 添加 PostgreSQL 集成

    从左侧边栏底部打开 Data 工作区。在 Integrations 旁点击 +，选择 PostgreSQL。命名为 Shop database。

  2. 填写连接信息

    在 Connection 卡片中，输入 Host（例如 ep-cool-name.us-east-2.aws.neon.tech）、Port（通常为 5432）、Database 和 User。保持 Ssl 为 require，或选择 verify-full 以同时校验服务器证书。

  3. 添加密码

    在 Secrets 卡片中，输入数据库用户的 Password。它在服务端加密保存，不会再次显示。

  4. 创建并测试

    点击 Create integration，然后在 Test connection 卡片中点击 Run test。显示 Connected 表示 Malla 已连上数据库并运行了一条简单查询。出错时会显示错误信息和代码，例如密码错误或主机无响应。

检查点

Shop database 集成列在 Integrations 下，测试结果为 Connected。

查询这张表

  1. 查看所有表

    在 Queries 旁点击 +，把查询重命名为 products。在 Source 中，把 Integration 设为 Shop database，Operation 设为 List tables，然后在 Result 卡片中点击 Run。你会看到该用户可读取的所有表及其列。

  2. 编写 SQL

    把 Operation 设为 Query。在 Sql 中写入：

    sql
    select id, name, price from products
where name ilike '%' || $1 || '%'
order by name

    $1 是一个占位符。它的值来自 Params，从不来自 SQL 文本，所以访客无法借此注入 SQL。

  3. 给参数一个值

    在 Params 下点击 Add item，输入带引号的 "mug"：每一项接受一个 JSON 值，所以文本需要引号，数字不需要。Max rows 留空时返回 200 行，最多 1000 行。

  4. 返回数据行

    查询返回一个包含 rows、rowCount、columns 和 truncated 的对象。在 When it runs 中，把 Response path 设为 rows，让查询只返回列表。点击 Run：结果是一个产品，即陶瓷马克杯。

  1. 创建搜索变量

    在 Page variables 旁点击 +，选择 String。把它重命名为 search，默认值留空。

  2. 用变量为参数提供值

    选中 products 查询。在 Params 下 "mug" 一项旁，点击 Use an expression（ƒ 按钮），把值替换为 vars.search。

    在 When it runs 中选择 Client。查询现在会在浏览器中于加载时运行，并在 vars.search 每次变化时再次运行。Debounce (ms) 会等到访客停止输入后再运行；默认为 250 ms。浏览器请求 Malla 来运行查询，所以密码永远不会离开服务端。

  3. 添加搜索框

    回到画布，在 Layers 标签页中点击 +，选择 Input。在 Field 分区中，把 Placeholder 设为 Search products，把 Value 设为 search。现在在输入框中打字就会写入这个变量。

  4. 列出产品

    在搜索框下方插入一个 Collection list。在 Collection list 中，把 Source 设为 Expression，Items 设为 queries.products.data。在 Item 内添加两段文本，并在 Typography 中把它们分别绑定到 item.name 和 item.price。把 Empty text 设为 No products match your search.。

检查点

由于搜索为空，画布列出了全部六个产品。

  1. 试试搜索

    按 ⌘↵ 预览页面，在搜索框中输入 oa。稍等片刻，列表只显示杯垫套装。输入 xyz 查看空状态文字。再按一次 ⌘↵ 回到编辑状态。

  2. 发布

    点击 Publish 并打开预发布页面。搜索对访客同样有效。

完成

你的页面从你自己的数据库读取产品，并随访客输入实时筛选。

你学到了什么

  • PostgreSQL 集成保存主机、数据库和用户，并在服务端加密保存密码。
  • $1、$2 占位符从 Params 获取值，参数可以读取变量。
  • 客户端查询会在其读取的变量变化时重新获取数据，从而把输入框变成实时搜索。

阅读本教程背后的指南：

查询与集成连接 REST、GraphQL 和 CMS，把密钥保留在服务端，并选择静态、服务端或客户端模式。变量由绑定读取、由工作流写入的页面和站点状态，可保存在 URL 或浏览器中。集合列表为查询或数组中的每个条目重复一次模板，支持空状态和分页。安全模型沙箱化画布、不使用 eval、服务端密钥、行规则、限流和出站策略。