add ability to deploy only service config changes (no sync config)

Author: stevensJourney

cli/README.md

@@ -231,6 +231,7 @@ See [docs/usage.md](../docs/usage.md) for full usage and resolution order (flags
 - [`powersync autocomplete [SHELL]`](#powersync-autocomplete-shell)
 - [`powersync commands`](#powersync-commands)
 - [`powersync deploy`](#powersync-deploy)
+- [`powersync deploy service-config`](#powersync-deploy-service-config)
 - [`powersync deploy sync-config`](#powersync-deploy-sync-config)
 - [`powersync destroy`](#powersync-destroy)
 - [`powersync docker configure`](#powersync-docker-configure)
@@ -354,6 +355,7 @@ DESCRIPTION
   Deploy local config (service.yaml, sync config) to the linked PowerSync Cloud instance.
   Validates connections and sync config before deploying.
   See also powersync deploy sync-config to deploy only sync config changes.
+  See also powersync deploy service-config to deploy only service config changes.
 
 EXAMPLES
   $ powersync deploy
@@ -363,6 +365,43 @@ EXAMPLES
 
 _See code: [src/commands/deploy/index.ts](https://github.com/powersync-ja/powersync-js/blob/v0.0.0/src/commands/deploy/index.ts)_
 
+## `powersync deploy service-config`
+
+[Cloud only] Deploy only local service config to the linked Cloud instance.
+
+```
+USAGE
+  $ powersync deploy service-config [--deploy-timeout <value>] [--directory <value>] [--instance-id <value> --project-id
+    <value>] [--org-id <value>]
+
+FLAGS
+  --deploy-timeout=<value>  [default: 300] Seconds to wait after scheduling a deploy before timing out while polling
+                            status (default 300 seconds).
+
+PROJECT FLAGS
+  --directory=<value>  [default: powersync] Directory containing PowerSync config. Defaults to "powersync". This is
+                       required if multiple powersync config files are present in subdirectories of the current working
+                       directory.
+
+CLOUD_PROJECT FLAGS
+  --instance-id=<value>  PowerSync Cloud instance ID. Manually passed if the current context has not been linked.
+  --org-id=<value>       Organization ID (optional). Defaults to the token’s single org when only one is available; pass
+                         explicitly if the token has multiple orgs.
+  --project-id=<value>   Project ID. Manually passed if the current context has not been linked.
+
+DESCRIPTION
+  [Cloud only] Deploy only local service config to the linked Cloud instance.
+
+  Deploy only service config changes (without sync config updates).
+
+EXAMPLES
+  $ powersync deploy service-config
+
+  $ powersync deploy service-config --instance-id=<id> --project-id=<id>
+```
+
+_See code: [src/commands/deploy/service-config.ts](https://github.com/powersync-ja/powersync-js/blob/v0.0.0/src/commands/deploy/service-config.ts)_
+
 ## `powersync deploy sync-config`
 
 [Cloud only] Deploy only local sync config to the linked Cloud instance.

cli/src/commands/deploy/index.ts

@@ -1,5 +1,6 @@
 import { Flags, ux } from '@oclif/core';
 import { CloudInstanceCommand, SERVICE_FILENAME } from '@powersync/cli-core';
+import { ServiceCloudConfigDecoded } from '@powersync/cli-schemas';
 import { routes } from '@powersync/management-types';
 import ora from 'ora';
 
@@ -13,7 +14,8 @@ export default class DeployAll extends CloudInstanceCommand {
   static description = [
     'Deploy local config (service.yaml, sync config) to the linked PowerSync Cloud instance.',
     'Validates connections and sync config before deploying.',
-    `See also ${ux.colorize('blue', 'powersync deploy sync-config')} to deploy only sync config changes.`
+    `See also ${ux.colorize('blue', 'powersync deploy sync-config')} to deploy only sync config changes.`,
+    `See also ${ux.colorize('blue', 'powersync deploy service-config')} to deploy only service config changes.`
   ].join('\n');
   static examples = [
     '<%= config.bin %> <%= command.id %>',
@@ -87,6 +89,23 @@ export default class DeployAll extends CloudInstanceCommand {
       });
   }
 
+  override parseConfig(projectDirectory: string): ServiceCloudConfigDecoded {
+    const config = super.parseConfig(projectDirectory);
+
+    /**
+     * This is a temporary hack to maintain compatibilty with the PowerSync Dashboard.
+     * The dashboard requires replication connections to have a name field set.
+     * This is not enforced by the management service.
+     */
+    for (const [index, connection] of config.replication?.connections?.entries() ?? []) {
+      if (!connection.name) {
+        connection.name = `Default${index > 0 ? `_${index}` : ''}`;
+      }
+    }
+
+    return config;
+  }
+
   async run(): Promise<void> {
     const { flags } = await this.parse(DeployAll);
 

cli/src/commands/deploy/service-config.ts

@@ -0,0 +1,39 @@
+import { DEFAULT_DEPLOY_TIMEOUT_MS } from '../../api/cloud/wait-for-operation.js';
+import DeployAll from './index.js';
+
+export default class DeployServiceConfig extends DeployAll {
+  static description = 'Deploy only service config changes (without sync config updates).';
+  static examples = [
+    '<%= config.bin %> <%= command.id %>',
+    '<%= config.bin %> <%= command.id %> --instance-id=<id> --project-id=<id>'
+  ];
+  static flags = {
+    ...DeployAll.flags
+  };
+  static summary = '[Cloud only] Deploy only local service config to the linked Cloud instance.';
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(DeployServiceConfig);
+
+    const project = await this.loadProject(flags, {
+      // local service config is required for this command
+      configFileRequired: true
+    });
+
+    const deployTimeoutMs = (flags['deploy-timeout'] ?? DEFAULT_DEPLOY_TIMEOUT_MS / 1000) * 1000;
+
+    // Parse and store for later
+    this.parseConfig(project.projectDirectory);
+
+    // The existing config is required to deploy changes. The instance should have been created already.
+    const cloudConfigState = await this.loadCloudConfigState();
+
+    this.log('Performing validations before deploy...');
+    await this.validateServiceConfig({ cloudConfigState });
+    await this.testConnections();
+
+    this.log('Validations completed successfully.\n');
+
+    await this.deployAll({ cloudConfigState, deployTimeoutMs, updateSyncConfig: false });
+  }
+}

docs/usage.md

@@ -37,6 +37,10 @@ Use separate config directories (e.g. `powersync`, `powersync-dev`, `powersync-s
 powersync deploy --directory=powersync          # production (linked in powersync/cli.yaml)
 powersync deploy --directory=powersync-dev     # dev (linked in powersync-dev/cli.yaml)
 powersync deploy --directory=powersync-staging # staging (linked in powersync-staging/cli.yaml)
+
+# Optional targeted deploys:
+powersync deploy service-config --directory=powersync   # service.yaml only (keeps cloud sync config)
+powersync deploy sync-config --directory=powersync      # sync-config.yaml only
 ```
 
 **Single directory and link file, with `!env` substitution**
@@ -90,8 +94,18 @@ powersync link cloud --create --project-id=<project-id>
 # If your token has multiple orgs: add --org-id=<org-id>
 powersync validate
 powersync deploy
+
+# Optional targeted deploys:
+powersync deploy service-config
+powersync deploy sync-config
 ```
 
+Deploy command modes:
+
+- `powersync deploy` — deploy both service config and sync config.
+- `powersync deploy service-config` — deploy only service config changes, without updating sync config.
+- `powersync deploy sync-config` — deploy only sync config changes.
+
 The instance **name** and **region** are taken from your local `service.yaml`; set them before running `powersync link cloud --create` if you want a specific display name and region.
 
 ## Using an existing Cloud instance
@@ -108,8 +122,14 @@ powersync pull instance --project-id=<project-id> --instance-id=<instance-id>
 # Edit the YAML files in powersync/ as needed
 powersync validate
 powersync deploy
+
+# Optional targeted deploys:
+powersync deploy service-config
+powersync deploy sync-config
 ```
 
+When you only changed one file, prefer a targeted deploy command to reduce unnecessary updates.
+
 If the config directory already exists and is linked, you can run **`powersync pull instance`** without passing IDs to refresh the local config from the cloud.
 
 ## Executing commands on an instance (no local config management)
@@ -202,7 +222,7 @@ If you decline this prompt, login exits without storing a token. Use `TOKEN` in
 
 # Supplying Linking Information for Cloud and Self-Hosted Commands
 
-Cloud and self-hosted commands need instance (and for Cloud, org and project) identifiers. **Cloud only:** `powersync deploy`, `powersync destroy`, `powersync stop`, `powersync fetch config`, `powersync pull instance`. **Both:** `powersync fetch status`, `powersync generate schema`, `powersync generate token`, `powersync validate`. The same three methods apply: the CLI uses the first that is available for each field (flags override environment variables, environment variables override link file). For Cloud, **org_id is optional**: when not set via flags, env, or link file, the CLI fetches the token’s organizations and uses the single org if there is exactly one; if the token has multiple orgs, the command errors and you must pass `--org-id` (or set `ORG_ID`).
+Cloud and self-hosted commands need instance (and for Cloud, org and project) identifiers. **Cloud only:** `powersync deploy`, `powersync deploy service-config`, `powersync deploy sync-config`, `powersync destroy`, `powersync stop`, `powersync fetch config`, `powersync pull instance`. **Both:** `powersync fetch status`, `powersync generate schema`, `powersync generate token`, `powersync validate`. The same three methods apply: the CLI uses the first that is available for each field (flags override environment variables, environment variables override link file). For Cloud, **org_id is optional**: when not set via flags, env, or link file, the CLI fetches the token’s organizations and uses the single org if there is exactly one; if the token has multiple orgs, the command errors and you must pass `--org-id` (or set `ORG_ID`).
 
 1. **Flags**
    - **Cloud:** `--instance-id`, `--project-id` (required when using instance-id), `--org-id` (optional; defaults to token’s single org)