Skip to content
Eric Hanson edited this page Dec 4, 2024 · 3 revisions

Code Style

  • Lowercase SQL (e.g. select count(*) from foo)
  • Spaces (4) not tabs
  • textwidth = 100
  • No fancy indenting and caps like pgddl (yet)

Error Handling

  • Use raise exception, not assert. Using assert would be nice, but "ASSERT is meant for detecting program bugs, not for reporting ordinary error conditions", and can be disabled via plpgsql.check_asserts.
  • Whe possible, use a begin ... exceptions block to catch and re-raise exceptions, instead of checking for things that constraints already enforce, for much speed.

Relations

  • Singular names
  • Lowercase
  • Underscores

Functions

  • Use plural names for set-returning functions.
  • "public" functions (ones the user might call from the psql prompt or their code) typically take human-readable text arguments, e.g. repository name instead of repository id.
select get_tracked_rows('io.my_repo');
  • "private" functions begin with a underscore, and typically take ids where applicable.
select _get_tracked_rows('01939312-8f21-7243-8bc8-e6b0e9352cf9');
  • "public" functions do error checking for things like repository existence, and meaningful error messages. "private" functions just blow up.
  • Functions should start with the action being taken, e.g. create_repository() instead of repository_create().
  • Functions that fetch values and don't change state should start with:
    • _get_loot() for functions that return vars and setof
    • _is_funkty() for booleans
  • Macro-ops (e.g. stage_tracked_rows(), track_untracked_rows() don't do all the sanity and error checking that single-op functions do, because they rely on internal logic that is expected to be consistent. Speeds.
  • Prefer returns setof to returns table, setof is inlinable where table is not?
  • Type signatures look like this:
create or replace function foo( x int, y int, z decimal ) returns x as $$
$$ language plpgsql;
  • When arguments collide with column names (e.g. repository_id), prefix the argument with a underscore (e.g. _repository_id)

File Structure

  • Core .sql source is in the root
  • Tests are in ./test
    • test/unit is for coverage of every function
    • test/shakespeare is for performance testing

Clone this wiki locally