Organize SQL Files for Readers, Not for Execution Order

If you named a schema file 1001-rpcs.sql just to make sure its functions load after your tables, that prefix is doing more than organizing your repository: it is encoding a dependency. Supabase Declarative Schema v2’s pg-delta workflow moves that responsibility into migration generation.

That lets you organize declarative SQL around how you understand your database—not around the sequence PostgreSQL needs to build it. The important qualification: schema files and migration files are different things, and only one of them gains this freedom.

What Numbered Schema Files Were Really Doing

Under the legacy declarative workflow, file order could be part of making the schema work.

Consider two tables:

• customers, which defines a primary key.
• orders, which has a foreign key referencing customers.

If the engine processes the orders definition before the referenced table exists, it can encounter an ordering failure. To avoid that, you might name the files:

supabase/schemas/
  001-customers.sql
  002-orders.sql
  1001-rpcs.sql

Those prefixes are effectively a small, manually maintained execution plan. The names communicate not just what is in the files, but when those files must be processed.

You could also control the order through schema_paths. Either way, the dependency knowledge lives partly outside the SQL definitions.

That creates a maintenance burden. A file rename or a repository reorganization can affect schema processing even when the SQL itself has not changed. Adding a dependency can require revisiting file order. Splitting one large file into several smaller ones becomes an operational change, not merely a readability improvement.

When filenames encode execution order, reorganizing your source can change whether your schema builds.

The problem is not that numbered files are inherently bad. It is that they make repository layout carry a correctness responsibility.

What Changes With pg-delta

With the v2 pg-delta workflow, sync recognizes schema dependencies and orders the generated migration statements accordingly.

For the orders and customers example, the dependency is already expressed by the foreign key. The engine can use that relationship to generate statements in an appropriate order instead of requiring you to communicate it through filename prefixes.

The same principle applies to dependencies such as:

• Views that reference tables.
• Triggers that use functions.
• Foreign keys that reference other tables.

The shift is in where ordering happens:

This is not “SQL order no longer matters.” PostgreSQL still requires a valid sequence of operations.

Instead, the engine takes on the job of deriving that sequence from the schema dependencies.

Declarative files describe the desired schema. Generated migrations describe the ordered changes needed to reach it.

That separation is the practical value of the feature.

Can You Rename 1001-rpcs.sql?

Yes—if it is a declarative schema file and the number exists solely to enforce dependency order.

For example:

supabase/schemas/1001-rpcs.sql

could become:

supabase/schemas/rpcs.sql

You could also split the functions into separate files if that makes them easier to find and review:

supabase/schemas/
  customers.sql
  orders.sql
  get-customer-orders.sql
  calculate-order-total.sql

These names are illustrative, not a prescribed layout. The point is that you no longer need 1001 to mean “process this after the table definitions.”

The condition: you must be using pg-delta

This advice assumes your project has pg-delta enabled.

On the legacy migra workflow, declarative file order still matters. Removing an ordering prefix without checking which engine your project uses can therefore remove a dependency safeguard you still need.

Before renaming files, distinguish two questions:

1. Which declarative engine is active?
2. Is this file a schema definition or a migration?

The answer is not determined by the filename alone.

Do Not Apply This Rule to Migration History

A similarly named file under supabase/migrations/ has a different role:

supabase/migrations/1001-rpcs.sql

Do not treat an existing migration as an organizational schema file.

Migrations remain ordered deployment history. They record changes that must be applied in sequence. V2 does not turn that history into a collection you can freely rename or rearrange for readability.

The directory distinction is decisive:

You are gaining freedom over the organization of your desired-state definitions, not permission to rewrite the ordering of existing deployments.

Make the Refactor, Then Review the Migration

A practical workflow is:

1. Confirm pg-delta is enabled.

2. Rename or split files in supabase/schemas/ according to what makes the SQL easier to navigate.

3. Keep the configured schema paths aligned with your layout, especially if you move files rather than merely rename them.

4. Generate the next migration:

   supabase db schema declarative sync
   

5. Review the generated SQL.

The engine handles dependency ordering, but the resulting migration still deserves inspection. Check that it represents the intended schema changes and that a readability refactor has not accidentally altered definitions.

There is also a limit to automatic ordering: if sync encounters a dependency cycle it cannot resolve, it reports an error rather than generating a broken migration. Removing numeric prefixes does not make an unresolvable dependency graph valid.

The Benefit Is Small—and Worth Taking

The immediate payoff is not a new database capability. It is less manual coordination between SQL dependencies and repository structure.

You can choose filenames that explain their contents, split files when they become difficult to review, and reorganize definitions without preserving a numbering scheme whose only purpose was execution order.

Keep the distinction clear:

• Organize declarative schema files for people.
• Let pg-delta order generated migration statements.
• Preserve migration history and review what gets generated.

That is what makes dropping 1001- useful: not fewer dependencies, but fewer places where you have to maintain them manually.

For workflow details, see the Supabase declarative database schemas documentation.