{"id":11329,"library":"minato","title":"Minato Database Framework","description":"Minato is a type-driven database framework for JavaScript and TypeScript, designed to provide a unified API across various database backends. It supports a wide range of drivers including Memory, MongoDB, MySQL, PostgreSQL, and SQLite, allowing developers to switch databases with minimal code changes. Written entirely in TypeScript, Minato offers comprehensive type safety for schema definitions and queries, aiming to eliminate common database-related errors at compile time. It distinguishes itself by providing a powerful, extensible, and modern ORM experience that can handle complex SQL operations through a JavaScript API. Currently at version 4.0.1, Minato maintains an active, demand-driven release cadence, focusing on compatibility, performance, and a consistent developer experience across diverse data stores. Its tight integration capabilities with the Cordis framework make it particularly suitable for modular and extensible application architectures.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/cordiverse/minato","tags":["javascript","orm","query","database","sql","mysql","sqlite","mongo","postgres","typescript"],"install":[{"cmd":"npm install minato","lang":"bash","label":"npm"},{"cmd":"yarn add minato","lang":"bash","label":"yarn"},{"cmd":"pnpm add minato","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for advanced integration with the Cordis application framework, enabling modular database services and context management.","package":"cordis","optional":true}],"imports":[{"note":"The main Database class is exported as a default export.","wrong":"import { Database } from 'minato'","symbol":"Database","correct":"import Database from 'minato'"},{"note":"Database drivers are provided as separate packages and typically exported as default exports from their respective modules. Replace 'mysql' with your desired driver (e.g., 'mongodb', 'sqlite').","symbol":"MySQLDriver","correct":"import MySQLDriver from '@minatojs/driver-mysql'"},{"note":"Schemas are typically defined by calling the `extend` method on an instantiated `Database` object, not by importing a separate `Schema` class.","symbol":"Schema Definition (method)","correct":"database.extend('collectionName', { /* schema */ })"}],"quickstart":{"code":"import Database from 'minato';\nimport MySQLDriver from '@minatojs/driver-mysql';\nimport type { Context } from 'cordis'; // Optional, if using Cordis\n\ninterface User {\n  id: number;\n  name: string;\n  age: number;\n  email?: string;\n}\n\nasync function runMinatoExample() {\n  // For Cordis integration, you might pass a Context, otherwise, it's optional.\n  // const ctx = new Context();\n  // const database = new Database(ctx); \n  const database = new Database();\n\n  // Define the schema for the 'user' collection/table\n  database.extend('user', {\n    id: 'unsigned', // Auto-incrementing primary key\n    name: 'string',\n    age: 'integer',\n    email: { type: 'string', nullable: true, unique: true },\n  }, {\n    primary: 'id',\n    autoInc: true,\n  });\n\n  // Connect to the database\n  try {\n    await database.connect(MySQLDriver, {\n      host: 'localhost',\n      port: 3306,\n      user: 'root',\n      password: process.env.DB_PASSWORD ?? '', // Use environment variable for sensitive info\n      database: 'minato_test_db',\n    });\n    console.log('Successfully connected to MySQL database.');\n\n    // Basic CRUD operations\n    // Create\n    const newUser = await database.create('user', {\n      name: 'Alice',\n      age: 30,\n      email: 'alice@example.com',\n    });\n    console.log('Created user:', newUser);\n\n    // Find\n    const users = await database.get('user', { age: { $gt: 25 } });\n    console.log('Users older than 25:', users);\n\n    // Update\n    await database.set('user', { id: newUser.id }, { age: 31 });\n    const updatedUser = await database.get('user', { id: newUser.id });\n    console.log('Updated user:', updatedUser[0]);\n\n    // Delete\n    await database.remove('user', { id: newUser.id });\n    console.log('Deleted user with ID:', newUser.id);\n\n  } catch (error) {\n    console.error('Database operation failed:', error);\n  } finally {\n    await database.disconnect();\n    console.log('Disconnected from database.');\n  }\n}\n\nrunMinatoExample();","lang":"typescript","description":"This quickstart demonstrates how to initialize Minato, define a type-safe schema, connect to a MySQL database using a separate driver, and perform common CRUD (Create, Read, Update, Delete) operations."},"warnings":[{"fix":"Consult the official Minato v4 release notes and documentation for specific migration instructions. Update method calls and schema definitions accordingly.","message":"Minato v4 introduces significant breaking changes from v3, particularly in API interfaces for database operations, schema definitions, and internal driver implementations. Users upgrading from v3 should carefully review the official migration guide (if available) or anticipate necessary code adjustments.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure you install the correct driver package using `npm install @minatojs/driver-<database-name>` in addition to `minato` itself.","message":"Minato requires separate driver packages (e.g., `@minatojs/driver-mysql`, `@minatojs/driver-mongodb`) for each database type. Forgetting to install the specific driver for your target database will result in runtime errors.","severity":"gotcha","affected_versions":">=3.x"},{"fix":"Utilize Minato's query builder features, population options, and careful schema design to minimize the number of database queries. Profile your application's database interactions in development.","message":"While Minato simplifies database interactions, complex data access patterns (e.g., deep nested relations, large joins) can still lead to N+1 query problems or inefficient database calls if not optimized. Always be mindful of the generated queries.","severity":"gotcha","affected_versions":"*"},{"fix":"Double-check your `database.extend` calls for accurate type mappings. Utilize IDE features for type hints and ensure your TypeScript configuration (`tsconfig.json`) is correctly set up for the project.","message":"Minato leverages TypeScript's powerful type inference. However, incorrect schema definitions or complex query constructs can sometimes lead to obscure TypeScript errors. Ensuring your types align with the actual database structure is crucial.","severity":"gotcha","affected_versions":"*"},{"fix":"Install `cordis` in your project: `npm install cordis`. Ensure its version is compatible with the `cordis` peer dependency range specified by Minato.","message":"The `cordis` package is a peer dependency in Minato v4. If you plan to use Minato within a Cordis application context, you must explicitly install `cordis` to avoid runtime errors related to missing modules or incompatible versions.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the required driver: `npm install @minatojs/driver-mysql` (replace `mysql` with your database).","cause":"The specific database driver package was not installed.","error":"Error: Cannot find module '@minatojs/driver-mysql' or its corresponding type declarations."},{"fix":"Change your import statement from `import { Database } from 'minato'` to `import Database from 'minato'`.","cause":"Attempting to instantiate `Database` using named import syntax when it's a default export.","error":"TypeError: minato_1.default is not a constructor"},{"fix":"Ensure your database server is running and accessible from your application's environment. Check database user permissions and connection string details. For local development, verify Docker containers are running or local services are active.","cause":"The application lacks necessary permissions to connect to the database socket or the database server is not running or misconfigured.","error":"Error: EACCES: permission denied, open '/var/run/mysqld/mysqld.sock'"},{"fix":"Pass the appropriate imported driver to the `connect` method: `await database.connect(MySQLDriver, config)`.","cause":"The `connect` method was called without passing a database driver (e.g., `MySQLDriver`).","error":"Error: No database driver provided."}],"ecosystem":"npm"}