sails-sqlite 0.0.0 → 0.2.0

package/lib/private/machines/create-manager.js

@@ -0,0 +1,174 @@
+module.exports = {
+  friendlyName: 'Create manager',
+
+  description: 'Build and initialize a connection manager instance for SQLite.',
+
+  inputs: {
+    connectionString: {
+      description: 'The SQLite connection string (file path).',
+      example: 'db/database.sqlite',
+      required: true
+    },
+
+    meta: {
+      friendlyName: 'Meta (custom)',
+      description:
+        'A dictionary of additional options to pass in when instantiating the SQLite client.',
+      example: '==='
+    }
+  },
+
+  exits: {
+    success: {
+      description: 'Connected to SQLite successfully.',
+      outputFriendlyName: 'Report',
+      outputDescription:
+        'The `manager` property is a SQLite database instance.',
+      outputExample: '==='
+    }
+  },
+
+  fn: function ({ connectionString, meta }, exits) {
+    const Database = require('better-sqlite3')
+    const path = require('path')
+    const fs = require('fs')
+
+    try {
+      // Ensure the directory exists for the database file
+      const dbDir = path.dirname(connectionString)
+      if (dbDir !== '.' && !fs.existsSync(dbDir)) {
+        fs.mkdirSync(dbDir, { recursive: true })
+      }
+
+      // Create database connection with optimized options
+      const dbOptions = {
+        // Enable verbose mode in development
+        verbose:
+          meta?.verbose || process.env.NODE_ENV === 'development'
+            ? console.log
+            : null,
+        // Set timeout for database operations
+        timeout: meta?.timeout || 5000,
+        // Enable read-only mode if specified
+        readonly: meta?.readonly || false,
+        // Enable file must exist mode if specified
+        fileMustExist: meta?.fileMustExist || false,
+        ...meta
+      }
+
+      const db = new Database(connectionString, dbOptions)
+
+      // Apply recommended performance pragmas for optimal SQLite performance
+      const defaultPragmas = {
+        // WAL mode for better concurrency (default)
+        journal_mode: 'WAL',
+        // Synchronous mode for better performance vs durability balance
+        synchronous: 'NORMAL',
+        // Enable foreign key support
+        foreign_keys: 'ON',
+        // Set cache size to 256MB (negative value means KB)
+        cache_size: -262144,
+        // Set page size to 4KB (recommended for modern systems)
+        page_size: 4096,
+        // Optimize for read-heavy workloads
+        optimize: true,
+        // Enable memory-mapped I/O
+        mmap_size: 268435456, // 256MB
+        // Set busy timeout to 30 seconds
+        busy_timeout: 30000,
+        // Enable automatic index creation for WHERE clauses
+        automatic_index: 'ON',
+        // Optimize temp store for performance
+        temp_store: 'MEMORY'
+      }
+
+      // Merge with user-provided pragmas
+      const pragmas = { ...defaultPragmas, ...(meta?.pragmas || {}) }
+
+      // Apply pragmas with error handling
+      Object.entries(pragmas).forEach(([key, value]) => {
+        if (value !== false && value !== null && value !== undefined) {
+          try {
+            db.pragma(`${key} = ${value}`)
+          } catch (pragmaError) {
+            console.warn(
+              `Warning: Could not set pragma ${key} = ${value}:`,
+              pragmaError.message
+            )
+          }
+        }
+      })
+
+      // Run ANALYZE to update query planner statistics
+      // This is especially important for new databases
+      try {
+        db.exec('ANALYZE')
+      } catch (analyzeError) {
+        // ANALYZE might fail on empty database, which is fine
+        console.debug(
+          'ANALYZE command failed (this is normal for new databases):',
+          analyzeError.message
+        )
+      }
+
+      // Prepare commonly used statements for better performance
+      // These will be cached and reused throughout the application lifecycle
+      const preparedStatements = new Map()
+
+      // Add helper method to get or create prepared statements
+      db.getPreparedStatement = function (sql) {
+        if (!preparedStatements.has(sql)) {
+          preparedStatements.set(sql, this.prepare(sql))
+        }
+        return preparedStatements.get(sql)
+      }
+
+      // Add transaction helper methods for better performance
+      db.runInTransaction = function (fn) {
+        return this.transaction(fn)()
+      }
+
+      // Add method to optimize database
+      db.optimize = function () {
+        this.exec('PRAGMA optimize')
+        this.exec('VACUUM')
+        this.exec('ANALYZE')
+      }
+
+      // Add graceful cleanup method
+      db.closeGracefully = function () {
+        // Clear prepared statements - newer better-sqlite3 doesn't need explicit finalize
+        preparedStatements.clear()
+
+        // Close the database connection
+        if (this.open) {
+          this.close()
+        }
+      }
+
+      // Set up connection health check
+      db.isHealthy = function () {
+        try {
+          this.prepare('SELECT 1').get()
+          return true
+        } catch (error) {
+          return false
+        }
+      }
+
+      return exits.success({
+        manager: db,
+        meta: {
+          ...meta,
+          connectionString,
+          pragmasApplied: pragmas,
+          connectionEstablishedAt: new Date().toISOString()
+        }
+      })
+    } catch (error) {
+      return exits.error(
+        new Error(`Failed to create SQLite database manager: ${error.message}`)
+      )
+    }
+  }
+}

package/lib/private/machines/create-record.js

@@ -0,0 +1,126 @@
+module.exports = {
+  friendlyName: 'Create (record)',
+
+  description: 'Create a new physical record in the SQLite database.',
+
+  inputs: {
+    query: require('../constants/query.input'),
+    connection: require('../constants/connection.input'),
+    dryOrm: require('../constants/dry-orm.input')
+  },
+
+  exits: {
+    success: {
+      outputFriendlyName: 'Record (maybe)',
+      outputDescription:
+        'Either `null` or (if `fetch:true`) a dictionary representing the new record that was created.',
+      outputExample: '==='
+    },
+    notUnique: require('../constants/not-unique.exit')
+  },
+
+  fn: function (inputs, exits) {
+    // Dependencies
+    const util = require('util')
+    const _ = require('@sailshq/lodash')
+    const processNativeRecord = require('./private/process-native-record')
+    const processNativeError = require('./private/process-native-error')
+    const reifyValuesToSet = require('./private/reify-values-to-set')
+
+    // Local var for the stage 3 query, for easier access.
+    const s3q = inputs.query
+    if (s3q.meta && s3q.meta.logSQLiteS3Qs) {
+      console.log(
+        '* * * * * *\nADAPTER (CREATE RECORD):',
+        util.inspect(s3q, { depth: 5 }),
+        '\n'
+      )
+    }
+
+    // Local var for the `tableName`, for clarity.
+    const tableName = s3q.using
+
+    // Grab the model definition
+    const WLModel = _.find(inputs.dryOrm.models, { tableName: tableName })
+    if (!WLModel) {
+      return exits.error(
+        new Error(
+          `No model with that tableName (\`${tableName}\`) has been registered with this adapter.  Were any unexpected modifications made to the stage 3 query?  Could the adapter's internal state have been corrupted?  (This error is usually due to a bug in this adapter's implementation.)`
+        )
+      )
+    }
+
+    // Reify values to set
+    try {
+      reifyValuesToSet(s3q.newRecord, WLModel, s3q.meta)
+    } catch (e) {
+      return exits.error(e)
+    }
+
+    // Determine whether to fetch or not
+    const isFetchEnabled = !!(s3q.meta && s3q.meta.fetch)
+
+    // Create this new record in the SQLite database
+    const db = inputs.connection
+
+    try {
+      // Build column names and values arrays
+      const columnNames = Object.keys(s3q.newRecord)
+      const columnValues = Object.values(s3q.newRecord)
+
+      // Validate that we have data to insert
+      if (columnNames.length === 0) {
+        throw new Error('Cannot create record: no data provided')
+      }
+
+      // Prepare the INSERT statement with proper SQL escaping
+      const columns = columnNames.map((col) => `\`${col}\``).join(', ')
+      const placeholders = columnNames.map(() => '?').join(', ')
+      const sql = `INSERT INTO \`${tableName}\` (${columns}) VALUES (${placeholders})`
+
+      // Use prepared statement (optimized for repeated use)
+      const stmt = db.getPreparedStatement
+        ? db.getPreparedStatement(sql)
+        : db.prepare(sql)
+
+      // Execute the INSERT statement within a transaction for consistency
+      const info = db.runInTransaction
+        ? db.runInTransaction(() => stmt.run(columnValues))
+        : stmt.run(columnValues)
+
+      // If `fetch` is NOT enabled, we're done.
+      if (!isFetchEnabled) {
+        return exits.success()
+      }
+
+      // Otherwise, fetch the newly created record
+      const selectSql = `SELECT * FROM \`${tableName}\` WHERE rowid = ?`
+      const selectStmt = db.prepare(selectSql)
+      const phRecord = selectStmt.get(info.lastInsertRowid)
+
+      if (!phRecord) {
+        return exits.error(
+          new Error(
+            'Consistency violation: Unable to retrieve the inserted record. This might indicate a consistency violation.'
+          )
+        )
+      }
+
+      try {
+        // Process record (mutate in-place) to wash away adapter-specific eccentricities.
+        processNativeRecord(phRecord, WLModel, s3q.meta)
+      } catch (e) {
+        return exits.error(e)
+      }
+
+      // Send back the record
+      return exits.success(phRecord)
+    } catch (err) {
+      err = processNativeError(err)
+      if (err.footprint && err.footprint.identity === 'notUnique') {
+        return exits.notUnique(err)
+      }
+      return exits.error(err)
+    }
+  }
+}

package/lib/private/machines/define-physical-model.js

@@ -0,0 +1,111 @@
+module.exports = {
+  friendlyName: 'Define (physical model)',
+
+  description:
+    'Define a physical model (i.e. SQLite table) with the specified characteristics, creating indexes as needed.',
+
+  sideEffects: 'idempotent',
+
+  inputs: {
+    connection: require('../constants/connection.input'),
+    tableName: require('../constants/table-name.input'),
+    columns: {
+      description: 'An array of column definitions.',
+      required: true,
+      example: '==='
+    },
+    meta: require('../constants/meta.input')
+  },
+
+  exits: {
+    success: {
+      description:
+        'New physical model (and any necessary indexes) were created successfully.'
+    }
+  },
+
+  fn: function (inputs, exits) {
+    const db = inputs.connection
+    function getSqliteType(columnType) {
+      if (!columnType || typeof columnType !== 'string') {
+        return 'TEXT' // Default fallback
+      }
+      switch (columnType.toLowerCase()) {
+        case '_string':
+        case '_text':
+        case '_mediumtext':
+        case '_longtext':
+          return 'TEXT'
+        case '_number':
+        case '_numberkey':
+        case '_numbertimestamp':
+        case 'integer':
+        case 'int':
+          return 'INTEGER'
+        case '_json':
+          return 'TEXT'
+        case 'float':
+        case 'double':
+        case 'real':
+          return 'REAL'
+        case 'boolean':
+          return 'INTEGER'
+        case 'date':
+        case 'datetime':
+          return 'TEXT'
+        case 'binary':
+        case 'blob':
+          return 'BLOB'
+        default:
+          return 'TEXT'
+      }
+    }
+
+    // Check if we're already in a transaction
+    const wasInTransaction = db.inTransaction
+
+    try {
+      // Start a transaction only if we're not already in one
+      if (!wasInTransaction) {
+        db.prepare('BEGIN').run()
+      }
+
+      // Build and execute the CREATE TABLE statement
+      let createTableSQL = `CREATE TABLE IF NOT EXISTS \`${inputs.tableName}\` (`
+      let columnDefs = inputs.columns.map((column) => {
+        const columnType = column.columnType ?? column.type
+        let def = `\`${column.columnName}\` ${column.autoIncrement ? 'INTEGER' : getSqliteType(columnType)}`
+        if (column.autoIncrement) {
+          def += ' PRIMARY KEY AUTOINCREMENT NOT NULL'
+        }
+        if (column.unique && !column.autoIncrement) def += ' UNIQUE'
+        return def
+      })
+      createTableSQL += columnDefs.join(', ') + ')'
+      db.prepare(createTableSQL).run()
+
+      // Create indexes
+      inputs.columns.forEach((column) => {
+        if (column.unique && !column.autoIncrement) {
+          const indexSQL = `CREATE UNIQUE INDEX IF NOT EXISTS \`idx_${inputs.tableName}_${column.columnName}\` ON \`${inputs.tableName}\` (\`${column.columnName}\`)`
+          db.prepare(indexSQL).run()
+        }
+      })
+
+      // Commit the transaction only if we started it
+      if (!wasInTransaction) {
+        db.prepare('COMMIT').run()
+      }
+
+      return exits.success()
+    } catch (error) {
+      // If there's an error, roll back the transaction (only if we started it)
+      if (!wasInTransaction) {
+        db.prepare('ROLLBACK').run()
+      }
+      return exits.error(
+        new Error(`Error defining table ${inputs.tableName}: ${error.message}`)
+      )
+    }
+  }
+}

package/lib/private/machines/destroy-manager.js

@@ -0,0 +1,87 @@
+module.exports = {
+  friendlyName: 'Destroy manager',
+
+  description: 'Destroy the specified SQLite connection manager.',
+
+  extendedDescription:
+    'For SQLite, this involves closing the database connection. Unlike other databases, SQLite does not use connection pools, so this operation is relatively straightforward.',
+
+  sync: true,
+
+  inputs: {
+    manager: {
+      description: 'The SQLite connection manager instance to destroy.',
+      extendedDescription:
+        'Only managers built using the `createManager()` method of this driver are supported. The database connection manager instance provided must not have been destroyed previously.',
+      example: '===',
+      required: true
+    },
+
+    meta: {
+      friendlyName: 'Meta (custom)',
+      description: 'Additional options to pass to the SQLite driver.',
+      extendedDescription:
+        'This is reserved for custom driver-specific extensions. Please refer to the better-sqlite3 documentation for more specific information.',
+      example: '==='
+    }
+  },
+
+  exits: {
+    success: {
+      description: 'The specified SQLite manager was successfully destroyed.',
+      outputFriendlyName: 'Report',
+      outputDescription:
+        'The `meta` property is reserved for custom driver-specific extensions.',
+      outputExample: '==='
+    }
+  },
+
+  fn: ({ manager, meta }, exits) => {
+    try {
+      // Validate the manager
+      if (
+        typeof manager !== 'object' ||
+        manager === null ||
+        typeof manager.close !== 'function'
+      ) {
+        return exits.error(
+          new Error(
+            'The provided `manager` is not a valid SQLite manager. It should be a better-sqlite3 Database instance with a `close` method.'
+          )
+        )
+      }
+
+      // Check if the database is already closed
+      if (!manager.open) {
+        console.warn(
+          'SQLite manager appears to already be closed, skipping destruction'
+        )
+        return exits.success({ meta })
+      }
+
+      // Use graceful cleanup if available (from enhanced create-manager)
+      if (typeof manager.closeGracefully === 'function') {
+        manager.closeGracefully()
+      } else {
+        // Fallback to basic close
+        manager.close()
+      }
+
+      // Verify the connection is actually closed
+      if (manager.open) {
+        throw new Error('Failed to close SQLite database connection')
+      }
+
+      return exits.success({
+        meta: {
+          ...meta,
+          destroyedAt: new Date().toISOString()
+        }
+      })
+    } catch (error) {
+      return exits.error(
+        new Error(`Error destroying SQLite manager: ${error.message}`)
+      )
+    }
+  }
+}

package/lib/private/machines/destroy-records.js

@@ -0,0 +1,114 @@
+const util = require('util')
+const processNativeRecord = require('./private/process-native-record')
+const buildSqliteWhereClause = require('./private/build-sqlite-where-clause')
+
+module.exports = {
+  friendlyName: 'Destroy (records)',
+
+  description:
+    'Destroy record(s) in the SQLite database matching a query criteria.',
+
+  inputs: {
+    query: require('../constants/query.input'),
+    connection: require('../constants/connection.input'),
+    dryOrm: require('../constants/dry-orm.input')
+  },
+
+  exits: {
+    success: {
+      outputFriendlyName: 'Records (maybe)',
+      outputDescription:
+        'Either `null` OR (if `fetch:true`) an array of physical records that were destroyed.',
+      outputExample: '==='
+    }
+  },
+
+  fn: async function (inputs, exits) {
+    const s3q = inputs.query
+    if (s3q.meta && s3q.meta.logSqliteS3Qs) {
+      console.log(
+        '* * * * * *\nADAPTER (DESTROY RECORDS):',
+        util.inspect(s3q, { depth: 5 }),
+        '\n'
+      )
+    }
+
+    const tableName = s3q.using
+    // Find model by tableName since models is an object, not an array
+    let WLModel = null
+    for (const modelIdentity in inputs.dryOrm.models) {
+      if (inputs.dryOrm.models[modelIdentity].tableName === tableName) {
+        WLModel = inputs.dryOrm.models[modelIdentity]
+        break
+      }
+    }
+
+    if (!WLModel) {
+      return exits.error(
+        new Error(
+          `No model with that tableName (\`${tableName}\`) has been registered with this adapter. Were any unexpected modifications made to the stage 3 query? Could the adapter's internal state have been corrupted? (This error is usually due to a bug in this adapter's implementation.)`
+        )
+      )
+    }
+
+    const pkColumnName = WLModel.attributes[WLModel.primaryKey].columnName
+    const isFetchEnabled = !!(s3q.meta && s3q.meta.fetch)
+
+    const sqliteWhere = buildSqliteWhereClause(
+      s3q.criteria.where,
+      WLModel,
+      s3q.meta
+    )
+
+    const db = inputs.connection
+
+    // Check if we're already in a transaction
+    const wasInTransaction = db.inTransaction
+
+    try {
+      // Start a transaction only if we're not already in one
+      if (!wasInTransaction) {
+        db.exec('BEGIN TRANSACTION')
+      }
+
+      let phRecords
+      if (isFetchEnabled) {
+        // Fetch matching records before deletion
+        const selectSql = sqliteWhere
+          ? `SELECT * FROM \`${tableName}\` WHERE ${sqliteWhere}`
+          : `SELECT * FROM \`${tableName}\``
+        const selectStmt = db.prepare(selectSql)
+        phRecords = selectStmt.all()
+      }
+
+      // Perform the deletion
+      const deleteSql = sqliteWhere
+        ? `DELETE FROM \`${tableName}\` WHERE ${sqliteWhere}`
+        : `DELETE FROM \`${tableName}\``
+      const deleteStmt = db.prepare(deleteSql)
+      const deleteInfo = deleteStmt.run()
+
+      // Commit the transaction only if we started it
+      if (!wasInTransaction) {
+        db.exec('COMMIT')
+      }
+
+      if (!isFetchEnabled) {
+        return exits.success()
+      }
+
+      // Process fetched records
+      phRecords.forEach((phRecord) => {
+        processNativeRecord(phRecord, WLModel, s3q.meta)
+      })
+
+      return exits.success(phRecords)
+    } catch (err) {
+      // Rollback the transaction in case of error (only if we started it)
+      if (!wasInTransaction) {
+        db.exec('ROLLBACK')
+      }
+      return exits.error(err)
+    }
+  }
+}

package/lib/private/machines/drop-physical-model.js

@@ -0,0 +1,51 @@
+module.exports = {
+  friendlyName: 'Drop (physical model)',
+
+  description:
+    'Completely drop & destroy any traces of a particular physical model (i.e. SQLite table).',
+
+  sideEffects: 'idempotent',
+
+  inputs: {
+    connection: require('../constants/connection.input'),
+    tableName: require('../constants/table-name.input'),
+    meta: require('../constants/meta.input')
+  },
+
+  exits: {
+    success: {
+      description:
+        'If such a physical model exists, it was dropped successfully.'
+    }
+  },
+
+  fn: function (inputs, exits) {
+    // Get the SQLite database connection
+    const db = inputs.connection
+
+    try {
+      // SQL to drop the table (properly escape the table name)
+      const dropTableSQL = `DROP TABLE IF EXISTS \`${inputs.tableName}\``
+
+      // Execute the drop table operation
+      db.prepare(dropTableSQL).run()
+
+      // SQL to remove the table's entry from sqlite_sequence (if it exists)
+      const cleanSequenceSQL = `DELETE FROM sqlite_sequence WHERE name = ?`
+
+      // Clean up the sqlite_sequence
+      db.prepare(cleanSequenceSQL).run(inputs.tableName)
+
+      // Return success, as the main operation (dropping the table) was successful
+      return exits.success()
+    } catch (error) {
+      if (error.message.includes('no such table: sqlite_sequence')) {
+        // If sqlite_sequence doesn't exist, it's not an error - just means no autoincrement was used
+        return exits.success()
+      }
+      return exits.error(
+        new Error(`Error dropping table ${inputs.tableName}: ${error.message}`)
+      )
+    }
+  }
+}