# @cap-js/postgres 中文文档

规范地址：https://npmcn.com/package/%40cap-js/postgres/

版本：3\.1\.2
npm 元数据更新时间：2026-10-12T09:07:25.413Z
中文译文更新时间：2026-11-09T03:14:03.228Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cap-js/postgres
原文对照：https://npmcn.com/package/%40cap-js/postgres/?lang=original
项目主页：https://github.com/cap-js/cds-dbs/tree/main/postgres#cds-database-service-for-postgres
源码仓库：https://github.com/cap-js/cds-dbs

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

- 包体积（解压后）：86.7 kB，10 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：@sap/cds ^10，pgvector ^0\.3\.0，@sap/cds-dk ^10
- 首次发布：2023-06-23T13:37:44.529Z
- 最新版本发布：2026-10-12T09:07:25.044Z
- 近 30 天下载量：56412（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：51（近 12 个月 16 个）

## 中文简介

Postgres 的 CDS 数据库服务

## 安装

```sh
npm install @cap-js/postgres
```

也可以使用：`pnpm add @cap-js/postgres`、`yarn add @cap-js/postgres`、`bun add @cap-js/postgres`

## README

# Postgres 的 CDS 数据库服务

欢迎使用 PostgreSQL 数据库服务 [SAP 云应用编程模型](https://cap.cloud.sap/) 以简化数据库架构和 [_页:1_ 驱动程序](https://www.npmjs.com/package/pg) 。 。 。 .

## 设置

一般来说,你只需要安装数据库软件包,如下所示:

```sh
npm add @cap-js/postgres
```

学习更多关于设置和使用 [各自的数据库指南](https://cap.cloud.sap/docs/guides/databases/postgres)。 。 。 .

## 支助

此项目可通过下列方式对特性请求/建议、错误报告等开放: [GitHub 问题](https://github.com/cap-js/cds-dbs/issues)。 。 。 .

## 捐款

鼓励并始终欢迎各方作出贡献和反馈。 关于如何作出贡献的更多信息,项目结构以及额外贡献信息见我们 [贡献准则](https://npmcn.com/package/%40cap-js/CONTRIBUTING.md)。 。 。 .

## 版本

这个图书馆跟随 [语义版本](https://semver.org/)。 。 。 . 所有显著变化均记录在 [变动情况](https://npmcn.com/package/%40cap-js/postgres/CHANGELOG.md)。 。 。 .

## 行为守则

作为成员、贡献者和领导人,我们保证使参加我们的社区成为每个人不受骚扰的经历。 通过参与这个项目,你同意遵守 [行为守则](https://npmcn.com/package/%40cap-js/CODE_OF_CONDUCT.md) 在任何时间.

## 许可证发放

版权2023 SAP SE或SAP下属公司和CDs-dbs撰稿人. 请看我们的 [自由主义](https://npmcn.com/package/%40cap-js/postgres/LICENSE) 版权和许可证信息。 详细信息,包括第三方组成部分及其许可证/版权信息 [通过REUSE工具](https://api.reuse.software/info/github.com/cap-js/cds-dbs)。 。 。 .

## 移徙指南 `cds-pg` 改为 `@cap-js/postgres`

`@cap-js/postgres` 用于替换 `cds-pg`。 。 。 .  
但是,一些初步检查和清理有助于:

-   用于使用 BTP Postgres 超缩放器作为数据库,
    -   知所取证自入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入出入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入`VCAP_SERVICES.postgres`(中文(简体) )
    -   服务绑定标签为 `postgresql-db`
    -   `cds-dbm` 替换为手工制作的"db-deploper"app → 见下文
-   您的本地语言 `package.json`: 您可以安全删除条目 `cds.requires.postgres` 以往的强制性 `cds-pg`
-   建议: 设置掩体 var `DEBUG=sql` 在本地开发时查看 PostgreSQL 的 DB 级输出

### 计划迁移

`@cap-js/postgres` 从SAP HANA和SQLite中得知的 PostgreSQL 带来了同样的计划进化能力.  
允许在现有情况下进行计划迁移 `cds-pg`\-基于项目包括生成和部署您数据库结构的"csn-snapshot".

#### 地方发展

首先,为演变奠定基础 `$> cds deploy --model-only`  
\- 这将创建表格 `cds_model` 为移徙计划奠定基础

随后的部署可通过 `$> cds deploy`

#### 在BTP上,云创始环境

以上"csn-snapshots"可通过下列程序执行: `mtar`\- 基础方法。 同时,同样 `mtar` 可用于之后的 PostgreSQL 部署(带有schema演化).

除了促进计划的演变之外,还有两个主要步骤 `mtar`。 。 。 .

1.  创建本地文件夹 `deployer` (任何名称的工作)
2.  内 `deployer`创建一个 `package.json` 包含

```json
...
"//npm run migrate": "only one-time!",
"migrate": "cds deploy --model-only",
"//npm run deploy": "subsequent deployments",
"deploy": "cds deploy"
...
```

3.  向您添加一节 `/mta.yaml` 标注 `deployer` 目录作为运行一次性的独立应用程序

```yaml
- name: pg-db-deployer
    type: custom
    path: deployer
    parameters:
      buildpacks: nodejs_buildpack
      no-route: true
      no-start: true
      disk-quota: 2GB
      memory: 512MB
      tasks:
      - name: migrate
        command: npm run migrate
      # # for subsequent deployments
      # - name: deploy
      #  command: npm run deploy
        disk-quota: 2GB
        memory: 512MB
    build-parameters:
      before-all:
        custom: 
        - npm i
        # generate the "csn-snapshot" - only necessary for one-time migration,
        # can be commented out on subsequent deployments
        - cds compile '*' -2 json > deployer/schema.csn
      ignore: ["node_modules/"]
    requires:
      - name: pg-database

resources:
  - name: pg-database
    parameters:
      path: ./pg-options.json
      service: postgresql-db
      service-plan: trial # change to yours!
      skip-service-updates:
        parameters: true
      service-tags:
        - plain
    type: org.cloudfoundry.managed-service
```

## 需要考虑的移民点

### 混合案件标识符

即使没有双引号的列名称在PostgreSQL中被折叠为小写(`yourName` - > (中文) `yourname`, (中文(简体) ), `"yourName"` - > (中文) `yourName`, (中文(简体) ),  
您可以使用您从您的 `.cds` 文档来引用它们.

示例: `brewery_id` 在 DB 级别 - > `brewery_ID` 在CDS级别

原为w/ `cds-pg` 您必须遵循 DB 级别 : `SELECT.from(Beers).columns('brewery_id').groupBy('brewery_id')`  
现在,重新使用CDS定义: `SELECT.from(Beers).columns('brewery_ID').groupBy('brewery_ID')`

所以,请调整你的 `CQL` 相应声明.

### 时区( 可能值) **破坏变化**(中文(简体) )

任何日期 - + 时间类型都将存储在 [`UTC`](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) **在实际数据字段中没有任何时区标识符**。 。 。 .  
CAP的出入境适配器负责将进出数据转换到理想的时区.  
所以当一个 `datetime` 进来了 [iSO 8601 标准](https://en.wikipedia.org/wiki/ISO_8601) 兼容格式  
`2009-01-01T15:00:00+01:00` 2009年1月1日15:00,维也纳(CEST)  
将被存储为  
`2009-01-01T13:00:00` (2009年1月1日13:00,协调世界时).

请注意这个概念, 并依靠客户端在您想要的时区( 格式) 解析 UTC .

### `cds.DatabaseService` 消费

`InsertResult` 现在只返回受影响的行及其 `ID`编号.

```js
const entries = [
  { name: 'Beer1', /* ... */ },
  { name: 'Beer2', /* ... */ },
  { name: 'Beer3', /* ... */ }
]
const insertResult = await cds.run(INSERT.into(Beers).entries(entries))
expect(insertResult.affectedRows).to.equal(3)
const beers = [...insertResult] //> this calls the [Symbol.iterator] method of the insert result
// beers:
// [ 
//   { ID: "f81d7ee5-922b-48a1-a12a-a899b8594c99" }, 
//   { ID: "ddda7f8e-e26b-430f-a80c-ac2c7df29510" },
//   { ID: "7228c40f-0046-4f53-8a2b-3d55ad825f59" }
// ]
```

单位 `cds-pg`,我们额外浮出整个插入的数据集.

```js
// continuing after the insert of the above example:
// const insertResult = await cds.run(INSERT.into(Beers).entries(entries))

// this works NO MORE - see above
const beers = insertResult.results
expect(beers.length).toStrictEqual(3)
expect(beers[0].ID).toMatch(uuidRegex)
expect(beers[0].createdAt.toISOString()).toMatch(timestampRegex)
expect(beers[0].modifiedAt.toISOString()).toMatch(timestampRegex)
```

请相应调整运行时间编码 .

## 常见问题

### @cap-js/postgres 是什么？

Postgres 的 CDS 数据库服务

### 如何安装 @cap-js/postgres？

在项目目录运行 npm install @cap-js/postgres，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@sap/cds（^10）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cap-js/postgres 支持 TypeScript 吗？

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

### @cap-js/postgres 支持 ESM 还是 CommonJS？

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

### @cap-js/postgres 可以商用吗？

@cap-js/postgres 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cap-js/postgres 的下载量有多少？

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

### @cap-js/postgres 还在维护吗？

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