AlloyDB
Write data to a Google AlloyDB table using INSERT ON CONFLICT for upsert. Use Zeotap to materialize model results, enriched profiles, or audience data into AlloyDB for low-latency serving and analytics.
Prerequisites
- A Google Cloud project with AlloyDB enabled
- An AlloyDB cluster and primary instance
- A database user with INSERT, UPDATE, DELETE, and CREATE TABLE privileges
- Network connectivity between Zeotap and the AlloyDB instance (via private IP, VPC peering, or AlloyDB Auth Proxy)
Authentication
AlloyDB uses Username & Password authentication with a PostgreSQL-compatible database user.
- Create a database user in your AlloyDB instance with the necessary privileges
- Enter the database Username and Password in Zeotap
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Host | Text | Yes | AlloyDB instance IP address or hostname. Use the private IP from the AlloyDB console, or the AlloyDB Auth Proxy address. |
| Port | Number | No | Server port. Default: 5432 |
| Database | Text | Yes | Database name |
| SSL Mode | Select | No | SSL mode: Require, Verify Full, Prefer, or Disable. Default: Require. When using AlloyDB Auth Proxy, Disable is safe since the proxy handles encryption. |
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Schema | Text | Yes | Database schema to write to. Default: public |
| Table | Text | Yes | Target table name |
Supported Operations
Sync Modes: Upsert, Insert, Update, Mirror
| Mode | Behavior |
|---|---|
| Upsert | Insert new rows and update existing rows matched by primary key using INSERT ON CONFLICT DO UPDATE |
| Insert | Insert new rows only, skip existing rows using INSERT ON CONFLICT DO NOTHING |
| Update | Update existing rows matched by primary key, ignore new rows |
| Mirror | Upsert new and changed rows, then delete removed rows to keep the target in sync with the source |
Audience Sync Modes: Add, Remove, Mirror, Upsert
| Mode | Behavior |
|---|---|
| Add | Insert audience members into the target table |
| Remove | Delete audience members from the target table |
| Mirror | Add new members, remove former members to keep the table in sync |
| Upsert | Add new members and update existing member attributes |
Features
- Field Mapping: Yes
- Schema Introspection: Yes — Zeotap reads column metadata from AlloyDB’s information_schema
How It Works
- Zeotap connects to AlloyDB using the PostgreSQL wire protocol
- A temporary staging table is created for each batch
- Rows are bulk-inserted into the staging table
- Based on the sync mode, Zeotap runs the appropriate SQL operation (INSERT ON CONFLICT, UPDATE, or DELETE) from the staging table into the target table
- The staging table is dropped after the operation completes
If the target table does not exist, Zeotap creates it automatically on the first sync with a primary key column and a unique constraint.
Connection Methods
AlloyDB instances use private IP addresses within your VPC. To connect from Zeotap, you can:
- AlloyDB Auth Proxy: Run the Auth Proxy on a compute instance or container that Zeotap can reach. The proxy handles mutual TLS automatically.
- VPC Peering / Private Service Connect: Peer your VPC with the network where Zeotap runs.
- AlloyDB Omni: If using AlloyDB Omni (self-managed), connect directly to the instance IP.
Best Practices
- Use the AlloyDB Auth Proxy for secure, encrypted connections without managing SSL certificates
- Grant the minimum required privileges to the database user (INSERT, UPDATE, DELETE on the target schema, plus CREATE TABLE if auto-creation is needed)
- Use Upsert mode for most use cases to handle both new and updated records
- Use Mirror mode when you need the target table to exactly match the source data, including deletions
- Place Zeotap and AlloyDB in the same region to minimize latency
Troubleshooting
Connection refused
Verify the host IP, port, and that the AlloyDB instance is running. AlloyDB instances use private IPs — ensure your network configuration allows connectivity from where Zeotap runs.
SSL connection errors
If connecting through the AlloyDB Auth Proxy, set SSL Mode to Disable since the proxy handles encryption. For direct connections, use Require or Verify Full.
Insufficient privileges
The database user needs INSERT, UPDATE, DELETE privileges on the target table, and CREATE TABLE privileges on the target schema if the table does not yet exist.
Table does not exist
Zeotap creates the target table automatically on the first sync. Ensure the database user has CREATE TABLE privileges on the target schema.
Connection timeout
AlloyDB uses private IPs. If the connection times out, verify that your VPC peering, firewall rules, or Auth Proxy configuration allows traffic on port 5432.
Authentication failed
Verify the username and password. AlloyDB supports standard PostgreSQL authentication. If using IAM-based authentication, ensure you are using the correct IAM user credentials and that the user has been granted access to the database.