sqlsim/sqlsimulator repository overview

SQL Simulator

Test SQL scripts against a disposable copy of your database — safely, without touching production.

SQL Simulator spins up an on-demand sandbox container scoped to just the tables your SQL scripts actually touch. It walks the foreign-key graph to pull in whatever related data is needed to keep referential integrity intact, giving your team (or CI pipeline) a safe, disposable place to run and validate SQL before it ever reaches production. Nothing persists between runs by design — tear a sandbox down and spin up a fresh one next time.

Supported databases SQL Server Oracle MySQL PostgreSQL

Getting started Download docker-compose.yml for your engine from the Get Started page, then start the container (swap sqlserver for your engine's profile — sqlserver, oracle, mysql, or postgres):

docker compose -f docker-compose.yml --profile sqlserver up Open http://localhost:8080⁠ to use the web UI, or drive everything from the API below.

Using the API

Full reference with copy-paste curl examples for every endpoint: https://sqlsim.dev/sql-simulator/docs/api-reference⁠

1- Set up this deployment's shared login — one-time only; the first call wins, every call after that returns 409 Conflict:

curl -X POST http://localhost:8080/api/Account/setup⁠
-H "Content-Type: application/json"
-d "{"username":"[username]","password":"[password]"}"

2- Add a data source. sourceConnectionString is a real connection string to your database; simulatedConnectionString is optional — leave it out and the sandbox's connection is resolved automatically:

curl -X POST http://localhost:8080/api/DataSources/Add⁠
-H "Content-Type: application/json"
-d "{"name":"Orders DB","databaseType":"SQLSERVER","sourceConnectionString":"Server=[host],1433;Database=[db];User Id=[user];Password=[password];TrustServerCertificate=True;"}"

databaseType is one of SQLSERVER, ORACLE, MYSQL, POSTGRES.

3- Upload SQL scripts to that data source (using the id returned by step 2):

curl -X POST http://localhost:8080/api/DataSources/1/scripts⁠
-F "[email protected]"
-F "[email protected]"

4- (Optional) Test both connections — the source database and the sandbox:

curl -X POST http://localhost:8080/api/DataSources/1/test-connection⁠

5- Run it. BuildSandbox provisions the schema and scoped data only; ApplySandbox also runs your uploaded scripts' DML and leaves the sandbox standing; DryRun does the same as ApplySandbox and then tears the sandbox back down immediately:

curl -X POST "http://localhost:8080/api/Run/BuildSandbox?dataSourceId=1⁠"

Each response includes the sandbox's own connection string so you can connect and review the results directly.

6- (Optional) Tear a sandbox down manually:

curl -X POST http://localhost:8080/api/DataSources/1/destroy⁠

You don't need to call this between runs — every run mode above destroys any standing sandbox automatically as its first step.

Documentation & support

Full docs: https://sqlsim.dev/sql-simulator/docs⁠ Questions or issues: https://sqlsim.dev/support⁠