Skip to content
XenonDocs
Esc
    GitHub
    Docs

    Database and storage adapters

    Reference documentation for database engines and object storage adapters supported by Xenon.

    On this page

    Overview

    Xenon decouples document persistence and asset storage using pluggable adapter interfaces.

    src/xenon.config.ts
    import { defineConfig } from "xenon-cms";
    import { postgresAdapter } from "xenon-cms/postgres";
    import { LocalStorageAdapter } from "xenon-cms/storage/local";
    
    export default defineConfig({
      collections: [],
      db: postgresAdapter({ connectionString: process.env.DATABASE_URL! }),
      storage: new LocalStorageAdapter({ directory: ".xenon/uploads" }),
    });

    Adapters are instantiated in xenon.config.ts and passed to defineConfig.

    Database adapters

    Three adapters, one per driver. Each has its own import, and that import loads only its own driver, so install just the one you use. All three store documents the same way.

    postgresAdapter

    Exported from xenon-cms/postgres. Connects to a Postgres server with the postgres driver.

    TypeScript
    import { postgresAdapter } from "xenon-cms/postgres";
    
    const db = postgresAdapter({
      connectionString: process.env.DATABASE_URL!,
    });
    OptionTypeDefaultDescription
    connectionStringstringRequiredPostgres connection URI.
    maxnumber10Maximum connections in the pool.

    Install postgres. xenonDocuments, the documents table definition, is also exported from xenon-cms/postgres.

    pgliteAdapter

    Exported from xenon-cms/pglite. Runs Postgres inside your server process with PGlite.

    TypeScript
    import { pgliteAdapter } from "xenon-cms/pglite";
    
    const db = pgliteAdapter({ dataDir: ".xenon/pgdata" });
    OptionTypeDefaultDescription
    dataDirstringIn memoryDirectory for the database files. Omit it for an in-memory database that's lost on restart.

    Install @electric-sql/pglite, then add it to serverExternalPackages and set experimental.cpus to 1 in next.config.ts:

    next.config.ts
    import type { NextConfig } from "next";
    
    const nextConfig: NextConfig = {
      serverExternalPackages: ["@electric-sql/pglite"],
      experimental: { cpus: 1 },
    };
    
    export default nextConfig;

    cpus: 1 makes next build use a single worker. Only one process can open a PGlite database at a time, so when several static pages read it while they prerender, the default worker count fails with an "already open in another process" error. A site with a single page that reads PGlite builds either way.

    drizzleAdapter

    Exported from xenon-cms/drizzle. Uses a Drizzle Postgres database you create, for example with node-postgres or Neon's driver.

    TypeScript
    import { drizzle } from "drizzle-orm/node-postgres";
    import { drizzleAdapter } from "xenon-cms/drizzle";
    
    const db = drizzleAdapter({ db: drizzle(process.env.DATABASE_URL!) });
    OptionTypeDefaultDescription
    dbPgDatabaseRequiredAny Drizzle Postgres database.

    Neither driver is needed; install the packages your Drizzle setup uses.

    Each adapter creates the tables it needs the first time it connects.

    Storage adapters

    LocalStorageAdapter

    Exported from xenon-cms/storage/local. Persists binary assets to a directory on the local filesystem.

    TypeScript
    import { LocalStorageAdapter } from "xenon-cms/storage/local";
    
    const storage = new LocalStorageAdapter({
      directory: ".xenon/uploads",
      baseUrl: "/api/xenon/_files",
    });
    OptionTypeDefaultDescription
    directorystring".xenon/uploads"Destination folder for uploaded files.
    baseUrlstring"/api/xenon/_files"HTTP base URL path for file retrieval.

    Rejects directory traversal sequences and unsafe keys.

    S3StorageAdapter

    Exported from xenon-cms/storage/s3. Uploads assets to Amazon S3, Cloudflare R2, or compatible object stores.

    TypeScript
    import { S3StorageAdapter } from "xenon-cms/storage/s3";
    
    const storage = new S3StorageAdapter({
      bucket: "my-bucket",
      endpoint: "https://<account>.r2.cloudflarestorage.com",
      region: "auto",
      accessKeyId: process.env.S3_KEY!,
      secretAccessKey: process.env.S3_SECRET!,
      publicUrl: "https://media.example.com",
      prefix: "uploads",
    });
    OptionTypeDefaultDescription
    bucketstringRequiredObject store bucket name.
    endpointstringRequiredS3 API endpoint URL.
    regionstring"auto"AWS region.
    accessKeyIdstringRequiredAccess key ID.
    secretAccessKeystringRequiredSecret access key.
    publicUrlstringRequiredBase URL where files are served.
    prefixstringundefinedSubfolder path prepended to all storage keys.

    Next steps