Declarative schemas help you manage complex Postgres databases more easily by defining your database structure in SQL files that represent the final, desired state. These schema files can be stored and versioned alongside your codebase, enabling better collaboration and simplified reviews.
With declarative schemas, you can:
- Maintain a single source of truth for your database schema, reducing duplication and errors.
- Generate migration files automatically by diffing your declarative schema against the current database state.
- Review changes easily through concise, readable diffs instead of long, complex migration scripts.
Key benefits
- Single source of truth: Define your entire database schema in a single, centralized location for better visibility and control.
- Version-controlled changes: Store your schema files alongside your application code, ensuring consistency across environments.
- Simplified code reviews: Schema changes become small, focused diffs that are easier to understand and validate.
- Reduce merge conflicts: Minimize the risk of conflicts when multiple developers work on the same schema.
- Support for advanced Postgres features: Manage tables, views, functions, triggers, policies, and more through declarative SQL files.
Declarative schemas make it easier to manage growing database complexity, so your team can iterate faster without sacrificing stability or control.
Use Cases for Declarative Schemas
Declarative schemas are valuable for a wide range of teams and scenarios:
- Teams managing complex databases. Simplify schema management when working with multiple tables, views, policies, and functions.
- Collaborative teams. Reduce merge conflicts and improve review processes when multiple developers are making schema changes.
- CI/CD pipelines. Use declarative schemas to automate schema updates in your deployment workflows.
- Teams adopting best practices. Adopt a more robust, maintainable approach to schema management with declarative patterns.
Integration capabilities with Supabase
Declarative schemas integrate directly with the Supabase CLI, allowing you to:
- Define your schema in SQL files within the
supabase/schemasdirectory. - Use
supabase db diffto generate migration files based on schema changes. - Apply and deploy migrations using the Supabase CLI, ensuring consistency across local and remote environments.
- Combine with the Postgres Language Server for enhanced IDE support when working with declarative schemas.
These tools help you maintain control over your database while moving faster and reducing the risk of errors.
FAQs about Declarative Schemas
Below are answers to common questions about declarative schemas.
How do declarative schemas differ from migrations?
Migrations are a record of incremental changes to your database schema. Declarative schemas define the final desired state of your schema, and the necessary migration files are generated by comparing the current database state with your schema files.
Do I need to write my own migration files?
No. Supabase provides a schema diff tool (supabase db diff) that automatically generates migration files from your declarative schema files.
Can I use declarative schemas with my existing projects?
Yes. You can pull your production schema into declarative files by running supabase db dump > supabase/schemas/prod.sql. From there, you can split the schema into smaller files and adopt a declarative workflow.
Are there any limitations to declarative schemas?
The schema diff tool handles most Postgres objects, but some entities (like DML statements) are not captured and may still require manual migrations.
For detailed instructions and best practices, see the Declarative Schemas documentation.