Instruction file imported from vibhorkum/column_encrypt (.github/instructions/*.instructions.md). Copyright stays with the author.

GitHub Copilot Instructions for column_encrypt

This repository is a PostgreSQL extension that implements transparent column-level encryption using C and SQL/PGXS. Treat it as security- sensitive systems code. Prefer correctness, safety, backward-compatible extension behavior, and testability over cleverness.

Project context

• Main extension code lives in column_encrypt.c.
• SQL extension objects and upgrade scripts live in:
  • column_encrypt--1.0.sql
  • column_encrypt--2.0.sql
  • column_encrypt--1.0--2.0.sql
• Build uses PGXS and the repository Makefile.
• The extension relies on PostgreSQL internals, custom types, GUCs, hooks, memory contexts, and pgcrypto.
• This project handles key material, ciphertext, decrypted values, log masking, and key version metadata. Be conservative.

General coding expectations

• Follow PostgreSQL extension conventions and core PostgreSQL coding style where practical.
• Do not introduce unnecessary abstractions or C++-style patterns.
• Keep patches small, reviewable, and easy to reason about.
• Prefer explicit code over magic.
• Preserve extension upgradeability and SQL install/upgrade semantics.
• Do not break on-disk format, SQL signatures, type I/O behavior, or upgrade scripts unless the task explicitly requires it.
• Avoid speculative refactors in security-sensitive code paths.

Security-first rules

• Never log plaintext keys, passphrases, decrypted values, raw key buffers, or secrets.
• Preserve and improve masking behavior for logs, errors, and diagnostics.
• Zero sensitive memory before release when practical and safe.
• Be careful with palloc, memory contexts, buffer ownership, and lifetimes of secret data.
• Do not copy key material more than necessary.
• Validate all lengths, headers, pointers, varlena handling, and binary parsing carefully.
• Fail closed on malformed ciphertext, invalid key state, unsupported algorithm choices, and version mismatches.
• Avoid insecure fallback behavior.
• Do not weaken RLS, key access restrictions, or superuser protections.
• Call out any cryptographic or secret-handling concern in PR summaries.

PostgreSQL extension rules

• Use PostgreSQL server APIs and idioms rather than generic libc replacements when PostgreSQL provides the correct facility.
• Ensure code compiles cleanly as a PostgreSQL extension, not as a standalone C project.
• Respect PGXS build patterns.
• Maintain compatibility only with supported PostgreSQL versions for this repository. Do not add compatibility hacks for end-of-life PostgreSQL releases.
• When changing SQL objects, make corresponding updates to install and upgrade scripts.
• Keep object names, types, operators, casts, and GUC names consistent.

SQL and migration rules

• Any user-visible SQL object change must be reflected in the appropriate extension SQL files and upgrade paths.
• Never edit an already-released install script in a way that breaks existing upgrade semantics unless explicitly requested.
• Prefer additive upgrade scripts for new functionality.
• Verify extension creation, upgrade, and regression behavior after SQL changes.
• For SQL style:
  • Use lowercase snake_case identifiers.
  • SQL keywords should be capitalized.
  • Prefer named parameters where applicable.
  • Keep comments concise and readable.

Error handling and diagnostics

• Use PostgreSQL error reporting idioms (ereport, errmsg, errdetail, errhint) appropriately.
• Error messages must be actionable but must not leak secrets.
• Be precise about privilege, configuration, malformed input, and key state failures.
• Prefer deterministic behavior over ambiguous recovery.

Performance expectations

• Avoid unnecessary encryption/decryption work, extra copies, repeated lookups, and repeated parsing in hot paths.
• Keep type input/output functions lean.
• Be mindful of memory allocations in frequently executed code.
• Optimize only after preserving correctness and security.

Testing expectations

When making changes, always look for the smallest realistic way to test them.

• Add or update regression tests for:
  • extension create/upgrade
  • encrypted type input/output behavior
  • NULL handling
  • malformed ciphertext/header cases
  • key loading/unloading behavior
  • GUC behavior
  • log masking-sensitive flows when testable
  • versioned ciphertext and upgrade compatibility
• Prefer deterministic tests.
• Do not propose changes without explaining how they should be tested.

Copilot behavior for code generation

When asked to implement or fix something:

1. First inspect relevant C, SQL, control, and Makefile files.
2. Explain assumptions briefly.
3. Propose the minimal safe patch.
4. Include any required SQL migration/upgrade changes.
5. Mention regression tests that should be added or updated.
6. Flag backward-compatibility or security risks explicitly.

Copilot behavior for code review

During reviews, pay special attention to:

• secret leakage in logs, errors, or memory
• misuse of PostgreSQL varlena / Datum / text / bytea APIs
• unsafe casts, unchecked lengths, and buffer handling
• broken upgrade scripts or extension versioning
• privilege boundary issues
• behavior changes in encrypted type I/O
• accidental ABI/API drift in SQL-visible functions
• unsupported PostgreSQL-version compatibility code
• missing tests

What to avoid

• Do not suggest storing plaintext keys in tables, files, logs, or static globals.
• Do not suggest bypassing masking because it is “just for debugging.”
• Do not replace PostgreSQL error/reporting/memory idioms with generic patterns unless clearly better and safe.
• Do not introduce large refactors unrelated to the task.
• Do not assume cryptographic changes are safe without careful review.
• Do not silently change install/upgrade behavior.

Contribution attribution

When generating pull requests, review comments, commit messages, documentation updates, or code suggestions for this repository:

• Do NOT present the comment as coming from "GitHub Copilot".
• Do NOT include phrases such as:
  • "Generated by Copilot"
  • "Copilot suggests"
  • "AI generated"
  • "This change was produced by Copilot"

All comments, commit messages, and pull request descriptions should be written as if they are authored by the maintainer.

Use the following attribution style when needed:

Author: Vibhor Kumar

The writing style should reflect a PostgreSQL extension maintainer: clear, direct, technically precise, and focused on correctness.

Example commit message format:

Title: Fix memory handling and improve ciphertext validation

Description: This patch improves validation of encrypted payload headers and fixes a memory handling issue when processing malformed ciphertext. Additional length checks were added to prevent invalid varlena access.

Signed-off-by: Vibhor Kumar

Example PR description ending:

Maintainer: Vibhor Kumar