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:

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

2. package.json dependencies:

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

Use Control File Name (`name`)

1. .control file requires line:

# sf-docs-embeddings.control
requires = 'rag-core'

2. SQL deploy file requires comments:

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

Real-World Example

Consider the sf-docs-embeddings module:

package.json (npm name for distribution):

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

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

# sf-docs-embeddings extension
comment = 'San Francisco documentation embeddings'
default_version = '0.0.1'
requires = 'rag-core'

pgpm.plan (control name for project):

%project=sf-docs-embeddings

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

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

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

# CORRECT
requires = 'rag-core'

Wrong: Using control name in pgpm install

# WRONG
pgpm install rag-core

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

Wrong: Using npm name in SQL requires

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