The AlloyDB Language Connectors are libraries that provide a simplified process to establish secure connections to your cluster use the following:
- Automated mTLS Connections
- Identity and Access Management (IAM)-based authorization support
- Automated IAM authentication
AlloyDB Language Connectors can't provide a network path to a AlloyDB cluster, if a network path isn't already present.
For more information about AlloyDB Language Connectors, see AlloyDB Language Connectors overview.
This page discusses the following AlloyDB Language Connectors:
- The AlloyDB Java Connector
- The AlloyDB Go Connector
- The AlloyDB Python Connector
Before you begin
Enable the AlloyDB Admin API.
Create an AlloyDB instance and configure the default user.
For more information about creating an instance, see Create a primary instance.
For more information about user roles, see Predefined AlloyDB IAM roles.
Configure the following roles and permissions required to connect to an AlloyDB instance:
- roles/alloydb.client
roles/serviceusage.serviceUsageConsumer
For more information about which roles and permissions are required, see Manage IAM authentication.
Install the AlloyDB Language Connectors
Java
The AlloyDB Java Connector is a library that provides IAM-based authorization and encryption when connecting to an AlloyDB instance.
Installation
For Maven, you can install the AlloyDB Java Connector by adding the following
to your project's pom.xml
:
<!-- Add the connector with the latest version -->
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>alloydb-jdbc-connector</artifactId>
<version>0.4.0</version>
</dependency>
<!-- Add the driver with the latest version -->
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>46.6.0<</version>
</dependency>
<!-- Add HikariCP with the latest version -->
<dependency>
<groupId>com.zaxxer</groupId>
<artifactId>HikariCP</artifactId>
<version>5.1.0</version>
</dependency>
For Gradle, you can install the AlloyDB Java Connector by including the following
in your project's gradle.build
:
// Add connector with the latest version
implementation group: 'com.google.cloud.alloydb', name: 'alloydb-jdbc-connector', version: '0.4.0'
// Add driver with the latest version
implementation group: 'org.postgresql', name: 'postgresql', version: '46.6.0'
// Add HikariCP with the latest version
implementation group: 'com.zaxxer', name: 'HikariCP', version: '5.1.0'
Python (pg8000)
The AlloyDB Python Connector is a library that can be used alongside a database driver to allow users with sufficient permissions to connect to an AlloyDB database without having to manually allowlist IPs.
Installation
You can install the AlloyDB Python Connector library with pip install
.
If you're using pg8000, then run the following command:
pip install "google-cloud-alloydb-connector[pg8000]" sqlalchemy
Python (asyncpg)
The AlloyDB Python Connector is a library that can be used alongside a database driver to allow users with sufficient permissions to connect to an AlloyDB database without having to manually allowlist IPs.
Installation
You can install the AlloyDB Python Connector library with pip install
.
If you're using asyncpg, then run the following command:
For asyncpg, use:
pip install "google-cloud-alloydb-connector[asyncpg]" "sqlalchemy[asyncio]"
For more information about async driver usage, see Async Driver Usage.
Go (pgx)
The AlloyDB Go Connector is an AlloyDB connector designed for use with the Go language.
Installation
You can install the AlloyDB Go Connector with go get
.
If you're using pgx, then run the following command:
go get github.com/jackc/pgx/v5
go get cloud.google.com/go/alloydbconn
Go (database/sql)
The AlloyDB Go Connector is an AlloyDB connector designed for use with the Go language.
Installation
You can install the AlloyDB Go Connector with go get
.
If you're using database/sql, then run the following command:
go get cloud.google.com/go/alloydbconn
Configure the AlloyDB Language Connectors
Java
To use the AlloyDB Java Connector to connect to your AlloyDB cluster, configure it using the following steps.
To use this snippet in the context of a web application, view the README on GitHub.
Use public IP
If you're using public IP to connect to your AlloyDB cluster, then include the following:
config.addDataSourceProperty("alloydbIpType", "PUBLIC");
Use Private Service Connect
If you're using Private Service Connect to connect to your AlloyDB instance, then include the following:
config.addDataSourceProperty("alloydbIpType", "PSC");
Automatic IAM authentication
By default, AlloyDB Language Connectors use built-in authentication. You can use automatic IAM authentication with the AlloyDB Java Connector. To enable, include the following:
config.addDataSourceProperty("alloydbEnableIAMAuth", "true");
Python (pg8000)
To use the AlloyDB Python Connector to connect to your AlloyDB
cluster, configure the connector using the following steps, if you're using pg8000
.
To use this snippet in the context of a web application, view the README on GitHub.
Use public IP
If you're using public IP to connect to your AlloyDB cluster, then replace your connection function the following:
def getconn() -> pg8000.dbapi.Connection:
conn: pg8000.dbapi.Connection = connector.connect(
inst_uri,
"pg8000",
user=user,
password=password,
db=db,
# use ip_type to specify public IP
ip_type=IPTypes.PUBLIC,
)
return conn
Use Private Service Connect
If you're using Private Service Connect to connect to your AlloyDB instance, then include the following:
def getconn() -> pg8000.dbapi.Connection:
conn: pg8000.dbapi.Connection = connector.connect(
inst_uri,
"pg8000",
user=user,
password=password,
db=db,
# use ip_type to specify PSC
ip_type=IPTypes.PSC,
)
return conn
Automatic IAM authentication
By default, AlloyDB Language Connectors use built-in authentication. You can use automatic IAM authentication with the AlloyDB Python Connector. To enable, replace your connection function with the following:
def getconn() -> pg8000.dbapi.Connection:
conn: pg8000.dbapi.Connection = connector.connect(
inst_uri,
"pg8000",
user=user,
password=password,
db=db,
# use enable_iam_auth to enable IAM authentication
enable_iam_auth=True,
)
return conn
Python (asyncpg)
To use the AlloyDB Python Connector to connect to your AlloyDB
cluster, configure the connector using the following steps, if you're using async
.
To use this snippet in the context of a web application, view the README on GitHub.
Use public IP
If you're using public IP to connect to your AlloyDB cluster, then replace your connection function with the following:
async def getconn() -> asyncpg.Connection:
conn: asyncpg.Connection = await connector.connect(
inst_uri,
"asyncpg",
user=user,
password=password,
db=db,
# use ip_type to specify public IP
ip_type=IPTypes.PUBLIC,
)
return conn
Use Private Service Connect
If you're using Private Service Connect to connect to your AlloyDB instance, then include the following:
async def getconn() -> asyncpg.Connection:
conn: asyncpg.Connection = await connector.connect(
inst_uri,
"asyncpg",
user=user,
password=password,
db=db,
# use ip_type to specify PSC
ip_type=IPTypes.PSC,
)
return conn
Automatic IAM authentication
By default, AlloyDB Language Connectors use built-in authentication. You can use automatic IAM authentication with the AlloyDB Python Connector. To enable, replace your connection function with the following:
async def getconn() -> asyncpg.Connection:
conn: asyncpg.Connection = await connector.connect(
inst_uri,
"asyncpg",
user=user,
password=password,
db=db,
# use enable_iam_auth to enable IAM authentication
enable_iam_auth=True,
)
return conn
Go (pgx)
To use the AlloyDB Go Connector to connect to your AlloyDB
cluster, configure the connetor using the following steps, if you're using pgx
.
To use this snippet in the context of a web application, view the README on GitHub.
Use public IP
If you're using public IP to connect to your AlloyDB cluster,
then replace your d.Dial
function with the following:
d.Dial(ctx, instURI, alloydbconn.WithPublicIP())
Use Private Service Connect
If you're using Private Service Connect to connect to your AlloyDB instance, then include the following:
d.Dial(ctx, instURI, alloydbconn.WithPSC())
Automatic IAM authentication
By default, AlloyDB Language Connectors use built-in authentication.
You can use automatic IAM authentication with the AlloyDB Go Connector. To enable, replace
the alloydbconn.NewDialer
function with the following:
d, err := alloydbconn.NewDialer(ctx, alloydbconn.WithIAMAuthN())
Go (database/sql)
To use the AlloyDB Go Connector to connect to your AlloyDB
cluster, configure the connector using the following steps, if you're using database/sql
.
To use this snippet in the context of a web application, view the README on GitHub.
Use public IP
If you're using public IP to connect to your AlloyDB cluster,
then replace your RegisterDriver
function with the following:
cleanup, err := pgxv5.RegisterDriver(
"alloydb",
alloydbconn.WithDefaultDialOptions(alloydbconn.WithPublicIP())
)
Use Private Service Connect
If you're using Private Service Connect to connect to your AlloyDB instance, then include the following:
cleanup, err := pgxv5.RegisterDriver(
"alloydb",
alloydbconn.WithDefaultDialOptions(alloydbconn.WithPSC())
)
Automatic IAM authentication
By default, AlloyDB Language Connectors use built-in authentication.
You can use automatic IAM authentication with the AlloyDB Go Connector. To enable, replace
your RegisterDriver
function with the following:
cleanup, err := pgxv4.RegisterDriver(
"alloydb",
alloydbconn.WithIAMAuthN()
)