Lovefield - Relational Database for Web Apps

Common errors

• ReferenceError: lf is not defined

  cause The Lovefield JavaScript file was not loaded, or the code attempting to use 'lf' is executing before the script has parsed.
  fix Ensure `<script src="path/to/lovefield.min.js"></script>` is correctly placed in your HTML, preferably before any inline scripts that use `lf`. Verify the path to `lovefield.min.js` is correct and accessible.

• Error: This database is already connected, cannot connect again.

  cause The `schemaBuilder.connect()` method was called more than once for the same database instance. Lovefield assumes a single connection at a time.
  fix Ensure `schemaBuilder.connect()` is called only once. Store the returned database instance (`db`) and reuse it for all subsequent operations. You might need a global or module-scoped variable to hold the database connection promise or instance.

• TypeError: Cannot read properties of undefined (reading 'connect')

  cause The `lf.schema` object was not correctly accessed, or the global `lf` object was not available when trying to call `create()` or `connect()`.
  fix Double-check that `lf` is defined and accessible. This often happens if the `lovefield.min.js` script failed to load or a module system (e.g., CommonJS `require`) was incorrectly used in a browser context. Ensure `lf.schema.create()` is called to get a schema builder before attempting `schemaBuilder.connect()`.

Warnings

• breaking Lovefield is an abandoned project. The last npm package was published in 2017 (v2.1.12), and active development by Google ceased significantly earlier. Use in new projects is strongly discouraged due to lack of security updates, bug fixes, or compatibility with modern browser APIs and JavaScript features.
  Fix: Consider migrating to actively maintained client-side database solutions like IndexedDB directly, Dexie.js, PouchDB, or other state management libraries with persistence layers.
• breaking Lovefield explicitly does NOT support Node.js environments. It relies on the browser's IndexedDB API, which is not available in Node.js. Attempts to use it in Node.js will result in runtime errors.
  Fix: Do not attempt to use Lovefield in Node.js. For server-side or desktop applications, choose a different database solution.
• gotcha Once the `connect()` method is called on a `schemaBuilder`, the database schema cannot be altered. Any attempts to modify the schema after connection will fail or require a database upgrade path, which needs to be explicitly handled.
  Fix: Ensure your entire schema is fully defined before calling `schemaBuilder.connect()`. For schema changes in existing databases, implement the `onUpgrade` callback within `connect()` options, providing logic for data migration between versions.
• gotcha The results returned from `select` queries should be treated as read-only. Modifying these objects directly is not recommended and may lead to unexpected behavior or inconsistencies, as Lovefield does not actively clone/freeze objects from its internal cache for performance reasons.
  Fix: If modifications are needed, clone the result objects explicitly or perform updates via Lovefield's `update()` API, which ensures data integrity and proper persistence.
• gotcha Lovefield's SQL-like API does not support the `HAVING` clause, which is common in standard SQL for filtering grouped results. Additionally, multi-column `ROLLUP` and `CUBE` are not supported for `GROUP BY` operations.
  Fix: To achieve `HAVING` functionality, perform a `select` query with `groupBy`, then filter the results in JavaScript. For complex `GROUP BY` scenarios, multiple queries or client-side aggregation may be necessary.
• gotcha Lovefield does not provide an API for programmatically deleting a database instance. This can complicate cleanup during development or for end-users who need to reset application data.
  Fix: Database deletion must be performed manually through browser developer tools (e.g., Application -> IndexedDB in Chrome DevTools) or by clearing site data, which will remove all IndexedDB databases for the origin.

Install

• npm install lovefield npm
• yarn add lovefield yarn
• pnpm add lovefield pnpm

Imports

• lf

  <!-- In HTML -->
  <script src="path/to/lovefield.min.js"></script>
  <script>
    const schemaBuilder = lf.schema.create('my_db', 1);
    // ... rest of your code using lf
  </script>

  Lovefield is primarily designed for browser environments and exposes a global `lf` object after script inclusion. It does not officially support module systems like CommonJS or ESM for Node.js.
• lf.schema.create
  wrong:

  import { schema } from 'lovefield'; // Incorrect for browser global
  const schemaBuilder = schema.create('my_db', 1);

  correct:

  const schemaBuilder = lf.schema.create('my_db', 1);

  The `lf` global object is the entry point, with `schema` being a property on it. Direct named imports from a module are not the intended usage.
• lf.Type
  wrong:

  import { Type } from 'lovefield';
  addColumn('id', Type.INTEGER);

  correct:

  addColumn('id', lf.Type.INTEGER);

  `lf.Type` provides constants for column types, accessed via the global `lf` object.

Quickstart

This quickstart demonstrates how to define a database schema, connect to the database, insert data, and query data using Lovefield's SQL-like API in a browser environment, including a simple update operation.

<!-- In an HTML file -->
<!doctype html>
<html>
<head>
  <meta charset="utf-8" />
  <title>Lovefield Quick Start</title>
  <script src="https://unpkg.com/lovefield@2.1.12/dist/lovefield.min.js"></script>
</head>
<body>
  <script>
    // Define the database schema
    const schemaBuilder = lf.schema.create('todoDb', 1);
    schemaBuilder.createTable('Item')
        .addColumn('id', lf.Type.INTEGER)
        .addColumn('description', lf.Type.STRING)
        .addColumn('deadline', lf.Type.DATE_TIME)
        .addColumn('done', lf.Type.BOOLEAN)
        .addPrimaryKey(['id'])
        .addIndex('idxDeadline', ['deadline'], false, lf.Order.DESC);

    let todoDb;
    let itemTable;

    // Connect to the database and perform operations
    schemaBuilder.connect().then(function(db) {
      todoDb = db;
      itemTable = db.getSchema().table('Item');

      // Create a new row
      const row = itemTable.createRow({
        'id': 1,
        'description': 'Buy groceries',
        'deadline': new Date(2026, 4, 25),
        'done': false
      });

      // Insert the row into the database
      return db.insertOrReplace().into(itemTable).values([row]).exec();
    }).then(function() {
      // Query data
      return todoDb.select().from(itemTable).where(itemTable.done.eq(false)).exec();
    }).then(function(results) {
      // Process results
      results.forEach(function(row) {
        console.log(`Task: ${row['description']}, Due: ${row['deadline'].toLocaleDateString()}`);
      });

      // Example: Update an item
      return todoDb.update(itemTable)
                   .set(itemTable.done, true)
                   .where(itemTable.id.eq(1))
                   .exec();
    }).then(() => {
      console.log('Task ID 1 marked as done.');
    }).catch(err => {
      console.error('Lovefield operation failed:', err);
    });
  </script>
</body>
</html>