pgpm-module-naming

Original：🇺🇸 English

Translated

Understand when to use npm package names vs control file names in pgpm modules. Use when creating .control files, writing SQL requires statements, running pgpm install, or referencing dependencies between modules.

1installs

Sourceconstructive-io/constructive-skills

Added on2026-02-28

NPX Install

npx skill4agent add constructive-io/constructive-skills pgpm-module-naming

SKILL.md Content

View Translation Comparison →

PGPM Module Naming: npm Names vs Control File Names

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

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

The Two Identifiers

Every pgpm module has two names:

1. npm Package Name (for distribution)

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
```

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

Defined by the

.control

filename and

%project=

in

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
```

When to Use Each

Use npm Package Name (

@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"
  }
}

Use Control File Name (

name

)

1. .control file requires line:

sh

# 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:

sh

%project=sf-docs-embeddings

4. Cross-package references in pgpm.plan:

sh

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):

sh

# 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

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.

Common Mistakes

Wrong: Using npm name in .control file

sh

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

# CORRECT
requires = 'rag-core'

Wrong: Using control name in pgpm install

bash

# WRONG
pgpm install rag-core

# CORRECT
pgpm install @sf-bot/rag-core

Wrong: Using npm name in SQL requires

sql

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

-- CORRECT
-- 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`

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.

References

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

pgpm-module-naming

NPX Install

Tags

SKILL.md Content

PGPM Module Naming: npm Names vs Control File Names

When to Apply

The Two Identifiers

1. npm Package Name (for distribution)

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

When to Use Each

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

Use Control File Name (
`name`
)

Real-World Example

The Mapping

Common Mistakes

Wrong: Using npm name in .control file

Wrong: Using control name in pgpm install

Wrong: Using npm name in SQL requires

Quick Reference Table

Summary

References

pgpm-module-naming

NPX Install

Tags

SKILL.md Content

PGPM Module Naming: npm Names vs Control File Names

When to Apply

The Two Identifiers

1. npm Package Name (for distribution)

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

When to Use Each

Use npm Package Name (@scope/name)

Use Control File Name (name)

Real-World Example

The Mapping

Common Mistakes

Wrong: Using npm name in .control file

Wrong: Using control name in pgpm install

Wrong: Using npm name in SQL requires

Quick Reference Table

Summary

References

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

Use Control File Name (
`name`
)