1.6. 入门¶

在本文件中，我们将快速浏览 CouchDB 的功能。我们将创建第一个文档并尝试使用 CouchDB 视图。

1.6.1. 万事俱备！¶

我们将快速了解 CouchDB 的基础应用程序编程接口 (API)，方法是使用命令行实用程序 curl。请注意，这不是与 CouchDB 交互的唯一方式。在接下来的文档中，我们将向您展示更多方法。curl 的有趣之处在于它可以让您控制原始 HTTP 请求，并且您可以准确地看到数据库“幕后”发生了什么。

确保 CouchDB 仍在运行，然后执行以下操作

curl http://127.0.0.1:5984/

这将向您新安装的 CouchDB 实例发出 GET 请求。

回复应该类似于

{
  "couchdb": "Welcome",
  "version": "3.0.0",
  "git_sha": "83bdcf693",
  "uuid": "56f16e7c93ff4a2dc20eb6acc7000b71",
  "features": [
    "access-ready",
    "partitioned",
    "pluggable-storage-engines",
    "reshard",
    "scheduler"
  ],
  "vendor": {
    "name": "The Apache Software Foundation"
  }
}

没什么特别的。CouchDB 正在使用运行的版本号进行“问候”。

接下来，我们可以获取数据库列表

curl -X GET http://admin:password@127.0.0.1:5984/_all_dbs

我们只是在之前的请求中添加了 _all_dbs 字符串，以及我们的管理员用户名和密码（在安装 CouchDB 时设置）。

响应应该类似于

["_replicator","_users"]

注意

如果这为您返回一个空数组，则意味着您没有正确完成安装。有关此方面的更多信息，请参阅设置。

出于本示例的目的，我们将在本节之后不再显示系统数据库。在您的安装中，无论何时您GET /_all_dbs，您都应该在列表中看到系统数据库。

哦，对了，我们还没有创建任何用户数据库！

注意

curl 命令默认情况下会发出 GET 请求。您可以使用 curl -X POST 发出 POST 请求。为了便于使用我们的终端历史记录，我们通常使用 -X 选项，即使在发出 GET 请求时也是如此。如果我们下次想要发送 POST 请求，我们只需要更改方法。

HTTP 在幕后执行的操作比您在此处示例中看到的要多。如果您对通过网络传输的每一个细节都感兴趣，请传入 -v 选项（例如，curl -vX GET），这将显示您尝试连接的服务器、它发送的请求标头以及它接收到的响应标头。非常适合调试！

让我们创建一个数据库

curl -X PUT http://admin:password@127.0.0.1:5984/baseball

CouchDB 将回复

{"ok":true}

再次检索数据库列表将显示一些有用的结果

curl -X GET http://admin:password@127.0.0.1:5984/_all_dbs

["baseball"]

注意

我们应该在这里提到 JavaScript 对象表示法 (JSON)，这是 CouchDB 使用的数据格式。JSON 是一种基于 JavaScript 语法的轻量级数据交换格式。由于 JSON 与 JavaScript 本机兼容，因此您的 Web 浏览器是 CouchDB 的理想客户端。

方括号 ([]) 表示有序列表，花括号 ({}) 表示键值字典。键必须是字符串，用引号 (") 括起来，值可以是字符串、数字、布尔值、列表或键值字典。有关 JSON 的更详细说明，请参阅附录 E，JSON 简介。

让我们再创建一个数据库

curl -X PUT http://admin:password@127.0.0.1:5984/baseball

CouchDB 将回复

{"error":"file_exists","reason":"The database could not be created,
the file already exists."}

我们已经有一个同名数据库，因此 CouchDB 将返回错误。让我们尝试使用不同的数据库名称

curl -X PUT http://admin:password@127.0.0.1:5984/plankton

CouchDB 将回复

{"ok":true}

再次检索数据库列表将显示一些有用的结果

curl -X GET http://admin:password@127.0.0.1:5984/_all_dbs

CouchDB 将回复

["baseball", "plankton"]

最后，让我们删除第二个数据库

curl -X DELETE http://admin:password@127.0.0.1:5984/plankton

CouchDB 将回复

{"ok":true}

数据库列表现在与之前相同

curl -X GET http://admin:password@127.0.0.1:5984/_all_dbs

CouchDB 将回复

["baseball"]

为了简洁起见，我们将跳过处理文档，因为下一节将介绍一种不同的、可能更容易的方法来处理 CouchDB，这将为您提供这方面的经验。在完成示例时，请记住，在“幕后”，应用程序执行的所有操作都与您在此处手动执行的操作完全相同。所有操作都是使用 GET、PUT、POST 和 DELETE 以及 URI 完成的。

1.6.2. 欢迎使用 Fauxton¶

在了解了 CouchDB 的原始 API 之后，让我们通过使用 Fauxton（内置的管理界面）来熟悉它。Fauxton 提供对所有 CouchDB 功能的完全访问权限，并简化了处理一些更复杂概念的操作。使用 Fauxton，我们可以创建和销毁数据库；查看和编辑文档；编写和运行 MapReduce 视图；以及触发数据库之间的复制。

要在浏览器中加载 Fauxton，请访问

http://127.0.0.1:5984/_utils/

并在提示时使用您的管理员密码登录。

在后面的文档中，我们将重点介绍如何从服务器端语言（如 Ruby 和 Python）使用 CouchDB。因此，本文件是一个很好的机会来展示使用 CouchDB 集成的 Web 服务器来原生提供动态 Web 应用程序的示例，您可能希望在自己的应用程序中这样做。

在全新安装 CouchDB 后，我们应该做的第一件事是运行测试套件，以验证一切正常。这可以确保我们遇到的任何问题都不是由于设置问题造成的。同样，Fauxton 测试套件中的失败是一个危险信号，告诉我们在尝试使用可能存在问题的数据库服务器之前仔细检查我们的安装步骤，这样可以避免在一切似乎都不按预期工作时感到困惑！

要验证您的安装，请单击左侧的“验证”链接，然后按绿色“验证安装”按钮。所有测试都应该通过并显示一个复选标记。如果任何测试失败，请重新检查您的安装步骤。

1.6.3. 您的第一个数据库和文档¶

在 Fauxton 中创建数据库很简单。在概述页面中，单击“创建数据库”。当询问名称时，输入 hello-world 并单击“创建”按钮。

创建数据库后，Fauxton 将显示其所有文档的列表。此列表最初为空，因此让我们创建第一个文档。单击“所有文档”旁边的加号，然后选择“新建文档”链接。CouchDB 将为您生成一个 UUID。

为了演示目的，让 CouchDB 分配 UUID 就可以了。当您编写第一个程序时，我们建议您分配自己的 UUID。如果您依赖服务器来生成 UUID，并且由于第一个 POST 请求失败而最终发出了两个 POST 请求，那么您可能会生成两个文档，并且永远不会发现第一个文档，因为只有第二个文档会被报告回来。生成您自己的 UUID 可以确保您永远不会生成重复的文档。

Fauxton 将显示新创建的文档及其 _id 字段。要创建新字段，只需使用编辑器编写有效的 JSON 即可。通过在 _id 值后添加逗号，然后添加以下文本，添加新字段

"hello": "my new value"

单击绿色的“创建文档”按钮以完成创建文档。

您可以尝试其他 JSON 值；例如，[1, 2, "c"] 或 {"foo": "bar"}。

您会注意到文档的 _rev 已被添加。我们将在后面的文档中详细介绍这一点，但现在，需要注意的是，_rev 在保存文档时充当安全功能。只要您和 CouchDB 同意文档的最新 _rev，您就可以成功保存更改。

为了清晰起见，您可能希望在所有文档视图中显示文档的内容。要启用此功能，请从窗口右上角选择“选项”，然后选中“包含文档”选项。最后，按“运行查询”按钮。完整文档应与 _id 和 _rev 值一起显示。

1.6.4. 运行 Mango 查询¶

现在我们已经成功存储了文档，我们希望能够查询它们。在 CouchDB 中执行此操作的最简单方法是运行 Mango 查询。Mango 查询始终包含两个部分：索引和选择器。

索引指定我们希望能够查询哪些字段，选择器包含定义我们正在寻找的确切内容的实际查询参数。

索引存储为行，这些行按您指定的字段排序。这使得即使在有数千或数百万行的情况下，从一系列键中检索数据也变得高效。

在运行示例查询之前，我们需要一些数据来运行它。我们将创建包含电影信息的文档。让我们为三部电影创建文档。（允许 CouchDB 生成 _id 和 _rev 字段。）使用 Fauxton 创建具有以下最终 JSON 结构的文档

{
    "_id": "00a271787f89c0ef2e10e88a0c0001f4",
    "type": "movie",
    "title": "My Neighbour Totoro",
    "year": 1988,
    "director": "miyazaki",
    "rating": 8.2
}

{
    "_id": "00a271787f89c0ef2e10e88a0c0003f0",
    "type": "movie",
    "title": "Kikis Delivery Service",
    "year": 1989,
    "director": "miyazaki",
    "rating": 7.8
}

{
    "_id": "00a271787f89c0ef2e10e88a0c00048b",
    "type": "movie",
    "title": "Princess Mononoke",
    "year": 1997,
    "director": "miyazaki",
    "rating": 8.4
}

现在，我们希望能够通过电影的上映年份来查找电影，我们需要创建一个 Mango 索引。为此，请在数据库概述中转到“使用 Mango 运行查询”。然后点击“管理索引”，并将左侧的索引字段更改为如下所示

{
   "index": {
      "fields": [
         "year"
      ]
   },
   "name": "year-json-index",
   "type": "json"
}

这定义了字段 year 上的索引，并允许我们发送特定年份的文档查询。

接下来，点击“编辑查询”并将 Mango 查询更改为如下所示

{
   "selector": {
      "year": {
         "$eq": 1988
      }
   }
}

然后点击“运行查询”。

结果应该是一个单一结果，即电影“龙猫”，其年份值为 1988。 $eq 这里代表“等于”。

注意

请注意，如果您跳过添加索引，查询仍然会返回正确的结果，尽管您会看到关于没有使用预先存在的索引的警告。在小型数据库上，不使用索引可以正常工作，并且在开发或培训中测试查询是可以接受的，但我们强烈建议在任何其他情况下不要这样做，因为索引对于良好的查询性能至关重要。

您也可以使用此选择器查询 1980 年代的所有电影

{
   "selector": {
      "year": {
         "$lt": 1990,
         "$gte": 1980
      }
   }
}

结果是 1988 年和 1989 年的两部电影。 $lt 这里表示“小于”，而 $gte 表示“大于或等于”。鉴于我们所有的电影都比 1980 年更新，后者目前没有任何影响，但这使查询具有未来性，并允许我们稍后添加更早的电影。

1.6.5. 触发复制¶

Fauxton 可以触发两个本地数据库之间的复制，本地数据库和远程数据库之间的复制，甚至两个远程数据库之间的复制。我们将向您展示如何将数据从一个本地数据库复制到另一个本地数据库，这是一种在处理示例时备份数据库的简单方法。

首先，我们需要创建一个空数据库作为复制的目标。返回到数据库概述并创建一个名为 hello-replication 的数据库。现在点击侧边栏中的“复制”，选择 hello-world 作为源，hello-replication 作为目标。点击“复制”以复制您的数据库。

要查看复制结果，请再次点击“数据库”选项卡。您应该看到 hello-replication 数据库的文档数量与 hello-world 数据库相同，并且它的大小也应该大致相同。

注意

对于更大的数据库，复制可能需要更长的时间。在复制过程中，务必保持浏览器窗口打开。或者，您可以通过 curl 或其他可以处理长时间运行连接的 HTTP 客户端触发复制。如果您的客户端在复制完成之前关闭连接，您将不得不重新触发它。幸运的是，CouchDB 的复制可以从它停止的地方接管，而不是从头开始。

1.6.6. 总结¶

现在您已经了解了 Fauxton 的大多数功能，您将准备好深入研究并检查您的数据，因为我们在接下来的几份文档中构建示例应用程序。Fauxton 使用纯 JavaScript 方法来管理 CouchDB，展示了如何仅使用 CouchDB 的 HTTP API 和集成 Web 服务器来构建功能齐全的 Web 应用程序。

但在我们到达那里之前，我们将再次看看 CouchDB 的 HTTP API——现在使用放大镜。让我们在沙发上蜷缩起来，放松一下。