Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 13 additions & 10 deletions docs/database/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -165,10 +165,11 @@ command line works on the same environment:
| `reflex db status` | `alembic history --indicate-current` |

Anything else alembic can do, such as `alembic downgrade -1`, works the same
way. The generated `env.py` skips an autogenerated revision when the schema has
not changed, for `reflex db makemigrations` and `alembic revision --autogenerate`
alike, and both evaluate the pages before comparing the models, as
`alembic check` does, so a model that only a page function imports is compared too.
way. `reflex db makemigrations` writes a revision only when `alembic check`
reports changes, and the generated `env.py` skips an empty autogenerated revision
for `alembic revision --autogenerate` too. Both evaluate the pages before
comparing the models, as `alembic check` does, so a model that only a page
function imports is compared too.

Generated scripts land in the `alembic/versions` directory. It is recommended
that they be inspected before applying them. Bear in mind that your newest
Expand All @@ -184,15 +185,17 @@ database schema is not up to date, a warning will be displayed on the console.

Apps initialized by an earlier Reflex release have a stock alembic `env.py` that does
not load the app. The next `reflex db` command, or `migrate()` call, replaces it
with the current template and keeps the previous file as `env.old`; existing
revisions are kept.
with the current template and keeps the previous file as `env.old` (or
`env.old.1`, and so on, if that name is taken); existing revisions are kept.

An `env.py` you edited yourself is kept as it is, as long as it no longer contains
the stock template's `target_metadata = None` line, which is how Reflex tells the
two apart. It then has none of the template's behavior, such as skipping empty
revisions or giving existing rows a new column's default. To adopt the current
template, move your `env.py` aside and run `reflex db init`, which writes a
missing `env.py` afresh.
two apart. It then has none of the template's behavior, such as taking the
database URL from `rxconfig.py` or giving existing rows a new column's default,
and Reflex warns about it once. If it fails, for example on the placeholder URL
in `alembic.ini`, the startup check logs the error and the app still starts,
while the `reflex db` commands exit with it. To adopt the current template, move
your `env.py` aside and run `reflex db init`, which writes a missing `env.py` afresh.
```

For a local experiment, `create_all` creates any missing tables without
Expand Down
1 change: 1 addition & 0 deletions news/+kept-env-py-errors.bugfix.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
A hand-edited `alembic/env.py` kept from an earlier release no longer stops `reflex run` when it fails, for example on the placeholder URL in `alembic.ini`: the startup check logs the error with the fix (move the file aside and run `reflex db init`), and the `reflex db` commands exit with that message instead of a traceback. Reflex also warns once that such an `env.py` is not the Reflex template, and replacing a stock `env.py` again keeps the earlier `env.old` as `env.old.1`.
1 change: 1 addition & 0 deletions news/+no-empty-revisions.bugfix.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
`reflex db makemigrations` and `migrate(autogenerate=True)` write a revision only when `alembic check` reports model changes, so an `env.py` that is not the Reflex template no longer gets an empty revision on every call.
37 changes: 20 additions & 17 deletions reflex/model.py
Original file line number Diff line number Diff line change
Expand Up @@ -439,22 +439,10 @@ def alembic_autogenerate(
)
if not environment.ALEMBIC_CONFIG.get().exists():
return False
from alembic.util.exc import AutogenerateDiffsDetected

from reflex.utils import migrations

_update_legacy_env()
try:
migrations.run("--quiet", "check")
except AutogenerateDiffsDetected:
if write_migration_scripts:
migrations.run(
"revision",
"--autogenerate",
*(("--message", message) if message else ()),
)
return True
return False
return migrations.autogenerate(message, write=write_migration_scripts)

def migrate(autogenerate: bool = False) -> bool | None:
"""Apply alembic migrations, optionally autogenerating one first.
Expand All @@ -470,17 +458,32 @@ def migrate(autogenerate: bool = False) -> bool | None:
Returns:
True - indicating the process was successful.
None - indicating the process was skipped.
False - indicating that an env.py other than the template failed;
the error is logged instead of raised, so that an app calling
this at import still starts, as before env.py was run.

Raises:
CommandError: If alembic reports an error.
"""
if not environment.ALEMBIC_CONFIG.get().exists():
return None
from alembic.util.exc import CommandError

from reflex.utils import migrations

_update_legacy_env()
# Pending scripts are applied first: autogenerate needs the database at head.
migrations.run("upgrade", "head")
if autogenerate:
migrations.run("revision", "--autogenerate")
try:
# Pending scripts are applied first: autogenerate needs the database at head.
migrations.run("upgrade", "head")
if autogenerate and migrations.autogenerate():
migrations.run("upgrade", "head")
except CommandError:
raise
except Exception as error:
if migrations.env_kind() != "custom":
raise
migrations.report_failure(error)
return False
return True

else:
Expand Down
12 changes: 6 additions & 6 deletions reflex/reflex.py
Original file line number Diff line number Diff line change
Expand Up @@ -1117,7 +1117,7 @@ def _alembic_errors() -> Generator[None, None, None]:
None, while the alembic commands run.

Raises:
Exit: With status 1 when alembic reports a CommandError.
Exit: With status 1 when alembic, or env.py as it runs, raises.
"""
from alembic.util.exc import CommandError

Expand All @@ -1128,6 +1128,9 @@ def _alembic_errors() -> Generator[None, None, None]:
except CommandError as error:
logger.error(migrations.describe_error(error), extra={"rich": True})
raise click.exceptions.Exit(1) from None
except Exception as error:
migrations.report_failure(error)
raise click.exceptions.Exit(1) from None


@db_cli.command(name="init")
Expand Down Expand Up @@ -1226,11 +1229,8 @@ def makemigrations(message: str | None):
if not prerequisites.check_db_initialized():
raise click.exceptions.Exit(1)
with _alembic_errors():
migrations.run(
"revision",
"--autogenerate",
*(("--message", message) if message else ()),
)
if not migrations.autogenerate(message):
logger.info("No model changes detected; no revision was written.")


@cli.command()
Expand Down
155 changes: 148 additions & 7 deletions reflex/utils/migrations.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@
import io
import logging
import shutil
import traceback
from pathlib import Path
from typing import Literal

from reflex_base.environment import environment
from rich.markup import escape
Expand All @@ -33,6 +35,27 @@
"Updated env.py to load the app; the previous one is kept as {backup}."
)

# In the docstring of every env.py written from the template, since 0.11.0a1.
TEMPLATE_MARKER = "Generated by ``reflex db init``"

# The line of alembic's stock env.py that earlier releases never ran or edited.
LEGACY_MARKER = "target_metadata = None"

CUSTOM_ENV_HINT = (
"alembic/env.py is not the Reflex template: move it aside and run "
"[bold]reflex db init[/bold] to write the current template."
)

CUSTOM_ENV_WARNING = (
"alembic/env.py is not the Reflex template, so what the template adds may be "
"missing: the database URL from rxconfig.py, the models of the whole app, "
"server defaults for added columns and warnings for dropped tables. Move it "
"aside and run [bold]reflex db init[/bold] to adopt the template; existing "
"revisions are kept."
)

EnvKind = Literal["template", "legacy", "custom"]

# True while env.py imports the app, when an import-time `migrate()` call would
# start a second alembic run inside the one already in progress.
_loading_app = False
Expand Down Expand Up @@ -72,6 +95,15 @@ def run(*args: str) -> None:
return
import alembic.config

# An env.py other than the template may apply the logging settings in
# alembic.ini, which replace the root handlers and disable every other logger.
root = logging.getLogger()
root_handlers, root_level = root.handlers[:], root.level
enabled = [
child
for child in logging.Logger.manager.loggerDict.values()
if isinstance(child, logging.Logger) and not child.disabled
]
_in_run = True
try:
alembic.config.main(
Expand All @@ -85,6 +117,38 @@ def run(*args: str) -> None:
)
finally:
_in_run = False
root.handlers[:] = root_handlers
root.setLevel(root_level)
for child in enabled:
child.disabled = False


def autogenerate(message: str | None = None, write: bool = True) -> bool:
"""Compare the models with the database and write a revision if they differ.

``alembic check`` runs first, so that no empty revision is written even when
env.py, unlike the template, does not skip one.

Args:
message: The message of the revision.
write: Write the revision; otherwise only compare.

Returns:
True when the models and the database differ.
"""
from alembic.util.exc import AutogenerateDiffsDetected

try:
run("--quiet", "check")
except AutogenerateDiffsDetected:
if write:
run(
"revision",
"--autogenerate",
*(("--message", message) if message else ()),
)
return True
return False


def evaluate_pages() -> None:
Expand Down Expand Up @@ -171,36 +235,72 @@ def script_directory() -> Path:
return Path(alembic.script.ScriptDirectory.from_config(config).dir)


def is_legacy_env() -> bool:
"""Whether env.py predates the reflex template and cannot load the app.
def env_kind() -> EnvKind | None:
"""Tell where env.py comes from.

Earlier Reflex releases ran `alembic init` with alembic's stock template and
never executed the resulting env.py, which still reads
``target_metadata = None`` and connects to the placeholder URL in alembic.ini.
An env.py with neither that line nor the template's marker was written or
edited by hand, and alembic runs it as it is.

Returns:
True if env.py is the stock alembic template.
``"template"`` for the reflex template, ``"legacy"`` for the stock one,
``"custom"`` for any other, or None without an env.py.
"""
from alembic.util.exc import CommandError

try:
env_py = script_directory() / "env.py"
except CommandError:
# Let the command that needs the directory report what is wrong with it.
return False
return env_py.exists() and "target_metadata = None" in env_py.read_text()
return None
if not env_py.exists():
return None
source = env_py.read_text()
if TEMPLATE_MARKER in source:
return "template"
return "legacy" if LEGACY_MARKER in source else "custom"


def check_env() -> EnvKind | None:
"""Tell where env.py comes from, warning once per process when it is custom.

Returns:
What ``env_kind`` returns.
"""
kind = env_kind()
if kind == "custom":
logger.warning(CUSTOM_ENV_WARNING, extra={"dedupe": True, "rich": True})
return kind


def is_legacy_env() -> bool:
"""Whether env.py predates the reflex template and cannot load the app.

Returns:
True if env.py is the stock alembic template.
"""
return env_kind() == "legacy"


def update_legacy_env() -> Path | None:
"""Replace a stock env.py with the reflex template, keeping it as env.old.

An earlier backup is kept too: the new one takes the first free name of
env.old, env.old.1, env.old.2 and so on.

Returns:
Where the previous env.py went, or None when env.py already loads the app.
Where the previous env.py went, or None when env.py is not the stock one.
"""
if not is_legacy_env():
if check_env() != "legacy":
return None
env_py = script_directory() / "env.py"
backup = env_py.with_name("env.old")
index = 0
while backup.exists():
index += 1
backup = env_py.with_name(f"env.old.{index}")
env_py.replace(backup)
install_env()
return backup
Expand All @@ -220,3 +320,44 @@ def describe_error(error: Exception) -> str:
if "Target database is not up to date." in message:
message += " Run [bold]reflex db migrate[/bold] to update database."
return message


def _raised_in_env_py(error: Exception) -> bool:
"""Whether env.py itself raised, not a revision script that it ran.

Args:
error: The exception raised while alembic ran.

Returns:
True if the innermost frame in the script directory is env.py's, or
env.py failed to compile, which leaves only its file name.
"""
scripts = script_directory()
paths = [frame.filename for frame in traceback.extract_tb(error.__traceback__)]
if isinstance(error, SyntaxError) and error.filename:
paths.append(error.filename)
for path in map(Path, reversed(paths)):
if path.is_relative_to(scripts):
return path == scripts / "env.py"
return False
Comment thread
masenf marked this conversation as resolved.
Resolved


def report_failure(error: Exception) -> None:
"""Log an exception other than a ``CommandError`` that an alembic run raised.

A custom env.py that failed is named with the fix and the traceback goes to
the debug log; any other failure, such as a revision script's, is logged
with its traceback. Each is logged once per process: an import-time
``migrate()`` and the startup check fail alike.

Args:
error: The exception raised while alembic ran.
"""
message = escape(f"Alembic failed with {type(error).__name__}: {error}")
if env_kind() == "custom" and _raised_in_env_py(error):
logger.error(
f"{message}\n{CUSTOM_ENV_HINT}", extra={"dedupe": True, "rich": True}
)
logger.debug("The alembic run failed.", exc_info=error)
else:
logger.error(message, exc_info=error, extra={"dedupe": True, "rich": True})
6 changes: 5 additions & 1 deletion reflex/utils/prerequisites.py
Original file line number Diff line number Diff line change
Expand Up @@ -872,7 +872,7 @@ def check_schema_up_to_date():

from reflex.utils import migrations

if migrations.is_legacy_env():
if migrations.check_env() == "legacy":
logger.error(migrations.LEGACY_ENV_HINT, extra={"dedupe": True, "rich": True})
return
try:
Expand All @@ -885,6 +885,10 @@ def check_schema_up_to_date():
)
except CommandError as command_error:
logger.error(migrations.describe_error(command_error), extra={"rich": True})
except Exception as error:
Comment thread
masenf marked this conversation as resolved.
Resolved
# Reported, not raised: the app starts without the check, as it did when
# earlier releases never ran env.py.
migrations.report_failure(error)


@once
Expand Down
Loading
Loading