Faz Docs

Connect faz to AWS DynamoDB. PartiQL or verb-based JSON queries; uses the AWS SDK credential chain.

DynamoDB's connector uses boto3. Queries are either PartiQL strings (ExecuteStatement) or verb-based JSON ({"verb": "Query", "TableName": ..., ...}). Authentication uses the standard AWS SDK credential chain — environment variables, instance profiles, or explicit values via extra.

Default port	Query language	Write support	Schema discovery	Driver
8000*	PartiQL / verb-based JSON	Yes (RBAC-gated)	`ListTables` + `DescribeTable`	`boto3`

* Default port is for the local DynamoDB container (amazon/dynamodb-local). Managed AWS DynamoDB uses HTTPS via the SDK's regional endpoint.

Quick example (managed AWS)

faz.yaml — AWS

databases:
  - name: <database>          # used as --database <database> in queries
    type: dynamodb
    host: dynamodb.<region>.amazonaws.com
    port: 443
    database: <table>          # convention only — DynamoDB has no database concept
    extra:
      region: <region>          # e.g. us-east-1
      # Credentials NOT in faz.yaml — boto3 picks them up from:
      #   AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY env vars, OR
      #   the IAM role attached to the EC2/ECS/EKS/Lambda host

permissions:
  - database: <database>      # must match `name:` above
    access: R
    # access codes:
    # R    read only           — Query, Scan, GetItem, BatchGetItem (incl. PartiQL SELECT)
    # W    write only          — PutItem, UpdateItem, DeleteItem (no reads)
    # RW   read + write
    # RA   read + append       — reads + PutItem
    # RWA  read + write, no DELETE
    # A    admin (incl. CreateTable, DeleteTable, UpdateTable)

See Permissions for the full model, per-table overrides, and the operation matrix.

Quick example (local container)

faz.yaml — local

databases:
  - name: <database>          # used as --database <database> in queries
    type: dynamodb
    host: localhost
    port: 8000
    database: <table>
    username: <access-key-id>
    password: <secret-access-key>
    extra:
      endpoint_url: http://localhost:8000
      region: us-east-1

permissions:
  - database: <database>      # must match `name:` above
    access: R

faz query '{"verb":"Scan","TableName":"<table>","Limit":5}' --database <database> --table <table> --language dynamo

uv run faz query '{"verb":"Scan","TableName":"<table>","Limit":5}' --database <database> --table <table> --language dynamo

python -m faz query '{"verb":"Scan","TableName":"<table>","Limit":5}' --database <database> --table <table> --language dynamo

Configuration

Field	Type	Default	Notes
`host`	string	`localhost`	DynamoDB endpoint hostname. Used when `extra.endpoint_url` isn't set.
`port`	integer	`8000`	Local container port. Ignored for managed AWS (boto3 uses HTTPS endpoints).
`database`	string	`""`	Convention only — DynamoDB has no database concept. faz uses it as a routing aid.
`username`	string	`""`	Maps to `AWS_ACCESS_KEY_ID` when set explicitly. Leave empty for IAM-role-based auth.
`password`	string	`""`	Maps to `AWS_SECRET_ACCESS_KEY` when set explicitly.
`ssl`	boolean	`false`	Not used. boto3 handles TLS via the endpoint URL scheme.
`extra`	mapping	`{}`	`region` (default `us-east-1`), `endpoint_url` (for local container or VPC endpoints).

Don't put long-lived AWS credentials in faz.yaml for production. Run faz on a host with an IAM role attached (EC2 instance profile, ECS task role, EKS service account, Lambda execution role). boto3 picks the role up automatically and rotates the credentials. Static keys in YAML are a last resort.

Capabilities

Two query shapes:

Verb-based JSON: {"verb": "Query", "TableName": ..., "KeyConditionExpression": ..., ...}. Verbs cover Query, Scan, GetItem, BatchGetItem, PutItem, UpdateItem, DeleteItem, BatchWriteItem.
PartiQL: {"verb": "ExecuteStatement", "Statement": "SELECT * FROM events WHERE id = ?", "Parameters": [...]}.

Schema discovery enumerates tables via ListTables and reads each table's primary-key schema and attribute definitions via DescribeTable. Secondary indexes appear in the metadata.

Limitations

PartiQL INSERT/UPDATE/DELETE are gated by RBAC the same way verb-based writes are. Permissions are enforced at the operation-class level.
DDL — CreateTable, DeleteTable, UpdateTable — requires A. DynamoDB's "DDL" is the AWS API surface, not SQL.
extra.endpoint_url is required for local container. Without it, boto3 hits AWS regional endpoints. Always set endpoint_url: http://localhost:8000 for the local container.
Pagination — DynamoDB returns LastEvaluatedKey for paginated queries. faz currently buffers the first page only; for very large scans, paginate explicitly via the verb-based shape.

Troubleshooting

Unable to locate credentials — boto3 has no credentials. Either set AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY env vars, attach an IAM role to your host, or set username/password in faz.yaml (development only).

AccessDeniedException: User X is not authorized to perform Y — the IAM principal lacks the action on the table. Check IAM policies; the action set you need is at minimum dynamodb:DescribeTable, dynamodb:Query, dynamodb:Scan, dynamodb:GetItem for reads.

ResourceNotFoundException: Cannot do operations on a non-existent table — table doesn't exist in the region. Check extra.region.

Local container connection refused — start it: docker run -p 8000:8000 amazon/dynamodb-local.

UnrecognizedClientException — credentials are syntactically valid but rejected by AWS (typo in the secret key). Test with aws dynamodb list-tables from the same shell.

For the broader troubleshooting flow, see Connection failed.

Databases overview — cross-connector basics.
Secrets — patterns for credential management on AWS.
faz.yaml — the full config schema.

DynamoDB