Core Database Adapter

/**
 * Creates a PostgreSQL database adapter for Payload CMS
 * @param args - Configuration options for the adapter
 * @returns DatabaseAdapterObj containing the configured adapter
 */
function postgresAdapter(args: PostgresAdapterArgs): DatabaseAdapterObj<PostgresAdapter>;

interface PostgresAdapterArgs {
  /** PostgreSQL connection pool configuration (required) */
  pool: PoolConfig;
  
  /** Primary key type for generated IDs */
  idType?: 'serial' | 'uuid';
  
  /** Database schema name (experimental) */
  schemaName?: string;
  
  /** PostgreSQL extensions to enable */
  extensions?: string[];
  
  /** Directory containing migration files */
  migrationDir?: string;
  
  /** Allow custom ID values in create operations */
  allowIDOnCreate?: boolean;
  
  /** Store blocks as JSON instead of relational structure */
  blocksAsJSON?: boolean;
  
  /** Disable automatic database creation */
  disableCreateDatabase?: boolean;
  
  /** Suffix for locale tables */
  localesSuffix?: string;
  
  /** Suffix for relationship tables */
  relationshipsSuffix?: string;
  
  /** Suffix for version tables */
  versionsSuffix?: string;
  
  /** Filter specific tables */
  tablesFilter?: string[];
  
  /** Read replica connection strings */
  readReplicas?: string[];
  
  /** Transaction configuration or false to disable */
  transactionOptions?: false | PgTransactionConfig;
  
  /** Schema transformation hooks before schema initialization */
  beforeSchemaInit?: PostgresSchemaHook[];
  
  /** Schema transformation hooks after schema initialization */
  afterSchemaInit?: PostgresSchemaHook[];
  
  /** Drizzle query logger configuration */
  logger?: DrizzleConfig['logger'];
  
  /** Custom pg dependency injection */
  pg?: typeof import('pg');
  
  /** Enable schema pushing in development */
  push?: boolean;
  
  /** Production migration definitions */
  prodMigrations?: Array<{
    name: string;
    up: (args: MigrateUpArgs) => Promise<void>;
    down: (args: MigrateDownArgs) => Promise<void>;
  }>;
}

import { postgresAdapter } from '@payloadcms/db-postgres';
import { buildConfig } from 'payload';

// Basic configuration
export default buildConfig({
  db: postgresAdapter({
    pool: {
      connectionString: process.env.DATABASE_URI,
    },
  }),
});

// Advanced configuration
export default buildConfig({
  db: postgresAdapter({
    pool: {
      host: 'localhost',
      port: 5432,
      user: 'postgres',
      password: 'password',
      database: 'myapp',
      ssl: false,
      max: 20,
      min: 5,
    },
    idType: 'uuid',
    schemaName: 'payload',
    extensions: ['uuid-ossp', 'postgis'],
    allowIDOnCreate: true,
    blocksAsJSON: false,
    readReplicas: [
      'postgresql://user:pass@replica1:5432/db',
      'postgresql://user:pass@replica2:5432/db',
    ],
    beforeSchemaInit: [
      ({ schema }) => {
        // Preserve existing schema elements
        return { ...existingSchema, ...schema };
      },
    ],
    afterSchemaInit: [
      ({ schema }) => {
        // Add custom indices or constraints
        return enhanceSchemaWithCustomFeatures(schema);
      },
    ],
    transactionOptions: {
      isolationLevel: 'read committed',
      accessMode: 'read write',
    },
  }),
});

interface PoolConfig {
  /** Full connection string (alternative to individual options) */
  connectionString?: string;
  
  /** Database host */
  host?: string;
  
  /** Database port */
  port?: number;
  
  /** Database user */
  user?: string;
  
  /** Database password */
  password?: string;
  
  /** Database name */
  database?: string;
  
  /** SSL configuration */
  ssl?: boolean | {
    rejectUnauthorized?: boolean;
    ca?: string;
    cert?: string;
    key?: string;
  };
  
  /** Maximum number of connections in pool */
  max?: number;
  
  /** Minimum number of connections in pool */
  min?: number;
  
  /** Idle timeout in milliseconds */
  idle?: number;
  
  /** Acquire timeout in milliseconds */
  acquire?: number;
  
  /** Eviction timeout in milliseconds */
  evict?: number;
}

interface PgTransactionConfig {
  /** Transaction isolation level */
  isolationLevel?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable';
  
  /** Transaction access mode */
  accessMode?: 'read only' | 'read write';
  
  /** Whether transaction is deferrable */
  deferrable?: boolean;
}

/**
 * Schema transformation hook function
 * @param args - Object containing the current schema
 * @returns Modified schema object
 */
type PostgresSchemaHook = (args: { schema: Record<string, unknown> }) => Record<string, unknown>;

// Preserve existing database schema
const beforeSchemaInit: PostgresSchemaHook[] = [
  ({ schema }) => {
    // Merge with existing schema to avoid conflicts
    return { ...existingDatabaseSchema, ...schema };
  },
];

// Add custom features after schema generation
const afterSchemaInit: PostgresSchemaHook[] = [
  ({ schema }) => {
    // Add composite indices
    schema.users.indices = {
      ...schema.users.indices,
      email_name_idx: { columns: ['email', 'name'], unique: true },
    };
    return schema;
  },
];

interface MigrateUpArgs {
  /** The Postgres Drizzle instance for executing SQL directly within the current transaction */
  db: PostgresDB;
  /** The Payload instance for executing Local API methods */
  payload: Payload;
  /** The PayloadRequest object containing the current transaction */
  req: PayloadRequest;
}

interface MigrateDownArgs {
  /** The Postgres Drizzle instance for executing SQL directly within the current transaction */
  db: PostgresDB;
  /** The Payload instance for executing Local API methods */
  payload: Payload;
  /** The PayloadRequest object containing the current transaction */
  req: PayloadRequest;
}

interface DatabaseAdapterObj<PostgresAdapter> {
  /** Adapter name identifier */
  name: 'postgres';
  
  /** Whether custom IDs are allowed on create */
  allowIDOnCreate: boolean;
  
  /** Default ID type for the adapter */
  defaultIDType: 'number' | 'text';
  
  /** Initialization function that creates the adapter instance */
  init: (options: { payload: Payload }) => PostgresAdapter;
}

interface PostgresAdapter extends BasePostgresAdapter {
  /** Drizzle ORM database instance */
  drizzle: Drizzle;
  
  /** PostgreSQL driver dependency */
  pg: typeof import('pg');
  
  /** Active connection pool */
  pool: Pool;
  
  /** Pool configuration options */
  poolOptions: PoolConfig;
}