Your first pull request
This walkthrough uses PostgreSQL and a GitHub repository with SQLAlchemy 2.0 models. Use a development database and code you can safely experiment with. The SQL and model below are examples, not a hosted demo or a guaranteed generated result.
1. Connect your example application
Follow Getting started to connect GitHub, add your development database, and link the branch containing the application that uses it. Use the dedicated account in the PostgreSQL guide, rather than your administrator account.
Choose an existing table that has a corresponding model in your repository. In this example, it is public.customers and the model is Customer.
Read Security & data before connecting. An organisation owner must set up an active subscription, including an active Starter trial, before members can run checks.
2. Establish the starting schema
Before making your example change, select Check changes on the linked branch and let the check finish. Initial schema capture records the starting schema for comparison. Connecting an existing schema does not by itself request a rewrite of all your application models.
If no new changes are detected, that is an expected result at this stage. If a run starts for an existing change, review it in Run history before proceeding.
3. Set project instructions
Open the connection’s settings. Confirm that Schemas to track includes public, then add instructions appropriate to your project. For example:
Use SQLAlchemy 2.0 typed models. The public.customers table is represented by Customer. Preserve existing API field names. Map new nullable text columns as Mapped[str | None]. Do not edit existing migrations. Run the project's model tests if available.
Replace these conventions with your own. Instructions help guide proposals; review the result against your requirements.
4. Make a small development-database change
Using your normal development database administration tools and an account permitted to alter tables, add a nullable column that does not already exist:
ALTER TABLE public.customers
ADD COLUMN display_name TEXT;Do this in your development database, not a production database or the Reverse Migrations service database. The dedicated metadata account is not the account to use for this change.
5. Check and follow the run
Select Check changes again. If a new tracked schema difference is detected, follow its progress in Run history. Open Schema diff to inspect the database changes supplied to the run.
When a pull request is available, use View pull request. A possible model update is:
display_name: Mapped[str | None] = mapped_column(Text, nullable=True)The actual proposal depends on your repository, schema, and instructions. Review the entire PR and run your normal tests before deciding whether to merge.
Understand the result
- No new schema changes detected: confirm that the change happened after the starting schema was recorded, that the connection points at the intended database, and that the schema is tracked. An existing unprocessed difference may also be picked up by a check.
- A run is queued or running: follow it in Run history; a PR is not available yet.
- A pull request is available: inspect its schema diff, proposed code, and test results in GitHub.
- Complete without a confirmed result: completion alone is not proof of a PR or that no changes were needed. Read the outcome and suggested next step.
- Failed or timed out: follow the action in Run history. Check organisation settings when access needs attention, or try again later when asked.
What about schema optimisation?
Schema optimisation reviews an existing recorded schema alongside repository code; it does not require a new column change. It can propose indexing or data-model improvements with reasoning in a PR.
Optimisation runs are started by the service’s scheduled jobs. View results by choosing Schema optimisation in Run history.
Index suggestions are based on available schema and code context, not a guarantee derived from your production workload. Validate query plans, write overhead, and representative workloads before applying them.