mcpField
F
faasjs-pg

faasjs-pg

github.com/faasjsData & databases120187 installsUpdated 10w ago
Repository

About faasjs-pg

faasjs-pg is a skill for working with PostgreSQL in FaasJS projects. It guides typed queries, schema migrations, transactions, and database testing.

Key features

  1. 01Typed QueryBuilder guidance
  2. 02Schema and migration practices
  3. 03Transaction and locking guidance
  4. 04Numeric type boundary guidance
  5. 05PostgreSQL testing practices

Use cases

  1. 01Designing typed PostgreSQL queries
  2. 02Planning reversible schema migrations
  3. 03Testing transaction and locking behavior

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/faasjs/faasjs --skill faasjs-pg

After installing, type/faasjs-pgin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/guidelines/
pg-numeric-boundaries.md
pg-query-builder.md
pg-schema-and-migrations.md
pg-table-types.md
pg-testing.md
pg-transactions-and-locking.md

Details

From the project README

FaasJS PostgreSQL

Default Workflow

  1. Keep table declarations, migrations, queries, and tests aligned.
  2. Prefer typed QueryBuilder clauses before raw SQL.
  3. Parameterize raw SQL values and keep trusted boundaries explicit.
  4. Keep migrations deterministic, lexically sortable, and reversible where possible.
  5. Pair runtime database assertions with type assertions when query inference is part of the behavior.
  6. Use explicit transactions and concurrency tests when atomicity or row locking matters.

Load These References

  • Declaration merging on Tables and concrete row shapes: references/guidelines/pg-table-types.md.
  • QueryBuilder, aliases, raw SQL, update expressions, returning, and edge semantics: references/guidelines/pg-query-builder.md.
  • Transaction modes, transaction client lifetime, row locks, retry ownership, and concurrency tests: references/guidelines/pg-transactions-and-locking.md.
  • Exact numeric, decimal, and bigint values across TypeScript and API boundaries: references/guidelines/pg-numeric-boundaries.md.
  • Timestamped migrations, SchemaBuilder, TableBuilder, and schema execution: references/guidelines/pg-schema-and-migrations.md.
  • PgVitestPlugin(), shared migration snapshots, per-file database isolation, DATABASE_URL, and expectTypeOf(...): references/guidelines/pg-testing.md.

Gotchas

  • Treat Tables declarations as the source of truth for query inference.
  • Use raw SQL deliberately; move repeated raw SQL back toward shared helpers or builder clauses.
  • Keep write queries and transactions guarded by caller scope and expected failure handling; never let a transaction client escape its callback.
  • Let PgVitestPlugin() own the lazy global setup: it migrates one run-scoped snapshot and gives every database-using test file an isolated clone.
  • When a transaction also calls enqueueJob, load FaasJS API And Jobs and test rollback of both business data and the job row.
  • DATABASE_URL is required for migration and PG integration test commands.

Validation

  • Run npx faasjs-pg migrate when schema changes need migration verification and DATABASE_URL is available.
  • Run focused PG tests with vp test <pattern>.
  • Include expectTypeOf(...) when changing type-sensitive query behavior.
  • Use overlapping real transactions for lock or concurrency behavior; generated SQL assertions alone are insufficient.

Comments

Markdown supported