{"id":16451,"library":"neo4j-driver-bolt-connection","title":"Neo4j Bolt Connection (Internal)","description":"The `neo4j-driver-bolt-connection` package provides the low-level implementation for establishing and managing connections to Neo4j databases using the binary Bolt Protocol. It is an internal dependency foundational to the official `neo4j-driver` and `neo4j-driver-lite` packages for JavaScript and TypeScript. Crucially, this package is explicitly *not* intended for direct consumption by end-users, serving as an abstraction layer for Bolt protocol specifics. The current stable version is 5.28.3, with version 6.0.x introducing new features like support for Neo4j's Vector type. Release cadence for the main `neo4j-driver` and its internal components, including this one, has evolved; post-6.0, minor releases occur as warranted by significant features or improvements, moving away from a monthly cadence to reduce user update overhead. Key differentiators include its role in abstracting complex network communication and Bolt handshake protocols, enabling the higher-level drivers to offer robust API usability, transaction management, and connection pooling capabilities transparently. While it handles the core communication, developers should always use the comprehensive `neo4j-driver` for a stable and supported experience.","status":"active","version":"5.28.3","language":"javascript","source_language":"en","source_url":"git://github.com/neo4j/neo4j-javascript-driver","tags":["javascript","bolt","neo4j","driver","typescript"],"install":[{"cmd":"npm install neo4j-driver-bolt-connection","lang":"bash","label":"npm"},{"cmd":"yarn add neo4j-driver-bolt-connection","lang":"bash","label":"yarn"},{"cmd":"pnpm add neo4j-driver-bolt-connection","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides core interfaces like Connection and ConnectionProvider, which this package implements.","package":"neo4j-driver-core"}],"imports":[{"note":"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`.","wrong":"import { Connection } from 'neo4j-driver-bolt-connection';","symbol":"Connection","correct":"// This package is for internal use. Use 'neo4j-driver' instead."},{"note":"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.","wrong":"const { ConnectionProvider } = require('neo4j-driver-bolt-connection');","symbol":"ConnectionProvider","correct":"// This package is for internal use. Use 'neo4j-driver' instead."},{"note":"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.","wrong":"import * as boltInternals from 'neo4j-driver-bolt-connection';","symbol":"any internal export","correct":"// Refer to the 'neo4j-driver' documentation for public APIs."}],"quickstart":{"code":"import neo4j from 'neo4j-driver';\n\n// IMPORTANT: neo4j-driver-bolt-connection is an internal package.\n// Always use the official 'neo4j-driver' for your applications.\n\nconst uri = process.env.NEO4J_URI ?? 'bolt://localhost:7687';\nconst user = process.env.NEO4J_USERNAME ?? 'neo4j';\nconst password = process.env.NEO4J_PASSWORD ?? 'password';\n\nconst driver = neo4j.driver(uri, neo4j.auth.basic(user, password));\n\nasync function queryNeo4j() {\n  const session = driver.session();\n  try {\n    const result = await session.run(\n      'CREATE (a:Greeting {message: $message}) RETURN a.message AS message',\n      { message: 'Hello, Neo4j!' }\n    );\n    const singleRecord = result.records[0];\n    const message = singleRecord.get('message');\n    console.log(`Successfully created a node with message: ${message}`);\n  } catch (error) {\n    console.error('Error connecting to Neo4j or running query:', error);\n  } finally {\n    await session.close();\n    console.log('Session closed.');\n  }\n}\n\nqueryNeo4j()\n  .then(() => driver.close())\n  .catch(error => {\n    console.error('Driver encountered an error:', error);\n    driver.close();\n  });","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"6.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.x <5.28.3"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`.","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.","error":"Error: Cannot find module 'neo4j-driver-bolt-connection'"},{"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`.","cause":"Accessing `ServerInfo.protocolVersion` expecting a `Number` after upgrading to `neo4j-driver` v6.0.0 or higher, but the type has changed to `ProtocolVersion`.","error":"TypeError: Cannot read properties of undefined (reading 'protocolVersion')"}],"ecosystem":"npm"}