{
  "instruction": "Always apply PostgreSQL best practices by default: connection pooling with production settings, parameterized queries, type handling, error codes, and production hardening",
  "relevant_when": "Agent creates or modifies a Node.js application that uses or will use PostgreSQL",
  "context": "pg Pool should have max connections, timeouts, keepAlive, statement_timeout, SSL config, error handler, and graceful shutdown. Connection string from env. Queries must be parameterized. BIGINT/NUMERIC type coercion must be handled. Bulk inserts should use unnest. Error codes should be handled specifically.",
  "sources": [
    {
      "type": "file",
      "filename": "skills/postgresql-node-best-practices/SKILL.md",
      "tile": "tessl-labs/postgresql-node-best-practices@0.1.3"
    }
  ],
  "checklist": [
    {
      "name": "pool-used",
      "rule": "Agent creates a pg Pool (not individual Client instances) with max and timeout settings",
      "relevant_when": "Agent creates or modifies a Node.js application that connects to PostgreSQL"
    },
    {
      "name": "statement-timeout",
      "rule": "Agent configures statement_timeout on the pool to prevent runaway queries from holding connections indefinitely",
      "relevant_when": "Agent creates or modifies a Node.js application that connects to PostgreSQL"
    },
    {
      "name": "keepalive-enabled",
      "rule": "Agent enables keepAlive: true and sets keepAliveInitialDelayMillis to prevent cloud infrastructure from killing idle TCP connections",
      "relevant_when": "Agent creates or modifies a Node.js application that connects to PostgreSQL"
    },
    {
      "name": "ssl-configured",
      "rule": "Agent configures SSL for production environments and never sets rejectUnauthorized: false in production",
      "relevant_when": "Agent creates or modifies a Node.js application that connects to PostgreSQL"
    },
    {
      "name": "graceful-shutdown",
      "rule": "Agent calls pool.end() on SIGTERM/SIGINT to drain connections and allow clean process exit",
      "relevant_when": "Agent creates or modifies a Node.js application that connects to PostgreSQL"
    },
    {
      "name": "parameterized-queries",
      "rule": "Agent uses parameterized queries ($1, $2) not string interpolation for all dynamic values",
      "relevant_when": "Agent creates or modifies a Node.js application that queries PostgreSQL"
    },
    {
      "name": "any-for-array-params",
      "rule": "Agent uses ANY($1::type[]) with a single array parameter instead of dynamically building IN ($1, $2, $3...) placeholders",
      "relevant_when": "Agent writes a query that filters by a list or array of values in PostgreSQL"
    },
    {
      "name": "bigint-type-handling",
      "rule": "Agent configures pg.types.setTypeParser for BIGINT (OID 20) and/or NUMERIC (OID 1700) columns to avoid silent string coercion bugs",
      "relevant_when": "Agent creates or modifies a Node.js application that uses BIGINT or NUMERIC columns in PostgreSQL"
    },
    {
      "name": "bulk-inserts",
      "rule": "Agent uses unnest or multi-row VALUES for bulk inserts instead of inserting rows one at a time in a loop",
      "relevant_when": "Agent writes code that inserts multiple rows into PostgreSQL"
    },
    {
      "name": "error-code-handling",
      "rule": "Agent handles specific PostgreSQL error codes (e.g., 23505 unique_violation, 23503 foreign_key_violation) instead of catching errors generically",
      "relevant_when": "Agent writes database operations that could violate constraints in PostgreSQL"
    }
  ]
}