From cd68a02fd9730ea10c488de0d3a04a45dbd365fb Mon Sep 17 00:00:00 2001 From: Khaleel Al-Adhami Date: Thu, 2 Jul 2026 11:23:08 -0700 Subject: [PATCH 1/4] docs: document async_db_url and reflex[db] extra (ENG-8371) --- docs/database/overview.md | 9 +++++++++ docs/database/queries.md | 19 +++++++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/docs/database/overview.md b/docs/database/overview.md index 830d24a6716..bcf74bea9f1 100644 --- a/docs/database/overview.md +++ b/docs/database/overview.md @@ -18,6 +18,15 @@ For advanced use cases, please see the If you are using a NoSQL database (e.g. MongoDB), you can work with it in Reflex by installing the appropriate Python client library. In this case, Reflex will not provide any ORM features. ``` +## Installation + +The ORM dependencies (SQLAlchemy, SQLModel, and Alembic) are an optional extra. +Install them with the `db` extra: + +```bash +pip install "reflex[db]" +``` + ## Connecting Reflex provides a built-in SQLite database for storing and retrieving data. diff --git a/docs/database/queries.md b/docs/database/queries.md index 9baa24dc4f3..b7934cd85d1 100644 --- a/docs/database/queries.md +++ b/docs/database/queries.md @@ -194,6 +194,25 @@ class State(rx.State): Reflex provides an async version of the session function called `rx.asession` for asynchronous database operations. This is useful when you need to perform database operations in an async context, such as within async event handlers. +### Configuring the Async Database URL + +Unlike `rx.session`, which uses `db_url`, `rx.asession` requires a separate +`async_db_url` to be set in your `rxconfig.py`. It must point at the same +database as `db_url` but use an async driver, and calling `rx.asession()` +without it configured raises an error. + +```python +config = rx.Config( + app_name="my_app", + db_url="sqlite:///reflex.db", + async_db_url="sqlite+aiosqlite:///reflex.db", +) +``` + +You must also install the matching async DBAPI driver. For SQLite, install +`aiosqlite` as shown above; for PostgreSQL, use a URL like +`postgresql+asyncpg://...` and install `asyncpg`. + The `rx.asession` function returns an async SQLAlchemy session that must be used with an async context manager. Most operations against the `asession` must be awaited. ```python From 4b286e23e935f48d5dd889e0a299277fd790fdb6 Mon Sep 17 00:00:00 2001 From: Khaleel Al-Adhami Date: Thu, 2 Jul 2026 11:27:44 -0700 Subject: [PATCH 2/4] docs: add async driver install commands, fix reflex[db] extra dep list --- docs/database/overview.md | 2 +- docs/database/queries.md | 15 ++++++++++++--- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/database/overview.md b/docs/database/overview.md index bcf74bea9f1..32a0b5fc9bb 100644 --- a/docs/database/overview.md +++ b/docs/database/overview.md @@ -20,7 +20,7 @@ If you are using a NoSQL database (e.g. MongoDB), you can work with it in Reflex ## Installation -The ORM dependencies (SQLAlchemy, SQLModel, and Alembic) are an optional extra. +The ORM dependencies (SQLModel and Alembic) are an optional extra. Install them with the `db` extra: ```bash diff --git a/docs/database/queries.md b/docs/database/queries.md index b7934cd85d1..847aa785319 100644 --- a/docs/database/queries.md +++ b/docs/database/queries.md @@ -209,9 +209,18 @@ config = rx.Config( ) ``` -You must also install the matching async DBAPI driver. For SQLite, install -`aiosqlite` as shown above; for PostgreSQL, use a URL like -`postgresql+asyncpg://...` and install `asyncpg`. +You must also install the matching async DBAPI driver, which is not included in +the `reflex[db]` extra. For the SQLite URL shown above, install `aiosqlite`: + +```bash +pip install aiosqlite +``` + +For PostgreSQL, use a URL like `postgresql+asyncpg://...` and install `asyncpg`: + +```bash +pip install asyncpg +``` The `rx.asession` function returns an async SQLAlchemy session that must be used with an async context manager. Most operations against the `asession` must be awaited. From a8bb9f7961a7efb83e84e86033f7d2c97aec2e91 Mon Sep 17 00:00:00 2001 From: Khaleel Al-Adhami Date: Thu, 2 Jul 2026 11:30:23 -0700 Subject: [PATCH 3/4] docs: recommend psycopg3 over asyncpg for PostgreSQL async --- docs/database/queries.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/database/queries.md b/docs/database/queries.md index 847aa785319..29363f2fce1 100644 --- a/docs/database/queries.md +++ b/docs/database/queries.md @@ -216,10 +216,12 @@ the `reflex[db]` extra. For the SQLite URL shown above, install `aiosqlite`: pip install aiosqlite ``` -For PostgreSQL, use a URL like `postgresql+asyncpg://...` and install `asyncpg`: +For PostgreSQL, install `psycopg` (psycopg3), which works as both the sync and +async driver — so `db_url` and `async_db_url` can share the same +`postgresql+psycopg://...` scheme: ```bash -pip install asyncpg +pip install "psycopg[binary]" ``` The `rx.asession` function returns an async SQLAlchemy session that must be used with an async context manager. Most operations against the `asession` must be awaited. From 899ce9871fb9ced3684ebd8c99b70d880f296717 Mon Sep 17 00:00:00 2001 From: Khaleel Al-Adhami Date: Thu, 2 Jul 2026 11:32:11 -0700 Subject: [PATCH 4/4] docs: tighten async database prose --- docs/database/queries.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/database/queries.md b/docs/database/queries.md index 29363f2fce1..31a96e4eb91 100644 --- a/docs/database/queries.md +++ b/docs/database/queries.md @@ -196,10 +196,9 @@ Reflex provides an async version of the session function called `rx.asession` fo ### Configuring the Async Database URL -Unlike `rx.session`, which uses `db_url`, `rx.asession` requires a separate -`async_db_url` to be set in your `rxconfig.py`. It must point at the same -database as `db_url` but use an async driver, and calling `rx.asession()` -without it configured raises an error. +`rx.asession` needs its own `async_db_url` in `rxconfig.py`. It must point at +the same database as `db_url` but use an async driver. Calling `rx.asession()` +when it is unset raises an error. ```python config = rx.Config( @@ -209,15 +208,15 @@ config = rx.Config( ) ``` -You must also install the matching async DBAPI driver, which is not included in -the `reflex[db]` extra. For the SQLite URL shown above, install `aiosqlite`: +The matching async DBAPI driver is not part of the `reflex[db]` extra, so +install it separately. For the SQLite URL above, install `aiosqlite`: ```bash pip install aiosqlite ``` -For PostgreSQL, install `psycopg` (psycopg3), which works as both the sync and -async driver — so `db_url` and `async_db_url` can share the same +For PostgreSQL, install `psycopg` (psycopg3). It works as both the sync and +async driver, so `db_url` and `async_db_url` can share one `postgresql+psycopg://...` scheme: ```bash