The turbine-orm/cli module

turbine-orm/cli holds the config behind the turbine CLI: the TurbineCliConfig type and the functions that find, load and resolve it. Most projects import only the type:

// turbine.config.ts
import type { TurbineCliConfig } from 'turbine-orm/cli';
 
const config: TurbineCliConfig = {
  url: process.env.DATABASE_URL,
  out: './generated/turbine',
  schema: 'public',
  migrationsDir: './turbine/migrations',
  seedFile: './turbine/seed.ts',
  schemaFile: './turbine/schema.ts',
};
 
export default config;

The module exports no commands and opens no connection, so importing it has no side effects.

TurbineCliConfig#

• The module's TurbineConfig export is an alias of TurbineCliConfig, not the runtime TurbineConfig from the package root.
• A schema that looks like a file path (a / or \, or a .ts, .mts, .cts, .js, .mjs, .cjs or .json ending) would match no tables, so turbine generate refuses it. The check is the exported looksLikeSchemaFilePath(value).

Finding and loading the config#

import { findConfigFile, loadConfig, loadConfigResult } from 'turbine-orm/cli';
 
const { config, loadError } = await loadConfigResult();
if (loadError) {
  console.error(`Failed to load ${loadError.filename}:`, loadError.error);
}

Candidates are turbine.config.ts, turbine.config.mts, turbine.config.js and turbine.config.mjs, in that order. The first that imports successfully wins.

unwrapModuleDefault(mod) and unwrapConfigModule(mod) unwrap a module's default export. In a "type": "commonjs" project, importing turbine.config.ts through tsx can wrap the default twice ({ default: { default: config } }), which would otherwise read every field as undefined.

resolveConfig(fileConfig, overrides)#

Merges a loaded config with flag overrides and the environment into a fully defaulted ResolvedConfig.

import { loadConfig, resolveConfig } from 'turbine-orm/cli';
 
const resolved = resolveConfig(await loadConfig(), { url: argv.url, out: argv.out });

• A flag beats the config file, which beats the default.
• url alone reads the environment: --url, then DATABASE_URL, then the file's url. A shell DATABASE_URL therefore overrides the config file.
• An empty or whitespace-only value counts as unset.
• CliOverrides covers url, out, schema, schemaFile, include, exclude, importExtension, keepColumnNames and legacyToManyUniques. Everything else comes from the file.

resolveSeedFile(config, cwd?)#

Returns the seed file's absolute path, or null.

import { resolveSeedFile } from 'turbine-orm/cli';
 
const seed = resolveSeedFile({ seedFile: './turbine/seed.ts' });

An explicit seedFile (or seed) wins even when the file does not exist yet, so a typo surfaces as a missing file. Otherwise the first that exists of seed.ts, seed.js, seed.sql, turbine/seed.ts, turbine/seed.js, turbine/seed.sql.

configTemplate(connectionString?, schema?)#

Returns the turbine.config.ts source that turbine init writes, with schema defaulting to 'public'. A connection string without a password is inlined. One with a password, or none, gives url: process.env.DATABASE_URL. DEFAULT_INIT_SEED_FILE is the seed path the template uses.

See also#

• CLI: every command and flag.
• Seeding: writing the seed file.
• Schema: the schemaFile that push applies.