# Cloud SQL

> Run Cloud SQL locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/cloud-sql/

Cloud SQL is a managed relational database service. LocalCloud exposes supported instance, database, and user APIs with local PostgreSQL and MySQL engines for application tests.

## Typical uses

Use when your application relies on a relational schema, SQL migrations, and transactions through PostgreSQL or MySQL drivers. Test database and user provisioning alongside application queries.

Examples

- Relational application backends
- Database provisioning and migration tests

Connection

Environment variable

`CLOUD_SQL_EMULATOR_HOST=http://localhost:5380`

Runtime details

- **Endpoints:** HTTP/REST :5380 · PostgreSQL :5391 · MySQL :5406
- **Minimum tier:** Community
- **Persistence:** service-data
- **Implementation:** Local Facade

## Example usage

Service ID: `cloudsql`. Starts by default. Use an already running LocalCloud runtime for the examples below.

Export the local project and mapped endpoints in your client process, then use the client settings below. [First-time setup](https://local.cloud/docs/)

```bash
# Export GOOGLE_CLOUD_PROJECT and CLOUD_SQL_EMULATOR_HOST
eval "$(localcloud env)"
```

REST gateway examples use the generated HTTP address in `SERVICE_USAGE_EMULATOR_HOST`; native SDKs can use a different protocol.

Java · REST:

### Java · REST

### List SQL instances

List SQL instances; Cloud SQL provides relational databases for application queries, migrations, and transactions.

Call the Google Cloud REST API with the JDK HTTP client. Requires JDK 17+. Results reflect resources already created in your local project.

Discovery check · reads existing local state.

#### Save as Hello.java

```java
import java.net.URI;
import java.net.http.*;
import java.time.Duration;
import java.util.Objects;

public class Hello {
  public static void main(String[] args) throws Exception {
    var project = Objects.requireNonNull(System.getenv("GOOGLE_CLOUD_PROJECT"));
    var endpoint = Objects.requireNonNull(System.getenv("SERVICE_USAGE_EMULATOR_HOST"));
    var url = URI.create(endpoint.replaceAll("/+$", "") + "/sql/v1beta4/projects/" + project + "/instances");
    var request = HttpRequest.newBuilder(url).timeout(Duration.ofSeconds(30)).GET().build();
    var client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
    var response = client.send(request, HttpResponse.BodyHandlers.ofString());
    if (response.statusCode() >= 400) {
      throw new IllegalStateException(response.statusCode() + ": " + response.body());
    }
    System.out.println(response.body());
  }
}
```

#### Run the example

```bash
java Hello.java
```

#### Verify the result

The request succeeds. An empty list or no printed rows is valid before matching resources exist. Continue with the documented workflows for a resource test.

gcloud CLI:

### gcloud CLI

### List SQL instances

List SQL instances; Cloud SQL provides relational databases for application queries, migrations, and transactions.

Use the Google Cloud CLI against the local gateway in its default open IAM mode. Run these exports in a terminal dedicated to local development.

Discovery check · reads existing local state.

#### Configure gcloud CLI

```bash
: "${SERVICE_USAGE_EMULATOR_HOST:?Export the LocalCloud environment first}"
export CLOUDSDK_CORE_PROJECT="${GOOGLE_CLOUD_PROJECT:?Export the LocalCloud environment first}"
export CLOUDSDK_AUTH_DISABLE_CREDENTIALS=true
export CLOUDSDK_API_ENDPOINT_OVERRIDES_SQL="${SERVICE_USAGE_EMULATOR_HOST%/}/"
```

#### Run in your terminal

```bash
gcloud sql instances list
```

#### Verify the result

The request succeeds. An empty list or no printed rows is valid before matching resources exist. Continue with the documented workflows for a resource test.

Verify a resource workflow by creating isolated state, performing the operation, and reading the result back. Run cleanup even after a failure; delete only test-owned resources.

Connection failed? Check `localcloud status --verbose`, enabled services, and client exports. Stop accidental Google Cloud calls; correct local routing before retrying.

## Documented workflows

- ### Instance/database/user lifecycle; PostgreSQL and on-demand MySQL 8.4

    Create a local instance, database, and user, then connect through PostgreSQL or on-demand MySQL 8.4. Run a migration and assert rows through the native driver.

- ### Backup metadata CRUD and instance administration responses

    Create, list, and delete backup metadata and inspect instance administration responses. Export, import, restore, restart, and replica verbs return DONE without performing those data operations.

- ### Local server CA discovery and client certificate issuance

    With LocalCloud-generated TLS enabled, retrieve the engine CA and issue a client certificate, then verify the server through your driver. Operator-provided chains do not give LocalCloud a CA signing key.

## Service boundaries

- Shared engines; version labels, instance flags, and infrastructure settings do not provision separate servers
- Backups are metadata; export/import/restore/restart and replica verbs do no data work. Replace-restore and migration leave Cloud SQL untouched
- MySQL requires Docker access; project exports omit MySQL data, non-public PostgreSQL schemas, and passwords
- requireSsl/sslMode, revocation, and CA rotation are not enforced; PostgreSQL does not require client certificates

## Code examples and integrations

- [Provision resources with Terraform](https://local.cloud/docs/terraform/#supported-terraform-resources): Documented resources, provider configuration, and local routing setup.
- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

## Use Cloud SQL with an AI agent

Before the agent changes application logic, have it create local Cloud SQL state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

### Configure this repo

```
Set up this repository to use LocalCloud for local GCP development. First read https://local.cloud/ai/agents.md, then inspect this repo, identify the GCP services and SDK language, configure emulator environment variables, and run the narrowest integration test against localhost. Do not use real GCP credentials or production endpoints.
```

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

## Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud SQL documentation](https://docs.cloud.google.com/sql/docs/introduction): service concepts and cloud usage.