Skip to content

Fix connection URL example and link to Oracle docs #9044

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hashhar merged 1 commit into from
Sep 10, 2021
Merged

Fix connection URL example and link to Oracle docs #9044

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 18 additions & 4 deletions docs/src/main/sphinx/connector/oracle.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,27 @@ properties in the file:
.. code-block:: text

connector.name=oracle
connection-url=jdbc:oracle:thin:@example.net:1521/ORCLCDB
// The exact format of connection-url varies by Oracle version. Refer to
// the Oracle Database documentation for version-specific information on the
// JDBC Thin driver.
connection-url=jdbc:oracle:thin:@//example.net:1521/ORCLCDB
Copy link
Copy Markdown
Member

@hashhar hashhar Aug 31, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both are correct. Depends on how you want to connect to Oracle and what version of Oracle you are on.

Quoting the link you shared:

Starting Oracle Database 10g, Oracle Service IDs are not supported.

This is the one we use in our existing example.

Oracle also supports a lot of other ways (all mentioned in the linked document) but it's important to note:

Thin-style Service Name Syntax
jdbc:oracle:thin:scott/tiger@//myhost:1521/myservicename

This is the one you are adding now.

So IMO somehow we should make it more obvious that the example is just that - an example. People should consult the documentation to see whatever URL they should use.

Copy link
Copy Markdown
Member

@ppalucha ppalucha Aug 31, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My understanding of documentation (https://docs.oracle.com/cd/B28359_01/java.111/b31224/urls.htm#BEIDHCBA) is that these are correct forms:

  • connection-url=jdbc:oracle:thin:@example.net:1521:ORCLCDB
  • connection-url=jdbc:oracle:thin:@//example.net:1521/ORCLCDB

connection-url=jdbc:oracle:thin:@example.net:1521/ORCLCDB is not correct

Copy link
Copy Markdown
Member

@ppalucha ppalucha Aug 31, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But 12.x documentation here https://docs.oracle.com/en/database/oracle/oracle-database/21/tdpjd/getting-started.html#GUID-D1652CF5-5A80-40BF-BB96-016D1694BE5A gives example:

Connection connection =
        DriverManager.getConnection("jdbc:oracle:thin:@localhost:1522/xepdb1", "hr", "hr");

So I guess all forms are correct...

Copy link
Copy Markdown
Member

@mosabua mosabua Aug 31, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given all that we should probably have multiple examples and links to the JDBC driver docs and explain that the URL just has to be valid for the driver use and the connected Oracle database from Trino..

Copy link
Copy Markdown
Contributor Author

@jhlodin jhlodin Aug 31, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Followup question, the requirements section above says that you need Oracle 12 or higher, so should we even be documenting v11? I don't think we should provide example connection URLs for versions we say we don't support, a generic "refer to the Oracle docs for more information" should suffice.

Copy link
Copy Markdown
Member

@mosabua mosabua Aug 31, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should not imho

Copy link
Copy Markdown
Member

@hashhar hashhar Aug 31, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mosabua The existing example is present in 12g documentation too - the last link that Pawel shared.

We can have multiple examples but it can't possibly be exhaustive. If left to me I'd just add a comment in the example config (before the connection-url line) that says to consult the Oracle documentation for the URL to use.

Copy link
Copy Markdown
Contributor Author

@jhlodin jhlodin Sep 2, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated, please have a look to see if that's a good compromise.

Copy link
Copy Markdown
Member

@hashhar hashhar Sep 3, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What changed?

Copy link
Copy Markdown
Contributor Author

@jhlodin jhlodin Sep 3, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I remembered how to use git, apparently. 😅

Changes are there now.

connection-user=root
connection-password=secret

The ``connection-url`` defines the connection information and parameters to pass
to the Oracle JDBC Thin driver. See the `Oracle Database JDBC driver
documentation <https://docs.oracle.com/cd/B28359_01/java.111/b31224/urls.htm#BEIDHCBA>`_
for more information.

The ``connection-user`` and ``connection-password`` are typically required and
determine the user credentials for the connection, often a service user. You can
use :doc:`secrets </security/secrets>` to avoid actual values in the catalog
properties files.

.. note::
Oracle does not expose metadata comment via ``REMARKS`` column by default
in JDBC driver. You can enable it using ``oracle.remarks-reporting.enabled`` config option. See `Additional Oracle Performance Extensions
in JDBC driver. You can enable it using ``oracle.remarks-reporting.enabled``
config option. See `Additional Oracle Performance Extensions
<https://docs.oracle.com/en/database/oracle/oracle-database/19/jjdbc/performance-extensions.html#GUID-96A38C6D-A288-4E0B-9F03-E711C146632B>`_
for more details.

Expand Down Expand Up @@ -278,8 +292,8 @@ to Trino ``TIMESTAMP``.
Mapping character types
^^^^^^^^^^^^^^^^^^^^^^^

Trino's ``VARCHAR(n)`` maps to ``VARCHAR2(n CHAR)`` if ``n`` is no greater than
4000. A larger or unbounded ``VARCHAR`` maps to ``NCLOB``.
Trino's ``VARCHAR(n)`` maps to ``VARCHAR2(n CHAR)`` if ``n`` is no greater
than 4000. A larger or unbounded ``VARCHAR`` maps to ``NCLOB``.

Trino's ``CHAR(n)`` maps to ``CHAR(n CHAR)`` if ``n`` is no greater than 2000.
A larger ``CHAR`` maps to ``NCLOB``.
Expand Down