or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

cli-interface.md configuration-management.md data-seeding.md database-interface.md database-operations.md index.md migration-management.md

tile.json

Database Operations

Database-level operations for creating and dropping databases, useful for environment setup and teardown. These operations work across different database systems including MySQL, PostgreSQL, SQLite3, and MongoDB.

Capabilities

Create Database

Create a new database with the specified name.

/**
 * Create a database with the specified name
 * @param dbname - Name of database to create
 * @param callback - Completion callback (function)
 * @returns Promise
 */
createDatabase(dbname, callback): Promise;

Usage Examples:

const dbMigrate = require('db-migrate');
const instance = dbMigrate.getInstance();

// Create database
await instance.createDatabase('myapp_development');

// With callback
instance.createDatabase('myapp_test', (err) => {
  if (err) console.error('Failed to create database:', err);
  else console.log('Database created successfully');
});

// Create database for different environments
await instance.createDatabase('myapp_production');

Drop Database

Drop (delete) a database with the specified name.

/**
 * Drop a database with the specified name
 * @param dbname - Name of database to drop
 * @param callback - Completion callback (function)
 * @returns Promise
 */
dropDatabase(dbname, callback): Promise;

Usage Examples:

// Drop database
await instance.dropDatabase('myapp_test');

// With callback
instance.dropDatabase('old_database', (err) => {
  if (err) console.error('Failed to drop database:', err);
  else console.log('Database dropped successfully');
});

// Drop database with error handling
try {
  await instance.dropDatabase('myapp_staging');
  console.log('Staging database removed');
} catch (error) {
  if (error.message.includes('does not exist')) {
    console.log('Database was already removed');
  } else {
    throw error;
  }
}

Database-Specific Behavior

MySQL

Creates database with default character set (usually utf8mb4)
Requires appropriate user privileges (CREATE privilege)
Database names are case-sensitive on Linux, case-insensitive on Windows

Example Configuration:

{
  "dev": {
    "driver": "mysql",
    "host": "localhost",
    "user": "root",
    "password": "password",
    "multipleStatements": true
  }
}

PostgreSQL

Creates database with default encoding (usually UTF8)
Requires CREATEDB privilege or superuser access
Database names are converted to lowercase unless quoted

Example Configuration:

{
  "dev": {
    "driver": "pg",
    "host": "localhost", 
    "user": "postgres",
    "password": "password",
    "port": 5432
  }
}

SQLite3

Creates a new SQLite database file
Path can be relative or absolute
Directory must exist before creating database

Example Configuration:

{
  "dev": {
    "driver": "sqlite3",
    "filename": "./database/myapp.db"
  }
}

MongoDB

Creates a new MongoDB database
Database is created implicitly when first collection is created
Requires appropriate MongoDB user privileges

Example Configuration:

{
  "dev": {
    "driver": "mongodb",
    "host": "localhost",
    "database": "myapp_development",
    "port": 27017
  }
}

CLI Usage

Database operations are also available through the command-line interface:

# Create database
db-migrate db:create myapp_development

# Drop database  
db-migrate db:drop myapp_test

# With specific environment
db-migrate db:create myapp_production --env production

# With config file
db-migrate db:create myapp_staging --config ./config/database.json

Error Handling

Database operations can fail for various reasons:

try {
  await instance.createDatabase('myapp_production');
} catch (error) {
  if (error.message.includes('already exists')) {
    console.log('Database already exists, continuing...');
  } else if (error.message.includes('permission denied')) {
    console.error('Insufficient database privileges');
    throw error;
  } else if (error.message.includes('connection')) {
    console.error('Cannot connect to database server');
    throw error;
  } else {
    throw error;
  }
}

Environment-Based Operations

Database operations respect the current environment configuration:

// Using different configurations for different environments
const devInstance = dbMigrate.getInstance(true, { env: 'development' });
await devInstance.createDatabase('myapp_development');

const testInstance = dbMigrate.getInstance(true, { env: 'test' });  
await testInstance.createDatabase('myapp_test');

const prodInstance = dbMigrate.getInstance(true, { env: 'production' });
await prodInstance.createDatabase('myapp_production');

Best Practices

Development Workflow

// Setup development environment
async function setupDevelopment() {
  const instance = dbMigrate.getInstance(true, { env: 'development' });
  
  try {
    // Create database if it doesn't exist
    await instance.createDatabase('myapp_development');
    console.log('Development database ready');
    
    // Run migrations
    await instance.up();
    console.log('Migrations applied');
    
  } catch (error) {
    if (!error.message.includes('already exists')) {
      throw error;
    }
    console.log('Database already exists, running migrations...');
    await instance.up();
  }
}

Testing Workflow

// Setup and teardown test database
async function setupTestDatabase() {
  const instance = dbMigrate.getInstance(true, { env: 'test' });
  
  // Clean slate for tests
  try {
    await instance.dropDatabase('myapp_test');
  } catch (error) {
    // Ignore if database doesn't exist
  }
  
  await instance.createDatabase('myapp_test');
  await instance.up();
}

async function teardownTestDatabase() {
  const instance = dbMigrate.getInstance(true, { env: 'test' });
  await instance.dropDatabase('myapp_test');
}

Types

/**
 * Database operation callback function signature
 */
type DatabaseCallback = (error?: Error) => void;

/**
 * Database operation options
 */
interface DatabaseOptions {
  /** Target environment */
  env?: string;
  /** Configuration object or file path */
  config?: string | object;
}

Version

Tile

Files