Saving Data

Until now your feature has used local or mock data – close the browser and it's gone. Time to add a real database so data sticks around. We'll use Neon (hosted Postgres), and the best part: Claude sets it up for you through the Vercel Marketplace – you just approve the terms. No separate signups, no local database to run.

Why Neon, set up through Vercel

Neon is a serverless Postgres database. Provisioning it from the Vercel Marketplace means Claude can create the account and database for you, and Vercel automatically stores the connection details as environment variables across all your environments. It's remote-first – one real database from day one, the way production works.

1. Let Claude provision your database

Because the Vercel plugin is installed, Claude already knows how to add Neon through Vercel. Just ask – you'll only need to approve the terms when prompted.

Add a Neon database via the Vercel Marketplace
Add a Neon Postgres database to my project through the Vercel Marketplace (the Vercel-managed option, so I don't need a separate Neon account).
1.Run the Vercel integration to provision Neon and connect it to this project.
2.I'll approve the terms when prompted – walk me through that.
3.Make sure the database connection details are added to Vercel for all environments, and pulled down to my local .env.local.
4.Confirm the database is connected and tell me what was created.

Claude runs the Vercel integration (vercel integration add neon), Neon spins up a real database, and Vercel injects the connection string (DATABASE_URL) into your project.

Outcome: You have a live Neon Postgres database connected to your project – no manual signup.

Claude provisioned my Neon database through Vercel

2. How environment keys work (important)

That database connection is your first environment variable – a secret value your app needs but that should never be written into your code. Here's the model you'll use for every key from now on:

  • Vercel is the source of truth. Your keys live safely in Vercel, set for each environment (development, preview, production). The Neon integration just did this for you.
  • Your local copy is pulled down, never hand-written. Claude runs vercel env pull .env.local to copy the dev keys to your machine. .env.local stays out of Git, so secrets never get committed.
  • This is why a site can work locally but break live: if a key is missing or different on Vercel, the deployed app can't reach the service. (Remember that note from the Debugging lesson – this is the topic it pointed to.)
The rule

Never paste a secret into a file or your code by hand. Keys go into Vercel; your local .env.local is only ever pulled from there. When in doubt, ask Claude to re-pull your environment variables.

Outcome: You understand where keys live and how they reach your app safely.

I understand how environment keys are stored and pulled

3. Design and create your tables

Now model the data your feature needs and let Claude create the tables in Neon. Keep it to exactly what this feature needs.

Design and create my database tables
Help me set up the data my feature needs in Neon:
1.Look at my feature and my concept (in the docs folder), and propose a simple table structure – the tables, their columns, and how they relate. Keep it to what this feature actually needs right now.
2.Show me the plan and explain it in plain language before changing anything.
3.Once I approve, create the tables in my Neon database using migrations tracked in my repo, so changes are versioned and repeatable.
4.Verify the tables exist and add a little sample data to test.
Safe database changes

Schema changes can be risky (dropping a column loses data). Have Claude explain the impact and confirm with you before applying anything destructive – adding tables or columns is safe; removing or changing them needs a closer look. Claude tracks each change as a migration in your repo so it's repeatable and reversible.

Outcome: Your feature's tables exist in Neon, created through versioned migrations.

I designed and created my database tables in Neon

4. Connect your feature to the database

Wire your feature to read and write real data – on the server, where your database connection stays private.

Connect my feature to Neon with Server Actions
Connect my feature to the Neon database:
1.Set up a server-side database client using the DATABASE_URL from my environment.
2.Replace the feature's mock/local data with real reads and writes using Server Actions (server-side only – never expose the database connection to the browser).
3.Add clear loading and error states in the UI.
4.Walk me through testing it in the preview, and confirm data persists after a refresh.

Outcome: Your feature stores and loads real data from Neon, and it survives a refresh.

My feature reads and writes real data in Neon

5. Ship it

Your database is already live, and your keys are already on Vercel – so shipping is the same loop as always.

Commit and push to go live
Commit this work (including the migration files) with a clear message and push it to main so it deploys. Confirm the deploy is Ready and that the live site can read and write data.

Outcome: Your data-backed feature is live in production.

I shipped my data-backed feature

6. Changing your data later

When you need to add or change tables down the line, just describe it. Claude designs the change, explains the impact, confirms before anything destructive, applies it as a tracked migration, and ships it – the same simple flow you just used.

Outcome: You know how to evolve your database safely as your app grows.

I know how to safely change my database later