Installation & Setup

To run Tetris-SQL, you need two primary components running simultaneously: a PostgreSQL database to execute the game engine, and a Python environment to capture your keyboard inputs and send them to the database.

This guide covers everything you need to know to set up the environment, whether you prefer using Docker (recommended for a clean, isolated setup) or a local native installation.

System Prerequisites

Before you begin, ensure your system meets the following requirements:

  • PostgreSQL: Tested and confirmed working on versions 10 through 18. The database must support the dblink extension (included in standard Postgres distributions) and unlogged tables.
  • Python 3: Required for the input.py script which listens for keystrokes.
  • psycopg2: The standard PostgreSQL database adapter for Python.

Terminal Emulator Recommendations

Because Tetris-SQL renders the game by spamming the terminal with RAISE NOTICE outputs separated by newlines, the speed and buffering capabilities of your terminal emulator matter significantly. A slow terminal will result in visible flickering.

Tested & Recommended Terminals:

  • Windows Terminal (>= v1.22): Highly recommended for Windows users. Previous versions have known buffering issues that cause severe flickering.
  • Windows CMD: Surprisingly efficient at text rendering.
  • GNOME Terminal: Tested on Ubuntu 24.04; works flawlessly.
  • iTerm2 (MacOS): Excellent performance.
  • Terminal (MacOS): Standard Apple terminal works well.

Using Docker isolates the PostgreSQL environment and ensures you don't need to mess with your local database configurations or install extensions globally.

Step 1: Start the PostgreSQL Container

Pull and run the official PostgreSQL 18 image. We expose port 5432 so our local Python script can communicate with it (if we run Python locally), and set a default password.

docker run --name pg -p 5432:5432 -d -e POSTGRES_PASSWORD=postgres postgres:18

Step 2: Install Python Dependencies Inside the Container

To keep everything self-contained, we can install Python and psycopg2 directly inside the running pg container.

docker exec pg apt update
docker exec pg apt install -y python3-psycopg2
(Note: We use python3-psycopg2 from the apt repository because compiling psycopg2 via pip inside the minimal Postgres container requires installing build tools and libpq-dev, which is slower.)

Step 3: Copy the Project Files

Clone the repository and copy it into the container's file system, making sure the input script is executable.

git clone https://github.com/nuno-faria/tetris-sql
docker cp tetris-sql pg:tetris-sql
docker exec pg chmod +x ./tetris-sql/input.py

You are now ready to play! Head over to the Quick Start guide.

Method 2: Local Native Installation

If you are a database developer and already have a local instance of PostgreSQL running, you can easily run Tetris-SQL natively.

Step 1: Clone the Repository

git clone https://github.com/nuno-faria/tetris-sql
cd tetris-sql

Step 2: Install Python Dependencies

Ensure you have Python 3 installed, then install the psycopg2-binary package. (Using the binary version avoids the need for local C compilers).

pip install psycopg2-binary

Step 3: Database User Permissions

Ensure the PostgreSQL user you plan to use has the following permissions:

  1. Ability to create tables (specifically UNLOGGED tables).
  2. Ability to use/create the dblink extension.

By default, the postgres superuser has all necessary permissions. If you are using a restricted user, you may need to grant these explicitly.

Step 4: Verify the Connection

You can verify your local Python setup can reach the database by running the help command on the input script:

python3 input.py --help

If the script runs and displays the help menu, your local setup is ready. Proceed to the Quick Start guide.