From 8bdc62c3f1410a3c08e26aed1ff9e962015c3620 Mon Sep 17 00:00:00 2001 From: Stefano Ottolenghi Date: Mon, 17 Oct 2022 16:33:32 +0200 Subject: [PATCH 1/9] Updated Python manual with 5.0 changes, as well as some inevitable `common-content` updates related to 5.0. --- .../ROOT/partials/client-applications.adoc | 86 ++---------- .../ROOT/partials/cypher-workflow.adoc | 4 + .../modules/ROOT/partials/session-api.adoc | 4 + .../ROOT/pages/client-applications.adoc | 123 ++---------------- 4 files changed, 32 insertions(+), 185 deletions(-) diff --git a/common-content/modules/ROOT/partials/client-applications.adoc b/common-content/modules/ROOT/partials/client-applications.adoc index 2845244f..2379c603 100644 --- a/common-content/modules/ROOT/partials/client-applications.adoc +++ b/common-content/modules/ROOT/partials/client-applications.adoc @@ -114,17 +114,7 @@ A connection URI identifies a graph database and how to connect to it. The *_encryption_* and *_trust_* settings provide detail to how that connection should be secured. -[CAUTION] -==== -*There are significant changes to security settings between Neo4j 3.x and Neo4j 4.x* - -Please consider the information in this section before upgrading from a previous version. - -The https://neo4j.com/docs/migration-guide/current/[Migration Guide] is also a good source of information about changes in functionality. -==== - Starting with *Neo4j 4.0*, client-server communication uses only *_unencrypted local connections by default_*. - This is a change from previous versions, which switched on encryption by default, but generated a self-signed certificate out of the box. When a full certificate is installed, and encryption is enabled on the driver, full certificate checks are carried out (refer to link:/docs/operations-manual/5.0/security/ssl-framework[Operations Manual -> SSL framework]). @@ -141,23 +131,6 @@ To connect to *Neo4j Aura*, driver users must *_enable encryption_* and the comp For more information, see xref:client-applications.adoc#driver-configuration-examples[Examples] below. ==== -# tag::default-security-changes[] - -.Changes in default security settings between 3.x and 4.x -[options="header"] -|=== -| Setting | Neo4j 4.x | Neo4j 3.x (Drivers 1.x) -| Bundled certificate | none | auto-generated, self-signed -| Driver encryption | off | on -| Bolt interface | localhost |localhost -| Certificate expiry check | on |on -| Certificate CA check | on | off -| Certificate hostname check | on | off -|=== - -# end::default-security-changes[] - - [[initial-address-resolution]] === Initial address resolution @@ -802,54 +775,33 @@ The table below illustrates examples of how to connect to a service with routing ---- GraphDatabase.driver("neo4j+s://graph.example.com:7687", auth) ---- - -For Python Driver versions before 4.0.0 you need this snippet instead: -[source, python, indent=0] ----- -GraphDatabase.driver("neo4j://graph.example.com:7687", auth, - "encrypted"=True, "trust"=TRUST_SYSTEM_CA_SIGNED_CERTIFICATES) ----- | This is the default (and only option) for Neo4j Aura -|Neo4j 4.x +|Neo4j 5.x |Unsecured | [source, python, indent=0] ---- GraphDatabase.driver("neo4j://graph.example.com:7687", auth) ---- -|This is the default for Neo4j 4.x series +|This is the default for Neo4j 5.x series -|Neo4j 4.x +|Neo4j 5.x |Secured with full certificate | [source, python, indent=0] ---- GraphDatabase.driver("neo4j+s://graph.example.com:7687", auth) ---- - -For Python Driver versions before 4.0.0 you need this snippet instead: -[source, python, indent=0] ----- -GraphDatabase.driver("neo4j://graph.example.com:7687", auth, - "encrypted"=True, "trust"=TRUST_SYSTEM_CA_SIGNED_CERTIFICATES) ----- | -|Neo4j 4.x +|Neo4j 5.x |Secured with self-signed certificate | [source, python, indent=0] ---- neo4j.driver("neo4j+ssc://graph.example.com:7687", auth) ---- - -For Python Driver versions before 4.0.0 you need this snippet instead: -[source, python, indent=0] ----- -GraphDatabase.driver("neo4j://graph.example.com:7687", auth, - "encrypted"=True, "trust"=TRUST_ALL_CERTIFICATES) ----- | |Neo4j 3.x @@ -859,13 +811,6 @@ GraphDatabase.driver("neo4j://graph.example.com:7687", auth, ---- neo4j.driver("neo4j+s://graph.example.com:7687", auth) ---- - -For Python Driver versions before 4.0.0 you need this snippet instead: -[source, python, indent=0] ----- -GraphDatabase.driver("neo4j://graph.example.com:7687", auth, - "encrypted"=True, "trust"=TRUST_SYSTEM_CA_SIGNED_CERTIFICATES) ----- | |Neo4j 3.x @@ -875,13 +820,6 @@ GraphDatabase.driver("neo4j://graph.example.com:7687", auth, ---- neo4j.driver("neo4j+ssc://graph.example.com:7687", auth) ---- - -For Python Driver versions before 4.0.0 you need this snippet instead: -[source, python, indent=0] ----- -GraphDatabase.driver("neo4j://graph.example.com:7687", auth, - "encrypted"=True, "trust"=TRUST_ALL_CERTIFICATES) ----- |This is the default for Neo4j 3.x series |Neo4j 3.x @@ -1312,7 +1250,7 @@ Specify a custom server address resolver used by the routing driver to resolve t Specify whether to use an encrypted connection between the driver and server. + -*Default:* None +*Default:* False # end::configuration-Encryption[] @@ -1486,19 +1424,21 @@ include::{python-examples}/test_config_max_retry_time_example.py[tags=config-max # tag::configuration-TrustStrategy[] -`TrustStrategy`:: +`TrustedCertificates`:: Specify how to determine the authenticity of encryption certificates provided by the Neo4j instance that you are connecting to. -There are three choices as to which strategy to use: -* `TRUST_SYSTEM_CA_SIGNED_CERTIFICATES` - Accept any certificate that can be verified against the system store. ++ -* `TRUST_CUSTOM_CA_SIGNED_CERTIFICATES` - Accept any certificate that can be verified against a custom CA. +Possible values are: ++ +* `neo4j.TrustSystemCAs()` - Accept any certificate that can be verified against the system store. +* `neo4j.TrustCustomCAs("/path/ca1.crt", "/path/ca2.crt", ...)` - Accept certificates at specified paths. +* `neo4j.TrustAll()` - Accept any certificate, including self-signed ones. *Not recommended for production environments.* -* `TRUST_ALL_CERTIFICATES` - Accept any certificate provided by the server, regardless of CA chain. *We do not recommend using this setting for production environments.* + -*Default:* `TRUST_SYSTEM_CA_SIGNED_CERTIFICATES` (Note - only when encryption is enabled) +*Default:* `neo4j.TrustSystemCAs()` (Only when encryption is enabled) # end::configuration-TrustStrategy[] diff --git a/common-content/modules/ROOT/partials/cypher-workflow.adoc b/common-content/modules/ROOT/partials/cypher-workflow.adoc index c7cdc0a6..d5daffcc 100644 --- a/common-content/modules/ROOT/partials/cypher-workflow.adoc +++ b/common-content/modules/ROOT/partials/cypher-workflow.adoc @@ -229,6 +229,9 @@ This is only used in cases when the access mode cannot otherwise be specified. The driver does not parse *Cypher* and therefore cannot automatically determine whether a transaction is intended to carry out read or write operations. As a result, a write transaction tagged as a read will still be sent to a read server, but will fail on execution. +[NOTE] +The methods `execute_read` and `execute_write` were called `read_transaction` and `write_transaction` in version 4.x. + # end::access-modes-transaction[] [.tabbed-example] @@ -680,5 +683,6 @@ Transient errors are those which are generated by the server and marked as safe Examples of such errors are deadlocks and memory issues. When using transaction functions, the driver will usually be able to automatically retry when a transient failure occurs. +The exception method `is_retriable()` gives insights into whether a further attempt might be successful. # end::exceptions-errors[] diff --git a/common-content/modules/ROOT/partials/session-api.adoc b/common-content/modules/ROOT/partials/session-api.adoc index 2a827754..f43e5253 100644 --- a/common-content/modules/ROOT/partials/session-api.adoc +++ b/common-content/modules/ROOT/partials/session-api.adoc @@ -98,8 +98,12 @@ To that end, transaction functions can return values but these should be derived *_When a transaction fails, the driver retry logic is invoked_*. For several failure cases, the transaction can be immediately retried against a different server. These cases include connection issues, server role changes (e.g. leadership elections) and transient errors. + ==== +[NOTE] +The methods `execute_read` and `execute_write` were called `read_transaction` and `write_transaction` in version 4.x. + # end::simple-transaction-fn[] [.tabbed-example] diff --git a/python-manual/modules/ROOT/pages/client-applications.adoc b/python-manual/modules/ROOT/pages/client-applications.adoc index f973f48b..42fec8e2 100644 --- a/python-manual/modules/ROOT/pages/client-applications.adoc +++ b/python-manual/modules/ROOT/pages/client-applications.adoc @@ -121,22 +121,15 @@ The tables below illustrate examples of how to connect to a service with routing GraphDatabase.driver("neo4j+s://graph.example.com:7687", auth) ---- -For Python Driver versions before 4.0.0 you need this snippet instead: -[source, python, indent=0] ----- -GraphDatabase.driver("neo4j://graph.example.com:7687", auth, - "encrypted"=True, "trust"=TRUST_SYSTEM_CA_SIGNED_CERTIFICATES) ----- - | Comments | This is the default (and only option) for Neo4j Aura. |=== -.Neo4j 4.x, unsecured +.Neo4j >= 4.x, unsecured [cols="<15s,<85a"] |=== | Product -| Neo4j 4.x +| Neo4j >= 4.x | Security | Unsecured @@ -149,86 +142,14 @@ GraphDatabase.driver("neo4j://graph.example.com:7687", auth) ---- | Comments -| This is the default for Neo4j 4.x series -|=== - -.Neo4j 4.x, secured with full certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 4.x - -| Security -| Secured with full certificate - -| Code snippet -| -[source, python, indent=0] ----- -GraphDatabase.driver("neo4j+s://graph.example.com:7687", auth) ----- - -For Python Driver versions before 4.0.0 you need this snippet instead: -[source, python, indent=0] ----- -GraphDatabase.driver("neo4j://graph.example.com:7687", auth, - "encrypted"=True, "trust"=TRUST_SYSTEM_CA_SIGNED_CERTIFICATES) ----- -|=== - -.Neo4j 4.x, secured with self-signed certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 4.x - -| Security -| Secured with self-signed certificate - -| Code snippet -| -[source, python, indent=0] ----- -neo4j.driver("neo4j+ssc://graph.example.com:7687", auth) ----- - -For Python Driver versions before 4.0.0 you need this snippet instead: -[source, python, indent=0] ----- -GraphDatabase.driver("neo4j://graph.example.com:7687", auth, - "encrypted"=True, "trust"=TRUST_ALL_CERTIFICATES) ----- -|=== - -.Neo4j 3.x, secured with full certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 3.x - -| Security -| Secured with full certificate - -| Code snippet -| -[source, python, indent=0] ----- -neo4j.driver("neo4j+s://graph.example.com:7687", auth) ----- - -For Python Driver versions before 4.0.0 you need this snippet instead: -[source, python, indent=0] ----- -GraphDatabase.driver("neo4j://graph.example.com:7687", auth, - "encrypted"=True, "trust"=TRUST_SYSTEM_CA_SIGNED_CERTIFICATES) ----- +| This is the default for Neo4j >= 4.x series |=== -.Neo4j 3.x, secured with self-signed certificate +.Neo4j >= 4.x, secured with self-signed certificate [cols="<15s,<85a"] |=== | Product -| Neo4j 3.x +| Neo4j >= 4.x | Security | Secured with self-signed certificate @@ -237,34 +158,7 @@ GraphDatabase.driver("neo4j://graph.example.com:7687", auth, | [source, python, indent=0] ---- -neo4j.driver("neo4j+ssc://graph.example.com:7687", auth) ----- - -For Python Driver versions before 4.0.0 you need this snippet instead: -[source, python, indent=0] ----- -GraphDatabase.driver("neo4j://graph.example.com:7687", auth, - "encrypted"=True, "trust"=TRUST_ALL_CERTIFICATES) ----- - -| Comments -| This is the default for Neo4j 3.x series -|=== - -.Neo4j 3.x, unsecured -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 3.x - -| Security -| Unsecured - -| Code snippet -| -[source, python, indent=0] ----- -neo4j.driver("neo4j://graph.example.com:7687", auth) +GraphDatabase.driver("neo4j+ssc://graph.example.com:7687", auth) ---- |=== @@ -517,3 +411,8 @@ logging.getLogger("neo4j").addHandler(handler) logging.getLogger("neo4j").setLevel(logging.DEBUG) # from now on, DEBUG logging to stderr is enabled in the driver ---- + +== Async +Starting from version 5.0, the driver can also function asynchronously. +The flow to connect and interact with the database is the same, except that async functions have the `Async` prefix and that database function calls need to `await` the result. +More information can be found in the link:https://neo4j.com/docs/api/python-driver/5.0/async_api.html[API documentation]. From 16997e1528933bb12e0933b2b193aab49c5c27e3 Mon Sep 17 00:00:00 2001 From: Stefano Ottolenghi Date: Thu, 20 Oct 2022 11:40:44 +0200 Subject: [PATCH 2/9] Bring dotnet manual up to date for v5, plus some splitting away from partials. --- .../ROOT/partials/client-applications.adoc | 93 +----------- .../ROOT/partials/cypher-workflow.adoc | 4 - .../modules/ROOT/partials/session-api.adoc | 3 +- .../ROOT/pages/client-applications.adoc | 137 ++---------------- .../modules/ROOT/pages/cypher-workflow.adoc | 2 + .../modules/ROOT/pages/session-api.adoc | 9 ++ .../ROOT/pages/client-applications.adoc | 11 +- .../modules/ROOT/pages/cypher-workflow.adoc | 5 + .../modules/ROOT/pages/session-api.adoc | 4 +- 9 files changed, 45 insertions(+), 223 deletions(-) diff --git a/common-content/modules/ROOT/partials/client-applications.adoc b/common-content/modules/ROOT/partials/client-applications.adoc index 2379c603..98aaebd0 100644 --- a/common-content/modules/ROOT/partials/client-applications.adoc +++ b/common-content/modules/ROOT/partials/client-applications.adoc @@ -376,109 +376,34 @@ The table below illustrates examples of how to connect to a service with routing ---- GraphDatabase.Driver("neo4j+s://graph.example.com:7687", auth) ---- - -If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, csharp, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -IDriver driver = GraphDatabase.Driver(uri, auth, - o => o.WithEncryptionLevel(EncryptionLevel.Encrypted)); ----- |Comments | This is the default (and only option) for Neo4j Aura -|Neo4j 4.x +|Neo4j >= 4.x |Unsecured | [source, csharp, indent=0] ---- GraphDatabase.Driver("neo4j://graph.example.com:7687", auth); ---- -|This is the default for Neo4j 4.x series - -|Neo4j 4.x -|Secured with full certificate -| -[source, csharp, indent=0] ----- -GraphDatabase.Driver("neo4j+s://graph.example.com:7687", auth) ----- - -If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, csharp, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -IDriver driver = GraphDatabase.Driver(uri, auth, - o => o.WithEncryptionLevel(EncryptionLevel.Encrypted)); ----- -| - -|Neo4j 4.x -|Secured with self-signed certificate -| -[source, csharp, indent=0] ----- -GraphDatabase.Driver("neo4j+ssc://graph.example.com:7687", auth) ----- - -If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, csharp, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -IDriver driver = GraphDatabase.Driver(uri, auth, - o => o.WithEncryptionLevel(EncryptionLevel.Encrypted) - .WithTrustManager(TrustManager.CreateInsecure())); ----- -| +|This is the default for Neo4j >= 4.x series -|Neo4j 3.x +|Neo4j >= 4.x |Secured with full certificate | [source, csharp, indent=0] ---- GraphDatabase.Driver("neo4j+s://graph.example.com:7687", auth) ---- - -If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, csharp, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -IDriver driver = GraphDatabase.Driver(uri, auth, - o => o.WithEncryptionLevel(EncryptionLevel.Encrypted)); ----- | -|Neo4j 3.x +|Neo4j >= 4.x |Secured with self-signed certificate | [source, csharp, indent=0] ---- GraphDatabase.Driver("neo4j+ssc://graph.example.com:7687", auth) ---- - -If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, csharp, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -IDriver driver = GraphDatabase.Driver(uri, auth, - o => o.WithEncryptionLevel(EncryptionLevel.Encrypted) - .WithTrustManager(TrustManager.CreateInsecure())); ----- -|This is the default for Neo4j 3.x series - -|Neo4j 3.x -|Unsecured -| -[source, csharp, indent=0] ----- -GraphDatabase.Driver("neo4j://graph.example.com:7687", auth); ----- | - |=== [NOTE] @@ -1426,19 +1351,11 @@ include::{python-examples}/test_config_max_retry_time_example.py[tags=config-max `TrustedCertificates`:: -Specify how to determine the authenticity of encryption certificates provided by the Neo4j instance that you are connecting to. +Specify how to determine the authenticity of encryption certificates provided by the Neo4j instance that you are connecting to. If encryption is disabled, this option has no effect. + Possible values are: -+ -* `neo4j.TrustSystemCAs()` - Accept any certificate that can be verified against the system store. -* `neo4j.TrustCustomCAs("/path/ca1.crt", "/path/ca2.crt", ...)` - Accept certificates at specified paths. -* `neo4j.TrustAll()` - Accept any certificate, including self-signed ones. *Not recommended for production environments.* - - -+ -*Default:* `neo4j.TrustSystemCAs()` (Only when encryption is enabled) # end::configuration-TrustStrategy[] diff --git a/common-content/modules/ROOT/partials/cypher-workflow.adoc b/common-content/modules/ROOT/partials/cypher-workflow.adoc index d5daffcc..c7cdc0a6 100644 --- a/common-content/modules/ROOT/partials/cypher-workflow.adoc +++ b/common-content/modules/ROOT/partials/cypher-workflow.adoc @@ -229,9 +229,6 @@ This is only used in cases when the access mode cannot otherwise be specified. The driver does not parse *Cypher* and therefore cannot automatically determine whether a transaction is intended to carry out read or write operations. As a result, a write transaction tagged as a read will still be sent to a read server, but will fail on execution. -[NOTE] -The methods `execute_read` and `execute_write` were called `read_transaction` and `write_transaction` in version 4.x. - # end::access-modes-transaction[] [.tabbed-example] @@ -683,6 +680,5 @@ Transient errors are those which are generated by the server and marked as safe Examples of such errors are deadlocks and memory issues. When using transaction functions, the driver will usually be able to automatically retry when a transient failure occurs. -The exception method `is_retriable()` gives insights into whether a further attempt might be successful. # end::exceptions-errors[] diff --git a/common-content/modules/ROOT/partials/session-api.adoc b/common-content/modules/ROOT/partials/session-api.adoc index f43e5253..d7a00c87 100644 --- a/common-content/modules/ROOT/partials/session-api.adoc +++ b/common-content/modules/ROOT/partials/session-api.adoc @@ -101,8 +101,7 @@ These cases include connection issues, server role changes (e.g. leadership elec ==== -[NOTE] -The methods `execute_read` and `execute_write` were called `read_transaction` and `write_transaction` in version 4.x. + # end::simple-transaction-fn[] diff --git a/dotnet-manual/modules/ROOT/pages/client-applications.adoc b/dotnet-manual/modules/ROOT/pages/client-applications.adoc index e2775306..3e28c0e1 100644 --- a/dotnet-manual/modules/ROOT/pages/client-applications.adoc +++ b/dotnet-manual/modules/ROOT/pages/client-applications.adoc @@ -102,11 +102,11 @@ include::{common-partial}/client-applications.adoc[tag=examples-pt2] .Connecting to a service The tables below illustrate examples of how to connect to a service with routing: -.Neo4j Aura, secured with full certificate +.Neo4j Aura or Neo4j >= 4.x, secured with full certificate [cols="<15s,<85a"] |=== | Product -| Neo4j Aura +| Neo4j Aura, Neo4j >= 4.x | Security | Secured with full certificate @@ -118,24 +118,15 @@ The tables below illustrate examples of how to connect to a service with routing GraphDatabase.Driver("neo4j+s://graph.example.com:7687", auth) ---- -If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, csharp, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -IDriver driver = GraphDatabase.Driver(uri, auth, - o => o.WithEncryptionLevel(EncryptionLevel.Encrypted)); ----- - | Comments | This is the default (and only option) for Neo4j Aura. |=== -.Neo4j 4.x, unsecured +.Neo4j >= 4.x, unsecured [cols="<15s,<85a"] |=== | Product -| Neo4j 4.x +| Neo4j >= 4.x | Security | Unsecured @@ -148,40 +139,14 @@ GraphDatabase.Driver("neo4j://graph.example.com:7687", auth); ---- | Comments -| This is the default for Neo4j 4.x series +| This is the default for Neo4j >= 4.x series |=== -.Neo4j 4.x, secured with full certificate +.Neo4j >= 4.x, secured with self-signed certificate [cols="<15s,<85a"] |=== | Product -| Neo4j 4.x - -| Security -| Secured with full certificate - -| Code snippet -| -[source, csharp, indent=0] ----- -GraphDatabase.Driver("neo4j+s://graph.example.com:7687", auth) ----- - -If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, csharp, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -IDriver driver = GraphDatabase.Driver(uri, auth, - o => o.WithEncryptionLevel(EncryptionLevel.Encrypted)); ----- -|=== - -.Neo4j 4.x, secured with self-signed certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 4.x +| Neo4j >= 4.x | Security | Secured with self-signed certificate @@ -192,89 +157,6 @@ IDriver driver = GraphDatabase.Driver(uri, auth, ---- GraphDatabase.Driver("neo4j+ssc://graph.example.com:7687", auth) ---- - -If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, csharp, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -IDriver driver = GraphDatabase.Driver(uri, auth, - o => o.WithEncryptionLevel(EncryptionLevel.Encrypted) - .WithTrustManager(TrustManager.CreateInsecure())); ----- -|=== - -.Neo4j 3.x, secured with full certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 3.x - -| Security -| Secured with full certificate - -| Code snippet -| -[source, csharp, indent=0] ----- -GraphDatabase.Driver("neo4j+s://graph.example.com:7687", auth) ----- - -If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, csharp, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -IDriver driver = GraphDatabase.Driver(uri, auth, - o => o.WithEncryptionLevel(EncryptionLevel.Encrypted)); ----- -|=== - -.Neo4j 3.x, secured with self-signed certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 3.x - -| Security -| Secured with self-signed certificate - -| Code snippet -| -[source, csharp, indent=0] ----- -GraphDatabase.Driver("neo4j+ssc://graph.example.com:7687", auth) ----- - -If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, csharp, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -IDriver driver = GraphDatabase.Driver(uri, auth, - o => o.WithEncryptionLevel(EncryptionLevel.Encrypted) - .WithTrustManager(TrustManager.CreateInsecure())); ----- - -| Comments -| This is the default for Neo4j 3.x series -|=== - -.Neo4j 3.x, unsecured -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 3.x - -| Security -| Unsecured - -| Code snippet -| -[source, csharp, indent=0] ----- -GraphDatabase.Driver("neo4j://graph.example.com:7687", auth); ----- |=== [NOTE] @@ -430,6 +312,11 @@ include::{dotnet-examples}/Examples.cs[tags=config-max-retry-time] ====== include::{common-partial}/client-applications.adoc[tag=configuration-TrustStrategy] + +* `TrustManager.CreateChainTrust()` - Accept any certificate that can be verified against the system store. +* `TrustManager.CreateCertTrust(new []{"/path/ca1.crt", "/path/ca2.crt"})` - *[Default]* Accept certificates at specified paths. +* `TrustManager.CreateInsecure()` - Accept any certificate, including self-signed ones. *Not recommended for production environments.* + + .Configure trusted certificates ====== diff --git a/dotnet-manual/modules/ROOT/pages/cypher-workflow.adoc b/dotnet-manual/modules/ROOT/pages/cypher-workflow.adoc index c0636bd9..ca828bd9 100644 --- a/dotnet-manual/modules/ROOT/pages/cypher-workflow.adoc +++ b/dotnet-manual/modules/ROOT/pages/cypher-workflow.adoc @@ -129,3 +129,5 @@ Inbound conversion is carried out using http://cldr.unicode.org/development/deve == Exceptions and error handling include::{common-partial}/cypher-workflow.adoc[tag=exceptions-errors] + +The exception property `CanBeRetried` gives insights into whether a further attempt might be successful. diff --git a/dotnet-manual/modules/ROOT/pages/session-api.adoc b/dotnet-manual/modules/ROOT/pages/session-api.adoc index 95d67c08..c56ab8e4 100644 --- a/dotnet-manual/modules/ROOT/pages/session-api.adoc +++ b/dotnet-manual/modules/ROOT/pages/session-api.adoc @@ -32,6 +32,9 @@ See xref:session-api.adoc#dotnet-driver-session-configuration[Session configurat include::{common-partial}/session-api.adoc[tag=simple-transaction-fn] +[CAUTION] +The methods `ExecuteRead` and `ExecuteWrite` have replaced `ReadTransaction` and `WriteTransaction`, which are deprecated in version 5.x and will be removed in version 6.0. + [source, csharp, indent=0] ---- include::{dotnet-examples}/Examples.cs[tags=transaction-function] @@ -90,6 +93,9 @@ See xref:session-api.adoc#dotnet-driver-session-configuration[Session configurat include::{common-partial}/session-api.adoc[tag=async-transaction-fn] +[CAUTION] +The methods `ExecuteRead` and `ExecuteWrite` have replaced `ReadTransaction` and `WriteTransaction`, which are deprecated in version 5.x and will be removed in version 6.0. + [source, csharp, indent=0] ---- include::{dotnet-examples}/ExamplesAsync.cs[tags=async-transaction-function] @@ -150,6 +156,9 @@ include::{common-partial}/session-api.adoc[tag=rx-lifecycle] include::{common-partial}/session-api.adoc[tag=rx-transaction-fn] +[CAUTION] +The methods `ExecuteRead` and `ExecuteWrite` have replaced `ReadTransaction` and `WriteTransaction`, which are deprecated in version 5.x and will be removed in version 6.0. + [source, csharp, indent=0] ---- include::{dotnet-examples}/ExamplesRx.cs[tags=rx-transaction-function] diff --git a/python-manual/modules/ROOT/pages/client-applications.adoc b/python-manual/modules/ROOT/pages/client-applications.adoc index 42fec8e2..834cd606 100644 --- a/python-manual/modules/ROOT/pages/client-applications.adoc +++ b/python-manual/modules/ROOT/pages/client-applications.adoc @@ -105,11 +105,11 @@ include::{common-partial}/client-applications.adoc[tag=examples-pt2] .Connecting to a service The tables below illustrate examples of how to connect to a service with routing: -.Neo4j Aura, secured with full certificate +.Neo4j Aura or Neo4j >= 4.x, secured with full certificate [cols="<15s,<85a"] |=== | Product -| Neo4j Aura +| Neo4j Aura, Neo4j >= 4.x | Security | Secured with full certificate @@ -363,7 +363,12 @@ include::{python-examples}/test_config_max_retry_time_example.py[tags=config-max ====== include::{common-partial}/client-applications.adoc[tag=configuration-TrustStrategy] -+ + +* `neo4j.TrustSystemCAs()` - Accept any certificate that can be verified against the system store. +* `neo4j.TrustCustomCAs("/path/ca1.crt", "/path/ca2.crt", ...)` - *[Default]* Accept certificates at specified paths. +* `neo4j.TrustAll()` - Accept any certificate, including self-signed ones. *Not recommended for production environments.* + + .Configure trusted certificates ====== [source, python, indent=0] diff --git a/python-manual/modules/ROOT/pages/cypher-workflow.adoc b/python-manual/modules/ROOT/pages/cypher-workflow.adoc index 30d75972..e08cd24e 100644 --- a/python-manual/modules/ROOT/pages/cypher-workflow.adoc +++ b/python-manual/modules/ROOT/pages/cypher-workflow.adoc @@ -56,6 +56,9 @@ include::{python-examples}/test_pass_bookmarks_example.py[tags=pass-bookmarks] include::{common-partial}/cypher-workflow.adoc[tag=access-modes-transaction] +[NOTE] +The methods `execute_read` and `execute_write` were called `read_transaction` and `write_transaction` in version 4.x. + .Read-write transaction ====== [source, python, indent=0] @@ -274,3 +277,5 @@ include::{python-examples}/test_geospatial_types_example.py[tags=geospatial-type == Exceptions and error handling include::{common-partial}/cypher-workflow.adoc[tag=exceptions-errors] + +The exception method `is_retriable()` gives insights into whether a further attempt might be successful. diff --git a/python-manual/modules/ROOT/pages/session-api.adoc b/python-manual/modules/ROOT/pages/session-api.adoc index 6e6cc23e..9d85bd1e 100644 --- a/python-manual/modules/ROOT/pages/session-api.adoc +++ b/python-manual/modules/ROOT/pages/session-api.adoc @@ -31,6 +31,9 @@ See xref:session-api.adoc#python-driver-session-configuration[Session configurat include::{common-partial}/session-api.adoc[tag=simple-transaction-fn] +[CAUTION] +The methods `execute_read` and `execute_write` have replaced `read_transaction` and `write_transaction`, which are deprecated in version 5.x and will be removed in version 6.0. + .Transaction function ====== [source, python, indent=0] @@ -44,7 +47,6 @@ include::{python-examples}/test_transaction_function_example.py[tags=transaction ---- ====== - [[python-driver-simple-autocommit-transactions]] === Auto-commit transactions (or implicit transactions) From f3dcd316b38fe753b71f466637f40d4703eea300 Mon Sep 17 00:00:00 2001 From: Stefano Ottolenghi Date: Thu, 20 Oct 2022 11:54:24 +0200 Subject: [PATCH 3/9] Update Go manual. --- .../ROOT/pages/client-applications.adoc | 85 ++----------------- go-manual/modules/ROOT/pages/session-api.adoc | 3 + 2 files changed, 10 insertions(+), 78 deletions(-) diff --git a/go-manual/modules/ROOT/pages/client-applications.adoc b/go-manual/modules/ROOT/pages/client-applications.adoc index b68d93ff..dda117b2 100644 --- a/go-manual/modules/ROOT/pages/client-applications.adoc +++ b/go-manual/modules/ROOT/pages/client-applications.adoc @@ -96,11 +96,11 @@ include::{common-partial}/client-applications.adoc[tag=examples-pt2] .Connecting to a service The tables below illustrate examples of how to connect to a service with routing: -.Neo4j Aura, secured with full certificate +.Neo4j Aura or Neo4j >= 4.x, secured with full certificate [cols="<15s,<85a"] |=== | Product -| Neo4j Aura +| Neo4j Aura, Neo4j >= 4.x | Security | Secured with full certificate @@ -116,11 +116,11 @@ neo4j.NewDriver("neo4j+s://graph.example.com:7687", auth) | This is the default (and only option) for Neo4j Aura. |=== -.Neo4j 4.x, unsecured +.Neo4j >= 4.x, unsecured [cols="<15s,<85a"] |=== | Product -| Neo4j 4.x +| Neo4j >= 4.x | Security | Unsecured @@ -133,65 +133,14 @@ neo4j.NewDriver("neo4j://graph.example.com:7687", auth); ---- | Comments -| This is the default for Neo4j 4.x series +| This is the default for Neo4j >= 4.x series |=== -.Neo4j 4.x, secured with full certificate +.Neo4j >= 4.x, secured with self-signed certificate [cols="<15s,<85a"] |=== | Product -| Neo4j 4.x - -| Security -| Secured with full certificate - -| Code snippet -| -[source, go, indent=0] ----- -neo4j.NewDriver("neo4j+s://graph.example.com:7687", auth) ----- -|=== - -.Neo4j 4.x, secured with self-signed certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 4.x - -| Security -| Secured with self-signed certificate - -| Code snippet -| -[source, go, indent=0] ----- -neo4j.NewDriver("neo4j+ssc://graph.example.com:7687", auth) ----- -|=== - -.Neo4j 3.x, secured with full certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 3.x - -| Security -| Secured with full certificate - -| Code snippet -| -[source, go, indent=0] ----- -neo4j.NewDriver("neo4j+s://graph.example.com:7687", auth) ----- -|=== - -.Neo4j 3.x, secured with self-signed certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 3.x +| Neo4j >= 4.x | Security | Secured with self-signed certificate @@ -202,26 +151,6 @@ neo4j.NewDriver("neo4j+s://graph.example.com:7687", auth) ---- neo4j.NewDriver("neo4j+ssc://graph.example.com:7687", auth) ---- - -| Comments -| This is the default for Neo4j 3.x series -|=== - -.Neo4j 3.x, unsecured -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 3.x - -| Security -| Unsecured - -| Code snippet -| -[source, go, indent=0] ----- -neo4j.NewDriver("neo4j://graph.example.com:7687", auth); ----- |=== [NOTE] diff --git a/go-manual/modules/ROOT/pages/session-api.adoc b/go-manual/modules/ROOT/pages/session-api.adoc index 7f39e725..c968d35c 100644 --- a/go-manual/modules/ROOT/pages/session-api.adoc +++ b/go-manual/modules/ROOT/pages/session-api.adoc @@ -28,6 +28,9 @@ See xref:session-api.adoc#go-driver-session-configuration[Session configuration] include::{common-partial}/session-api.adoc[tag=simple-transaction-fn] +[CAUTION] +The methods `ExecuteRead` and `ExecuteWrite` have replaced `ReadTransaction` and `WriteTransaction`, which are deprecated in version 5.x and will be removed in version 6.0. + [source, go, indent=0] ---- include::{go-examples}/examples_test.go[tags=transaction-function] From 267a988ebf89c6df5d4ee7bbf36c4352dfa5ed55 Mon Sep 17 00:00:00 2001 From: Stefano Ottolenghi Date: Thu, 20 Oct 2022 14:06:25 +0200 Subject: [PATCH 4/9] Java manual and fixes to async prefixes in dotnet. --- .../modules/ROOT/pages/session-api.adoc | 2 +- .../ROOT/pages/client-applications.adoc | 147 ++---------------- .../modules/ROOT/pages/session-api.adoc | 9 ++ .../modules/ROOT/pages/cypher-workflow.adoc | 3 - 4 files changed, 22 insertions(+), 139 deletions(-) diff --git a/dotnet-manual/modules/ROOT/pages/session-api.adoc b/dotnet-manual/modules/ROOT/pages/session-api.adoc index c56ab8e4..351bd46c 100644 --- a/dotnet-manual/modules/ROOT/pages/session-api.adoc +++ b/dotnet-manual/modules/ROOT/pages/session-api.adoc @@ -94,7 +94,7 @@ See xref:session-api.adoc#dotnet-driver-session-configuration[Session configurat include::{common-partial}/session-api.adoc[tag=async-transaction-fn] [CAUTION] -The methods `ExecuteRead` and `ExecuteWrite` have replaced `ReadTransaction` and `WriteTransaction`, which are deprecated in version 5.x and will be removed in version 6.0. +The methods `ExecuteReadAsync` and `ExecuteWriteAsync` have replaced `ReadTransactionAsync` and `WriteTransactionAsync`, which are deprecated in version 5.x and will be removed in version 6.0. [source, csharp, indent=0] ---- diff --git a/java-manual/modules/ROOT/pages/client-applications.adoc b/java-manual/modules/ROOT/pages/client-applications.adoc index 30efd705..04f8ed23 100644 --- a/java-manual/modules/ROOT/pages/client-applications.adoc +++ b/java-manual/modules/ROOT/pages/client-applications.adoc @@ -103,11 +103,11 @@ include::{common-partial}/client-applications.adoc[tag=examples-pt2] .Connecting to a service The tables below illustrate examples of how to connect to a service with routing: -.Neo4j Aura, secured with full certificate +.Neo4j Aura or Neo4j >= 4.x, secured with full certificate [cols="<15s,<85a"] |=== | Product -| Neo4j Aura +| Neo4j Aura, Neo4j >= 4.x | Security | Secured with full certificate @@ -119,27 +119,16 @@ The tables below illustrate examples of how to connect to a service with routing GraphDatabase.driver("neo4j+s://graph.example.com:7687", auth) ---- -If you do not have at least the Java Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, java, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -Config config = Config.builder() - .withEncryption() - .build(); -Driver driver = GraphDatabase.driver(uri, auth, config); ----- - | Comments | This is the default (and only option) for Neo4j Aura |=== -.Neo4j 4.x, unsecured +.Neo4j >= 4.x, unsecured [cols="<15s,<85a"] |=== | Product -| Neo4j 4.x +| Neo4j >= 4.x | Security | Unsecured @@ -152,42 +141,14 @@ GraphDatabase.driver("neo4j://graph.example.com:7687", auth) ---- | Comments -| This is the default for Neo4j 4.x series +| This is the default for Neo4j >= 4.x series |=== -.Neo4j 4.x, secured with full certificate +.Neo4j >= 4.x, secured with self-signed certificate [cols="<15s,<85a"] |=== | Product -| Neo4j 4.x - -| Security -| Secured with full certificate - -| Code snippet -| -[source, java, indent=0] ----- -GraphDatabase.driver("neo4j+s://graph.example.com:7687", auth) ----- - -If you do not have at least the Java Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, java, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -Config config = Config.builder() - .withEncryption() - .build(); -Driver driver = GraphDatabase.driver(uri, auth, config); ----- -|=== - -.Neo4j 4.x, secured with self-signed certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 4.x +| Neo4j >= 4.x | Security | Secured with self-signed certificate @@ -198,95 +159,6 @@ Driver driver = GraphDatabase.driver(uri, auth, config); ---- GraphDatabase.driver("neo4j+ssc://graph.example.com:7687", auth) ---- - -If you do not have at least the Java Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, java, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -Config config = Config.builder() - .withEncryption() - .withTrustStrategy( trustAllCertificates() ) - .build(); -Driver driver = GraphDatabase.driver(uri, auth, config); ----- -|=== - -.Neo4j 3.x, secured with full certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 3.x - -| Security -| Secured with full certificate - -| Code snippet -| -[source, java, indent=0] ----- -GraphDatabase.driver("neo4j+s://graph.example.com:7687", auth) ----- - -If you do not have at least the Java Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, java, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -Config config = Config.builder() - .withEncryption() - .build(); -Driver driver = GraphDatabase.driver(uri, auth, config); ----- -|=== - -.Neo4j 3.x, secured with self-signed certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 3.x - -| Security -| Secured with self-signed certificate - -| Code snippet -| -[source, java, indent=0] ----- -GraphDatabase.driver("neo4j+ssc://graph.example.com:7687", auth) ----- - -If you do not have at least the Java Driver 4.0.1 patch installed, you will need this snippet instead: - -[source, java, indent=0] ----- -String uri = "neo4j://graph.example.com:7687"; -Config config = Config.builder() - .withEncryption() - .withTrustStrategy( trustAllCertificates() ) - .build(); -Driver driver = GraphDatabase.driver(uri, auth, config); ----- - -| Comments -| This is the default for Neo4j 3.x series -|=== - -.Neo4j 3.x, unsecured -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 3.x - -| Security -| Unsecured - -| Code snippet -| -[source, java, indent=0] ----- -GraphDatabase.driver("neo4j://graph.example.com:7687", auth) ----- |=== [NOTE] @@ -435,6 +307,11 @@ include::{java-examples}/ConfigMaxRetryTimeExample.java[tags=config-max-retry-ti include::{common-partial}/client-applications.adoc[tag=configuration-TrustStrategy] + + +* `Config.TrustStrategy.trustSystemCertificates()` - Accept any certificate that can be verified against the system store. +* `Config.TrustStrategy.trustCustomCertificateSignedBy("/path/ca1.crt", "/path/ca2.crt", ...)` - *[Default]* Accept certificates at specified paths. +* `Config.TrustStrategy.trustAllCertificates()` - Accept any certificate, including self-signed ones. *Not recommended for production environments.* + .Configure trusted certificates ====== [source, java, indent=0] diff --git a/java-manual/modules/ROOT/pages/session-api.adoc b/java-manual/modules/ROOT/pages/session-api.adoc index a41c4b1d..082edef6 100644 --- a/java-manual/modules/ROOT/pages/session-api.adoc +++ b/java-manual/modules/ROOT/pages/session-api.adoc @@ -32,6 +32,9 @@ See xref:session-api.adoc#java-driver-session-configuration[Session configuratio include::{common-partial}/session-api.adoc[tag=simple-transaction-fn] +[CAUTION] +The methods `executeRead` and `executeWrite` have replaced `readTransaction` and `writeTransaction`, which are deprecated in version 5.x and will be removed in version 6.0. + [source, java, indent=0] ---- include::{java-examples}/TransactionFunctionExample.java[tags=transaction-function] @@ -90,6 +93,9 @@ See xref:session-api.adoc#java-driver-session-configuration[Session configuratio include::{common-partial}/session-api.adoc[tag=async-transaction-fn] +[CAUTION] +The methods `executeReadAsync` and `executeWriteAsync` have replaced `readTransactionAsync` and `writeTransactionAsync`, which are deprecated in version 5.x and will be removed in version 6.0. + [source, java, indent=0] ---- include::{java-examples}/AsyncTransactionFunctionExample.java[tags=async-transaction-function] @@ -150,6 +156,9 @@ include::{common-partial}/session-api.adoc[tag=rx-lifecycle] include::{common-partial}/session-api.adoc[tag=rx-transaction-fn] +[CAUTION] +The methods `executeRead` and `executeWrite` have replaced `readTransaction` and `writeTransaction`, which are deprecated in version 5.x and will be removed in version 6.0. + [source, java, indent=0] ---- include::{java-examples}/RxTransactionFunctionExample.java[tags=rx-transaction-function] diff --git a/python-manual/modules/ROOT/pages/cypher-workflow.adoc b/python-manual/modules/ROOT/pages/cypher-workflow.adoc index e08cd24e..3f318f4d 100644 --- a/python-manual/modules/ROOT/pages/cypher-workflow.adoc +++ b/python-manual/modules/ROOT/pages/cypher-workflow.adoc @@ -56,9 +56,6 @@ include::{python-examples}/test_pass_bookmarks_example.py[tags=pass-bookmarks] include::{common-partial}/cypher-workflow.adoc[tag=access-modes-transaction] -[NOTE] -The methods `execute_read` and `execute_write` were called `read_transaction` and `write_transaction` in version 4.x. - .Read-write transaction ====== [source, python, indent=0] From b32996b0d52b899819d99d75a80df7e298523ead Mon Sep 17 00:00:00 2001 From: Stefano Ottolenghi Date: Thu, 20 Oct 2022 14:34:44 +0200 Subject: [PATCH 5/9] Updated javascript manual. --- .../ROOT/pages/client-applications.adoc | 140 ++---------------- .../modules/ROOT/pages/session-api.adoc | 6 + 2 files changed, 18 insertions(+), 128 deletions(-) diff --git a/javascript-manual/modules/ROOT/pages/client-applications.adoc b/javascript-manual/modules/ROOT/pages/client-applications.adoc index 645babf5..e448a037 100644 --- a/javascript-manual/modules/ROOT/pages/client-applications.adoc +++ b/javascript-manual/modules/ROOT/pages/client-applications.adoc @@ -103,11 +103,11 @@ include::{common-partial}/client-applications.adoc[tag=examples-pt2] .Connecting to a service The tables below illustrate examples of how to connect to a service with routing: -.Neo4j Aura, secured with full certificate +.Neo4j Aura or Neo4j >= 4.x, secured with full certificate [cols="<15s,<85a"] |=== | Product -| Neo4j Aura +| Neo4j Aura, Neo4j >= 4.x | Security | Secured with full certificate @@ -119,24 +119,15 @@ The tables below illustrate examples of how to connect to a service with routing neo4j.driver("neo4j+s://graph.example.com:7687", auth) ---- -If you do not have at least the JavaScript Driver 4.0.2 patch installed, you will need this snippet instead: - -[source, javascript, indent=0] ----- -const uri = 'neo4j://graph.example.com:7687' -const driver = neo4j.driver(uri, auth, { - encrypted: 'ENCRYPTION_ON' -}) ----- | Comments | This is the default (and only option) for Neo4j Aura. |=== -.Neo4j 4.x, unsecured +.Neo4j >= 4.x, unsecured [cols="<15s,<85a"] |=== | Product -| Neo4j 4.x +| Neo4j >= 4.x | Security | Unsecured @@ -148,41 +139,14 @@ const driver = neo4j.driver(uri, auth, { neo4j.driver("neo4j://graph.example.com:7687", auth) ---- | Comments -| This is the default for Neo4j 4.x series -|=== - -.Neo4j 4.x, secured with full certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 4.x - -| Security -| Secured with full certificate - -| Code snippet -| -[source, javascript, indent=0] ----- -neo4j.driver("neo4j+s://graph.example.com:7687", auth) ----- - -If you do not have at least the JavaScript Driver 4.0.2 patch installed, you will need this snippet instead: - -[source, javascript, indent=0] ----- -const uri = 'neo4j://graph.example.com:7687' -const driver = neo4j.driver(uri, auth, { - encrypted: 'ENCRYPTION_ON' -}) ----- +| This is the default for Neo4j >= 4.x series |=== -.Neo4j 4.x, secured with self-signed certificate +.Neo4j >= 4.x, secured with self-signed certificate [cols="<15s,<85a"] |=== | Product -| Neo4j 4.x +| Neo4j >= 4.x | Security | Secured with self-signed certificate @@ -193,91 +157,6 @@ const driver = neo4j.driver(uri, auth, { ---- neo4j.driver("neo4j+ssc://graph.example.com:7687", auth) ---- - -If you do not have at least the JavaScript Driver 4.0.2 patch installed, you will need this snippet instead: - -[source, javascript, indent=0] ----- -const uri = 'neo4j://graph.example.com:7687' -const driver = neo4j.driver(uri, auth, { - encrypted: 'ENCRYPTION_ON', - trust: 'TRUST_ALL_CERTIFICATES' -}) ----- -|=== - -.Neo4j 3.x, secured with full certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 3.x - -| Security -| Secured with full certificate - -| Code snippet -| -[source, javascript, indent=0] ----- -neo4j.driver("neo4j+s://graph.example.com:7687", auth) ----- - -If you do not have at least the JavaScript Driver 4.0.2 patch installed, you will need this snippet instead: - -[source, javascript, indent=0] ----- -const uri = 'neo4j://graph.example.com:7687' -const driver = neo4j.driver(uri, auth, { - encrypted: 'ENCRYPTION_ON' -}) ----- -|=== - -.Neo4j 3.x, secured with self-signed certificate -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 3.x - -| Security -| Secured with self-signed certificate - -| Code snippet -| -[source, javascript, indent=0] ----- -neo4j.driver("neo4j+ssc://graph.example.com:7687", auth) ----- - -If you do not have at least the JavaScript Driver 4.0.2 patch installed, you will need this snippet instead: - -[source, javascript, indent=0] ----- -const uri = 'neo4j://graph.example.com:7687' -const driver = neo4j.driver(uri, auth, { - encrypted: 'ENCRYPTION_ON', - trust: 'TRUST_ALL_CERTIFICATES' -}) ----- -| Comments -| This is the default for Neo4j 3.x series -|=== - -.Neo4j 3.x, unsecured -[cols="<15s,<85a"] -|=== -| Product -| Neo4j 3.x - -| Security -| Unsecured - -| Code snippet -| -[source, javascript, indent=0] ----- -neo4j.driver("neo4j://graph.example.com:7687", auth) ----- |=== [NOTE] @@ -429,6 +308,11 @@ include::{javascript-examples}/examples.test.js[tags=config-max-retry-time] include::{common-partial}/client-applications.adoc[tag=configuration-TrustStrategy] + + +* `TRUST_SYSTEM_CA_SIGNED_CERTIFICATES` - *[Default]* Accept any certificate that can be verified against the system store. +* `TRUST_CUSTOM_CA_SIGNED_CERTIFICATES` - Accept certificates at specified paths. Paths are specified as a list to the extra config parameter `trustedCertificates`. +* `TRUST_ALL_CERTIFICATES` - Accept any certificate, including self-signed ones. *Not recommended for production environments.* + .Configure trusted certificates ====== [source, javascript, indent=0] diff --git a/javascript-manual/modules/ROOT/pages/session-api.adoc b/javascript-manual/modules/ROOT/pages/session-api.adoc index acc3cf24..1003bcbc 100644 --- a/javascript-manual/modules/ROOT/pages/session-api.adoc +++ b/javascript-manual/modules/ROOT/pages/session-api.adoc @@ -24,6 +24,9 @@ See xref:session-api.adoc#js-driver-session-configuration[Session configuration] include::{common-partial}/session-api.adoc[tag=async-transaction-fn] +[CAUTION] +The methods `executeRead` and `executeWrite` have replaced `readTransaction` and `writeTransaction`, which are deprecated in version 5.x and will be removed in version 6.0. + [source, javascript, indent=0] ---- include::{javascript-examples}/examples.test.js[tags=async-transaction-function] @@ -85,6 +88,9 @@ include::{common-partial}/session-api.adoc[tag=rx-lifecycle] include::{common-partial}/session-api.adoc[tag=rx-transaction-fn] +[CAUTION] +The methods `executeRead` and `executeWrite` have replaced `readTransaction` and `writeTransaction`, which are deprecated in version 5.x and will be removed in version 6.0. + [source, javascript, indent=0] ---- include::{javascript-examples}/examples.test.js[tags=rx-transaction-function] From 01a50014737e40735642e2be13b1b9fadec6909b Mon Sep 17 00:00:00 2001 From: Stefano Ottolenghi Date: Thu, 20 Oct 2022 14:45:56 +0200 Subject: [PATCH 6/9] Reverting changes to `Connecting to a service` section in `common-content` since that sections are not included, and this avoids a useless diff. --- .../ROOT/partials/client-applications.adoc | 126 ++++++++++++++++-- 1 file changed, 118 insertions(+), 8 deletions(-) diff --git a/common-content/modules/ROOT/partials/client-applications.adoc b/common-content/modules/ROOT/partials/client-applications.adoc index 98aaebd0..559e24e1 100644 --- a/common-content/modules/ROOT/partials/client-applications.adoc +++ b/common-content/modules/ROOT/partials/client-applications.adoc @@ -376,34 +376,109 @@ The table below illustrates examples of how to connect to a service with routing ---- GraphDatabase.Driver("neo4j+s://graph.example.com:7687", auth) ---- + +If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: + +[source, csharp, indent=0] +---- +String uri = "neo4j://graph.example.com:7687"; +IDriver driver = GraphDatabase.Driver(uri, auth, + o => o.WithEncryptionLevel(EncryptionLevel.Encrypted)); +---- |Comments | This is the default (and only option) for Neo4j Aura -|Neo4j >= 4.x +|Neo4j 4.x |Unsecured | [source, csharp, indent=0] ---- GraphDatabase.Driver("neo4j://graph.example.com:7687", auth); ---- -|This is the default for Neo4j >= 4.x series +|This is the default for Neo4j 4.x series -|Neo4j >= 4.x +|Neo4j 4.x |Secured with full certificate | [source, csharp, indent=0] ---- GraphDatabase.Driver("neo4j+s://graph.example.com:7687", auth) ---- + +If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: + +[source, csharp, indent=0] +---- +String uri = "neo4j://graph.example.com:7687"; +IDriver driver = GraphDatabase.Driver(uri, auth, + o => o.WithEncryptionLevel(EncryptionLevel.Encrypted)); +---- +| + +|Neo4j 4.x +|Secured with self-signed certificate +| +[source, csharp, indent=0] +---- +GraphDatabase.Driver("neo4j+ssc://graph.example.com:7687", auth) +---- + +If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: + +[source, csharp, indent=0] +---- +String uri = "neo4j://graph.example.com:7687"; +IDriver driver = GraphDatabase.Driver(uri, auth, + o => o.WithEncryptionLevel(EncryptionLevel.Encrypted) + .WithTrustManager(TrustManager.CreateInsecure())); +---- +| + +|Neo4j 3.x +|Secured with full certificate +| +[source, csharp, indent=0] +---- +GraphDatabase.Driver("neo4j+s://graph.example.com:7687", auth) +---- + +If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: + +[source, csharp, indent=0] +---- +String uri = "neo4j://graph.example.com:7687"; +IDriver driver = GraphDatabase.Driver(uri, auth, + o => o.WithEncryptionLevel(EncryptionLevel.Encrypted)); +---- | -|Neo4j >= 4.x +|Neo4j 3.x |Secured with self-signed certificate | [source, csharp, indent=0] ---- GraphDatabase.Driver("neo4j+ssc://graph.example.com:7687", auth) ---- + +If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead: + +[source, csharp, indent=0] +---- +String uri = "neo4j://graph.example.com:7687"; +IDriver driver = GraphDatabase.Driver(uri, auth, + o => o.WithEncryptionLevel(EncryptionLevel.Encrypted) + .WithTrustManager(TrustManager.CreateInsecure())); +---- +|This is the default for Neo4j 3.x series + +|Neo4j 3.x +|Unsecured +| +[source, csharp, indent=0] +---- +GraphDatabase.Driver("neo4j://graph.example.com:7687", auth); +---- | + |=== [NOTE] @@ -700,33 +775,54 @@ The table below illustrates examples of how to connect to a service with routing ---- GraphDatabase.driver("neo4j+s://graph.example.com:7687", auth) ---- + +For Python Driver versions before 4.0.0 you need this snippet instead: +[source, python, indent=0] +---- +GraphDatabase.driver("neo4j://graph.example.com:7687", auth, + "encrypted"=True, "trust"=TRUST_SYSTEM_CA_SIGNED_CERTIFICATES) +---- | This is the default (and only option) for Neo4j Aura -|Neo4j 5.x +|Neo4j 4.x |Unsecured | [source, python, indent=0] ---- GraphDatabase.driver("neo4j://graph.example.com:7687", auth) ---- -|This is the default for Neo4j 5.x series +|This is the default for Neo4j 4.x series -|Neo4j 5.x +|Neo4j 4.x |Secured with full certificate | [source, python, indent=0] ---- GraphDatabase.driver("neo4j+s://graph.example.com:7687", auth) ---- + +For Python Driver versions before 4.0.0 you need this snippet instead: +[source, python, indent=0] +---- +GraphDatabase.driver("neo4j://graph.example.com:7687", auth, + "encrypted"=True, "trust"=TRUST_SYSTEM_CA_SIGNED_CERTIFICATES) +---- | -|Neo4j 5.x +|Neo4j 4.x |Secured with self-signed certificate | [source, python, indent=0] ---- neo4j.driver("neo4j+ssc://graph.example.com:7687", auth) ---- + +For Python Driver versions before 4.0.0 you need this snippet instead: +[source, python, indent=0] +---- +GraphDatabase.driver("neo4j://graph.example.com:7687", auth, + "encrypted"=True, "trust"=TRUST_ALL_CERTIFICATES) +---- | |Neo4j 3.x @@ -736,6 +832,13 @@ neo4j.driver("neo4j+ssc://graph.example.com:7687", auth) ---- neo4j.driver("neo4j+s://graph.example.com:7687", auth) ---- + +For Python Driver versions before 4.0.0 you need this snippet instead: +[source, python, indent=0] +---- +GraphDatabase.driver("neo4j://graph.example.com:7687", auth, + "encrypted"=True, "trust"=TRUST_SYSTEM_CA_SIGNED_CERTIFICATES) +---- | |Neo4j 3.x @@ -745,6 +848,13 @@ neo4j.driver("neo4j+s://graph.example.com:7687", auth) ---- neo4j.driver("neo4j+ssc://graph.example.com:7687", auth) ---- + +For Python Driver versions before 4.0.0 you need this snippet instead: +[source, python, indent=0] +---- +GraphDatabase.driver("neo4j://graph.example.com:7687", auth, + "encrypted"=True, "trust"=TRUST_ALL_CERTIFICATES) +---- |This is the default for Neo4j 3.x series |Neo4j 3.x From 91067106a8f9f230f1e833ab4670a5d78f5ac05c Mon Sep 17 00:00:00 2001 From: Stefano Ottolenghi Date: Thu, 20 Oct 2022 14:59:06 +0200 Subject: [PATCH 7/9] Add mentions of `CanBeRetried` methods do Go and Javascript manuals. --- go-manual/modules/ROOT/pages/cypher-workflow.adoc | 1 + javascript-manual/modules/ROOT/pages/cypher-workflow.adoc | 2 ++ 2 files changed, 3 insertions(+) diff --git a/go-manual/modules/ROOT/pages/cypher-workflow.adoc b/go-manual/modules/ROOT/pages/cypher-workflow.adoc index a7da103b..cdd44c91 100644 --- a/go-manual/modules/ROOT/pages/cypher-workflow.adoc +++ b/go-manual/modules/ROOT/pages/cypher-workflow.adoc @@ -199,3 +199,4 @@ Transient errors are those which are generated by the server and marked as safe Examples of such errors are deadlocks and memory issues. When using transaction functions, the driver will usually be able to automatically retry when a transient failure occurs. +The function `IsRetryable` gives insights into whether a further attempt might be successful. diff --git a/javascript-manual/modules/ROOT/pages/cypher-workflow.adoc b/javascript-manual/modules/ROOT/pages/cypher-workflow.adoc index 4eb57798..06292683 100644 --- a/javascript-manual/modules/ROOT/pages/cypher-workflow.adoc +++ b/javascript-manual/modules/ROOT/pages/cypher-workflow.adoc @@ -242,3 +242,5 @@ include::{javascript-examples}/examples.test.js[tags=geospatial-types-wgs84] == Exceptions and error handling include::{common-partial}/cypher-workflow.adoc[tag=exceptions-errors] + +The method `isRetriableError` gives insights into whether a further attempt might be successful. From c2f6ff40bcaaf7e492c53f1a825051049da956be Mon Sep 17 00:00:00 2001 From: Stefano Ottolenghi Date: Thu, 20 Oct 2022 15:43:15 +0200 Subject: [PATCH 8/9] Correct mistake for default value for `TrustedCertificates`. --- dotnet-manual/modules/ROOT/pages/client-applications.adoc | 4 ++-- java-manual/modules/ROOT/pages/client-applications.adoc | 4 ++-- python-manual/modules/ROOT/pages/client-applications.adoc | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/dotnet-manual/modules/ROOT/pages/client-applications.adoc b/dotnet-manual/modules/ROOT/pages/client-applications.adoc index 3e28c0e1..1aa2f96b 100644 --- a/dotnet-manual/modules/ROOT/pages/client-applications.adoc +++ b/dotnet-manual/modules/ROOT/pages/client-applications.adoc @@ -313,8 +313,8 @@ include::{dotnet-examples}/Examples.cs[tags=config-max-retry-time] include::{common-partial}/client-applications.adoc[tag=configuration-TrustStrategy] -* `TrustManager.CreateChainTrust()` - Accept any certificate that can be verified against the system store. -* `TrustManager.CreateCertTrust(new []{"/path/ca1.crt", "/path/ca2.crt"})` - *[Default]* Accept certificates at specified paths. +* `TrustManager.CreateChainTrust()` - *[Default]* Accept any certificate that can be verified against the system store. +* `TrustManager.CreateCertTrust(new []{"/path/ca1.crt", "/path/ca2.crt"})` - Accept certificates at specified paths. * `TrustManager.CreateInsecure()` - Accept any certificate, including self-signed ones. *Not recommended for production environments.* + diff --git a/java-manual/modules/ROOT/pages/client-applications.adoc b/java-manual/modules/ROOT/pages/client-applications.adoc index 04f8ed23..8646b765 100644 --- a/java-manual/modules/ROOT/pages/client-applications.adoc +++ b/java-manual/modules/ROOT/pages/client-applications.adoc @@ -308,8 +308,8 @@ include::{java-examples}/ConfigMaxRetryTimeExample.java[tags=config-max-retry-ti include::{common-partial}/client-applications.adoc[tag=configuration-TrustStrategy] + -* `Config.TrustStrategy.trustSystemCertificates()` - Accept any certificate that can be verified against the system store. -* `Config.TrustStrategy.trustCustomCertificateSignedBy("/path/ca1.crt", "/path/ca2.crt", ...)` - *[Default]* Accept certificates at specified paths. +* `Config.TrustStrategy.trustSystemCertificates()` - *[Default]* Accept any certificate that can be verified against the system store. +* `Config.TrustStrategy.trustCustomCertificateSignedBy("/path/ca1.crt", "/path/ca2.crt", ...)` - Accept certificates at specified paths. * `Config.TrustStrategy.trustAllCertificates()` - Accept any certificate, including self-signed ones. *Not recommended for production environments.* .Configure trusted certificates diff --git a/python-manual/modules/ROOT/pages/client-applications.adoc b/python-manual/modules/ROOT/pages/client-applications.adoc index 834cd606..d7386f6b 100644 --- a/python-manual/modules/ROOT/pages/client-applications.adoc +++ b/python-manual/modules/ROOT/pages/client-applications.adoc @@ -364,8 +364,8 @@ include::{python-examples}/test_config_max_retry_time_example.py[tags=config-max include::{common-partial}/client-applications.adoc[tag=configuration-TrustStrategy] -* `neo4j.TrustSystemCAs()` - Accept any certificate that can be verified against the system store. -* `neo4j.TrustCustomCAs("/path/ca1.crt", "/path/ca2.crt", ...)` - *[Default]* Accept certificates at specified paths. +* `neo4j.TrustSystemCAs()` - *[Default]* Accept any certificate that can be verified against the system store. +* `neo4j.TrustCustomCAs("/path/ca1.crt", "/path/ca2.crt", ...)` - Accept certificates at specified paths. * `neo4j.TrustAll()` - Accept any certificate, including self-signed ones. *Not recommended for production environments.* From 9eb41d74a13781e540df7373af92ed70b9b87114 Mon Sep 17 00:00:00 2001 From: Stefano Ottolenghi Date: Thu, 20 Oct 2022 15:46:38 +0200 Subject: [PATCH 9/9] Extra line breaks. Co-authored-by: David Oliver --- common-content/modules/ROOT/partials/client-applications.adoc | 3 ++- python-manual/modules/ROOT/pages/client-applications.adoc | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/common-content/modules/ROOT/partials/client-applications.adoc b/common-content/modules/ROOT/partials/client-applications.adoc index 559e24e1..d5a04fce 100644 --- a/common-content/modules/ROOT/partials/client-applications.adoc +++ b/common-content/modules/ROOT/partials/client-applications.adoc @@ -1461,7 +1461,8 @@ include::{python-examples}/test_config_max_retry_time_example.py[tags=config-max `TrustedCertificates`:: -Specify how to determine the authenticity of encryption certificates provided by the Neo4j instance that you are connecting to. If encryption is disabled, this option has no effect. +Specify how to determine the authenticity of encryption certificates provided by the Neo4j instance that you are connecting to. +If encryption is disabled, this option has no effect. + diff --git a/python-manual/modules/ROOT/pages/client-applications.adoc b/python-manual/modules/ROOT/pages/client-applications.adoc index d7386f6b..5ce0429f 100644 --- a/python-manual/modules/ROOT/pages/client-applications.adoc +++ b/python-manual/modules/ROOT/pages/client-applications.adoc @@ -420,4 +420,5 @@ logging.getLogger("neo4j").setLevel(logging.DEBUG) == Async Starting from version 5.0, the driver can also function asynchronously. The flow to connect and interact with the database is the same, except that async functions have the `Async` prefix and that database function calls need to `await` the result. + More information can be found in the link:https://neo4j.com/docs/api/python-driver/5.0/async_api.html[API documentation].