Skip to content
No description, website, or topics provided.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Have you ever wanted to to play pokemon, but also cheat? Is the GameGenie interface a little bit too user friendly for you? Do you want to do inner joins on lists of Pokemon?

PostgresPlaysPokemon is for you!



cd ./server

The "server" in this case is a visual emulator that exposes a GRPC interface. It is written in Python, and requires pypy to run at a reasonable speed. You'll need the Python2 PyPy version pending resolution of this issue.

  1. Install pypy and SDL.
  2. Set up a virtualenv: virtualenv -p $(which pypy) venv
  3. Activate the virtualenv: . venv/bin/activate
  4. Install the requirements: pip install -r requirements.txt
  5. Run make to build the protobufs
  6. Launch the emulator: python

You'll also need a Pokemon Red ROM. Place it in [server/ROMs/][gb]



cd ./client/extension

The "client" is a postgres extension. You first need to compile it, then make Postgres aware of it, and then you can use it!

  1. Install rust and cargo
  2. Install Postgres. I test with Postgres 10; Other versions may or may not work.
  3. run make to build the extension
  4. run sudo make install to install all the required files where Postgres expects them.
  5. If you don't have one already, set up a postgres admin. On Linux at least, if you make a superuser matching your username and a database matching your username, you can just type psql.
  6. Get a psql shell. It doesn't matter what database you use, where we're going we don't need databases!
  7. CREATE EXTENSION pokemon;
  9. All done!
Table Cooresponds To Operations Supported
party Your (up to) six pokemon SELECT, UPDATE
inventory Items you're carryin SELECT, INSERT, UPDATE
story Critical story event triggers SELECT, UPDATE

Pokemon ID are not the same as pokemon numbers. Items are listed here. Keep in mind that by default, Postgres will insert decimal numbers, not hexidecimal.


cd ./client

There's also a CLI that performs much of the same actions as the Postgres API. cargo run -- --help should list all available operations. You'll need rust and cargo but not Postgres. But where's the fun in that?

How it Works

In the same process that's running the emulator, a GRPC server is listening for commands. Using PyBoy's API, the server looks manipulates the emulated Gameboy's memory.

Right now, that server is exposed over a unix socket which the database server can connect to.

The client uses Rust to translate SQL commands into GRPC, which connects


  • More story flags!
  • Tables for battles
  • Changing pokemon
  • Configurable connection between client and server (not just unix sockets)
  • Enums for pokemon and items instead of opaque constants
  • Maybe bazel for building?
You can’t perform that action at this time.