From 2e6cf0e472ac5f1af0b770ed784ed572cfcc3e31 Mon Sep 17 00:00:00 2001 From: pilcrowOnPaper <80624252+pilcrowOnPaper@users.noreply.github.com> Date: Fri, 1 Sep 2023 01:28:10 +0900 Subject: [PATCH] Add `@vercel/postgres` guide (#1044) --- .../content/guidebook/vercel-postgres.md | 43 +++++++++++++++++++ documentation/content/main/basics/database.md | 6 ++- .../content/main/database-adapters/pg.md | 2 +- .../content/main/getting-started/$astro.md | 2 +- .../content/main/getting-started/$express.md | 2 +- .../content/main/getting-started/$fastify.md | 2 +- .../content/main/getting-started/$hono.md | 2 +- .../main/getting-started/$nextjs-app.md | 2 +- .../main/getting-started/$nextjs-pages.md | 2 +- .../content/main/getting-started/$remix.md | 2 +- .../main/getting-started/$solidstart.md | 2 +- .../main/getting-started/$sveltekit.md | 2 +- .../content/main/getting-started/index.md | 2 +- documentation/src/pages/guidebook/index.astro | 6 +-- documentation/src/utils/content.ts | 7 ++- 15 files changed, 68 insertions(+), 16 deletions(-) create mode 100644 documentation/content/guidebook/vercel-postgres.md diff --git a/documentation/content/guidebook/vercel-postgres.md b/documentation/content/guidebook/vercel-postgres.md new file mode 100644 index 000000000..1ceb4e0e1 --- /dev/null +++ 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; + + // 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 index 532e472d5..16cb8d398 100644 --- 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 index cb83f9c45..ebde6c923 100644 --- 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 index fad435e44..c1501a681 100644 --- 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 index 17f843234..a81de5943 100644 --- 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 index 29d903431..85b788a99 100644 --- 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 index e11d8c08b..81d3d3e13 100644 --- 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 index 8a34f25a1..ed8c1a61b 100644 --- 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 index 448dabead..9db79a152 100644 --- 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 index d6788094b..1d7a5e4d2 100644 --- 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 index e090b9106..86ee222a4 100644 --- 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 index 15f2c67ed..ce3ee6f97 100644 --- 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 index 4a629da63..2f9da2c11 100644 --- 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 index c1535e32e..8b54c5a7a 100644 --- 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 (
-

{title}

-

{description}

+

+

diff --git a/documentation/src/utils/content.ts b/documentation/src/utils/content.ts index 575d1ef18..a7c2652c5 100644 --- 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 => { const pages = await Promise.all( targetImports.map(async ([pathname, resolve]): Promise => { 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),