What the agent does
In a Flask app laid out like miguelgrinberg/microblog, config.py sets SQLALCHEMY_DATABASE_URI from DATABASE_URL, rewriting a postgres:// prefix to postgresql://, and falls back to sqlite:///app.db beside the code. There is no SQLALCHEMY_ENGINE_OPTIONS, so Flask-SQLAlchemy 3.1.1 (requirements.txt, with SQLAlchemy==2.0.23 and psycopg2-binary==2.9.9) builds the engine with SQLAlchemy's QueuePool defaults: five pooled connections, ten of overflow, a thirty second wait for one, and no recycling. app/__init__.py makes one SQLAlchemy() and calls db.init_app(app) inside create_app; boot.sh runs flask db upgrade and then gunicorn -b :5000 microblog:app; and app/tasks.py builds a second app with create_app() for the RQ worker that deployment/supervisor/microblog-tasks.conf runs. So there are at least two processes, each with its own pool, against one database.
The agent adds SQLALCHEMY_ENGINE_OPTIONS to Config, built from the URI rather than hard-coded. For postgresql:// and mysql:// it sets pool_pre_ping=True and reads pool_size, max_overflow, pool_timeout and pool_recycle from DB_POOL_SIZE, DB_MAX_OVERFLOW, DB_POOL_TIMEOUT and DB_POOL_RECYCLE, leaving each at SQLAlchemy's own default when the variable is unset; the right pool_recycle is the idle timeout of the reader's database or proxy, which the repository does not know, so the pull request names the variable instead of guessing a value. Flask-SQLAlchemy's own two hour pool_recycle for MySQL stays when nothing overrides it. For sqlite:// the agent sets none of them: Flask-SQLAlchemy already gives SQLite its own pool class and check_same_thread handling, tests.py uses an in-memory sqlite:// that would refuse a pool_size, and TestConfig is left untouched.
Proof is a dropped connection. In its sandbox the agent installs PostgreSQL with apt-get, creates a database, sets DATABASE_URL, runs flask db upgrade across the nine migrations under migrations/versions, and starts the app with flask run. It creates a user through POST /api/users so the pool holds a connection, then runs SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = ... from psql to kill that connection on the server, and repeats the request. Without pool_pre_ping the second request raises psycopg2.OperationalError with server closed the connection unexpectedly, which app/errors/handlers.py turns into a 500 after db.session.rollback(); with it, the pool pings the connection at checkout, sees it is dead, replaces it, and the request answers normally. Both transcripts are quoted. It then runs python tests.py, which still uses in-memory SQLite, to show that path is unchanged.
The change is confined to config.py, where the four variables sit beside the other environment-driven settings. boot.sh, the Dockerfile and the supervisor files are untouched, since the worker and the web app read the same Config and get the same options, and a deploy that wants a different pool for the worker sets the variables differently for that process.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add connection pool settings to this Flask and SQLAlchemy app. Read config.py, app/__init__.py, app/tasks.py, boot.sh, Dockerfile, requirements.txt and tests.py first. Add SQLALCHEMY_ENGINE_OPTIONS to Config built from the database URI: for postgresql and mysql set pool_pre_ping and read pool_size, max_overflow, pool_timeout and pool_recycle from environment variables, keeping SQLAlchemy's defaults when they are unset; leave sqlite with no pool options so tests.py keeps working. Install PostgreSQL in the sandbox, run flask db upgrade, start the app, create a user through POST /api/users, terminate that server-side connection with pg_terminate_backend, and repeat the request with and without pool_pre_ping, quoting both responses and the log lines. Run python tests.py. Open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that changes config.py and nothing else. The description quotes the OperationalError line and the 500 from the run without pool_pre_ping, the normal response from the run with it, and the python tests.py result, and lists the four environment variables with what each does and the SQLAlchemy default that applies when it is unset.
The run's record holds the PostgreSQL install, the migrations, the pg_terminate_backend call and both request transcripts, so a reviewer can see the failure the setting prevents rather than take the pull request's word for it.
Before merging, a reviewer picks a pool_recycle that is shorter than the idle timeout of their database or proxy, and checks the arithmetic for their deploy: each gunicorn worker and the RQ worker carry their own pool, so workers times pool_size plus max_overflow has to stay under the database's connection limit.
Run it on every repository with a Flask app and no engine options
A team with several Flask services runs this once per repository from a handler on their own server: for each repository the handler calls POST /o/{org}/sessions with this page's body and that repository's URL in resources, and a request_id that is a UUID v5 of the repository name, so running the script twice returns the runs already started instead of opening a second pull request on each.
Each run reads that service's own config.py and deploy files, so a service on MySQL gets the two hour recycle Flask-SQLAlchemy already applies and a service that only ever uses SQLite gets a pull request saying there is nothing to set. The key's run.completed webhook reports each run, with its answer, when it finishes.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A pool setting is cheap to write and hard to prove: the bug it prevents only appears when the database or a proxy closes an idle connection, which a laptop test never does. In a Rush sandbox the agent has a PostgreSQL of its own and kills the connection on purpose, so the pull request shows the error and then shows it gone.
The transcript of the failing request, the passing one and the test run stay in the run's record, and the pull request quotes them, so review is reading a diff of one file against evidence rather than reasoning about pool behavior from memory. The same job runs on every Flask service a team keeps at once, each with its own sandbox and its own pull request.
Frequently asked questions
Why not set pool_pre_ping for SQLite too?
SQLite does not drop connections the way a server does, Flask-SQLAlchemy already picks a pool class and check_same_thread for it, and the in-memory sqlite:// that tests.py uses would refuse a pool_size. The options are built from the URI so the SQLite path stays exactly as it is.
Does the RQ worker need its own settings?
It reads the same Config, so it gets the same options and its own pool, since it is a separate process. Its connections count toward the database's limit alongside the web workers'; a deploy that wants a smaller pool for it sets DB_POOL_SIZE lower in that process's environment.
What value should pool_recycle have?
Shorter than the idle timeout of whatever closes connections in your deploy, which the repository does not record, so the pull request leaves it at SQLAlchemy's default of off and names the variable. pool_pre_ping covers the case where a connection died anyway, at the cost of one round trip per checkout.
Will the tests change?
No. tests.py runs on sqlite:// in memory through TestConfig, the SQLite branch sets no pool options, and the agent runs the suite to show it still passes. The new behavior is only proved against the PostgreSQL in the sandbox.