Add @vercel/postgres guide (#1044)

lucia-auth · Aug 31, 2023 · 2e6cf0e · 2e6cf0e · vercel · Aug 31, 2023
1 parent 3b422de
commit 2e6cf0e
Show file tree

Hide file tree

Showing 15 changed files with 68 additions and 16 deletions.
diff --git a/documentation/content/guidebook/vercel-postgres.md b/documentation/content/guidebook/vercel-postgres.md
@@ -0,0 +1,43 @@
+---
+title: "Using `@vercel/postgres`"
+description: "Learn how to use `@vercel/postgres` with Lucia"
+---
+
+`@vercel/postgres` can be used as a drop-in replacement for [`pg`](https://github.com/brianc/node-postgres). This means that it can be used with Lucia using the [`pg` adapter](/database-adapters/pg). Make sure to pass `db`, which is the equivalent to `Pool` in `pg`, since the adapter needs to have access to transactions.
+
+```ts
+import { db } from "@vercel/postgres";
+
+export const auth = lucia({});
+```
+
+## Errors
+
+Unfortunately, `@vercel/postgres` does not export an error class that can be used to check for database errors. Nor are the error types or messages documented, though it's the same as `@neondatabase/serverless`. However, the error codes are PostgreSQL error codes, which are [well documented](https://www.postgresql.org/docs/current/errcodes-appendix.html).
+
+```ts
+type VercelPostgresError = {
+	code: string;
+	detail: string;
+	schema?: string;
+	table?: string;
+	column?: string;
+	dataType?: string;
+	constraint?: "auth_user_username_key";
+};
+```
+
+```ts
+try {
+	// ...
+} catch (e) {
+	const maybeVercelPostgresError = (
+		typeof e === "object" ? e : {}
+	) as Partial<VercelPostgresError>;
+
+	// error code for unique constraint violation
+	if (maybeVercelError.code === "23505") {
+		// ...
+	}
+}
+```
diff --git a/documentation/content/main/basics/database.md b/documentation/content/main/basics/database.md
@@ -23,7 +23,11 @@ We currently provide the following adapters:
 - [Redis](/database-adapters/redis)
 - [Unstorage](/database-adapters/unstorage)
 
-You can also use query builders like Drizzle ORM and Kysely since they rely on underlying drivers that we provide adapters for.
+SDKs such as `@vercel/postgres` and `@neonserverless/database` provide drop-in replacements for existing drivers. You can also use query builders like Drizzle ORM and Kysely since they rely on underlying drivers that we provide adapters for. Refer to these guides:
+
+- [Using `@vercel/postgres`](/guidebook/vercel-postgres)
+- [Using Drizzle ORM](/guidebook/vercel-postgres)
+- [Using Kysely](/guidebook/vercel-postgres)
 
 ## Database model
 

diff --git a/documentation/content/main/database-adapters/pg.md b/documentation/content/main/database-adapters/pg.md
@@ -3,7 +3,7 @@ title: "`pg` adapter"
 description: "Learn how to use pg with Lucia"
 ---
 
-Adapter for [`pg`](https://github.com/brianc/node-postgres) provided by the PostgreSQL adapter package.
+Adapter for [`pg`](https://github.com/brianc/node-postgres) provided by the PostgreSQL adapter package. This adapter can be used for `@vercel/postgres` and `@neondatabase/serverless` as well. See guide [Using `@vercel/postgres`](/guidebook/vercel-postgres).
 
 ```ts
 import { pg } from "@lucia-auth/adapter-postgresql";

diff --git a/documentation/content/main/getting-started/$astro.md b/documentation/content/main/getting-started/$astro.md
@@ -54,7 +54,7 @@ const auth = lucia({
 - [libSQL](/database-adapters/libsql): libSQL (Turso)
 - [Mongoose](/database-adapters/mongoose): MongoDB
 - [`mysql2`](/database-adapters/mysql2): MySQL
-- [`pg`](/database-adapters/pg): PostgreSQL
+- [`pg`](/database-adapters/pg): PostgreSQL (including `@neondatabase/serverless`, `@vercel/postgres`)
 - [`postgres`](/database-adapters/postgres): PostgreSQL
 - [Prisma](/database-adapters/prisma): MongoDB, MySQL, PostgreSQL, SQLite
 - [Redis](/database-adapters/redis): Redis

diff --git a/documentation/content/main/getting-started/$express.md b/documentation/content/main/getting-started/$express.md
@@ -104,7 +104,7 @@ const auth = lucia({
 - [libSQL](/database-adapters/libsql): libSQL (Turso)
 - [Mongoose](/database-adapters/mongoose): MongoDB
 - [`mysql2`](/database-adapters/mysql2): MySQL
-- [`pg`](/database-adapters/pg): PostgreSQL
+- [`pg`](/database-adapters/pg): PostgreSQL (including `@neondatabase/serverless`, `@vercel/postgres`)
 - [`postgres`](/database-adapters/postgres): PostgreSQL
 - [Prisma](/database-adapters/prisma): MongoDB, MySQL, PostgreSQL, SQLite
 - [Redis](/database-adapters/redis): Redis

diff --git a/documentation/content/main/getting-started/$fastify.md b/documentation/content/main/getting-started/$fastify.md
@@ -78,7 +78,7 @@ const auth = lucia({
 - [libSQL](/database-adapters/libsql): libSQL (Turso)
 - [Mongoose](/database-adapters/mongoose): MongoDB
 - [`mysql2`](/database-adapters/mysql2): MySQL
-- [`pg`](/database-adapters/pg): PostgreSQL
+- [`pg`](/database-adapters/pg): PostgreSQL (including `@neondatabase/serverless`, `@vercel/postgres`)
 - [`postgres`](/database-adapters/postgres): PostgreSQL
 - [Prisma](/database-adapters/prisma): MongoDB, MySQL, PostgreSQL, SQLite
 - [Redis](/database-adapters/redis): Redis

diff --git a/documentation/content/main/getting-started/$hono.md b/documentation/content/main/getting-started/$hono.md
@@ -54,7 +54,7 @@ const auth = lucia({
 - [libSQL](/database-adapters/libsql): libSQL (Turso)
 - [Mongoose](/database-adapters/mongoose): MongoDB
 - [`mysql2`](/database-adapters/mysql2): MySQL
-- [`pg`](/database-adapters/pg): PostgreSQL
+- [`pg`](/database-adapters/pg): PostgreSQL (including `@neondatabase/serverless`, `@vercel/postgres`)
 - [`postgres`](/database-adapters/postgres): PostgreSQL
 - [Prisma](/database-adapters/prisma): MongoDB, MySQL, PostgreSQL, SQLite
 - [Redis](/database-adapters/redis): Redis

diff --git a/documentation/content/main/getting-started/$nextjs-app.md b/documentation/content/main/getting-started/$nextjs-app.md
@@ -64,7 +64,7 @@ const auth = lucia({
 - [libSQL](/database-adapters/libsql): libSQL (Turso)
 - [Mongoose](/database-adapters/mongoose): MongoDB
 - [`mysql2`](/database-adapters/mysql2): MySQL
-- [`pg`](/database-adapters/pg): PostgreSQL
+- [`pg`](/database-adapters/pg): PostgreSQL (including `@neondatabase/serverless`, `@vercel/postgres`)
 - [`postgres`](/database-adapters/postgres): PostgreSQL
 - [Prisma](/database-adapters/prisma): MongoDB, MySQL, PostgreSQL, SQLite
 - [Redis](/database-adapters/redis): Redis

diff --git a/documentation/content/main/getting-started/$nextjs-pages.md b/documentation/content/main/getting-started/$nextjs-pages.md
@@ -60,7 +60,7 @@ const auth = lucia({
 - [libSQL](/database-adapters/libsql): libSQL (Turso)
 - [Mongoose](/database-adapters/mongoose): MongoDB
 - [`mysql2`](/database-adapters/mysql2): MySQL
-- [`pg`](/database-adapters/pg): PostgreSQL
+- [`pg`](/database-adapters/pg): PostgreSQL (including `@neondatabase/serverless`, `@vercel/postgres`)
 - [`postgres`](/database-adapters/postgres): PostgreSQL
 - [Prisma](/database-adapters/prisma): MongoDB, MySQL, PostgreSQL, SQLite
 - [Redis](/database-adapters/redis): Redis

diff --git a/documentation/content/main/getting-started/$remix.md b/documentation/content/main/getting-started/$remix.md
@@ -85,7 +85,7 @@ const auth = lucia({
 - [libSQL](/database-adapters/libsql): libSQL (Turso)
 - [Mongoose](/database-adapters/mongoose): MongoDB
 - [`mysql2`](/database-adapters/mysql2): MySQL
-- [`pg`](/database-adapters/pg): PostgreSQL
+- [`pg`](/database-adapters/pg): PostgreSQL (including `@neondatabase/serverless`, `@vercel/postgres`)
 - [`postgres`](/database-adapters/postgres): PostgreSQL
 - [Prisma](/database-adapters/prisma): MongoDB, MySQL, PostgreSQL, SQLite
 - [Redis](/database-adapters/redis): Redis

diff --git a/documentation/content/main/getting-started/$solidstart.md b/documentation/content/main/getting-started/$solidstart.md
@@ -63,7 +63,7 @@ const auth = lucia({
 - [libSQL](/database-adapters/libsql): libSQL (Turso)
 - [Mongoose](/database-adapters/mongoose): MongoDB
 - [`mysql2`](/database-adapters/mysql2): MySQL
-- [`pg`](/database-adapters/pg): PostgreSQL
+- [`pg`](/database-adapters/pg): PostgreSQL (including `@neondatabase/serverless`, `@vercel/postgres`)
 - [`postgres`](/database-adapters/postgres): PostgreSQL
 - [Prisma](/database-adapters/prisma): MongoDB, MySQL, PostgreSQL, SQLite
 - [Redis](/database-adapters/redis): Redis

diff --git a/documentation/content/main/getting-started/$sveltekit.md b/documentation/content/main/getting-started/$sveltekit.md
@@ -57,7 +57,7 @@ export const auth = lucia({
 - [libSQL](/database-adapters/libsql): libSQL (Turso)
 - [Mongoose](/database-adapters/mongoose): MongoDB
 - [`mysql2`](/database-adapters/mysql2): MySQL
-- [`pg`](/database-adapters/pg): PostgreSQL
+- [`pg`](/database-adapters/pg): PostgreSQL (including `@neondatabase/serverless`, `@vercel/postgres`)
 - [`postgres`](/database-adapters/postgres): PostgreSQL
 - [Prisma](/database-adapters/prisma): MongoDB, MySQL, PostgreSQL, SQLite
 - [Redis](/database-adapters/redis): Redis

diff --git a/documentation/content/main/getting-started/index.md b/documentation/content/main/getting-started/index.md
@@ -85,7 +85,7 @@ const auth = lucia({
 - [libSQL](/database-adapters/libsql): libSQL (Turso)
 - [Mongoose](/database-adapters/mongoose): MongoDB
 - [`mysql2`](/database-adapters/mysql2): MySQL
-- [`pg`](/database-adapters/pg): PostgreSQL
+- [`pg`](/database-adapters/pg): PostgreSQL (including `@neondatabase/serverless`, `@vercel/postgres`)
 - [`postgres`](/database-adapters/postgres): PostgreSQL
 - [Prisma](/database-adapters/prisma): MongoDB, MySQL, PostgreSQL, SQLite
 - [Redis](/database-adapters/redis): Redis

diff --git a/documentation/src/pages/guidebook/index.astro b/documentation/src/pages/guidebook/index.astro
@@ -29,12 +29,12 @@ const parentPages = allPages.filter((page) => page.frameworkId === null);
 						.sort((pageA, pageB) => {
 							return pageA.title.localeCompare(pageB.title);
 						})
-						.map(({ title, description, pathname }) => {
+						.map(({ htmlTitle, htmlDescription, pathname }) => {
 							return (
 								<article class="group w-full border-b bg-white">
 									<a class=" block py-4" href={pathname}>
-										<h2 class="text-xl font-semibold">{title}</h2>
-										<p>{description}</p>
+										<h2 class="text-xl font-semibold" set:html={htmlTitle}></h2>
+										<p set:html={htmlDescription}></p>
 										<div class="text-main mt-0.5 flex place-items-center gap-x-0.5">
 											<div class="h-5 w-5 fill-current ">
 												<ArticleIcon />

diff --git a/documentation/src/utils/content.ts b/documentation/src/utils/content.ts
@@ -32,6 +32,7 @@ export type Page = {
 	title: string;
 	htmlTitle: string;
 	hidden: boolean;
+	htmlDescription: string | null;
 	description: string | null;
 	versions: FrameworkVersion[];
 	frameworkId: FrameworkId | null;
@@ -57,13 +58,17 @@ export const getPages = async (collectionId: string): Promise<Page[]> => {
 	const pages = await Promise.all(
 		targetImports.map(async ([pathname, resolve]): Promise<Page> => {
 			const resolvedFile = await resolve();
+			const rawDescription = resolvedFile.frontmatter.description ?? null;
 			return {
 				pathname,
 				href: getHrefFromContentPathname(pathname),
 				collectionId,
 				title: removeMarkdownCode(resolvedFile.frontmatter.title),
 				htmlTitle: parseMarkdownCode(resolvedFile.frontmatter.title),
-				description: resolvedFile.frontmatter.description ?? null,
+				description: rawDescription ? removeMarkdownCode(rawDescription) : null,
+				htmlDescription: rawDescription
+					? parseMarkdownCode(rawDescription)
+					: null,
 				hidden: Boolean(resolvedFile.frontmatter.hidden),
 				versions: [],
 				frameworkId: getFrameworkIdFromContentPathname(pathname),