Skip to content
Last updated on June 7, 2023
6 min read

Getting Started with Vercel Postgres

You can get started with writing to and reading data from Vercel Postgres by following this quickstart guide.

Vercel Postgres is available in Beta on Pro and Hobby plans

In this quickstart, you'll learn how to do the following:

  • Create an Postgres database called pets_postgres_db that's connected to one of your projects
  • Learn how to create and manage the database through the Vercel dashboard
  • Populate the database using the Vercel Postgres SDK. You can also use other supported ORM providers to help you create queries

If you'd prefer to jump straight to code or deploy the template, head to the examples section.

For more information on how Vercel Postgres works, see Postgres overview.

To follow this quickstart, you'll need the following:

An existing Vercel Project
Install the Vercel Postgres package
pnpm i @vercel/postgres
Install or update to the latest version of Vercel CLI
pnpm i -g vercel@latest

Navigate to the Project you'd like to add a Postgres database to. Adding the database at the project-level means that Vercel will automatically create the environment variables for you.

Select the Storage tab, then select the Connect Database button. Under the Create New tab, select Postgres and then the Continue button.

Note: During the Vercel Postgres beta phase, you must accept the Data Acknowledgement notice that this product should not be considered SOC 2 Type 2 compliant. If this compliance is required by your organization and project, please do not proceed.

To create a new database, do the following in the dialog that opens:

  1. Enter pets_postgres_db (or any other name you wish) under Store Name. The name can only contain alphanumeric letters, "_" and "-" and can't exceed 32 characters.
  2. Select a region. We recommend choosing a region geographically close to your Edge and Serverless Function regions for reduced latency
  3. Click Create

Your empty database is created in the region specified.

Because you created the Postgres database in a project, we automatically created and added the following environment variables to the project for you. Later in this quickstart, we'll pull them locally so we can use them with the project.

  • POSTGRES_URL
  • POSTGRES_PRISMA_URL
  • POSTGRES_URL_NON_POOLING
  • POSTGRES_USER
  • POSTGRES_HOST
  • POSTGRES_PASSWORD
  • POSTGRES_DATABASE

When you created your Postgres database, your API URL and credentials were created as environment variables automatically. You'll need to pull down the latest environment variables to get your local project working with the Postgres database.

vercel env pull .env.development.local

We're going to add a function to your project through an API route. Add the following file and code:

pages/api/pets.ts
import { db } from '@vercel/postgres';
import { NextApiRequest, NextApiResponse } from 'next';
 
export default async function handler(
  request: NextApiRequest,
  response: NextApiResponse,
) {
  const client = await db.connect();
 
  try {
    await client.sql`CREATE TABLE Pets ( Name varchar(255), Owner varchar(255) );`;
    const names = ['Fiona', 'Lucy'];
    await client.sql`INSERT INTO Pets (Name, Owner) VALUES (${names[0]}, ${names[1]});`;
  } catch (error) {
    return response.status(500).json({ error });
  }
 
  const pets = await client.sql`SELECT * FROM Pets;`;
  return response.status(200).json({ pets });
}

While it might look we are just hardcoding variables into the query, sql is a function that translates your query into a native Postgres parametrized query to help prevent SQL injection.

Run your application locally and visit /api/pets to see your data output. The function intercepts requests to /api/pets and responds with the data from your Postgres database.

You can deploy our example templates to see Vercel Postgres in action immediately: