dbasim — learn to fix Oracle from real incidents

dbasim plants a "the database is broken" incident in Oracle Database Free on your own computer. A simulated app keeps using it the whole time. You find the cause, fix it, and dbasim checks whether your fix really worked.

⚠️ dbasim creates and drops users and tablespaces in the database it points at. Only use it with Oracle Free on your own machine. It refuses to run against anything that is not Free and never drops a SHOP user it did not create.

Requirements

• Docker (on Windows: Docker Desktop + WSL2)
• About 3GB free RAM and 10GB free disk
• Python 3.9 or newer

1. Start Oracle Database Free

docker run -d --name dbasim-oracle -p 1521:1521 \
  -e ORACLE_PWD=ChangeMe123 \
  container-registry.oracle.com/database/free:latest

docker logs -f dbasim-oracle   # wait for DATABASE IS READY TO USE!

Downloading and using Oracle Database Free is governed by the Oracle Free Use Terms and Conditions, between you and Oracle.

2. Install dbasim

pip install dbasim

If dbasim is "not recognized" afterwards, your Python scripts folder is not on PATH. Either run every command as python -m dbasim ... instead of dbasim ..., or install with pipx (pipx install dbasim), which puts it on PATH for you.

3. Configure (once)

dbasim setup

It asks for the SYSTEM password you gave the container (ChangeMe123 above), saves it in ~/.dbasim/config.json, and checks the connection. From then on every command works in any terminal window with nothing to export first.

Options: dbasim setup --scale 0.3 makes the scenario data smaller for slow machines; --dsn host:port/service if Oracle is not on localhost:1521/FREEPDB1. The environment variables DBASIM_ADMIN_PASSWORD, DBASIM_DSN and DBASIM_SCALE still work and override the saved file (handy for scripts).

4. Play

Use any tool you like: SQL*Plus, SQLcl, SQL Developer, connected as SYSTEM to FREEPDB1. Every scenario can be solved with what Oracle Free ships (v$ views, DBMS_XPLAN, trace). No AWR/ASH needed.

When you're done

dbasim stop                  # or: dbasim reset   (clears the scenario)
docker stop dbasim-oracle    # gives the memory back; docker start dbasim-oracle next time

Quit Docker Desktop before shutting the computer down. Shutting down while it is still running is what causes its "An unexpected error occurred ... engine.sock" message on the next start.

Troubleshooting

dbasim doctor checks the whole chain (Docker, the container, the database, the password) and tells you which link is broken. The usual ones:

Scenarios

The first three scenarios are free forever: no sign-up and no licence key. Pro scenarios are not on sale yet (coming soon). Watch this repository to hear when they launch.

Found a problem, or want to suggest a scenario? Open an issue at https://github.com/kulchartt/oracledbasim/issues