A Firebase SQL Connect service has three main components:

- An underlying PostgreSQL **database** with its own **SQL schema**
- a SQL Connect **application schema** (declared in your `.gql` files)
- a number of **connectors** (declared in your `.gql` files, configured in `connector.yaml` files).

The SQL schema is the source of truth for your data, the SQL Connect
schema is how your connectors can see that data, and the connectors declare the
APIs that your clients can use to access that data.

When you deploy your SQL Connect service with the CLI, you will
migrate your SQL schema, then update your SQL Connect schema, then
update each of your connectors.

> [!NOTE]
> **Note:** Deploying and managing client code you develop with generated SDKs is covered in the SDK guides ([Android](https://firebase.google.com/docs/sql-connect/android-sdk.md.txt), [web](https://firebase.google.com/docs/sql-connect/web-sdk.md.txt), [iOS](https://firebase.google.com/docs/sql-connect/ios-sdk.md.txt), and [Flutter](https://firebase.google.com/docs/sql-connect/flutter-sdk.md.txt)).

## Important deployment concepts

To fully understand deployment, it's important to note key concepts about
schemas and connectors.

### Schema deployments

Deployment of a SQL Connect schema affects the SQL schema for your
Cloud SQL database. SQL Connect helps you *migrate* your
schemas
during deployment, whether you're working with a new database or need to
non-destructively adapt an existing database.

SQL Connect schema migrations have two different schema validation
modes: *strict* and *compatible*.

- Strict mode validation requires that the database schema *exactly* match the
  application schema before the application schema can be updated. Any
  tables or columns that are not used in your SQL Connect schema
  will be deleted from the database.

- Compatible mode validation requires that the database schema be *compatible*
  with the application schema before the application schema can be updated; any
  additional changes that drop schemas, tables or columns are optional.

  Compatible means that schema migrations only affect tables and columns
  referenced in your application schema. Elements in your database that are not
  used by your application schema are left unmodified. Therefore, after
  deployment, your database may contain unused:
  - Schemas
  - Tables
  - Columns

> [!NOTE]
> **Note:** By default, tooling that handles migration will apply compatible mode changes automatically and then prompt you for optional strict mode changes. You can adjust this behavior as discussed in [migrate database schemas](https://firebase.google.com/docs/sql-connect/manage-schemas-and-connectors.md.txt#migrate-schemas-manually).

### Connector deployments

SQL Connect queries and mutations are not submitted by client code
and executed on the server. Instead, when deployed, these SQL Connect
operations are stored on the server, like Cloud Functions. This means
deployment may break existing users.

SQL Connect integrates analysis of breaking changes in your
connector updates into the Firebase CLI.

The CLI analyzes changes to each connector with respect to
your schema, and issues a set of assessment messages with respect to connector
changes that might *alter client behavior* (messages are warning-level) or
**might or will break** (messages are breaking-level) previous versions of
client code.

For example:

- Connector changes that might alter client behavior include removing a nullable field from a query without a `@retired` schema annotation.
- Connector changes that might or will break clients include changing a nullable operation variable to non-null without a default value, or changing the data type of a field to something incompatible (e.g. `String` to `Int`).

A more extensive list of warning-level and breaking-level scenarios is given
in the [CLI reference guide](https://firebase.google.com/docs/sql-connect/cli-reference.md.txt#update-connectors).

## Follow the deployment workflow

You can work on a SQL Connect project both in a local project
directory and in the Firebase console.

A recommended deployment flow involves:

1. Listing currently-deployed **schemas and connectors** with `firebase dataconnect:services:list`.
2. Managing any **schema updates** .
   1. Check for SQL schema differences between your Cloud SQL database and local SQL Connect schema with `firebase dataconnect:sql:diff`.
   2. If needed, perform SQL schema migration with `dataconnect:sql:migrate`.
3. Performing **schema and connect deployments** by running `firebase deploy`, for either just your schema, just your connectors, or combinations of resources.

## Deploy and manage SQL Connect resources

It's a good idea to verify production resources before performing deployments.

```bash
firebase dataconnect:services:list
```

When working in a local project directory, you'll generally use the
`firebase deploy` command to deploy your schema and connectors into production,
with interactive feedback.

Using any `deploy` command, the `--only dataconnect` flag lets you to separate
SQL Connect deployments from other products in your project.

### Normal deployment

```bash
firebase deploy --only dataconnect
```

In this normal deployment, the Firebase CLI attempts to deploy your schema
and connectors.

> [!NOTE]
> **Note:** SQL Connect imposes a 100kB limit on schema source files and connector source files. Avoid including extraneous or unused files in your schema or connector deployments to prevent hitting this limit.

It validates that the new schema does not breaking any existing connectors.
Follow [best practices](https://firebase.google.com/docs/sql-connect/manage-schemas-and-connectors.md.txt#best-practices) when making breaking changes.

It also verifies that the SQL schema is already migrated before updating the
SQL Connect schema. If not, it automatically prompts you through any
necessary steps to [migrate schemas](https://firebase.google.com/docs/sql-connect/manage-schemas-and-connectors.md.txt#migrate-schemas-manually).

### `--force` flag deployment

```bash
firebase deploy --only dataconnect --force
```

If neither the connector or SQL schema validations are of concern, you can
re-run the command with `--force` to ignore them.

The `--force` deploy still checks if the SQL schema matches the
SQL Connect schema, warns of incompatibility, and prompts.

### Deploy selected resources

To deploy with more granular control, use the `--only` flag with the
`serviceId` argument. To deploy only schema changes for a particular service:

```bash
firebase deploy --only dataconnect:serviceId:schema
```

You can also deploy all resources for a specified connector and service.

```bash
firebase deploy --only dataconnect:serviceId:connectorId
```

Finally, you can deploy the schema and all connectors for a single service.

```bash
firebase deploy --only dataconnect:serviceId
```

### Roll back a deployment

To perform a manual rollback, check out a previous version of your code and
deploy it. If the original deployment included destructive breaking changes,
you may not be able to fully recover any data deleted.

## Migrate database schemas

If you're prototyping rapidly, experimenting with schemas, and know your schema
changes are destructive, you can plan on using SQL Connect tools to
verify the changes and supervise how the updates are carried out.

> [!TIP]
> **Tip:** Follow our recommended best practices for working with [new databases](https://firebase.google.com/docs/sql-connect/manage-schemas-and-connectors.md.txt#new-databases-recommendations) and [existing databases](https://firebase.google.com/docs/sql-connect/manage-schemas-and-connectors.md.txt#existing-databases-recommendations).

### Diff SQL schema changes

You can verify changes:

```bash
firebase dataconnect:sql:diff
```

You can pass a comma-separated list of services.

The command compares local schema for a service with the current schema of the
corresponding Cloud SQL database. If there is a difference, it
prints out the
SQL commands that would be run to fix that difference

### Apply changes

When you're satisfied and ready to deploy changes to the schema
Cloud SQL
instance, issue the `firebase dataconnect:sql:migrate` command. You'll be
prompted to approve changes.

```bash
firebase dataconnect:sql:migrate [serviceId]
```

In interactive environments, SQL migration statements and action prompts are
displayed.

### Migrate in strict or compatible mode

In a brand new project, the default [schema validation mode](https://firebase.google.com/docs/sql-connect/manage-schemas-and-connectors.md.txt#schema-deployments)
applies. The behavior of the `migrate` command is to apply all database schema
changes that are required by your application schema, then prompt you to approve
optional operations that drop schemas, tables or columns to force your database
schema to exactly match your application schema.

You can adjust this behavior by modifying your `dataconnect.yaml` file.
Uncomment the `schemaValidation` key, and declare `COMPATIBLE` so that only
required changes are applied in migrations.

```yaml
schemaValidation: "COMPATIBLE"
```

Or set the behavior to `STRICT` so that all schema changes are applied and your
database schema is forced to match your application schema.

```yaml
schemaValidation: "STRICT"
```

See the [SQL Connect CLI reference for more information](https://firebase.google.com/docs/sql-connect/cli-reference.md.txt#manage-cloudsql-schemas).

## Update connectors

When you run `firebase deploy`, the CLI initiates an update of the applicable
connectors and issues applicable warning-level (may impact client behavior) and
breaking-level (possibly or certainly breaking) assessment messages.

### Manage connector updates with the CLI

The CLI has slightly different behavior in interactive mode and non-interactive
mode.

As you might expect, in interactive mode, the CLI prompts you to accept all
messages. You can override and force connector deployment with the `--force`
flag.

```bash
# Prompts for acceptance for any warning-level or breaking-level changes prior
# to deploying connectors.
firebase deploy --only dataconnect
# Will deploy connectors without prompting.
firebase deploy --only dataconnect --force
```

In non-interactive mode, the CLI will deploy your connector as long as there
are no breaking-level assessments. Otherwise, your script will exit with a log
of breaking changes. You can override and deploy by setting the `--force` flag.

```bash
# Will deploy connectors with warning-level changes. If any breaking changes
# are present, the deploy will fail and output any breaking changes
firebase deploy --only dataconnect --non-interactive
# Will deploy the connectors from the previous step, if the same issues are present.
firebase deploy --only dataconnect --non-interactive --force
```

For more information, see the [CLI reference guide](https://firebase.google.com/docs/sql-connect/cli-reference.md.txt#update-connectors).

## Best practices for managing schemas and connectors

Firebase recommends some practices to follow in your SQL Connect
projects.

### Minimize breaking changes

- Firebase recommends keeping your SQL Connect schema and connector files in source control.
- Avoid breaking changes when possible. Some common examples of breaking changes include:
  - Removing a field from your schema
  - Making a nullable field in your schema nonnullable (ie `Int` -\> `Int!`)
  - Renaming a field in your schema.
- If you do need to remove a field from your schema, consider splitting it into a few deployments to minimize impact:
  - First, remove any references to the field in your connectors, and deploy the change.
  - Next, update your apps to use newly generated SDKs.
  - Finally, remove the field in your schema `.gql` file, migrate your SQL schema, and deploy once more.

### Use strict mode when working with new databases

If you are using SQL Connect with a new database and actively
developing your application schema, and you want to ensure your database schema
stays exactly in line with your application schema, you can specify
`schemaValidation: "STRICT"` in your `dataconnect.yaml`.

This will ensure optional changes are applied as well.

### Use compatible mode when you have production data in your database

If you are making changes to a database that contains production data, we
recommend you execute your schema migrations in compatible mode, to ensure
existing data is not dropped. You can specify `schemaValidation: "COMPATIBLE"`
in your `dataconnect.yaml`.

In compatible mode, only required schema migration changes are applied to your
database.

- `DROP SCHEMA`, `DROP TABLE`, and `DROP COLUMN` are considered optional statements and will not be generated for your plan, even if your database schema contains schemas, tables, or columns not defined in your application schema.
- If your database table contains a non-null column that is not included in your application schema, the `NOT NULL` constraint will be removed, so that data can still be added to the table with your defined connectors.

## What's next?

- Deploying and managing client code you develop with generated SDKs are covered in the guides for [Android](https://firebase.google.com/docs/sql-connect/android-sdk.md.txt), [iOS](https://firebase.google.com/docs/sql-connect/ios-sdk.md.txt), [web](https://firebase.google.com/docs/sql-connect/web-sdk.md.txt), and [Flutter](https://firebase.google.com/docs/sql-connect/flutter-sdk.md.txt).
- For more information about deployment tooling, review the [SQL Connect CLI reference](https://firebase.google.com/docs/sql-connect/cli-reference.md.txt) and [SQL Connect configuration file reference](https://firebase.google.com/docs/sql-connect/configuration-reference.md.txt).