What / Why

Adds cloud-sql as a supported DatabaseIntegrationType in the @deepnote/database-integrations package.

This is the upstream schema extraction for the Cloud SQL integration — vscode-deepnote#406 added a local shim with the comment "Pending addition to @deepnote/database-integrations; remove once the package includes 'cloud-sql'." This PR fulfils that.

Changes

• database-integration-types.ts — 'cloud-sql' added to sqlIntegrationTypes
• database-integration-metadata-schemas.ts — cloudSqlMetadataSchema (service_account: z.string(), consistent with Spanner/BigQuery convention)
• database-integration-config.ts — config union member added
• secret-field-paths.ts — 'cloud-sql': ['service_account'] (service account JSON is a secret)
• database-integration-env-vars.ts — case 'cloud-sql': return null (Cloud SQL connects via the cloud-sql-python-connector, not a plain SQLAlchemy URL — satisfies the exhaustiveness check)
• integrations-prompts/cloud-sql.ts — new CLI prompt (single service_account field, modelled on Spanner)
• add-integration.ts + edit-integration.ts — import + switch case wired in
• database-integration-metadata-schemas.test.ts — 2 new test cases

Why cloud-sql produces no SQLAlchemy input

How integrations normally reach the runtime. For a SQL integration, getEnvVarForSqlCells (database-integration-env-vars.ts) calls getSqlAlchemyInput and, only if it returns a non-null { url, params, param_style }, emits an env var. The deepnote-toolkit runtime reads that env var and feeds the triple straight into SQLAlchemy: execute_sql → _query_data_source → create_engine(url, **params, pool_pre_ping=True) (deepnote_toolkit/sql/sql_execution.py:506). So url has to be a DSN that create_engine can dial directly, e.g. postgresql://user:pass@host:port/db.

Cloud SQL has no such DSN. A Cloud SQL instance isn't addressable by a static host:port URL — you connect through the Cloud SQL Python Connector (from google.cloud.sql.connector import Connector), which resolves the instance (project:region:instance), performs the IAM/TLS handshake using the service account, and hands SQLAlchemy a creator callable instead of a URL (see docs/google-cloud-sql.md). There is no url + params pair that captures that flow, so there is nothing valid for getSqlAlchemyInput to emit — hence return null.

Why null specifically (not a placeholder URL). Returning null makes getEnvVarForSqlCells skip the env var entirely (the new test asserts getSqlAlchemyInputVar(envVars, 'my-cloud-sql') is undefined). Emitting a half-formed URL would instead make the toolkit call create_engine on a DSN it can't dial and fail at query time. null cleanly means "no platform-injected engine; the connection is established in-notebook via the connector," which matches the documented Cloud SQL workflow today.

The toolkit gates this too. The toolkit bundles sqlalchemy-spanner and sqlalchemy-bigquery (pyproject.toml), so those can build engines from a Google-specific URL — Spanner emits spanner+spanner:///projects/<id>/instances/<instance>/databases/<db>, BigQuery emits bigquery:// with credentials_info in params. The toolkit does not ship cloud-sql-python-connector and has no google.cloud.sql import, so even a correct URL would have no driver to consume it. The closest existing precedent in this same file is BigQuery federated auth, which already return nulls when the platform can't construct a URL (database-integration-env-vars.ts:611, plus the federated-auth guard at :140). cloud-sql follows that shape; a full connector-backed implementation (toolkit + env-var) is a follow-up.

How to review

Start with database-integration-types.ts (one-liner), then database-integration-metadata-schemas.ts, then secret-field-paths.ts, then database-integration-env-vars.ts. The CLI files (add-integration.ts, edit-integration.ts, cloud-sql.ts) follow the exact same pattern as Spanner.

Testing

• Typecheck: clean (tsc --noEmit across all packages)
• Unit tests: 227/227 pass in @deepnote/database-integrations; all pass in @deepnote/cli when run in isolation
• Build: succeeds (ESM + CJS + types)
• CLI prompt (promptForFieldsCloudSql): not manually run, but covered by typecheck — follows the Spanner pattern exactly
• Note: some pre-existing add-integration tests are intermittently flaky under parallel local execution (unrelated to this diff); CI is unaffected

Risks

• Safe: purely additive, no existing behaviour changed
• The return null in env-vars is intentional — Cloud SQL connects via the Cloud SQL Python Connector rather than a SQLAlchemy URL, mirroring how BigQuery federated auth already returns null (see Why cloud-sql produces no SQLAlchemy input above). A full connector-backed implementation (toolkit + env-var) is a follow-up.

Next step

Once this merges and @deepnote/database-integrations publishes a new version, vscode-deepnote#406 can be updated to remove the local shim and consume the package directly.

Summary by CodeRabbit

• New Features
  • Added Cloud SQL database integration support, allowing users to create and manage Cloud SQL connections through the CLI with service account-based authentication.
  • CLI now supports adding and editing Cloud SQL integrations with streamlined configuration workflows for service account credentials.
  • Added comprehensive validation and environment variable handling for Cloud SQL integration configurations.