Running the Cloud SQL Proxy as a Windows Service

The Cloud SQL proxy provides fast, secure, encrypted connections to Cloud SQL database instances, without any need to manage allowed IP addresses or SSL/TLS configuration details. It’s a small self-contained executable that you can download for free, and it uses IAM authentication for simple role-based access management. The proxy is great for local development and testing, because once it’s running all your code and client tools can connect to 127.0.0.1 to access your databases instances.

If you’ve done much Cloud SQL development, however, you know that it’s easy to forget that bit about “just need to have it running.” If you forget to launch the proxy before testing locally, your code will eventually time out with an error message from your SQL driver. The exact error may vary depending on the driver, and a misleading error message can lead to even more wasted time.

Wouldn’t it be great if instead you could just have the proxy running at all times as a background service, listening on 127.0.0.1 and ready for new connections? Even better, wouldn’t it be great if that service would gracefully restart in the event of errors or reboots?

You can have the proxy work this way, and in this post I’ll show you how easy it is to set up. This is a great way to go if you’re doing Cloud SQL development on a Windows machine — you can invoke the proxy once, and it will keep running and managing connections until you explicitly stop it with a net stop command. This approach combines the benefits of a fully managed service with the convenience of a local database.

Getting Started

If you want to follow along with the example covered here, follow the instructions in my Cloud SQL Setup post to create a database instance and service account. Be sure to download the JSON credentials file as covered there, because you’ll need it for authenticating with the proxy.

I’ll use a Cloud SQL for SQL Server instance for this example, although the core principles apply to other Cloud SQL database instance types such as MySQL or PostgreSQL.

If you already have a SQL Server database, you can migrate it to Cloud SQL and connect via the proxy as covered below. See Migrate your Microsoft SQL Server workloads to Google Cloud for simple step-by-step instructions on how to migrate from an in-house service or another cloud service.

Installing the proxy as a service

Cloud SQL proxy executable doesn’t currently provide native support for running as a Windows services, but that isn’t a problem because there are a variety of open source service managers that you can use to install any Windows executable as a service.

My favorite is NSSM, “the Non-Sucking Service Manager.” Unlike most third-party service managers, NSSM can monitor a running service and automatically restart it if it stops responding. It also offers a simple GUI for configuration, as well as command-line options for automated configuration.

You can download NSSM here, and documentation is available here. Put the nssm.exe executable in a folder with the Cloud SQL proxy executable and your service account’s JSON credentials file, and you’re ready to get started.

Administrator access is required for creating and managing Windows services, so right-click on the Start button and select Windows PowerShell (Admin). Then use this command to create a new service:

.\nssm.exe install <servicename>

A graphical user interface will open, to guide you through configuring the new service. There are several tabs with a variety of options, but for installing the Cloud SQL proxy you’ll only need to enter the Path, Startup directory, and Arguments options on the Application tab.

configuring the Cloud SQL proxy as a Windows service

The arguments option is set to the proxy’s command line arguments: the name of the database instance, the port number (1433 in this example, because that’s the default for SQL Server), and the name of the credentials file. Here’s the syntax:

-instances=<instance-name>=tcp:1433 -credential_file=<filename>.json

Note that we’re assuming here that the credentials file is in the same folder as the proxy executable. If it’s in a different folder, you’ll need to specify the full path to it in the credential_file argument.

Select Install service, and you should get a message saying the service was installed successfully.

Starting the service

The service is installed now, but not yet started. As the final setup step, use this command at the Administrator prompt to start the service:

net start <service-name>

That’s all there is to it! The proxy is now running and listening for connections (at 127.0.0.1:1433 in this example). It will automatically restart if needed, including after rebooting the machine.

To verify that the service is running, you can use PowerShell’s Get-Service cmdlet. The output can be quite long, because it includes every service currently running, but you can use a where clause to show the status of a named service as shown below.

displaying the status of a service with Get-Service

Using the proxy service

Once the proxy is running as a service, any other program or process on your machine can communicate with Cloud SQL at 127.0.0.1. For example, here’s a sample that writes random names and locations to tables and then runs a query to retrieve them:

example of local code connecting to Cloud SQL via the proxy running as a Windows service

The connection for that sample uses a SQL Server ODBC driver to connect as shown here:

CNXN = pyodbc.connect(
    “DRIVER={ODBC Driver 17 for SQL Server};SERVER=127.0.0.1;”+
    f”UID={DB_USER};PWD={DB_PASS}”,
    autocommit=True,
)
CURSOR = CNXN.cursor()

You can also connect from tools such as SQL Server Management Studio (SSMS):

SSMS connecting to the proxy running locally as a Windows service

After connecting as shown above, SSMS can run queries and manage database objects:

running a SQL query with SSMS

Stopping and removing the service

To stop the proxy service, use this command in a PowerShell admin prompt:

net stop <service-name>

The service is still installed and configured, so you can use net start to restart it if needed.

To remove the service permanently, use this NSSM command:

.\nssm.exe remove <service-name> confirm

Finally, a word of caution: the proxy uses secure encryption to communicate with your Cloud SQL instance, but the local connection to the proxy at 127.0.0.1 is not encrypted. This isn’t an issue in the scenarios covered above, because we’re working on the Windows machine locally, but you should avoid exposing the proxy on a network that you don’t trust. To learn more about best practices when connecting from external applications, see the documentation on connecting from an external application using the proxy.