Skip to main content
emisar

Google Cloud SQL diagnostics and recovery

v0.3.4

Cloud SQL diagnostics for instances, databases, users, backups, operations, server CA certificates, and Query Insights query rankings, plus governed instance restart and high-availability failover. Fixed projections omit passwords, replication credentials, database-flag values, labels, descriptions, and certificate PEM. Mutations return their operation without waiting and are polled with gcp.sql_operation_describe.

9 allowed by default 2 need approval by default
Pack ID
gcp-cloudsql
Vendor
emisar
OS
linux
Actions
11
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
gcloud jq curl

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install gcp-cloudsql --hash sha256:09f16c5b7b9f327369f4920b08045612ca0e39cac8634679eec55e274cfaf120

Setup

Drives gcloud and projects Cloud SQL API responses locally before they leave the runner. Authenticate gcloud before loading the pack.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

  • CLOUDSDK_CONFIG

    Optional gcloud configuration directory.

  • CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE

    Optional credential file that overrides the active gcloud account.

Notes

  • Grant least privilege for the actions you enable: reads need roles/cloudsql.viewer or equivalent; restart and failover need cloudsql.instances.restart and cloudsql.instances.failover (both in roles/cloudsql.editor).
  • Actions use mode-0600 temporary response files so gcloud failures remain distinguishable from jq failures; files are removed before exit.
  • Database query execution, log contents, auth tokens, client certificates, and credential retrieval are excluded.
  • gcp.sql_query_insights additionally needs roles/monitoring.viewer: Query Insights has no Cloud SQL Admin API surface, so it is read from the Cloud Monitoring API rather than gcloud. It returns Query Insights' own normalized query text, in which literals are already replaced by placeholders, and never executes a query or reads log contents.
  • Query Insights must be enabled on the instance (settings.insightsConfig, reported by gcp.sql_instance_describe) or the ranking is empty; shared-core tiers may not support it.
  • This remote-target pack declares no host detection signal and is never auto-suggested merely because gcloud is installed.

Verify it works

Runs gcp.sql_instances, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify gcp-cloudsql

Install and configure a pack walks through the whole sequence on a host.

Actions 11 total

View on GitHub
  • gcp.sql_backups script low Low — read-only or trivially reversible

    gcloud sql backups list

    List bounded Cloud SQL backup status, type, location, version, and timing.

    View source on GitHub
  • gcp.sql_databases script low Low — read-only or trivially reversible

    gcloud sql databases list

    List bounded database names, charset, collation, and SQL Server details for one instance.

    View source on GitHub
  • gcp.sql_instance_describe script low Low — read-only or trivially reversible

    gcloud sql instances describe

    Show one Cloud SQL instance's engine, HA, networking, backup, maintenance, and capacity summary.

    View source on GitHub
  • gcp.sql_instance_failover script high High — service-affecting

    gcloud sql instances failover

    Fail one high-availability (REGIONAL) Cloud SQL primary over to its standby in the secondary zone. Connections are dropped and writes pause until the standby is serving; only works on an instance with REGIONAL availability. Returns the Cloud SQL operation immediately without waiting; poll gcp.sql_operation_describe until it reports DONE.

    View source on GitHub
  • gcp.sql_instance_restart script high High — service-affecting

    gcloud sql instances restart

    Restart one Cloud SQL instance. Every connection is dropped and the database is unavailable until the restart completes. Returns the Cloud SQL operation immediately without waiting; poll gcp.sql_operation_describe until it reports DONE.

    View source on GitHub
  • gcp.sql_instances script low Low — read-only or trivially reversible

    gcloud sql instances list

    List bounded Cloud SQL engine, HA, networking, backup, maintenance, and capacity summaries.

    View source on GitHub
  • gcp.sql_operation_describe script low Low — read-only or trivially reversible

    gcloud sql operations describe

    Show one Cloud SQL operation's type, target, status, timing, and error codes.

    View source on GitHub
  • gcp.sql_operations script low Low — read-only or trivially reversible

    gcloud sql operations list

    List bounded recent Cloud SQL operation type, target, status, timing, and error codes.

    View source on GitHub
  • gcp.sql_query_insights script low Low — read-only or trivially reversible

    Show the top Cloud SQL queries by Query Insights metric

    Show the normalized PostgreSQL queries ranked highest by one Query Insights metric over a recent window — total execution, I/O or lock time, rows or shared-block accesses, or p50/p95/p99 latency. This is the read that names which query is spending the instance's time.

    View source on GitHub
  • gcp.sql_server_ca_certs script low Low — read-only or trivially reversible

    gcloud sql ssl server-ca-certs list

    List bounded Cloud SQL server CA identity, type, fingerprint, and expiry without certificate PEM.

    View source on GitHub
  • gcp.sql_users script low Low — read-only or trivially reversible

    gcloud sql users list

    List bounded Cloud SQL user identities, hosts, types, and password-policy state without passwords.

    View source on GitHub
← Back to registry
Pack reference  Publish your own