Skip to content

Commit 3ae1261

Browse files
dnwparkdnwpark
authored
Update GelConnection class and docs (#53)
1 parent 9591784 commit 3ae1261

File tree

5 files changed

+135
-237
lines changed

5 files changed

+135
-237
lines changed

‎docs/connecting.rst‎

Lines changed: 45 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44
Connection Parameters
55
=====================
66

7-
The ``GelClientPool`` constructor can consume an ``GelConnection`` class
8-
containing connection arguments for the client.
7+
The ``GelClientPool`` constructor can optionally consume a ``GelConnection``
8+
object containing connection arguments for the client.
99

1010
Most of the time, the connection arguments are implicitly resolved via
1111
:ref:`projects <ref_intro_projects>`. In other cases, the ``GelConnection``
@@ -20,87 +20,50 @@ You can use a provided builder by calling the ``builder()`` method on
2020
.. code-block:: java
2121
2222
var builder = GelConnection.builder();
23+
var connection = builder.build();
2324
24-
The builder has the following methods:
25-
26-
+---------------------+-----------------+-----------------------------------------------------------------------+
27-
| Name | Type | Description |
28-
+=====================+=================+=======================================================================+
29-
| ``withUser`` | String | The username to connect as. |
30-
+---------------------+-----------------+-----------------------------------------------------------------------+
31-
| ``withPassword`` | String | The password used to authenticate. |
32-
+---------------------+-----------------+-----------------------------------------------------------------------+
33-
| ``withDatabase`` | String | The name of the database to use. |
34-
+---------------------+-----------------+-----------------------------------------------------------------------+
35-
| ``withHostname`` | String | The hostname of the database. |
36-
+---------------------+-----------------+-----------------------------------------------------------------------+
37-
| ``withPort`` | int | The port of the database. |
38-
+---------------------+-----------------+-----------------------------------------------------------------------+
39-
| ``withTlsca`` | String | The TLS certificate authority, used to verify the server certificate. |
40-
+---------------------+-----------------+-----------------------------------------------------------------------+
41-
| ``withTlsSecurity`` | TLSSecurityMode | The TLS security policy. |
42-
+---------------------+-----------------+-----------------------------------------------------------------------+
43-
44-
45-
Parse & constructor methods
46-
---------------------------
47-
48-
``GelConnection`` also exposes static methods used to parse connection
49-
arguments from different sources.
50-
51-
fromDSN
52-
^^^^^^^
53-
54-
This method parses a :ref:`DSN <ref_dsn>` string into an ``GelConnection``.
55-
56-
.. code-block:: java
57-
58-
var connection = GelConnection
59-
.fromDSN("gel://user:pass@host:port/db");
60-
61-
fromProjectFile
62-
^^^^^^^^^^^^^^^
63-
64-
This method resolves connection arguments from a ``gel.toml``
65-
:ref:`project file <ref_intro_projects>`.
66-
67-
.. code-block:: java
68-
69-
var connection = GelConnection
70-
.fromProjectFile("~/myproject/gel.toml");
25+
The builder accepts several `parameters <https://docs.edgedb.com/database/reference/connection>`_
26+
which are used to construct the final ``GelConnection``.
7127

72-
fromInstanceName
73-
^^^^^^^^^^^^^^^^
28+
If no parameters are provided, the default behavior is to search for the
29+
project's ``gel.toml`` file.
7430

75-
This method resolves the connection arguments for a given instance name.
76-
77-
.. code-block:: java
78-
79-
var connection = GelConnection
80-
.fromInstanceName("my_instance_name");
81-
82-
resolveEdgeDBTOML
83-
^^^^^^^^^^^^^^^^^
84-
85-
This method is the default behaviour, it scans the current directory for
86-
a ``gel.toml`` project file, if none is found, the parent directory is
87-
scanned recursivly until a project file is found; if none is found, a
88-
``FileNotFoundException`` is raised.
89-
90-
.. code-block:: java
91-
92-
var connection = GelConnection
93-
.resolveEdgeDBTOML();
94-
95-
parse
96-
^^^^^
97-
98-
The parse method will resolve the given arguments as well as apply
99-
environment variables to the connection, following the
100-
:ref:`priority levels <ref_reference_connection_priority>` of arguments.
101-
102-
.. code-block:: java
103-
104-
var connection = GelConnection
105-
.parse("my_instance");
31+
The builder has the following methods:
10632

33+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
34+
| Name | Type | Description |
35+
+=====================================+==========================+=========================================================================+
36+
| ``withInstance`` | String | The name of the gel instance to connect to. |
37+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
38+
| ``withDsn`` | String | The DSN to connect to. See: `here <https://www.edgedb.com/docs/reference/dsn>`_ for more information. |
39+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
40+
| ``withCredentials`` | String | A json representation of the connection arguments. |
41+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
42+
| ``withCredentialsFile`` | Path | A file to read as the credentials. |
43+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
44+
| ``withHost`` | String | The hostname to connect as. |
45+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
46+
| ``withPort`` | int | The port of the database. |
47+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
48+
| ``withBranch`` | String | The name of the branch to use. |
49+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
50+
| ``withDatabase`` | String | The name of the database to use. (Deprecated in favor of withBranch) |
51+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
52+
| ``withUser`` | String | The username to connect as. |
53+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
54+
| ``withPassword`` | String | The password used to authenticate. |
55+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
56+
| ``withSecretKey`` | String | The secret key used to use for cloud connections. |
57+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
58+
| ``withTLSCertificateAuthority`` | String | The TLS certificate authority, used to verifiy the server certificate. |
59+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
60+
| ``withTLSCertificateAuthorityFile`` | Path | A file to read as the TLS certificate authority. |
61+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
62+
| ``withTlsSecurity`` | TLSSecurityMode | The TLS security policy. |
63+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
64+
| ``withTLSServerName`` | String | The TLS server name to use. Overrides the hostname. |
65+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
66+
| ``withWaitUntilAvailable`` | WaitTime | The time to wait for a connection to the server to be established. |
67+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+
68+
| ``withServerSettings`` | HashMap<String, String> | Additional settings for the server connection. Currently has no effect. |
69+
+-------------------------------------+--------------------------+-------------------------------------------------------------------------+

‎src/driver/src/main/java/com/gel/driver/GelClientPool.java‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,10 @@ public Duration age() {
6969
* @param config The configuration for this client.
7070
* @throws ConfigurationException A configuration parameter is invalid.
7171
*/
72-
public GelClientPool(GelConnection connection, @NotNull GelClientConfig config) throws ConfigurationException {
72+
public GelClientPool(
73+
@NotNull GelConnection connection,
74+
@NotNull GelClientConfig config
75+
) throws ConfigurationException {
7376
this.clients = new ConcurrentLinkedQueue<>();
7477
this.config = config;
7578
this.connection = connection;
@@ -84,7 +87,7 @@ public GelClientPool(GelConnection connection, @NotNull GelClientConfig config)
8487
* @param connection The connection parameters used to connect this client to Gel.
8588
* @throws ConfigurationException A configuration parameter is invalid.
8689
*/
87-
public GelClientPool(GelConnection connection) throws GelException {
90+
public GelClientPool(@NotNull GelConnection connection) throws GelException {
8891
this(connection, GelClientConfig.DEFAULT);
8992
}
9093

0 commit comments

Comments
 (0)