my-workspace

Getting Started

This workspace was generated with pgpm init workspace. For a complete guide on developing with pgpm workspaces, see Workspaces: Organize Postgres.

Quick Start

# Install dependencies
pnpm install

# Start PostgreSQL (requires Docker) and load its connection variables.
# Already running your own PostgreSQL? Skip both lines and export
# PGHOST/PGPORT/PGUSER/PGPASSWORD for a superuser instead.
pgpm docker start
eval "$(pgpm env)"

# Create a module
pgpm init

# Navigate to your module and run tests
cd packages/your-module
pnpm test:watch

# Audit every module's schema (security + performance grades, see safegres.config.js)
pnpm run audit:db

Using your own PostgreSQL

pgpm docker start is a convenience, not a requirement. If PostgreSQL (17+) is already running on your machine, point pgpm at it and carry on — nothing else changes:

export PGHOST=localhost PGPORT=5432 PGUSER=postgres PGPASSWORD=yourpassword
pgpm admin-users bootstrap --yes   # once: creates the roles pgpm and tests expect

Don't run eval "$(pgpm env)" in that case: it prints the Docker container's defaults (postgres/password on localhost:5432) and would overwrite yours. If you want the Docker container alongside an existing server, give it another port and match it: pgpm docker start --port 5433 then export PGPORT=5433.

Install scripts

pnpm install never asks you to approve build scripts here: every dependency that wants to run code at install time already has a decision in pnpm-policy.yaml. If a new dependency stops the install with ERR_PNPM_IGNORED_BUILDS, add it there — under allowBuilds with a reason if it truly needs its script, or as false if it does not — and run pnpm run policy. Don't use pnpm approve-builds; it writes outside the managed block and pnpm run policy:check will fail.

Working with an AI agent

pgpm init workspace installed the pgpm skill at .agents/skills/pgpm/ — a guide to pgpm's commands, the deploy/revert/verify pattern, plan files, dependencies, testing, and CI. Agents that read .agents/skills/ (Codex, Cursor, Gemini CLI, opencode, ...) pick it up automatically; see AGENTS.md.

For an agent that looks elsewhere — Claude Code reads .claude/skills/ — either point it at .agents/skills/pgpm/SKILL.md directly, or install the skill into the location it expects:

npx skills add https://github.com/constructive-io/constructive --skill pgpm

Prerequisites

• Node.js 22+
• pnpm
• Docker, or a local PostgreSQL 17+ you have superuser credentials for
• PostgreSQL client tools (psql)
• pgpm (npm install -g pgpm)

See Prerequisites for detailed setup instructions.

Credits

🛠 Built by the Constructive team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on GitHub.

Disclaimer

AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.

No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.