cloud-sql-execute
Advanced tools
A CLI tool that executes SQL statements using Google Cloud SQL Admin API's ExecuteSql method
A CLI tool that executes SQL statements using Google Cloud SQL Admin API's ExecuteSql method. Like Cloud SQL Studio, it allows direct SQL execution against Cloud SQL instances.
Built with Commander.js for maintainable TypeScript implementation.
This package exists because the cloudsql.instances.executeSql API of Google Cloud SQL Admin API v1beta4 is not implemented in the official Google Cloud Node.js SDK client. This package will become unnecessary once the ExecuteSQL API is implemented in the official SDK.
At the time of this library implementation, the ExecuteSQL API has no official documentation.
bunx cloud-sql-execute --help
npx cloud-sql-execute --help
npm install -g cloud-sql-execute
# or
bun install -g cloud-sql-execute
git clone https://github.com/k2wanko/cloud-sql-execute.git
cd cloud-sql-execute
bun install
Uses Google Cloud Application Default Credentials:
gcloud auth application-default login
# Basic usage (auto-detect project ID, results only)
bunx cloud-sql-execute -i INSTANCE_ID -d DATABASE_NAME -u USERNAME --password PASSWORD "SELECT 1"
# Run with verbose logging
bunx cloud-sql-execute -i INSTANCE_ID -d DATABASE_NAME -u USERNAME --password PASSWORD -v "SELECT 1"
# Use IAM authentication (auto-detect project ID)
bunx cloud-sql-execute -i INSTANCE_ID -d DATABASE_NAME --auto-iam-authn "SELECT 1"
# Use access token (with verbose logging)
bunx cloud-sql-execute -i INSTANCE_ID -d DATABASE_NAME --access-token TOKEN -v "SELECT 1"
Set up environment variables to minimize command line arguments:
# Set common configuration
export CLOUD_SQL_INSTANCE=my-instance
export CLOUD_SQL_DATABASE=postgres
export CLOUD_SQL_AUTO_IAM_AUTHN=true
# Now you can run with minimal command
bunx cloud-sql-execute "SELECT 1"
# Or with database authentication
export CLOUD_SQL_USER=myuser
export CLOUD_SQL_PASSWORD=mypass
unset CLOUD_SQL_AUTO_IAM_AUTHN # Remove IAM auth
bunx cloud-sql-execute "SELECT * FROM users LIMIT 5"
# Verbose mode with environment variable
export CLOUD_SQL_VERBOSE=true
bunx cloud-sql-execute "SELECT version()"
Command line arguments take precedence over environment variables:
# Use env vars for common settings, override specific ones
export CLOUD_SQL_INSTANCE=my-instance
export CLOUD_SQL_DATABASE=postgres
export CLOUD_SQL_AUTO_IAM_AUTHN=true
# Override database for this specific query
bunx cloud-sql-execute -d test_db "SELECT 1"
-p, --project: Google Cloud Project ID (optional, auto-detects if not specified)-i, --instance: Cloud SQL Instance ID (required)-d, --database: Database name (required)-u, --user: Database username--password: Database password--access-token: IAM access token for authentication--secret-path: Secret Manager password reference path--auto-iam-authn: Use IAM authentication (API caller identity)-f, --format: Output format (json|text, default: text)-l, --limit: Maximum number of rows to return-v, --verbose: Enable verbose logging-h, --help: Show help message| Variable | Description | Type | Example |
|---|---|---|---|
GOOGLE_CLOUD_PROJECT | Google Cloud Project ID | string | my-project |
CLOUD_SQL_INSTANCE | Cloud SQL Instance ID (required) | string | my-instance |
CLOUD_SQL_DATABASE | Database name | string | postgres |
CLOUD_SQL_USER | Database username | string | myuser |
CLOUD_SQL_PASSWORD | Database password | string | mypass |
CLOUD_SQL_ACCESS_TOKEN | IAM access token | string | ya29.c.b0A... |
CLOUD_SQL_SECRET_PATH | Secret Manager path | string | projects/.../secrets/.../versions/latest |
CLOUD_SQL_AUTO_IAM_AUTHN | Enable IAM authentication | boolean | true or 1 |
CLOUD_SQL_FORMAT | Output format | string | json or text |
CLOUD_SQL_LIMIT | Maximum rows to return | number | 100 |
CLOUD_SQL_VERBOSE | Enable verbose logging | boolean | true or 1 |
Note: Command line arguments take precedence over environment variables.
cloud-sql-execute -p PROJECT_ID -i INSTANCE_ID "SELECT 1"
chmod +x index.ts
./index.ts -p PROJECT_ID -i INSTANCE_ID "SELECT 1"
This tool uses Google Cloud SQL Admin API's sql.instances.executeSql method.
This API is used internally by Cloud SQL Studio but currently has no official documentation.
$ bunx cloud-sql-execute -p my-project -i my-instance -d postgres -u myuser --password mypass "SELECT 1 as one, 'Hello' as greeting"
one greeting
------------
1 Hello
When project ID is not specified, the tool attempts auto-detection in this order:
GOOGLE_CLOUD_PROJECT environment variableIf auto-detection fails, explicitly specify the project ID with -p/--project option.
This CLI tool supports two log levels:
$ bunx cloud-sql-execute -i my-instance -d my-db --auto-iam-authn "SELECT 1"
?column?
--------
1
-v/--verbose)$ bunx cloud-sql-execute -i my-instance -d my-db --auto-iam-authn -v "SELECT 1"
[07:21:28] INFO: No project specified, attempting to detect default project...
[07:21:28] INFO: Using detected project: my-project
[07:21:28] INFO: Executing SQL on my-project/my-instance...
?column?
--------
1
[07:21:29] INFO: Execution time: 0.000832622s
This CLI tool supports 3 working authentication methods:
# Auto-detect project ID
bunx cloud-sql-execute -i INSTANCE_ID -d DATABASE_NAME -u USERNAME --password PASSWORD "SELECT 1"
# Explicit project ID
bunx cloud-sql-execute -p PROJECT_ID -i INSTANCE_ID -d DATABASE_NAME -u USERNAME --password PASSWORD "SELECT 1"
bunx cloud-sql-execute -i INSTANCE_ID -d DATABASE_NAME --auto-iam-authn "SELECT 1"
bunx cloud-sql-execute -i INSTANCE_ID -d DATABASE_NAME --access-token $(gcloud auth print-access-token) "SELECT 1"
# This method is currently not working (as of January 27, 2025)
# bunx cloud-sql-execute -i INSTANCE_ID -d DATABASE_NAME -u USERNAME --secret-path projects/PROJECT_ID/secrets/db-password/versions/latest "SELECT 1"
--auto-iam-authn, the API caller must be an IAM user in the database--secret-path) is not supported by the Cloud SQL Admin API ExecuteSql method, despite being defined in the API specification. The API returns "Credential for the user cannot be empty" error when attempting to use Secret Manager paths.# Global installation from npm
npm install -g cloud-sql-execute
# Or use directly with bunx/npx
bunx cloud-sql-execute [options] "<query>"
npx cloud-sql-execute [options] "<query>"
# Development installation
git clone https://github.com/k2wanko/cloud-sql-execute.git
cd cloud-sql-execute
bun install
bun run index.ts [options] "<query>"
FAQs
A CLI tool that executes SQL statements using Google Cloud SQL Admin API's ExecuteSql method
The npm package cloud-sql-execute receives a total of 9 weekly downloads. As such, cloud-sql-execute popularity was classified as not popular.
We found that cloud-sql-execute demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Four npm packages disguised as cryptographic tools steal developer credentials and send them to attacker-controlled Telegram infrastructure.
Security News
Ruby maintainers from Bundler and rbenv teams are building rv to bring Python uv's speed and unified tooling approach to Ruby development.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.