Contributing to Postgres by Example

June 11, 2026 · View on GitHub

Thank you for your interest in contributing! This project is a beginner-friendly PostgreSQL tutorial. Here's how you can help.

How to Contribute

  1. Fork the repository on GitHub.
  2. Create a branch for your changes: git checkout -b my-improvement
  3. Make your changes following the guidelines below.
  4. Submit a pull request with a clear description of what you changed.

Contribution Guidelines

Lesson Content

  • Keep the tone friendly and direct. Beginners should not get lost; experienced readers should not be talked down to.
  • Each lesson should include:
    • Intro paragraph(s) — what this concept is for, when to reach for it, how it relates to nearby ones.
    • What you'll learn — 3 to 5 bullet points stating the takeaways.
    • Runnable SQL example — a single code block that exercises the concept end-to-end. Match the .sql file in source/.
    • Walkthrough prose — 1 to 3 paragraphs explaining the key parts of the example and the reasoning behind them.
    • To run — the psql -f source/lesson.sql postgres command and a sample of the expected output.
    • Common pitfalls — bullet list of the bugs and surprises real users hit. This is where pro experience shows.
    • Tip — one concise practical pointer most users do not know.
    • Try it — one or two small variations the reader can type and observe.
    • Source / Next / Home footer links.
  • Ensure SQL examples run correctly against current stable PostgreSQL (lessons target PG 17 unless stated).
  • When introducing a topic, note the minimum PostgreSQL version that supports it if it was introduced in the last few releases.

Source Code

  • Source files live in source/. Each lesson links to its corresponding .sql file.
  • Use a -example suffix for filenames when the topic is a reserved word or common identifier (e.g. user-table-example.sql).
  • Keep examples minimal and focused on the lesson topic.

Markdown Format

  • Use standard Markdown. Code blocks with sql or bash language tags.
  • Links to other lessons use relative paths: (next-topic.md) within lessons/, (../source/script.sql) for source files.
  • The last lesson in each section links to the next; the final lesson links back: [Table of Contents](../README.md).

Running Examples

  • All run commands assume execution from the repository root: psql -f source/script.sql (or psql -f source/script.sql postgres if you need to specify the database).
  • Examples assume a running PostgreSQL server; default database is postgres unless stated. You can set PGDATABASE or pass the database name to psql if you use a different one.
  • Verify that examples produce the documented output before submitting.

Repository Structure

postgres-by-example/
├── README.md          # Table of contents and intro
├── CONTRIBUTING.md    # This file
├── LICENSE            # CC BY 4.0
├── lessons/           # Lesson markdown files
└── source/            # SQL example scripts

License

By contributing, you agree that your contributions will be licensed under the same Creative Commons Attribution 4.0 International (CC BY 4.0) license that covers this project.

Questions?

Open an issue on GitHub for questions or suggestions.