This page provides an overview of PGAdapter. To learn how to start PGAdapter,seeStarting PGAdapter.

PGAdapter is a sidecar proxy which is a small application that runsalongside your main application to support communications between thePostgreSQL interface for Spanner and Spanner.For Java applications you can even link PGAdapter to the applicationdirectly without having to run it in a separate process. PGAdapter isdesigned to run on the same machine as the application and exposes anendpoint on localhost that supports the PostgreSQL wire protocol. Ittranslates the PostgreSQL wire protocol into the Spanner wireprotocol, gRPC. With this proxy running locally, a PostgreSQL clientsuch aspsql can connect to a PostgreSQL-dialect Spannerdatabase.

PGAdapter adds, at most, 0.2 ms of latency overhead. ThePostgreSQL interface has the same latency levels asGoogleSQL.

Note:PostgreSQL drivers and ORMs lists all clients that PGAdapter supports.

The following diagram shows howpsql connects to Spanner throughPGAdapter.

PGAdapter supports basic and extended query modes, andsupports any data type that the PostgreSQL interface for Spanner supports.

PGAdapter execution environments

You can run PGAdapter by using one of the following methods:

• Standalone: PGAdapter is supplied as a JAR file and runsstandalone in the JVM.
• Docker. PGAdapter is also packaged as a Docker image.
• Cloud Run: PGAdapter can be deployed as a sidecar proxyon Cloud Run.
• Sidecar proxy: a typical use as a sidecar proxy is in a Kubernetescluster.
• In-process: your Java application code can use the supplied JAR file tocreate and start a PGAdapter instance.

For details about these methods, seeStart PGAdapter.

Authorization with PGAdapter

PGAdapter determines the service account or other Identity and Access Management(IAM) principal to use for the connection by examining thecredentials that you specify when you start it. The IAMpermissions granted to that principal determine the permissions that theconnecting application has on the database.

When fine-grained access control is in use, you can optionally specify adatabase role when you start PGAdapter. If you specify a database role,then PGAdapter uses fine-grained access control when it sends requests for queriesand DML statements. This requires the IAM permissionspanner.databases.useRoleBasedAccess and, for database roles other thanpublic, thespanner.databaseRoles.use permission. The privileges granted tothe database role determine the operations that the connecting application canperform. If you don't specify a database role, then the database-levelpermissions that are granted to the IAMprincipal are used. To perform DDL statements, the principal must have thespanner.databases.updateDdl permission.

For more information, seeAbout fine-grained access control andAccess control with IAM.

What's next

• Start PGAdapter
• Learn more about thePGAdapter GitHub repository.
• Learn more aboutPostgreSQL drivers and ORMsfor a table of PostgreSQL drivers and ORMs that PGAdaptersupports.