Neo4j Bolt Connection (Internal)

Common errors

• Error: Cannot find module 'neo4j-driver-bolt-connection'

  cause Attempting to import `neo4j-driver-bolt-connection` directly or it's missing as a transitive dependency due to incorrect installation or package manager issues.
  fix This package is an internal dependency. Do not install or import it directly. Instead, ensure `neo4j-driver` (or `neo4j-driver-lite`) is correctly installed: `npm install neo4j-driver`.

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

  cause Accessing `ServerInfo.protocolVersion` expecting a `Number` after upgrading to `neo4j-driver` v6.0.0 or higher, but the type has changed to `ProtocolVersion`.
  fix Refactor code to handle the new `ProtocolVersion` type for `ServerInfo.protocolVersion` in `neo4j-driver` v6.0.0+. Consult the `neo4j-driver` v6 documentation for updated API details on `ServerInfo`.

Warnings

• gotcha This package (`neo4j-driver-bolt-connection`) is an internal component of the official `neo4j-driver` and `neo4j-driver-lite`. It is explicitly *not* intended for direct consumption by end-users. Direct usage can lead to unexpected behavior, API instability, and lack of support.
  Fix: Always use the main `neo4j-driver` or `neo4j-driver-lite` package instead. This internal package handles low-level Bolt protocol details transparently, which is encapsulated by the public drivers.
• breaking The `protocolVersion` property on the `ServerInfo` object changed its type from a `Number` to a new `ProtocolVersion` type in v6.0.0 of the `neo4j-driver`. Code expecting a plain number for Bolt protocol version information will break.
  Fix: Update code that accesses `ServerInfo.protocolVersion` to correctly handle the new `ProtocolVersion` type. This change prevents issues if Bolt minor versions exceed 9. Ensure your application's logic adapts to this new type rather than assuming a primitive number.
• gotcha TypeScript exports for `Vector` and `vectors` types were initially incorrect or incomplete in the `neo4j-driver` v6.0.0 release, affecting applications utilizing the new Bolt 6.0 features for vector data types.
  Fix: Upgrade to `neo4j-driver` version 6.0.1 or higher to ensure correct TypeScript typings for `Vector` and `vectors` are available when working with the new vector features.
• gotcha When connecting directly to IP addresses using previous versions of the `neo4j-driver`, users might encounter SNI (Server Name Indication) deprecation messages, indicating a potential issue with hostname verification.
  Fix: Upgrade to `neo4j-driver` version 5.28.3 or newer. This version includes a fix specifically addressing the SNI deprecation message when connecting directly to IP addresses.

Install

• npm install neo4j-driver-bolt-connection npm
• yarn add neo4j-driver-bolt-connection yarn
• pnpm add neo4j-driver-bolt-connection pnpm

Imports

• Connection
  wrong:

  import { Connection } from 'neo4j-driver-bolt-connection';

  correct:

  // This package is for internal use. Use 'neo4j-driver' instead.

  Directly importing internal types or modules from `neo4j-driver-bolt-connection` is strongly discouraged as its API is unstable and subject to breaking changes without notice. It's intended to be an internal dependency of `neo4j-driver`.
• ConnectionProvider
  wrong:

  const { ConnectionProvider } = require('neo4j-driver-bolt-connection');

  correct:

  // This package is for internal use. Use 'neo4j-driver' instead.

  For CommonJS environments, requiring this internal package directly is also a footgun. Always use the public API provided by `neo4j-driver` for reliable interaction with Neo4j.
• any internal export
  wrong:

  import * as boltInternals from 'neo4j-driver-bolt-connection';

  correct:

  // Refer to the 'neo4j-driver' documentation for public APIs.

  Any attempt to access internal components of `neo4j-driver-bolt-connection` directly constitutes an unsupported usage pattern that bypasses the stable, versioned API of the main `neo4j-driver` package. This can lead to unhandled errors and difficult-to-debug issues.

Quickstart

This quickstart demonstrates how to connect to a Neo4j database using the official `neo4j-driver` package, which internally relies on `neo4j-driver-bolt-connection`. It shows a basic query execution and proper resource management, emphasizing that direct usage of this internal package is discouraged.

import neo4j from 'neo4j-driver';

// IMPORTANT: neo4j-driver-bolt-connection is an internal package.
// Always use the official 'neo4j-driver' for your applications.

const uri = process.env.NEO4J_URI ?? 'bolt://localhost:7687';
const user = process.env.NEO4J_USERNAME ?? 'neo4j';
const password = process.env.NEO4J_PASSWORD ?? 'password';

const driver = neo4j.driver(uri, neo4j.auth.basic(user, password));

async function queryNeo4j() {
  const session = driver.session();
  try {
    const result = await session.run(
      'CREATE (a:Greeting {message: $message}) RETURN a.message AS message',
      { message: 'Hello, Neo4j!' }
    );
    const singleRecord = result.records[0];
    const message = singleRecord.get('message');
    console.log(`Successfully created a node with message: ${message}`);
  } catch (error) {
    console.error('Error connecting to Neo4j or running query:', error);
  } finally {
    await session.close();
    console.log('Session closed.');
  }
}

queryNeo4j()
  .then(() => driver.close())
  .catch(error => {
    console.error('Driver encountered an error:', error);
    driver.close();
  });