pgpm-module-naming

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PGPM Module Naming: npm Names vs Control File Names

PGPM模块命名：npm名称 vs 控制文件名

pgpm modules have two different identifiers that serve different purposes. Understanding when to use each is critical for correct dependency management.

pgpm模块有两种作用不同的标识符，了解各自的使用时机对正确进行依赖管理至关重要。

When to Apply

适用场景

Use this skill when:

Creating or editing
```
.control
```
files
Writing
```
-- requires:
```
statements in SQL deploy files
Running
```
pgpm install
```
commands
Referencing dependencies between modules
Publishing modules to npm

在以下场景中使用本指南：

创建或编辑
```
.control
```
文件
在SQL部署文件中编写
```
-- requires:
```
语句
运行
```
pgpm install
```
命令
引用模块之间的依赖
发布模块到npm

The Two Identifiers

两种标识符

Every pgpm module has two names:

每个pgpm模块都有两个名称：

1. npm Package Name (for distribution)

1. npm包名（用于分发）

Defined in

package.json

as the

name

field. Used for npm distribution and the

pgpm install

command.

Format:

@scope/package-name

(scoped) or

package-name

(unscoped)

Examples:

```
@sf-bot/rag-core
```
```
@san-francisco/sf-docs-embeddings
```
```
@pgpm/base32
```

在

package.json

的

name

字段中定义，用于npm分发和

pgpm install

命令。

格式：

@scope/package-name

（作用域格式）或

package-name

（无作用域格式）

示例：

```
@sf-bot/rag-core
```
```
@san-francisco/sf-docs-embeddings
```
```
@pgpm/base32
```

2. Control File Name / Extension Name (for PostgreSQL)

2. 控制文件名/扩展名称（用于PostgreSQL）

Defined by the

.control

filename and

%project=

pgpm.plan

. Used in PostgreSQL extension system and SQL dependency declarations.

Format:

module-name

(no scope, no @ symbol)

Examples:

```
rag-core
```
```
sf-docs-embeddings
```
```
pgpm-base32
```

由

.control

文件名和

pgpm.plan

中的

%project=

定义，用于PostgreSQL扩展系统和SQL依赖声明。

格式：

module-name

（无作用域，无@符号）

示例：

```
rag-core
```
```
sf-docs-embeddings
```
```
pgpm-base32
```

When to Use Each

各自的适用场景

Use npm Package Name (

@scope/name

)

使用npm包名（

@scope/name

）的场景

1. pgpm install command:

bash

pgpm install @sf-bot/rag-core @sf-bot/rag-functions @sf-bot/rag-indexes

2. package.json dependencies:

json

{
  "dependencies": {
    "@sf-bot/rag-core": "^0.0.3"
  }
}

1. pgpm install命令：

bash

pgpm install @sf-bot/rag-core @sf-bot/rag-functions @sf-bot/rag-indexes

2. package.json依赖：

json

{
  "dependencies": {
    "@sf-bot/rag-core": "^0.0.3"
  }
}

Use Control File Name (

name

)

使用控制文件名（

name

）的场景

1. .control file requires line:

undefined

1. .control文件的requires行：

undefined

sf-docs-embeddings.control

requires = 'rag-core'


**2. SQL deploy file requires comments:**
```sql
-- Deploy data/seed_collection to pg
-- requires: rag-core

3. pgpm.plan %project declaration:

%project=sf-docs-embeddings

4. Cross-package references in pgpm.plan:

data/seed [rag-core:schemas/rag/schema] 2026-01-25T00:00:00Z Author <author@example.com>

requires = 'rag-core'


**2. SQL部署文件的requires注释：**
```sql
-- Deploy data/seed_collection to pg
-- requires: rag-core

3. pgpm.plan的%project声明：

%project=sf-docs-embeddings

4. pgpm.plan中的跨包引用：

data/seed [rag-core:schemas/rag/schema] 2026-01-25T00:00:00Z Author <author@example.com>

Real-World Example

实际示例

Consider the

sf-docs-embeddings

module:

package.json (npm name for distribution):

json

{
  "name": "@san-francisco/sf-docs-embeddings",
  "version": "0.0.3"
}

sf-docs-embeddings.control (control name for PostgreSQL):

undefined

以

sf-docs-embeddings

模块为例：

package.json（用于分发的npm名称）：

json

{
  "name": "@san-francisco/sf-docs-embeddings",
  "version": "0.0.3"
}

sf-docs-embeddings.control（用于PostgreSQL的控制文件名）：

undefined

sf-docs-embeddings extension

comment = 'San Francisco documentation embeddings' default_version = '0.0.1' requires = 'rag-core'


**pgpm.plan** (control name for project):
```sh
%project=sf-docs-embeddings

deploy/data/seed_collection.sql (control name in requires):

sql

-- Deploy data/seed_collection to pg
-- requires: rag-core

comment = 'San Francisco documentation embeddings' default_version = '0.0.1' requires = 'rag-core'


**pgpm.plan**（用于项目的控制文件名）：
```sh
%project=sf-docs-embeddings

deploy/data/seed_collection.sql（requires语句中的控制文件名）：

sql

-- Deploy data/seed_collection to pg
-- requires: rag-core

The Mapping

映射关系

pgpm maintains an internal mapping between control names and npm names. When you run

pgpm install

, it:

Reads the
```
.control
```
file's
```
requires
```
list (control names)
Maps those to npm package names
Installs the npm packages

For example, if your

.control

has

requires = 'pgpm-base32'

, pgpm knows to install

@pgpm/base32

from npm.

pgpm会在内部维护控制文件名和npm名称之间的映射。当你运行

pgpm install

时，它会：

读取
```
.control
```
文件的
```
requires
```
列表（控制文件名）
将这些名称映射为npm包名
安装对应的npm包

例如，如果你的

.control

文件中有

requires = 'pgpm-base32'

，pgpm会自动识别需要从npm安装

@pgpm/base32

。

Common Mistakes

常见错误

Wrong: Using npm name in .control file

错误：在.control文件中使用npm名称

undefined

undefined

WRONG

错误写法

requires = '@sf-bot/rag-core'

CORRECT

正确写法

requires = 'rag-core'

undefined

requires = 'rag-core'

undefined

Wrong: Using control name in pgpm install

错误：在pgpm install中使用控制文件名

bash

undefined

bash

undefined

WRONG

错误写法

pgpm install rag-core

CORRECT

正确写法

pgpm install @sf-bot/rag-core

undefined

pgpm install @sf-bot/rag-core

undefined

Wrong: Using npm name in SQL requires

错误：在SQL requires语句中使用npm名称

sql

-- WRONG
-- requires: @sf-bot/rag-core

-- CORRECT
-- requires: rag-core

sql

-- 错误写法
-- requires: @sf-bot/rag-core

-- 正确写法
-- requires: rag-core

Quick Reference Table

快速参考表

Context	Use	Example
`pgpm install`	npm name	`@sf-bot/rag-core`
`package.json` name	npm name	`@sf-bot/rag-core`
`package.json` dependencies	npm name	`@sf-bot/rag-core`
`.control` requires	control name	`rag-core`
SQL `-- requires:`	control name	`rag-core`
`pgpm.plan` %project	control name	`rag-core`
Cross-package deps	control name	`rag-core:schemas/rag`

场景	使用名称类型	示例
`pgpm install` 命令	npm名称	`@sf-bot/rag-core`
`package.json` 的name字段	npm名称	`@sf-bot/rag-core`
`package.json` 的dependencies字段	npm名称	`@sf-bot/rag-core`
`.control` 文件的requires字段	控制文件名	`rag-core`
SQL `-- requires:` 语句	控制文件名	`rag-core`
`pgpm.plan` 的%project声明	控制文件名	`rag-core`
跨包依赖	控制文件名	`rag-core:schemas/rag`

Summary

总结

npm names (
```
@scope/name
```
): Used for distribution and installation via npm/pgpm install
Control names (
```
name
```
): Used for PostgreSQL extension system, .control files, and SQL dependency declarations

Think of it this way: npm names are for the JavaScript/npm ecosystem, control names are for the PostgreSQL ecosystem.

npm名称（
```
@scope/name
```
）：用于通过npm/pgpm install进行分发和安装
控制文件名（
```
name
```
）：用于PostgreSQL扩展系统、.control文件和SQL依赖声明

可以这么理解：npm名称适用于JavaScript/npm生态，控制文件名适用于PostgreSQL生态。

References

参考

Related skill:
```
pgpm-cli
```
for CLI commands
Related skill:
```
pgpm-workspace
```
for workspace structure
Related skill:
```
pgpm-changes
```
for authoring database changes

相关技能：CLI命令相关的
```
pgpm-cli
```
相关技能：工作区结构相关的
```
pgpm-workspace
```
相关技能：数据库变更编写相关的
```
pgpm-changes
```

pgpm-module-naming

Original

Translation

PGPM Module Naming: npm Names vs Control File Names

PGPM模块命名：npm名称 vs 控制文件名

When to Apply

适用场景

The Two Identifiers

两种标识符

1. npm Package Name (for distribution)

1. npm包名（用于分发）

2. Control File Name / Extension Name (for PostgreSQL)

2. 控制文件名/扩展名称（用于PostgreSQL）

When to Use Each

各自的适用场景

Use npm Package Name (@scope/name)

使用npm包名（@scope/name）的场景

Use Control File Name (name)

使用控制文件名（name）的场景

sf-docs-embeddings.control

sf-docs-embeddings.control

Real-World Example

实际示例

sf-docs-embeddings extension

sf-docs-embeddings extension

The Mapping

映射关系

Common Mistakes

常见错误

Wrong: Using npm name in .control file

错误：在.control文件中使用npm名称

WRONG

错误写法

CORRECT

正确写法

Wrong: Using control name in pgpm install

错误：在pgpm install中使用控制文件名

WRONG

错误写法

CORRECT

正确写法

Wrong: Using npm name in SQL requires

错误：在SQL requires语句中使用npm名称

Quick Reference Table

快速参考表

Summary

总结

References

参考

Use npm Package Name (
`@scope/name`
)

使用npm包名（
`@scope/name`
）的场景

Use Control File Name (
`name`
)

使用控制文件名（
`name`
）的场景