Configuration

Durcno uses a configuration file (durcno.config.ts) to define your database connection, schema location, and migration settings. This page documents all available configuration options.

Config File Location

By default, Durcno looks for durcno.config.ts in your project root. You can specify a custom path using the --config flag:

npm exec durcno generate --config ./config/durcno.config.ts

Basic Structure

// durcno.config.ts
import { defineConfig } from "durcno";
import { pg } from "durcno/connectors/pg";

export default defineConfig({
  schema: "db/schema.ts",
  out: "migrations",
  connector: pg({
    dbCredentials: {
      url: process.env.DATABASE_URL!,
    },
  }),
});

Configuration Options

schema

Type: string
Required: Yes

The path to your database schema file, relative to the config file location.

export default defineConfig({
  schema: "db/schema.ts",
  // ...
});

out

Type: string
Default: "migrations"

The output directory where generated migration files will be stored.

export default defineConfig({
  schema: "db/schema.ts",
  out: "migrations",
  // ...
});

connector

Type: Connector
Required: Yes

The database connector instance. Pass the result of calling one of the connector factory functions (pg(), postgres(), bun(), pglite()), each configured with connection credentials and optional pool/logger settings.

See Connectors for the full list of available connectors.

URL Format

export default defineConfig({
  schema: "db/schema.ts",
  connector: pg({
    dbCredentials: {
      url: "postgresql://user:password@localhost:5432/database",
    },
  }),
});

tip

Use environment variables for database credentials:

connector: pg({
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
}),

Individual Parameters

Parameter	Type	Required	Description
host	string	Yes	Database server hostname
port	number	No	Database server port (default: 5432)
user	string	Yes	Database username
password	string	No	Database password
database	string	Yes	Database name
ssl	boolean | string | ConnectionOptions	No	SSL/TLS configuration

export default defineConfig({
  schema: "db/schema.ts",
  connector: pg({
    dbCredentials: {
      host: "localhost",
      port: 5432,
      user: "postgres",
      password: "password",
      database: "myapp",
    },
  }),
});

SSL Configuration

The ssl option supports multiple formats:

// Disable SSL
connector: pg({
  dbCredentials: {
    host: "localhost",
    user: "postgres",
    database: "myapp",
    ssl: false,
  },
}),

// Require SSL (no certificate verification)
connector: pg({
  dbCredentials: {
    host: "db.example.com",
    user: "postgres",
    database: "myapp",
    ssl: "require",
  },
}),

// SSL with full certificate verification
connector: pg({
  dbCredentials: {
    host: "db.example.com",
    user: "postgres",
    database: "myapp",
    ssl: "verify-full",
  },
}),

// Custom SSL options (Node.js TLS ConnectionOptions)
connector: pg({
  dbCredentials: {
    host: "db.example.com",
    user: "postgres",
    database: "myapp",
    ssl: {
      rejectUnauthorized: true,
      ca: fs.readFileSync("/path/to/ca-cert.pem").toString(),
    },
  },
}),

SSL Mode Values:

Value	Description
false	Disable SSL
true	Enable SSL
"require"	Require SSL connection (no certificate verification)
"allow"	Try SSL first, fall back to non-SSL
"prefer"	Prefer SSL, fall back to non-SSL
"verify-full"	Require SSL with full certificate verification

logger

Type: DurcnoLogger (or QueryLogger)
Optional

A logger instance that receives query execution events and database lifecycle failures (such as transaction rollbacks or connection releases). Successful queries call info(), while failed queries and errors call error(). Any object with compatible info() and error() methods can be used. Durcno ships a pre-configured Winston logger via durcno/logger.

Pass logger inside the connector options. See Query Logger for full details and examples.

import { createLogger } from "durcno/logger";

export default defineConfig({
  schema: "db/schema.ts",
  connector: pg({
    dbCredentials: {
      url: process.env.DATABASE_URL!,
    },
    logger: createLogger(),
  }),
});

pool

Type: object
Optional

Connection pool configuration. Pass pool inside the connector options.

Property	Type	Default	Description
max	number	10	Maximum number of connections in the db pool

export default defineConfig({
  schema: "db/schema.ts",
  connector: pg({
    dbCredentials: {
      url: process.env.DATABASE_URL!,
    },
    pool: {
      max: 20,
    },
  }),
});

Full Example

Here's a complete configuration example with all options:

// durcno.config.ts
import { defineConfig } from "durcno";
import { pg } from "durcno/connectors/pg";

export default defineConfig({
  // Schema file location
  schema: "db/schema.ts",

  // Migration output directory
  out: "migrations",

  connector: pg({
    // Database connection
    dbCredentials: {
      host: process.env.DB_HOST ?? "localhost",
      port: Number(process.env.DB_PORT) || 5432,
      user: process.env.DB_USER ?? "postgres",
      password: process.env.DB_PASSWORD,
      database: process.env.DB_NAME ?? "myapp",
      ssl: process.env.NODE_ENV === "production" ? "require" : false,
    },

    // Connection pool settings
    pool: {
      max: 20,
    },
  }),
});

Environment-Specific Configuration

You can create environment-specific configurations:

// durcno.config.ts
import { defineConfig } from "durcno";
import { pg } from "durcno/connectors/pg";

const isDevelopment = process.env.NODE_ENV !== "production";

export default defineConfig({
  schema: "db/schema.ts",
  out: "migrations",
  connector: pg({
    dbCredentials: isDevelopment
      ? {
        host: "localhost",
        port: 5432,
        user: "postgres",
        password: "devpassword",
        database: "myapp_dev",
      }
      : {
        url: process.env.DATABASE_URL!,
      },
    pool: {
      max: isDevelopment ? 5 : 20,
    },
  }),
});

Type Reference

The full TypeScript types for the configuration:

type Config<T extends Connector = Connector> = {
  schema: string;
  out?: string;
  connector: T;
};

type ConnectorOptions = {
  dbCredentials:
    | {
      host: string;
      port?: number;
      user: string;
      password?: string;
      database: string;
      ssl?:
        | boolean
        | "require"
        | "allow"
        | "prefer"
        | "verify-full"
        | ConnectionOptions;
    }
    | {
      url: string;
    };
  pool?: {
    max?: number;
  };
  logger?: DurcnoLogger;
};