🚀 Ruby PostgreSQL Performance Workshop

Welcome to an interactive journey into PostgreSQL optimization for Rubyists! This self-paced workshop will take you from understanding PostgreSQL internals to mastering TimescaleDB for time-series data. Get ready to level up your database skills! 🎯

📚 Workshop Structure

This workshop is organized into progressive modules, each building upon the previous ones:

graph TD
    A[PostgreSQL Internals] -->|"See: 01_storage/README.md"| B[Transaction Management]
    B -->|"See: 02_transactions/README.md"| C[Query Optimization]
    C -->|"See: 03_queries/README.md"| D[TimescaleDB Extension]
    D -->|"See: 04_timescale/README.md"| E[Ruby Performance]
    E -->|"See: 05_ruby/README.md"| F[Performance Monitoring]

Loading

The troubleshooting section is optional and can be accessed at any time.

The glossary is also optional and can be accessed at any time.

🎯 Prerequisites

knowledge = {
  ruby: "Comfortable with Ruby and ActiveRecord",
  postgres: "Basic SQL knowledge",
  tools: ["psql", "ruby 3.0+", "postgres 15+"]
}

raise "Need to level up first! 💪" unless knowledge.values.all?(&:present?)

🛠 Setup

1. Clone this repository:

git clone https://github.com/timescale/postgresql-performance-for-rubyists
cd postgresql-performance-for-rubyists

2. Set up your database:

You can use Docker to setup a TimescaleDB database:

docker run -d --rm -it -e POSTGRES_HOST_AUTH_METHOD=trust -e POSTGRES_USER=$USER -e POSTGRES_DATABASE=workshop_db -p 5432:5432 timescale/timescaledb-ha:pg17

Then test if it's working:

psql -h 0.0.0.0 -d workshop_db

After the test you can export the database URI that will be used for all exercises.

# In your terminal
export DATABASE_URL="postgres://${USER}@0.0.0.0:5432/workshop_db"

3. Verify your setup running the first example:

ruby examples/01_storage/practice_storage.rb
# If you see table creation outputs, you're good to go! 🎉

📖 Core Concepts

Before diving into specific modules, familiarize yourself with these fundamental concepts:

1. PostgreSQL Architecture

• Process & Memory Structure
• Storage Layout
• Buffer Management

2. Data Consistency

• Transaction Management
• Concurrency Control
• ACID Properties

3. Performance Foundations

• Query Planning
• Index Types
• Statistics Collection

For detailed definitions of terms used throughout the workshop, refer to our Glossary.

📚 Learning Path

1. PostgreSQL Internals

Learn how PostgreSQL physically stores and manages data:

• Storage layout and TOAST
• WAL mechanics
• Buffer management
• Table structure optimization

2. Transaction Management

Master concurrency control and transaction isolation:

• ACID properties in practice
• Isolation levels
• Deadlock handling
• Transaction patterns

3. Query Optimization

Optimize query performance:

• Query planning and execution
• Index selection and usage
• Join optimization
• Performance monitoring

4. TimescaleDB Extension

Handle time-series data efficiently:

• Hypertables and chunks
• Continuous aggregates
• Data retention policies
• Compression strategies

5. Ruby Performance

Optimize Ruby and ActiveRecord usage:

• Batch processing
• Memory management
• Query optimization
• Connection pooling

🎮 Interactive Learning

Experiment Freely

def learning_approach
  loop do
    try_something_new
    break if it_works?
    learn_from_failure
  end
end

🤝 Contributing

Found a bug? Have an improvement idea? Want to add more examples? We love contributions!

module Contributor
  extend Enthusiasm
  
  def self.how_to_help
    [
      "🐛 Report bugs",
      "✨ Add new examples",
      "📚 Improve documentation",
      "🎨 Share your creative solutions"
    ]
  end
end

📘 Additional Resources

• PostgreSQL Documentation
• TimescaleDB Documentation
• Ruby on Rails Active Record Query Interface
• Workshop Troubleshooting Guide - For common issues, solutions, and performance comparisons

About this Workshop

This workshop is given at the following conferences:

• Ruby Community Conference 2025
• Tropical On Rails 2025

If you're interested in running this workshop for your conference or meetup, please contact me.

Happy learning! 🚀✨