Tetris-SQL: The Ultimate Database Game

Welcome to the official documentation for Tetris-SQL, a complete, playable implementation of the classic arcade game Tetris written entirely within a single PostgreSQL query.

Far from being just a novelty, Tetris-SQL serves as a profound technical exploration of SQL's Turing completeness, transaction isolation levels, and execution optimizers. It demonstrates how modern relational databases can be pushed to execute complex, real-time algorithms that they were never explicitly designed to handle.

Why Tetris in SQL?

SQL is traditionally a declarative language used for querying and modifying datasets. You describe what you want, and the database engine figures out how to get it. However, with the introduction of recursive Common Table Expressions (CTEs) in the SQL:1999 standard, SQL became a Turing-complete language. This means that, theoretically, any algorithm can be computed using SQL.

Tetris-SQL takes this theory and applies it to a real-time, interactive environment. It answers the question: Can a database engine run a 60 FPS video game loop with asynchronous user input, collision detection, and terminal rendering? The answer is a resounding yes.

Core Features & Mechanics

Tetris-SQL isn't a stripped-down version of the game; it is a feature-rich implementation that respects classic mechanics:

  • 100% SQL Game Loop: The core logic—gravity, lateral movement, rotation, line clearing, and scoring—executes inside a massive WITH RECURSIVE query.
  • Asynchronous Input Handling: Uses the PostgreSQL dblink extension to bypass Snapshot Isolation, allowing the query to read real-time keystrokes from an external Python client.
  • NES-Style Randomizer: Features a biased random piece generator inspired by the original Nintendo Entertainment System (NES) Tetris, reducing the chance of repeated pieces.
  • Advanced Gameplay: Supports piece previews (the "Next" box), hard drops (Spacebar), and ghost pieces (a visual indicator of where the piece will land).
  • Dynamic Difficulty: Includes a progressive level system where gravity increases as you clear lines, complete with score multipliers.

Who Should Read This Documentation?

  • Database Administrators & Engineers: Learn advanced PostgreSQL concepts, including how the query optimizer works (and how to defeat the Memoize node), how transaction isolation affects long-running queries, and the memory implications of recursive CTEs.
  • Educators & Students: Use this project as a fascinating case study in Turing completeness and the limits of declarative programming languages.
  • Curious Developers: If you love weird hacks and pushing software beyond its intended limits, the Architecture & Implementation section is written for you.

PGConf.EU Presentation

The architectural breakthroughs and implementation details of this project were proudly presented at PGConf.EU 2025. You can view the presentation slides detailing the architecture here: PGConf.EU Slides.

Project Navigation

Ready to get started? Follow the documentation in order, or jump straight to the technical deep dives:

  1. Installation: Get your PostgreSQL environment and terminal ready.
  2. Quick Start: Launch the game and learn the controls.
  3. Configuration: Tweak gravity, board size, and framerates.
  4. Architecture: The Game Loop: Understand the recursive CTE that powers the engine.
  5. Architecture: Input Handling: Discover how we broke out of PostgreSQL's Snapshot Isolation.
  6. Architecture: Game State: Learn how the board and collisions are calculated using 1D boolean arrays.
  7. Resource Usage: Explore the memory leaks and limitations of this approach.