neo4j

⭐️ New Features

• Pandas 3 support ( #1291 ).

• Instant one-shot retries on certain errors in session.run ( #1300 ). New driver and session config option disable_auto_commit_retries to opt-out.

• Pyarrow 23 and 24 support ( #1304 ).

🔧️ Fixes

• Fix overflow in DateTime + negative Duration ( #1279 ).

• Fix connection_write_timeout config being ignored ( #1294 ).

• Fix socket timeouts during connection establishment ( #1301 ).

• Prevent async driver from causing ValueError by using ssl_handshake_timeout=0 .

• Align async driver with sync driver:

• (lazily) raise a ValueError when configured with a negative connection_timeout .

• Treat connection_timeout=0 as "no timeout".

• Fix sync driver setting the socket timeout to 0 (non-blocking) on expired connection_acquisition_timeout .

👏️ Improvements

• Speed up iteration over Result ( #1295 ).

• Allow negative components in Duration.from_iso_format ( #1284 ).

• Improve error message on invalid Vector init overload invocation ( #1285 ).

• Migrate internal usage from deprecated package to spec ( #1293 ).

📚️ Docs

• List vector types next to other types ( #1287 ).

• clarify auto-commit caveats ( #1286 ).

🧹️ Clean-up

• Bump setuptools to 82.0.1 ( #1304 ).

🧑️‍💻️ Development

• Bump linters ( #1283 ).

• Fix Python 3.10 dev env ( #1292 ).

• Remove .snyk file ( #1296 ).

• Fix new mypy version being unhappy with type annotations ( #1298 ).

⭐️ New Features

• Add support for Python 3.14 ( #1264 ).

🔧️ Fixes

• Fix AttributeError when pool is None in Bolt3 error handling ( #1267 ). Thanks to @kirill-stepanishin for this contribution.

• connection_acquisition_timeout now covers TLS handshake ( #1274 ).

👏️ Improvements

• Unify connection error handling and logging between async and sync ( #1276 ).

📚️ Docs

• Fix outdated preview notes ( #1273 ).

🧑️‍💻️ Development

• Add .semgrepignore ( #1270 ).

🔧️ Fixes

• Fix Vector type native adapters ( #1263 ). Converting native Python types to Vector s and vice versa used to have alternative implementations using NumPy or the Rust extensions when available to speed up the process. These implementations didn't have behavioral equality (especially for f32 ) which was hard to establish. Further optimization of the pure Python implementation narrowed the performance gap to the point where maintaining the Numpy and Rust implementations alongside was deemed too little gain for too much effort. Therefore, only the new, fast pure Python implementation remains.

• Fix driver factory type hints suggesting supported options being unsupported ( #1255 ).

🔧️ Fixes

• Fix DNS error re-write on Windows ( #1254 ). On windows only, the driver would re-write the DNS error when resolving Address(None, None) to be retryable, which it shouldn't.

🔧️ Fixes

• Fix AttributeError on package import on Windows: socket.EAI_ADDRFAMILY ( #1252 ).

🔧️ Fixes

• Complete Bolt 6.0 implementation: add support for UnsupportedType ( #1241 ).

• Fix socket timeouts ( #1227 ).

• Apply connection timeout hint only to reads (as it was intended).

• Introduce new config option connection_write_timeout (default: 30 seconds ) to cover write operations.

• ℹ️ The option is broken in this version and has no effect.

👏️ Improvements

• Optimize error path in vector types ( #1226 ).

• Improve repr string representation of spatial types ( #1231 ).

• Improve repr and str string representations of SummaryCounters ( #1233 ).

• Improve repr string representation of Duration and ClockTime ( #1235 ).

• Improve repr string representation of internal classes (might change log output) ( #1236 ).

• Improve repr string representation of GqlStatusObject and SummaryInputPosition ( #1234 ).

• Unify str string representation of Vector with other drivers ( #1238 ).

• Minor formatting fixes ( #1246 ).

📚️ Docs

• Fix type hint resolution in docs ( #1247 ).

• Drop documented support for Bolt 4.4 ( #1221 ).

• Document continuation of support for Bolt 4.4 ( #1242 ).

• Fix deprecations around notification APIs as part of migrating notifications to GQL status ( #1240 ).

• Better explain security config options interplay ( #1239 ).

• Minor API docs improvements ( #1247 , #1248 , #1251 ).

🧑️‍💻️ Development

• Improve internal packstream Structure class for a better debugging and development experience ( #1232 ).

• Bump development dependencies ( #1250 ).

This release contains all fixes up until version 5.28.1 plus:

⭐️ New Features

• Introduce Bolt 6.0 support with vector types ( #1214 ).

• Chain failure causes on routing table fetching failure ( #1219 ). When a routing driver ( neo4j[+s[sc]] URL scheme), fails to fetch a routing table, instead of swallowing all errors from the connection and RT fetching attempts that lead up to the failure, the errors are not attached as cause of the raised error.

• Introduce helper method GqlError.find_by_gql_status ( #1216 ).

🔧️ Fixes

• Fix driver stuck on RecursionError on COMMIT SUCCESS ( #1192 ).

• Fix re-authentication interfering with connectivity checks ( #1144 ).

• ⚠️ make unsupported comparisons return NotImplemented instead of False or raising ( #1199 ). This means that when comparing a driver type with another type is doesn't support, the other type gets the chance to handle the comparison. Affected types:

• neo4j.Record

• neo4j.graph.Node , neo4j.graph.Relationship , neo4j.graph.Path

• neo4j.time.Date , neo4j.time.Time , neo4j.time.DateTime

• neo4j.spatial.Point (and subclasses)

👏️ Improvements

• ⚠️ Align connection_acquisition_timeout configuration option with other drivers ( #1215 ). The timeout now spans anything required to acquire a working connection from the pool. This includes potential fetching of routing tables which in itself requires acquiring a connection. Previously, the timeout would be restarted for auxiliary connection acquisitions like those for fetching a routing table.

• ⚠️ Make DNS error retryable ( #1211 ). Configuring the driver with a URL that cannot be DNS resolved will raise a (retryable) ServiceUnavailable error instead of a ValueError .

• Introduce new sub-logger neo4j.session ( #1206 ). This separates log entries that are session-related (including transaction retries) form sub-logger neo4j.pool .

• ⚠️ No longer implicitly closing drivers and sessions in del() (finalizer/destructor) ( #1183 ). Make sure to call .close() on them explicitly or use them in a with statement.

• ⚠️ Disallow using a closed driver ( #1182 ).

• Raise DriverError on using the closed driver.

• Calling driver.close() again is now a no-op.

• ⚠️ Slightly change Neo4jError and ClientError ( #1179 ).

• Properties message and code are always a str (instead of str | None ).

• Remove possibility to override/set message and code properties.

• Remove undocumented, internal methods Neo4jError.hydrate , Neo4jError.invalidates_all_connections , and Neo4jError.is_fatal_during_discovery .

• Remove deprecated method Neo4jError.is_retriable . Use Neo4jError.is_retryable instead.

• Change string representation of Neo4jError to include GQL error information.

• ⚠️ Raise ConfigurationError instead of ignoring the routing context (URI query parameters) when creating a direct driver ( "bolt[+s[sc]]://" scheme) ( #1178 ).

• ⚠️ Raise new ConnectionAcquisitionTimeoutError (subclass of DriverError ) instead of ClientError (subclass of Neo4jError ) the connection_acquisition_timeout is exceeded ( #1169 ).

• This improves the differentiation between DriverError for client-side errors and Neo4jError for server-side errors.

• ⚠️ Raise TypeError instead of ValueError when passing a Query object to Transaction.run ( #1171 ).

• ⚠️ Raise TransactionError (subclass of DriverError ) instead of ClientError (subclass of Neo4jError ) when calling session.run() while an explicit transaction is active on that session ( #1170 ).

• This improves the differentiation between DriverError for client-side errors and Neo4jError for server-side errors.

• It is now the same error raised as when trying to start an explicit transaction while another explicit transaction is already active.

• ⚠️ Improve validation of connection_acquisition_timeout configuration option ( #1168 ).

• Raise ValueError on invalid values (instead of ClientError ).

• Consistently restrict the value to be strictly positive.

• ⚠️ Raise neo4j.exceptions.UnsupportedServerProduct if no common bolt protocol version could be negotiated with the server (instead of internal neo4j._exceptions.BoltHandshakeError ) ( #1164 , #1224 ). UnsupportedServerProduct is now a subclass of ConfigurationError (instead of Exception directly).

• ⚠️ Improve validation of access_mode configuration option ( #1166 ).

• ValueError on invalid value (instead of ClientError ).

• Consistently check the value (also for non-routing drivers).

• ⚠️ Raise ConfigurationError if the passed auth parameters is not valid (instead of AuthError ) ( #1162 ).

• This improves the differentiation between DriverError for client-side errors and Neo4jError for server-side errors.

📚️ Docs

• Document that is_retryable is not applicable to auto-commit transactions ( #1217 ).

• Fix formatting, wording, and minor updates for 6.0 ( #1200 ).

• Minor fixes: add more links and versions changed/added remarks ( #1146 ).

🌳️ Maturing

• Stabilize GQL status objects (use these instead of notifications) ( #1209 ). Affected APIs:

• ResultSummary.gql_status_objects

• neo4j.GqlStatusObject

• ( neo4j.exceptions.GqlError , neo4j.exceptions.GqlErrorClassification )

• Stabilize driver debug mode ( #1205 ).

• warn_notification_severity config option

• concurrency checker

🧹️ Clean-up

• ⚠️ Bump minimum supported Python version to 3.10 ( #1153 ).

• Drop support for Python 3.7 (end of life 2023-06-27)

• Drop support for Python 3.8 (end of life 2024-10-07)

• Drop support for Python 3.9 (end of life scheduled for 2025-10).

• ⚠️ Remove deprecated Bookmark in favor or Bookmarks ( #1175 , #1196 ).

• Remove deprecated class neo4j.Bookmark in favor of neo4j.Bookmarks .

• Remove deprecated method session.last_bookmark() in favor of last_bookmarks() .

• Deprecate passing raw sting bookmarks as initial_bookmarks to GraphDatabase.bookmark_manager() . Use a neo4j.Bookmarks object instead.

• Driver.session() no longer accepts raw string bookmarks as bookmarks argument. Use a neo4j.Bookmarks object instead.

• ⚠️ Remove deprecated ServerInfo.connection_id ( #1193 ). There is no replacement as this is considered internal information.

• ⚠️ Make undocumented internal constants, helper functions, and other items private.

• neo4j.api ( #1176 , #1186 ).

• DRIVER_BOLT

• DRIVER_NEO4J

• SECURITY_TYPE_NOT_SECURE

• SECURITY_TYPE_SECURE

• SECURITY_TYPE_SELF_SIGNED_CERTIFICATE

• check_access_mode

• parse_neo4j_uri

• parse_routing_context

• neo4j.exceptions ( #1176 , #1195 ).

• CLASSIFICATION_CLIENT

• CLASSIFICATION_DATABASE

• CLASSIFICATION_TRANSIENT

• ERROR_REWRITE_MAP

• client_errors

• transient_errors

• all other indirectly exposed items from imports (e.g. typing as neo4j.exceptions.t )

• neo4j.time ( #1191 ).

• DATE_ISO_PATTERN

• TIME_ISO_PATTERN

• DURATION_ISO_PATTERN

• NANO_SECONDS

• AVERAGE_SECONDS_IN_MONTH

• AVERAGE_SECONDS_IN_DAY

• FORMAT_F_REPLACE

• IS_LEAP_YEAR

• DAYS_IN_YEAR

• DAYS_IN_MONTH

• round_half_to_even

• symmetric_divmod

• DateTimeType

• DateType

• TimeType

• all other indirectly exposed items from imports (e.g. re as neo4j.time.re )

• neo4j.spatial ( #1188 ).

• hydrate_point

• dehydrate_point

• point_type

• neo4j.GraphDatabase ( #1181 ).

• .bolt_driver

• .neo4j_driver

• neo4j.BoltDriver and neo4j.Neo4jDriver ( #1181 ).

• .open

• .parse_target

• .default_host

• .default_port

• .default_target

• neo4j.graph , neo4j.addressing , neo4j.api ( #1195 ).

• indirectly exposed items from imports (e.g. collections.abc.Mapping as neo4j.graph.Mapping ).

• BoltDriver and Neo4jDriver ( ).

• .open

• .parse_target

• .default_host

• .default_port

• .default_target

• neo4j.debug ( #1194 ).

• ColourFormatter

• TaskIdFilter

• all other indirectly exposed items from imports (e.g. asyncio as neo4j.debug.asyncio )

• ⚠️ Remove deprecated option to index EntitySetView by int id ( #1187 ). Graph type sets ( neo4j.graph.EntitySetView ) can no longer by indexed by legacy id ( int , e.g., graph.nodes[0] ). Use the element_id instead ( str , e.g., graph.nodes["..."] ).

• ⚠️ Make Summary.summary_notifications a tuple instead of a list and type it with Sequence to signify that it should be treated as immutable ( #1185 ).

• ⚠️ Remove deprecated session.read_transaction and session.write_transaction ( #1184 ). Instead, use session.execute_read and session.execute_write respectively.

• ⚠️ Deprecate notifications (use GQL status objects instead) ( #1209 ). Deprecated APIs:

• ResultSummary.notifications

• ResultSummary.summary_notifications

• neo4j.SummaryNotification

• neo4j.NotificationCategory

• neo4j.NotificationDisabledCategory

• ⚠️ Remove deprecated driver configuration option trust ( #1177 ). Use trusted_certificates instead.

• Remove the associated constants neo4j.TRUST_ALL_CERTIFICATES and neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES .

• ⚠️ Rework PreviewWarning ( #1173 ).

• Remove ExperimentalWarning and turn the few left instances of it into PreviewWarning .

• Deprecate importing PreviewWarning from neo4j . Import it from neo4j.warnings instead.

• ⚠️ Make undocumented classes ResolvedAddress , ResolvedIPv4Address , and ResolvedIPv6Address private ( #1174 ).

• ⚠️ Remove deprecated Record.getslice . This magic method has been removed in Python 3.0 ( #1172 ). If you were calling it directly, please use Record.getitem(slice(...)) or simply record[...] instead.

• ⚠️ ServerInfo.protocol_version now is a tuple[int, int] insteadof a api.Version ( #1164 ).

• This should be drop-in replacement is most cases:

• Version was a sup-type of tuple[int, int] .

• ServerInfo.protocol_version was already documented and typed as tuple[int, int] .

• Version 's additional methods were undocumented and shouldn't have been used.

• api.Version has been removed as it's unused now.

• ⚠️ Remove deprecated exports from neo4j ( #1160 ).

• log , Config , PoolConfig , SessionConfig , WorkspaceConfig (internal - no replacement).

• SummaryNotificationPosition (use SummaryInputPosition instead).

• ⚠️ Remove deprecated modules ( #1159 ):

• neo4j.conf

• neo4j.data

• neo4j.meta

• neo4j.packstream

• neo4j.routing

• neo4j.time.arithmetic

• neo4j.time.clock_implementation

• neo4j.time.hydration

• neo4j.time.metaclasses

• neo4j.work

• neo4j.work.query

• neo4j.work.summary

• ⚠️ Deprecate ClockTime and its accessors ( #1191 ).

• For each neo4j.time.Date , neo4j.time.DateTime , neo4j.time.Time

• from_clock_time and to_clock_time methods

• neo4j.time.ClockTime itself.

• Lift server agent string restrictions ( #1208 ).

📦️ Packaging

• ⚠️ Remove deprecated package alias neo4j-driver ( #1161 ). Use pip install neo4j instead.

• ⚠️ Remove setup.py . Please use a recent enough packaging/build tool that supports pyproject.toml ( #1161 ).

• PEP 639 style licensing metadata ( #1207 ).

🧑️‍💻️ Development

• Bump pre-commit hooks and fix new lints ( #1204 ).

• Use dependency-groups in pyproject.toml for dev dependencies ( #1201 ).

• Fix ParamSpec type annotation of internal method ( #1157 ).