Supabase

Head to the Supabase tab in Mosayic. Supabase handles authentication, your database, and optional services like storage.

Creating Your Supabase Project

Visit supabase.com to create a new project (and account if needed). You can start with a free account – and remarkably, you can power a small mobile application entirely on the free tier.

Tip

In a traditional cloud environment, a database alone could easily cost €15+ as a starting point. Supabase’s free projects are production-ready, which is genuinely powerful.

However, free projects lack important features like backups. For serious projects, upgrading to Supabase Pro is recommended to get backups, branching, and other production tooling.

Note

Self-hosting Supabase is possible, but the labor costs of implementing that infrastructure yourself far outweigh just using Supabase’s cloud environment. If you’re unsure whether to self-host – you probably shouldn’t.

Local Development with Docker

While your Supabase project lives in the cloud for production, Mosayic works on the principle of local development. Supabase provides tooling to spin up database instances on your local machine using Docker.

Mosayic will have you install:

• Docker
• The Supabase CLI

Then in the Supabase tab, you can start a server. This spins up a completely isolated local Supabase instance running only on your machine. Your local mobile app can connect to this, letting you experiment and modify your database while the production app continues running safely in the cloud.

Tip

This sandbox environment lets you develop new features for existing applications with real users – then decide whether to keep or discard your changes.

Once the server is running, Mosayic provides a button to open the local Studio on localhost. You can experiment freely without worrying about affecting production.

Data vs. Schema

The data itself (as opposed to the schema) is not persisted when you reset your local database. To maintain test data between resets, you’ll create a seed file.

The philosophy here is clear:

• Production data is sacred
• Development data is disposable

To save time recreating common data or test users, have your AI write a seed file. What data you initialize locally is entirely up to you.

Understanding Migrations

Don't let AI run on autopilot

Leaving the AI to make unsupervised changes to your database schema is a mistake. Take time to understand migrations.

Migrations are a critical concept. Your database schema can become complex because it can do essentially anything – it’s powered by PostgreSQL, a very well-established SQL database.

Quick SQL Primer

Your database is composed of tables that can be joined together. For example, in a chat app:

• A users table with name, email, and other data
• A messages table with a user_id column

You can join these tables to get message data and the associated user data in a single query. This is something Firestore (Firebase) can’t do by default – one of many reasons Supabase is the better choice unless you have a specific reason for NoSQL.

The Initial Schema

Mosayic starts you with a supabase folder in the API repository containing a migrations folder with an initial schema migration file. This creates:

The Public Users Table

When you use Supabase Auth, users are created in the auth schema. However, the initial migration includes a trigger that also creates a corresponding entry in a public.users table.

This public table is user-facing – you can store the user’s name, profile photo, and other data that the user can modify within the app.

Danger

Never give users direct access to the auth.users table. This separation is standard practice in database management.

The Items Table

There’s also an items table – this is a placeholder demonstrating CRUD operations (Create, Read, Update, Delete). You can modify or remove it based on what your app actually needs.

Tip

Talk to your AI about what Supabase should look like for your specific app. Play with the initial migration file to set up the schema that matches your vision.

Creating New Migrations

In the Python API repository, you’ll find a supabase/migrations folder. Mosayic provides an initial migration file, but you can add more as your schema evolves.

The workflow is:

1. Open your local Supabase Studio (the localhost address)
2. Make changes to your schema as you develop your mobile app
3. When ready to capture those changes, use Mosayic’s create migration button

When creating a migration, Mosayic compares the current state of your database against what’s defined in your existing migration files, then saves the difference as a new timestamped migration file.

This means your schema is saved as code.

Caution

Avoid making schema changes directly in the production dashboard. You can pull changes, but the recommended workflow is: make changes locally → save as migrations → push to production when ready.

Resetting the Database

Once you have migrations in place, your database can be recreated at any point. Mosayic provides a reset database button that:

1. Destroys everything in your local database
2. Recreates it from scratch using your migrations (run in timestamp order)

Note

Any data you’ve added locally will be destroyed on reset. Data you want to preserve between resets should be added to your seed file. Over time, you build a complete picture of your database as a combination of all migration files.

If you encounter errors during reset, use your AI to investigate the migration files and determine why they’re not building properly.

Pushing to Production

Because your migration files are a snapshot in code of exactly how your database should be structured, you can push changes from your local environment to your production Supabase project.

Mosayic provides two methods:

Manual (Command Line)

Link to your production project using the Supabase CLI and push migrations directly.

GitHub Actions (Recommended)

Mosayic provides a workflow for automated deployments. To use this, you’ll need:

• Connection string – available from your Supabase dashboard
• Database password – if you haven’t recorded this, you’ll need to reset it in the Supabase dashboard