Getting Started with Vercel Postgres
You can get started with writing to and reading data from Vercel Postgres by following this quickstart guide.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:
pnpm i @vercel/postgres
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.
To create a new database, do the following in the dialog that opens:
- 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. - Select a region. We recommend choosing a region geographically close to your Edge and Serverless Function regions for reduced latency
- 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:
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: