# @apostrophecms/db-connect 中文文档

规范地址：https://npmcn.com/package/%40apostrophecms/db-connect/

版本：1\.1\.0
npm 元数据更新时间：2026-10-20T16:57:19.846Z
中文译文更新时间：2026-11-06T11:04:20.603Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40apostrophecms/db-connect
原文对照：https://npmcn.com/package/%40apostrophecms/db-connect/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：428 kB，31 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：3 个
- 首次发布：2026-04-21T12:51:26.915Z
- 最新版本发布：2026-09-30T19:26:26.725Z
- 近 30 天下载量：7202（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

ApostropeCMS 数据库连接库和垃圾堆/存储工具

## 安装

```sh
npm install @apostrophecms/db-connect
```

也可以使用：`pnpm add @apostrophecms/db-connect`、`yarn add @apostrophecms/db-connect`、`bun add @apostrophecms/db-connect`

## README

# @ apostrophicems/ db- 连接

`@apostrophecms/db-connect` 定义数据库连接 API [ApostropheCMS 磁带控制系统](https://apostrophecms.com/)它为MongoDB、PostgreSQL和SQLite提供适配器,包括: `apos-db-dump` 财务报告和审定财务报表 `apos-db-restore` 用于数据库迁移和备份的命令行工具.

Db-连接的API与蒙戈DB API的一个大子集相兼容. 然而,在这份介绍性说明之后,本文件将介绍: **db 连接 API** 以自己的条件。 对于需要跨越所有三个数据库的项目,只需使用此处定义的功能即可.

## 支持的连接 URL

### 蒙戈DB

```
mongodb://localhost:27017/mydb
mongodb+srv://user:pass@cluster.example.com/mydb
```

标准MongoDB连接字符串. MongoDB适配器是围绕已存在的驱动器的薄薄包装.

### 邮递SQL

```
postgres://localhost:5432/mydb
```

单一数据库模式。 所有收藏作为表格存放于 `public` 计划.

### SQL 点

```
sqlite:///path/to/database.db
```

使用基于文件的 SQLite 数据库 `better-sqlite3`。父目录是 如果不存在,则创建.

与其它不同的是,这其实不是一个 URL: 之后的一切 `sqlite://` 是一个 **文件系统路径, 完全按照写入**这一点很重要,因为 文件系统路径不是 URL —— 它们不是% 编码的, 可能包含 字符 一个 URL 解析器处理为重要,在 Windows 上,它们以 驱动一个 URL 解析器读作 `host:port`。所以不要用% 编码 路径。 一个空间是空间 :

```
sqlite:///Users/jane/My Project/data/site.db
```

`%20` 这里表示一个字面百分比,2,0,而不是一个空间。 绝对和 相对路径工作,在Windows上,两个分隔符都这样做:

```
sqlite:///var/lib/mysite/data.db          absolute (POSIX)
sqlite://data/site.db                     relative to the working directory
sqlite://C:\Users\jane\site\data\site.db  absolute (Windows)
sqlite://C:/Users/jane/site/data/site.db  absolute (Windows, forward slashes)
sqlite:///C:/Users/jane/site/data/site.db absolute (Windows, file:// spelling)
```

内存数据库`sqlite://:memory:`)不支持——适配器 假设一个适合托管 ApostropeCMS 站点的持久商店.

### 多站点(多站点)

```
multipostgres://localhost:5432/shareddb-tenant1
```

设计用于AposropeCMS [多站点](https://apostrophecms.com/extensions/multisite-2) 模块。 在这个模式下,每个站点在一个单一的物理数据库内获得自己的PostgreSQL schema.

URL 路径在 **最后一个连字符**数字 :

-   最后一个连字符之前的每件事都是真实的 PostgreSQL 数据库名称(`shareddb`(中文(简体) )
-   之后的一切都是计划名称`tenant1`(中文(简体) )

每个方案在第一次使用时自动创建,在数据库被丢弃时被清理掉。 这提供了真正的多租户隔离——没有跨租户数据泄露——同时高效共享一个PostgreSQL实例.

## 连接中

```js
const connect = require('@apostrophecms/db-connect');

const client = await connect('postgres://localhost:5432/mydb');
const db = client.db();
const articles = db.collection('articles');

// Insert a document
const result = await articles.insertOne({ title: 'Hello', status: 'draft' });

// Query documents
const docs = await articles.find({ status: 'draft' })
  .sort({ title: 1 })
  .limit(10)
  .toArray();

// Update a document
await articles.updateOne(
  { _id: result.insertedId },
  { $set: { status: 'published' } }
);

await client.close();
```

`connect(uri)` 返回客户端。 打电话 `client.db()` 获取数据库,然后 `db.collection(name)` 获取收藏.

## 原子

`insertOne` 财务报告和审定财务报表 `deleteOne` 永远是原子.

`updateOne` 无 `upsert` 当原子只使用下列运算符时:

-   **`$set`**, (中文(简体) ), **`$inc`**, (中文(简体) ), **`$unset`**, (中文(简体) ), **`$currentDate`** -- 总是原子
-   **`$push`**, (中文(简体) ), **`$pull`**, (中文(简体) ), **`$addToSet`** - 当所有值都是原子时 **分级** (弦,数字,布尔斯). 对象或数组值返回到读-修改-写入.

这些运算符可以自由组合成一个 `updateOne` 和整个更新将是原子。 这涵盖了最常见的模式:计数器,状态旗,时间戳,字段清理,以及向/从数组中添加/删除项目.

**以下操作不能保证为原子** 并使用读取-修改-写入模式(文档被读取,更新在JavaScript中被应用,结果被回写) :

-   `updateOne` 与 **`$rename`** 或者说 **`upsert: true`**
-   `updateOne` 与 `$push`, (中文(简体) ), `$pull`,或 `$addToSet` 使用 **非薪级** 数值
-   **`updateMany`**, (中文(简体) ), **`findOneAndUpdate`**,以及 **`replaceOne`**

对于必须具有原子性质且以上未涵盖的操作,使用咨询锁定(`apos.lock`) 串行访问。 Aposrophe核心已经使用咨询锁定原子关系(例如, `apos.lock.lock` (见e/cn.4/sub.2/2000/l.31,附件).

## API 参考

-   [数据库和客户端](https://npmcn.com/package/%40apostrophecms/db-connect/docs/database.md) —— 说 `client.db(name)`,列出收藏,丢弃数据库
-   [收集方法](https://npmcn.com/package/%40apostrophecms/db-connect/docs/collections.md) – CRUD 操作,光标和批量写入
-   [查询运算符](https://npmcn.com/package/%40apostrophecms/db-connect/docs/queries.md) ——将文档与比较、逻辑、元素和阵列操作器过滤
-   [更新运算符](https://npmcn.com/package/%40apostrophecms/db-connect/docs/updates.md) - 修改文档使用 `$set`, (中文(简体) ), `$inc`, (中文(简体) ), `$push`和更多
-   [索引](https://npmcn.com/package/%40apostrophecms/db-connect/docs/indexes.md) ——创建和管理指数,包括数字和日期类型
-   [合计](https://npmcn.com/package/%40apostrophecms/db-connect/docs/aggregation.md) 管道阶段和组积器
-   [倾出并恢复](https://npmcn.com/package/%40apostrophecms/db-connect/docs/dump-restore.md) 用于备份和迁移的CLI工具和API方案

## 常见问题

### @apostrophecms/db-connect 是什么？

ApostropeCMS 数据库连接库和垃圾堆/存储工具

### 如何安装 @apostrophecms/db-connect？

在项目目录运行 npm install @apostrophecms/db-connect，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 apos-db-dump、apos-db-restore，可以用 npx apos-db-dump 直接运行。

### @apostrophecms/db-connect 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/apostrophecms\_\_db-connect 是否存在。

### @apostrophecms/db-connect 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @apostrophecms/db-connect 可以商用吗？

@apostrophecms/db-connect 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @apostrophecms/db-connect 的下载量有多少？

根据 npm 官方下载统计，@apostrophecms/db-connect 在 2026/10/07 – 2026/11/05 这 30 天内被下载 7,202 次，日均约 240 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @apostrophecms/db-connect 还在维护吗？

最新版本 1\.1\.0 发布于 2026/10/01（1 个月前）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2026/04/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。