How to Configure Mastra Bigquery Permissions

Published
Length
3 min read

Luis Felipe Dias

All posts

To set up mastra bigquery permissions, create a Google Cloud service account and assign read roles. Then pass those account keys to your Mastra agent tool so it can run queries. Most teams start by granting project-wide editor roles to get their agents working fast. Broad roles let an agent read private tables or change live data by mistake. How mastra bigquery permissions work in practice Mastra agents use custom tools to talk to external data platforms like Google BigQuery. The agent builds

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

To set up mastra bigquery permissions, create a Google Cloud service account and assign read roles. Then pass those account keys to your Mastra agent tool so it can run queries. Most teams start by granting project-wide editor roles to get their agents working fast. Broad roles let an agent read private tables or change live data by mistake.

How mastra bigquery permissions work in practice

Mastra agents use custom tools to talk to external data platforms like Google BigQuery. The agent builds a SQL query based on a user prompt and sends it out. BigQuery checks the identity attached to that request before it runs any job. You control this identity through Google Cloud Identity and Access Management, also known as IAM.

A good setup uses a dedicated service account for each Mastra agent in your app. That service account needs two basic permissions inside your cloud project to work well. First, it needs a role that lets it start and run query jobs. Second, it needs a role that lets it read data from specific tables or views.

You should attach the data viewer role at the dataset or table level. Do not attach data viewer roles at the top project level. Project-level roles let the agent read every dataset in your cloud project. Dataset-level roles keep the agent inside the exact tables it needs for its task.

Next, the Mastra app loads the service account credentials from a secure secret store. Teams running on Google Cloud can also bind the service account to their compute workload. Workload binding removes the need to store static key files on disk. When the agent runs a tool, the BigQuery client sends the request with those credentials.

Where native cloud roles fall short for agents

Cloud IAM roles are great at deciding which account can log in and start jobs. They also control which datasets and tables that account can see or change. For simple scripts with fixed queries, dataset roles are often enough to stay safe. AI agents change this model because they write their own SQL queries on the fly.

Once a service account has read rights on a table, it can read every row. Native IAM roles do not check the content of each SQL query in flight. An agent can run a huge full-table scan that drives up your cloud bill. It can also pull sensitive columns into its context window during a chat.

BigQuery IAM + AI Agent Permissions: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

BigQuery offers column tags and row access rules, but they take heavy work to maintain. Every time a schema changes, your data team must update tags across many tables. Also, static cloud roles do not link agent queries back to the human user asking. In your cloud logs, every query looks like it came from the same service account.

Steps to harden agent data workflows

Start by splitting your Mastra tools by task so each tool has one clear job. Give read-only agents a service account that cannot create, update, or drop any tables. If an agent needs to write output, give it write rights on one scratch dataset. Keep raw customer tables locked away from that write account at all times.

Set up curated SQL views that expose only the columns your agent needs to read. Grant the agent service account read rights on the view instead of the base table. You should also set a maximum bytes billed limit on the query jobs. This limit stops bad agent queries from scanning terabytes of data by mistake.

Even with views and byte limits, raw table values still reach the agent memory. Customer emails, phone numbers, card numbers, and national IDs can show up in query results. When those values enter the prompt context, the model may repeat them to users. Teams need a way to inspect queries and mask fields like emails in results.

Add runtime guardrails and masking beside your databases and APIs

Login rules, role grants, and CI checks govern who connects to your stack. Yet any allowed script, engineer, or AI agent still runs commands with the full scope of its role. For workloads on Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes, SSH, or internal HTTP services, hoop.dev sits beside the service as an open-source proxy, a sidecar for your database or API.

Before a query runs, hoop.dev guardrails check the statement against your rules. An AI Analyzer you configure can score intent or hold risky calls for human review. Next, hoop.dev data masking rewrites sensitive fields in responses, and each verdict is logged per listener. Explore the MIT-licensed project on GitHub.

Frequently asked questions

What is the safest BigQuery role for a Mastra read agent?

Grant a project-level job user role so the agent can run queries. Pair that with a data viewer role placed only on the specific dataset or view.

Should my Mastra agent use a personal user account for BigQuery?

No, you should never use a personal user account for an automated agent. Always create a dedicated service account so you can limit and audit its actions.

How do I stop a Mastra agent from reading sensitive columns?

You can build restricted SQL views or apply dynamic data masking to rewrite matched fields. Masking rewrites fields like emails, phone numbers, and card numbers in query results.

The query runs. The emails stay hidden.