Vercel S3 Tables Demo

Amazon S3 Tables Movie Catalog Demo

This demo uses Amazon S3 Tables with Next.js to compare movie-catalog snapshots stored as an Apache Iceberg table. It is able to securely connect to S3 Tables without using hardcoded access tokens through Vercel's OIDC Federation.

Getting Started:

Click the "Deploy" button to clone this repo, create a new Vercel project, set up the AWS integration, and provision a new S3 Tables table bucket:

Once the process is complete, you can clone the newly created GitHub repository and start making changes locally.

Requirements

• Installed Amazon S3 Tables. You can do that via Vercel Marketplace

Deploying provisions everything. The build creates the namespace and Iceberg table inside the table bucket and loads the catalog data, so there is nothing to run by hand.

Local Setup

1. Pull vercel environment variables locally

1
vercel env pull

vercel env pull reads the project's Development environment. The Deploy button connects the table bucket to every environment, but connecting it from the dashboard leaves Development unchecked by default. If .env.local has no AWS_* variables, open the S3 Tables resource in the Vercel dashboard, edit the project connection, enable Development, and pull again.

1. Install dependencies:

1
npm install

1. Create and seed the catalog table:

1
npm run db:setup

1. Start the development server:

1
npm run dev

1. View local development: http://localhost:3000

Other commands:

1
npm run db:check     # report table bucket and table state
2
npm run db:append    # append the next monthly snapshot
3
npm run db:migrate   # create the namespace and table only
4
npm run db:seed      # write the baseline snapshots only

How it works

1
Next.js on Vercel
2
  → Vercel OIDC federation
3
  → @aws-sdk/client-s3tables       (create namespace and table)
4
  → DuckDB + Iceberg REST endpoint (read and write rows)
5
  → catalog.movie_catalog_snapshots

The Vercel AWS integration provisions the S3 Tables table bucket. npm run db:setup creates the namespace and the Iceberg table inside it and loads the baseline data. Every step is idempotent, so re-running is safe.

Two clients are involved because they do different jobs. @aws-sdk/client-s3tables covers table and schema management, but has no row-level API. Rows move through an Iceberg client, so reads and writes use DuckDB against the S3 Tables Iceberg REST endpoint:

1
ATTACH '<table-bucket-arn>' AS s3t (TYPE ICEBERG, ENDPOINT_TYPE 'S3_Tables');

Snapshots

The table stores one row per title per snapshot, and the first seed writes two, one month apart. Presence is the signal — a retired title simply has no row in the later snapshot — so the catalog changes view derives Added, Removed, and Licence renewed by diffing the two most recent snapshots rather than reading a status column.

Which snapshots are compared is read from the table, not configured, so appending a snapshot moves the comparison forward on its own.

That is the point of the demo: catalog history stays queryable over time without the application team managing Parquet files, table metadata, compaction, or snapshot cleanup.

Queries

Each of the three views is a fixed, preset query rather than an open-ended query workspace:

Reads are cached for 60 seconds. A cache hit never opens DuckDB, which keeps the native binding and Iceberg extension off the request path. The window is deliberately short so a newly appended snapshot shows up promptly.

All S3 Tables access is server-side. No table identifier or credential is exposed to Client Components.

Environment variables

Supplied by the Vercel AWS integration:

1
AWS_ACCOUNT_ID
2
AWS_REGION
3
AWS_RESOURCE_ARN
4
AWS_ROLE_ARN
5
S3_TABLE_BUCKET_NAME

If you connected the table bucket with the aws_s3_tables_ prefix, the prefixed names (aws_s3_tables_AWS_ROLE_ARN and so on) are read first.

Identifies the catalog table:

1
S3_TABLES_NAMESPACE=catalog
2
S3_TABLES_TABLE_NAME=movie_catalog_snapshots

GET /api/status reports whether the required variables are present, and the names of any that are missing. It never returns account IDs, role ARNs, resource ARNs, or bucket names. GET /api/catalog returns the same catalog data the page renders, uncached.

Deployment

vercel.json runs provisioning before the build:

1
"buildCommand": "npm run db:setup && npm run build"

db:setup creates the namespace and Iceberg table if absent, then writes the baseline snapshots if the table is empty. Both halves are idempotent, so every deployment runs it and only the first does any work. It never fails the build — if the AWS integration is not connected yet, the site still deploys and the page explains what is missing.

DuckDB ships a native binding per platform, so next.config.ts keeps it out of the bundle and traces the binding into every route that queries the catalog. Both are required for deployment to work.

Appending snapshots

The page has two controls for exploring how the table changes over time:

• Append next snapshot derives the next month from the most recent snapshot. Titles whose rights have lapsed are renewed or retired, a few new titles are acquired, and some metadata gaps are filled. Since the app compares the two most recent snapshots, the comparison moves forward and the previous month's licence warnings become this month's retirements.
• Reset to baseline returns the catalog to its two starting snapshots.

The derivation is deterministic, so the same starting table always produces the same next snapshot. Appending stops at six snapshots; reset to continue.

The same operations are available from the command line:

1
npm run db:append

Reset has no in-place equivalent, because DuckDB's Iceberg support implements neither DELETE nor snapshot rollback. The reset control drops the table and rebuilds it, which is also what to do by hand:

1
aws s3tables delete-table \
2
  --table-bucket-arn "$AWS_RESOURCE_ARN" \
3
  --namespace catalog --name movie_catalog_snapshots
4
npm run db:setup

Structure

1
app/                             Next.js App Router entry points and global styles
2
app/page.tsx                     Server component; reads the cached catalog snapshot
3
app/api/status/route.ts          Configuration readiness endpoint
4
app/api/catalog/route.ts         Catalog data as JSON, uncached
5
components/catalog-insights.tsx  Single-page catalog snapshot experience
6
lib/catalog.ts                   Shared types
7
lib/s3-tables-config.ts          Server-only S3 Tables environment-variable contract
8
lib/s3-tables-client.ts          S3 Tables client using Vercel OIDC credentials
9
lib/s3-tables-metadata.ts        Table bucket and table state queries
10
lib/catalog-table-setup.ts       Idempotent namespace/table creation and Iceberg schema
11
lib/db/duckdb.ts                 DuckDB connection, Iceberg attach, local snapshot copy
12
lib/db/queries.ts                The three preset catalog queries
13
lib/db/catalog-data.ts           Cached loader used by the page
14
lib/db/setup.ts                  Build-time provisioning: migrate then seed
15
lib/db/migrate.ts                Creates the namespace and Iceberg table
16
lib/db/seed.ts                   Writes the baseline snapshots
17
lib/db/append.ts                 Appends the next monthly snapshot
18
lib/db/catalog-mutations.ts      Shared seed/append/reset logic
19
lib/db/snapshot-io.ts            Row writing and next-snapshot derivation
20
lib/db/actions.ts                Server actions behind the page controls
21
lib/db/seed-data.ts              Baseline snapshot definitions
22
lib/db/env.ts                    Loads local .env files (including vercel pull output) for the CLI scripts
23
lib/db/check.ts                  Reports table bucket and table state
24
.env.example                     Variable names only—no secrets