docs: reorganize documentation to split driver-specific info into separate files #409

shubha-rajan · 2021-02-19T02:21:10Z

Change Description

Reorganized docs to make information more organized and easier to navigate. Also updated the version updater script to find and replace versions in the new files instead of the main README and rewrote CONTRIBUTING.md for consistency with corresponding doc in Cloud SQL Proxy repo.

Checklist

Make sure to open an issue as a
bug/issue
before writing your code! That way we can discuss the change, evaluate
designs, and agree on the general idea.
Ensure the tests and linter pass
Appropriate documentation is updated (if necessary)

Relevant issues:

Fixes Improve documentation about possible authentication options and required roles, if any? #375 Update build badge for new CI builds #325

…te files

kurtisvg · 2021-02-19T17:28:53Z

README.md

+* [Connecting to MySQL using JDBC](docs/jdbc-mysql)
+* [Connecting to Postgres using JDBC](docs/jdbc-postgres.md)
+* [Connecting to SQL Server using JDBC](docs/jdbc-sqlserver.md)
+* [Connecting to MySQL using R2DBC](docs/r2dbc-mysql.md)
+* [Connecting to Postgres using R2DBC](docs/r2dbc-postgres.md)
+* [Connecting to SQL Server using R2DBC](docs/r2dbc-sqlserver.md)


What do you think about separating this into a list for JDBC and a list for R2DBC? (It feels hard to skim since most of the letters are similar)

kurtisvg · 2021-02-19T17:29:25Z

README.md

-## Authentication
-
-This library uses the [Application Default Credentials](
+The Cloud SQL Connector for Java is a library for the MySQL/PostgreSQL/SQL Server JDBC and R2DBC drivers that allows a user 


We need to work shop the description we are using for connectors. See my comment here: GoogleCloudPlatform/cloud-sql-proxy#621 (comment)

I updated this to look more like your suggestion in that comment. Let me know if there's anything else I need to change.

kurtisvg · 2021-02-19T17:31:54Z

README.md

-```
-jdbc:mysql:///<DATABASE_NAME>?unixSocketPath=</PATH/TO/UNIX/SOCKET>&cloudSqlInstance=<INSTANCE_CONNECTION_NAME>&socketFactory=com.google.cloud.sql.mysql.SocketFactory&user=<MYSQL_USER_NAME>&password=<MYSQL_USER_PASSWORD>
-```
+For examples of this library being used in the context of an application, check out the sample applications located 


I would suggest moving this line up into the usage section.

kurtisvg · 2021-02-19T18:31:37Z

docs/jdbc-mysql.md

+compile 'com.google.cloud.sql:mysql-socket-factory-connector-j-8:1.2.1'
+```
+
+### Create the JDBC URL


Suggested change

### Create the JDBC URL

### Creating the JDBC URL

kurtisvg · 2021-02-19T18:31:46Z

docs/jdbc-mysql.md

+
+## Setup and Usage
+
+### Add library as a dependency


Suggested change

### Add library as a dependency

### Adding the library as a dependency

kurtisvg · 2021-02-19T18:35:23Z

docs/jdbc-mysql.md

+### Specifying IP Types
+
+The `ipTypes` argument can be used to specify a comma delimited list of preferred IP types for
+connecting to a Cloud SQL instance. The argument `ipTypes=PRIVATE` will force the 


I think the phrasing here could be improved. Maybe something like:

"The `ipTypes` argument is used to specify a preferred order of IP types used to connect via a comma delimited list. For example, `ipTypes=PUBLIC,PRIVATE` will use the instance's Public IP if it exists, otherwise private. The value `ipTypes=PRIVATE` will force the Cloud SQL instance to connect via it's private IP. If not specified, the default used is `ipTypes=PUBLIC,PRIVATE`.

Also please add a link to the private IP requirements.

…ql-jdbc-socket-factory into rewrite-docs

kurtisvg · 2021-02-21T04:29:38Z

README.md


-## Examples
+JDBC:
+* [Connecting to MySQL using JDBC](docs/jdbc-mysql)


Is there a particular reason we're using the docs folder? Would it be better to put in the README for the artifact itself?

This is for consistency with the documentation structure of the proxy repo. We can do artifact READMEs instead if you think that's better.

kurtisvg · 2021-02-21T04:31:23Z

core/pom.xml

@@ -10,7 +10,7 @@
  <artifactId>jdbc-socket-factory-core</artifactId>
  <packaging>jar</packaging>

-  <name>Cloud SQL MySQL Socket Factory (Core Library, don't depend on this directly)</name>
+  <name>Cloud SQL Core Socket Factory (Core Library, don't depend on this directly)</name>
  <description>
    Core library for establishing secure connections. End users should depend on the the
    mysql-socket-factory


Good catch - can you update the description as well?

docs/jdbc-mysql.md

kurtisvg · 2021-02-21T04:33:34Z

docs/jdbc-mysql.md

+
+### Specifying IP Types
+
+"The `ipTypes` argument is used to specify a preferred order of IP types used to connect via a comma delimited list. For example, `ipTypes=PUBLIC,PRIVATE` will use the instance's Public IP if it exists, otherwise private. The value `ipTypes=PRIVATE` will force the Cloud SQL instance to connect via it's private IP. If not specified, the default used is `ipTypes=PUBLIC,PRIVATE`. For more info on connecting using a private IP address, see [Requirements for Private IP](https://cloud.google.com/sql/docs/mysql/private-ip#requirements_for_private_ip).


nit: I'd suggest moving the last sentence into it's own paragraph.

kurtisvg · 2021-02-21T04:34:37Z

docs/jdbc-mysql.md

+jdbc:mysql:///<DATABASE_NAME>?unixSocketPath=</PATH/TO/UNIX/SOCKET>&cloudSqlInstance=<INSTANCE_CONNECTION_NAME>&socketFactory=com.google.cloud.sql.mysql.SocketFactory&user=<MYSQL_USER_NAME>&password=<MYSQL_USER_PASSWORD>
+```
+
+## Examples


At some point we discussed referencing the Serverless docs for GAE, etc. Do we still want to do that somewhere?

Co-authored-by: Kurtis Van Gent <31518063+kurtisvg@users.noreply.github.com>

…ql-jdbc-socket-factory into rewrite-docs

enocom

Looks great!

enocom · 2021-02-23T16:16:22Z

.release/update_versions.sh

@@ -20,5 +20,5 @@ mvn versions:set -DnewVersion=$VERSION -DgenerateBackupPoms=false
 # Update versions in README if not snapshot release
 if ! [[ $VERSION =~ .*SNAPSHOT ]]
 then 
-    sed -Ei '' 's/[0-9]+\.[0-9]+\.[0-9]+/'"$VERSION"'/g' README.md
+    sed -Ei '' 's/[0-9]+\.[0-9]+\.[0-9]+/'"$VERSION"'/g' docs/*.md
 fi


Nit: There should be a newline terminating the file.

enocom · 2021-02-23T16:17:35Z

README.md

-The Cloud SQL Connector for Java is a library for the MySQL/PostgreSQL JDBC and R2DBC drivers that allows a user 
-with the appropriate permissions to connect to a Cloud SQL database without having to deal with IP 
-whitelisting or SSL certificates manually.
+![CI Java 8][ci-badge-java-8]


Is there a link to the continuous build available to the public? It might be nice to add it here if so. Ditto with the line below.

I'm not sure that there is. The only one I'm aware of is the one on Fusion.

enocom · 2021-02-23T16:19:17Z

README.md


-## Examples
+JDBC:
+* [Connecting to MySQL using JDBC](docs/jdbc-mysql.md)


This is a fantastic improvement!

…ql-jdbc-socket-factory into rewrite-docs

kurtisvg

This feels way more organized than before. Thank you!

kurtisvg · 2021-02-25T18:40:07Z

docs/jdbc-mysql.md

@@ -0,0 +1,77 @@
+# Connecting to MySQL using JDBC


When we reshuffle the modules, I think we should revisit keeping these in the docs folder or with the module.

shubha-rajan added 3 commits February 18, 2021 17:51

docs: rewrite documentation to split driver-specific info into separa…

f76e821

…te files

update version updater script

53c180f

update README.md

a5fe777

blunderbuss-gcf bot assigned enocom Feb 19, 2021

google-cla bot added the cla: yes label Feb 19, 2021

shubha-rajan added 2 commits February 18, 2021 18:28

add build badges

2ffc117

Merge branch 'main' into rewrite-docs

0600c04

shubha-rajan requested review from kurtisvg and enocom February 19, 2021 17:15

kurtisvg suggested changes Feb 19, 2021

View reviewed changes

shubha-rajan added 2 commits February 19, 2021 13:21

addressed review comments

85c3539

Merge branch 'rewrite-docs' of github.com:GoogleCloudPlatform/cloud-s…

aadf616

…ql-jdbc-socket-factory into rewrite-docs

shubha-rajan requested a review from kurtisvg February 19, 2021 21:23

kurtisvg suggested changes Feb 21, 2021

View reviewed changes

shubha-rajan and others added 2 commits February 22, 2021 10:29

Update docs/jdbc-mysql.md

bc91565

Co-authored-by: Kurtis Van Gent <31518063+kurtisvg@users.noreply.github.com>

address review comments

0f935db

shubha-rajan requested a review from kurtisvg February 22, 2021 18:40

Merge branch 'rewrite-docs' of github.com:GoogleCloudPlatform/cloud-s…

9486b6b

…ql-jdbc-socket-factory into rewrite-docs

enocom approved these changes Feb 23, 2021

View reviewed changes

shubha-rajan added 7 commits February 23, 2021 11:58

Update update_versions.sh

3e19bca

Merge branch 'main' into rewrite-docs

fc1c372

Merge branch 'main' into rewrite-docs

3dc854c

add reference documentation to mysql doc

90add0a

Merge branch 'rewrite-docs' of github.com:GoogleCloudPlatform/cloud-s…

422bb4d

…ql-jdbc-socket-factory into rewrite-docs

Merge branch 'main' into rewrite-docs

c5d88d4

Merge branch 'main' into rewrite-docs

205e39d

kurtisvg approved these changes Feb 25, 2021

View reviewed changes

Merge branch 'main' into rewrite-docs

dbb06ee

shubha-rajan merged commit 453e04d into main Feb 26, 2021

shubha-rajan deleted the rewrite-docs branch February 26, 2021 07:19

shubha-rajan mentioned this pull request Feb 26, 2021

docs: Provide more information and pointers re. private IP connectivity in new Troubleshooting section in README #376

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: reorganize documentation to split driver-specific info into separate files #409

docs: reorganize documentation to split driver-specific info into separate files #409

shubha-rajan commented Feb 19, 2021 •

edited

Loading

kurtisvg Feb 19, 2021

shubha-rajan Feb 19, 2021

kurtisvg Feb 19, 2021

shubha-rajan Feb 19, 2021

kurtisvg Feb 19, 2021

shubha-rajan Feb 19, 2021

kurtisvg Feb 19, 2021

shubha-rajan Feb 19, 2021

kurtisvg Feb 19, 2021

shubha-rajan Feb 19, 2021

kurtisvg Feb 19, 2021

shubha-rajan Feb 19, 2021

kurtisvg Feb 21, 2021

kurtisvg Feb 21, 2021

shubha-rajan Feb 22, 2021

kurtisvg Feb 21, 2021

kurtisvg Feb 21, 2021

kurtisvg Feb 21, 2021

enocom left a comment

enocom Feb 23, 2021

enocom Feb 23, 2021

shubha-rajan Feb 23, 2021

enocom Feb 23, 2021

kurtisvg left a comment

kurtisvg Feb 25, 2021

	### Add library as a dependency
	### Adding the library as a dependency


		### Specifying IP Types

		"The `ipTypes` argument is used to specify a preferred order of IP types used to connect via a comma delimited list. For example, `ipTypes=PUBLIC,PRIVATE` will use the instance's Public IP if it exists, otherwise private. The value `ipTypes=PRIVATE` will force the Cloud SQL instance to connect via it's private IP. If not specified, the default used is `ipTypes=PUBLIC,PRIVATE`. For more info on connecting using a private IP address, see [Requirements for Private IP](https://cloud.google.com/sql/docs/mysql/private-ip#requirements_for_private_ip).

docs: reorganize documentation to split driver-specific info into separate files #409

docs: reorganize documentation to split driver-specific info into separate files #409

Conversation

shubha-rajan commented Feb 19, 2021 • edited Loading

Change Description

Checklist

Relevant issues:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

enocom left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kurtisvg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shubha-rajan commented Feb 19, 2021 •

edited

Loading