tetris-sql
Tetris-SQL is a demonstration of Turing completeness in PostgreSQL, implementing a fully functional Tetris game using only SQL queries with recursive CTEs. It requires PostgreSQL 10+, Python 3 with psycopg2, and a compatible terminal for rendering.
Key facts
Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.
| Field | Value |
|---|---|
| Repository | nuno-faria/tetris-sql |
| Owner | nuno-faria |
| Primary language | PLpgSQL |
| License | MIT — OSI-approved |
| Stars | 1k |
| Forks | 43 |
| Open issues | 1 |
| Latest release | Unknown |
| Last updated | 2025-10-26 |
| Source | https://github.com/nuno-faria/tetris-sql |
What tetris-sql is
The implementation uses recursive Common Table Expressions (CTEs) to implement a game loop, RAISE NOTICE for rendering output, and the dblink extension to read fresh input snapshots during query execution. Game state and logic are maintained entirely within SQL, with a Python helper script converting terminal input into database writes.
Get the tetris-sql source
Clone the repository and explore it locally.
git clone https://github.com/nuno-faria/tetris-sql.gitcd tetris-sql# follow the project's README for install & configurationNeed it deployed, integrated, or customized instead? DEV.co ships production installs.
Best use cases
Implementation considerations
- Requires PostgreSQL 10+ with dblink extension enabled; tested on versions 10 through 18.
- Python 3 with psycopg2 is mandatory for the input handler; Docker Compose setup is recommended for isolated environment management.
- Terminal compatibility is critical; Windows Terminal ≥v1.22, GNOME Terminal, iTerm2, and macOS Terminal are documented as tested, but other terminals may exhibit rendering flicker.
- Initial query execution includes JIT compilation overhead in PostgreSQL; disabling JIT (`SET jit = off`) may improve perceived responsiveness but is not recommended for production workloads.
- The game loop depends on polling the input table via dblink with a synthetic counter appended to bypass query result caching; this is a workaround specific to PostgreSQL's snapshot isolation.
When to avoid it — and what to weigh
- Production game or interactive application — This is not suitable for any production use case. SQL is not designed for general-purpose programming, and game performance will be severely limited by database round-trips and query overhead.
- Real-time or high-performance requirements — The rendering relies on RAISE NOTICE output and dblink polling, introducing latency and rendering artifacts. Initial JIT compilation adds significant startup delay.
- Scenarios requiring modern game development tools — If you need a functional Tetris game, use established game engines (Unity, Godot) or JavaScript libraries. This project explicitly trades practicality for demonstrating SQL's theoretical capabilities.
- Systems without direct PostgreSQL access or without Python support — The implementation requires both a PostgreSQL server (versions 10–18) and Python 3 with psycopg2, plus dblink extension enabled, creating a specific operational footprint.
License & commercial use
MIT License. Permits unrestricted use, modification, and distribution in both open-source and proprietary contexts, provided the license and copyright notice are included.
The MIT License permits commercial use without restriction. However, this is a demonstration project explicitly unsuitable for production use; commercial interest should focus on the educational or reference value, not operational deployment of the game itself.
DEV.co evaluation signals
Editorial assessment — not user reviews. Directional, with an explicit confidence level.
| Signal | Assessment |
|---|---|
| Maintenance | Active |
| Documentation | Strong |
| License clarity | Clear |
| Deployment complexity | Moderate |
| DEV.co fit | Possible |
| Assessment confidence | High |
dblink connections to the local database use default credentials specified on the command line, creating potential exposure if credentials appear in process lists. The input table mechanism assumes only the input.py script writes to it; unauthorized writes could alter game state. SQL injection is not a concern in the game context, but the reliance on string interpolation in dblink queries (`'--' || i`) should be reviewed if adapted to other use cases. No encryption or authentication layer is described.
Alternatives to consider
JavaScript/Canvas Tetris implementations
Vastly more practical for actual gameplay. Numerous open-source examples exist (e.g., GitHub search for 'tetris-js'), with proper input handling, rendering performance, and no database dependency.
PostgreSQL procedural language (PL/pgSQL) stored procedures
Better suited than recursive CTEs for complex game logic, offering imperative control flow, easier debugging, and more idiomatic database programming; dblink polling would still be required for input.
Other Turing-completeness demonstrations (SQL 3D renderer, SQL ray tracer, SQL GPT implementations)
If the goal is to explore SQL's theoretical power, these projects (mentioned in the README) offer different application domains and may provide clearer insights depending on your learning objective.
Build on tetris-sql with DEV.co software developers
If you're considering tetris-sql for education, proof-of-concept work, or technical presentations, our engineering team can help you set up, customize, and integrate it into your development workflow. We specialize in PostgreSQL optimization and advanced SQL patterns.
Talk to DEV.coRelated on DEV.co
Explore the category and the services that help you build with it.
tetris-sql FAQ
Can I play this on any database (MySQL, SQLite, etc.)?
Why does the game take so long to start?
Is this suitable for learning real SQL optimization?
Can I modify the game rules or add features?
Work with a software development agency
From first prototype to production, DEV.co delivers software development services around tools like tetris-sql. Our software development agency staffs experienced software developers and web developers for custom software development, web development, integrations, and ongoing support across open-source databases and beyond.
Explore tetris-sql for your team
If you're considering tetris-sql for education, proof-of-concept work, or technical presentations, our engineering team can help you set up, customize, and integrate it into your development workflow. We specialize in PostgreSQL optimization and advanced SQL patterns.