RethinkDB JavaScript Driver

Common errors

• Error: connect ECONNREFUSED 127.0.0.1:28015

  cause The RethinkDB server is not running, or the connection details (host/port) are incorrect.
  fix Ensure the RethinkDB server is running and accessible from your application. Verify the `host` and `port` parameters in your `r.connect()` call match the server's configuration.

• RethinkDBError: Table `db.table_name` does not exist.

  cause The specified database or table has not been created in RethinkDB.
  fix Ensure that the database and table exist before attempting to query them. You can use `r.dbCreate('your_db')` and `r.db('your_db').tableCreate('your_table')` to create them programmatically or via the RethinkDB Data Explorer.

• TypeError: r.table(...).insert is not a function

  cause A ReQL query command was called without a `run()` method or with incorrect syntax, or the connection object was not passed.
  fix All ReQL queries must be terminated with a `.run(connection, callback)` or `await .run(connection)` call to execute them against the database. Verify your ReQL chain for correct command usage.

Warnings

• breaking The API for the `r.js` ReQL command experienced breaking changes in version 2.4.2. Users relying on this command should review their code.
  Fix: Consult the RethinkDB 2.4.0 release notes for details on the `r.js` command changes and update usage accordingly.
• breaking RethinkDB 2.4.x servers are not compatible with 2.3.x or earlier versions when mixed in the same cluster. Mixing versions can lead to cluster instability or data inconsistencies.
  Fix: Ensure all servers in a cluster are upgraded to 2.4.x before deploying new instances. Avoid running mixed-version clusters for extended periods during upgrades.
• gotcha The HTTP connection type provided by the driver is intended only for the RethinkDB web UI and is explicitly stated not to be secure for application use. Using it in production applications is a security risk.
  Fix: Always use the default TCP connection for applications. The HTTP connection type is planned to be removed from the driver in future versions.
• breaking When upgrading to RethinkDB 2.4.0 from versions 1.16 or earlier, data files will be automatically migrated. However, it is strongly recommended to back up your data files before performing any major version upgrade.
  Fix: Before upgrading to RethinkDB 2.4.0 or later from older major versions, perform a full backup of all your data files to prevent potential data loss.
• breaking On 32-bit platforms and Windows (both 32 and 64-bit), RethinkDB 2.3.5 servers should not be mixed with servers running 2.3.3 or older in the same cluster. This can cause server crashes, especially when using the web UI or accessing system tables.
  Fix: On affected platforms, ensure a complete cluster upgrade to 2.3.5+ without mixing older versions. On 64-bit Linux/macOS, mixed 2.3.x versions are temporarily tolerated during upgrade.

Install

• npm install rethinkdb npm
• yarn add rethinkdb yarn
• pnpm add rethinkdb pnpm

Imports

• r

  const r = require('rethinkdb');

  The 'rethinkdb' package exports a single object, typically aliased as 'r', which is the entry point for all ReQL commands and connection functions. ESM import 'import r from "rethinkdb"' may work in modern Node.js environments but CJS is historically dominant.
• connect
  wrong:

  import { connect } from 'rethinkdb'

  correct:

  const r = require('rethinkdb');
  r.connect({...})

  The `connect` method is a property of the main `r` object, not a named export. Ensure you import the entire 'rethinkdb' module first.
• RethinkDBError
  wrong:

  import { RethinkDBError } from 'rethinkdb'

  correct:

  const r = require('rethinkdb');
  const { RethinkDBError } = r;

  RethinkDB error types are typically accessed as properties of the main `r` object rather than direct named exports. `r.Error` is the base class for all RethinkDB errors.

Quickstart

Demonstrates connecting to RethinkDB, creating a table if it doesn't exist, inserting a document, and fetching all documents.

const r = require('rethinkdb');

async function runExample() {
  let connection;
  try {
    connection = await r.connect({
      host: process.env.DB_HOST ?? 'localhost',
      port: parseInt(process.env.DB_PORT ?? '28015'),
      db: process.env.DB_NAME ?? 'test',
      user: process.env.DB_USER ?? 'admin',
      password: process.env.DB_PASSWORD ?? ''
    });

    // Create a table if it doesn't exist
    const tableList = await r.db('test').tableList().run(connection);
    if (!tableList.includes('authors')) {
      await r.db('test').tableCreate('authors').run(connection);
      console.log('Table "authors" created.');
    }

    // Insert a document
    const insertResult = await r.table('authors').insert({
      name: 'John Doe',
      posts: 5
    }).run(connection);
    console.log('Inserted:', insertResult.generated_keys[0]);

    // Fetch all documents
    const cursor = await r.table('authors').run(connection);
    const authors = await cursor.toArray();
    console.log('Authors:', authors);

  } catch (err) {
    console.error('Error:', err.message);
  } finally {
    if (connection) {
      await connection.close();
      console.log('Connection closed.');
    }
  }
}

runExample();