Setup prerequisites

Applies to VAST Cluster 5.5. Examples use the VAST DataBase Python SDK 2.1.0.

Before you can use VAST DataBase from the Python SDK, Trino, Spark or another client, your platform team has to set up a few things on the cluster. This page lists them, says what to ask for, and shows how to check that everything works.

Checklist

What your client connects to, and what your platform team provides.

Admin task: send to your platform team. The setup steps are in the KB: Configuring the VAST Cluster for Database Access (database, owner user and keys) and Managing Permissions for Accessing VAST Tabular Databases (identity policies). For the Query Engine, see VAST Query Engine.

What your platform team sets up, in order, before your client connects.

What to send your platform team

Copy this and fill it in:

I need access to VAST DataBase for <project>.

- Database: an existing database (bucket) <name>, or please create one.
- Endpoint: a virtual IP pool address or DNS name that serves VAST DataBase,
  reachable from <client host or network>.
- Credentials: an S3 access key pair for a user <user name>.
- Permissions: an identity policy for that user on the database, allowing
  s3:ListBucket on <bucket>, and these Tabular actions on <bucket> and <bucket>/*:
  <actions from the table on the setup-prerequisites page>
- (If using the VAST Query Engine) s3:QueryEngine* and the Query Engine VIP pool address.
- (If using ADBC end-user impersonation) s3:EndUserImpersonation for the service account.

Permissions

An identity policy grants actions on resources. For a database named my-db, the resources are the bucket itself (my-db, for bucket-level actions such as listing schemas) and everything in it (my-db/*). See Managing Permissions for Accessing VAST Tabular Databases.

Actions each SDK operation needs

Every SDK workflow starts with tx.bucket(name), which needs s3:ListBucket (or s3:HeadBucket) on the bucket. This isn't a Tabular action, so a policy that grants only s3:Tabular* fails at that first step with a Forbidden error and no code.

Opening a schema or table needs a few list and get actions too, because the SDK loads each table's columns and statistics when it opens the table. The table below shows what each operation needs on top of those.

Include the transaction actions too: s3:TabularBeginTransaction, s3:TabularCommitTransaction, s3:TabularRollbackTransaction and s3:TabularGetTransaction, for example as s3:Tabular*Transaction.

For other operations, see the list of Tabular actions.

Other engines and clients:

• VAST Query Engine: also needs s3:QueryEngine* (VAST Query Engine). The policy must be attached to the user in the database's tenant. For a user of the cluster's default local provider, attaching it without naming the tenant attaches it in the default tenant, and every Query Engine request then fails with request was denied according to policies res=2, even SELECT 1, while the SDK's own calls still work for the bucket owner. To attach it in the tenant: user modify --tenant-id in the VAST CLI, or PATCH /api/users/<user id>/tenant_data/ with tenant_id (Vector Search setup).
• ADBC end-user impersonation (Session(end_user=...)): the ADBC driver's service account needs s3:EndUserImpersonation; see "ADBC User Impersonation" on the same page.
• Row and column security with Trino: the Trino user needs s3:EndUserImpersonation and s3:TabularGetRowColumnSecurity. s3:Tabular* covers the second but not the first. See security.

Example policies

A practitioner policy that can read, write and change tables in one database, my-db:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:ListBucket", "s3:Tabular*"],
      "Resource": ["my-db", "my-db/*"]
    }
  ]
}

A read-only policy (list and query) for the same database:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:Tabular*Transaction",
        "s3:TabularList*",
        "s3:TabularGetTableStats",
        "s3:TabularQueryData"
      ],
      "Resource": ["my-db", "my-db/*"]
    }
  ]
}

Check the action names carefully: the cluster accepts a policy even if it contains an action name that doesn't exist, and that action then grants nothing. A key with the read-only policy can list schemas and tables and run select(). create_schema() and insert() fail with Forbidden (AccessDenied).

The SDK doesn't list buckets, so it doesn't need the ListBuckets permission in the view policy. Tools that list your databases may need it.

Check that it works

Set the environment variables from the quickstart, then run:

import os
import vastdb

session = vastdb.connect()
with session.transaction() as tx:
    bucket = tx.bucket(os.environ["VASTDB_BUCKET"])
    print("Connected to database:", bucket.name)
    print("Schemas:", [s.name for s in bucket.schemas()])

Connected to database: docs-capture-db
Schemas: []

Your list of schemas depends on what's in your database; a new database has none. Each step checks one item on the checklist:

If all three lines run, your endpoint, keys and basic permissions are right. To check a particular operation, such as creating a table, run it; a missing action shows up as Forbidden with code AccessDenied (see errors).

Next steps

• Quickstart: create a table, insert rows and query them.
• Security: how identity policies and row and column security affect your queries.
• Version compatibility: which SDK and connector versions go with your cluster.