Database-js Interface for Firebase

Common errors

• Error: Driver not found for protocol 'database-js-firebase:'

  cause The `database-js-firebase` package was not installed or correctly registered with `database-js`.
  fix Ensure both `database-js` and `database-js-firebase` are installed: `npm install database-js database-js-firebase`.

• FirebaseError: Firebase: Error (auth/invalid-email).

  cause The email provided in the connection string is not a valid format or does not correspond to an existing Firebase user account.
  fix Verify the email format and ensure it matches an authenticated user in your Firebase project.

• FirebaseError: Firebase: Error (auth/wrong-password).

  cause The password provided in the connection string is incorrect for the specified Firebase user.
  fix Double-check the password in your connection string for accuracy.

• Error: SQL command 'OUTER JOIN' not supported.

  cause Attempting to use an SQL command (like OUTER JOIN) that this library's SQL interpreter does not support.
  fix Refactor your SQL query to use only supported commands and join types (INNER, LEFT, RIGHT JOINs).

Warnings

• breaking The project appears to be abandoned, with no significant updates since 2018-2019. This means it is highly unlikely to be compatible with newer Firebase SDK versions, recent Node.js runtimes, or modern JavaScript features (e.g., native ESM support). It will not receive security patches, bug fixes, or new features.
  Fix: For new development, consider modern, actively maintained Firebase client libraries or alternative ORM/ODM solutions. For existing projects, evaluate the risk of using an unmaintained dependency.
• gotcha The SQL-like interface has significant functional limitations. Notably, `OUTER JOIN` is not supported, and JSON values cannot be directly UPDATEd, INSERTed, or used in WHERE clauses.
  Fix: Design database queries and schema to avoid unsupported SQL features. For complex JSON interactions, directly use the Firebase SDK or preprocess data at the application layer.
• gotcha Authentication is strictly limited to email and password within the connection string. This method is insecure and does not support modern authentication flows such as OAuth, multi-factor authentication, or token-based authentication (e.g., from the Firebase Authentication SDK).
  Fix: This library is not suitable for applications requiring secure or diverse authentication methods. Directly integrate the Firebase Authentication SDK for proper user management and secure access.
• gotcha Data storage is restricted to Firebase's `ref.push` pattern, which automatically generates unique, sequential keys for new entries. This may not be suitable for use cases requiring specific, user-defined keys or custom sorting.
  Fix: Understand that all insertions will result in auto-generated keys. If specific keys or non-sequential IDs are needed, direct manipulation of the Firebase SDK is required.
• gotcha The `CREATE` SQL command in this library does not create a table structure in Firebase, as Firebase Realtime Database is a NoSQL database without a rigid schema. It essentially acts as a no-op for schema definition.
  Fix: Do not rely on `CREATE` statements to define or enforce a schema; Firebase's schema is implicitly defined by the data structure. Schema validation and management must be handled at the application layer.

Install

• npm install database-js-firebase npm
• yarn add database-js-firebase yarn
• pnpm add database-js-firebase pnpm

Imports

• Database
  wrong:

  const Database = require('database-js2'); // This refers to an unrelated package or an outdated alias.
  import { Database } from 'database-js-firebase'; // database-js-firebase is a driver, not the primary class export.

  correct:

  import { Database } from 'database-js';

  The 'Database' class is provided by the `database-js` package. `database-js-firebase` registers itself as a driver that `database-js` loads when a connection string with the 'database-js-firebase://' protocol is used. The example in the README incorrectly uses 'database-js2' for the import.

Quickstart

Demonstrates establishing a connection to Firebase via the `database-js-firebase` driver, executing a parameterized SELECT query, and handling results or errors. Uses environment variables for sensitive credentials.

import { Database } from 'database-js';

(async () => {
    let connection, statement, rows;
    // Set these environment variables or replace with actual values
    const firebaseEmail = process.env.FIREBASE_EMAIL ?? 'your-email@example.com';
    const firebasePassword = process.env.FIREBASE_PASSWORD ?? 'your-password';
    const firebaseProjectId = process.env.FIREBASE_PROJECT_ID ?? 'your-project-id';
    const firebaseRootNodePath = process.env.FIREBASE_ROOT_NODE_PATH ?? 'your-root-node-path';
    const firebaseApiKey = process.env.FIREBASE_API_KEY ?? 'your-api-key';

    const connectionString = `database-js-firebase://${firebaseEmail}:${firebasePassword}@${firebaseProjectId}/${firebaseRootNodePath}?apiKey=${firebaseApiKey}`;
    connection = new Database(connectionString);
    
    try {
        console.log('Attempting to connect to Firebase Realtime Database...');
        // Example: Assume a 'users' collection with 'username' field
        statement = await connection.prepareStatement("SELECT * FROM users WHERE username = ?");
        rows = await statement.query('dduck');
        console.log('Query results:', rows);
    } catch (error) {
        console.error('An error occurred:', error);
    } finally {
        if (connection) {
            await connection.close();
            console.log('Connection closed.');
        }
    }
})();