Add comprehensive JDBC Guide #3784
Conversation
The examples module contains documentation code snippets that are meant to be extracted and shown to users. These snippets intentionally: - Use System.out.println to demonstrate output - Trigger false positive resource leak warnings from SpotBugs This commit disables PMD, SpotBugs, and Checkstyle for the examples module. Also fixed unused import in ComplexTypesEmbedded.java.
alecgrieser left a comment
alecgrieser left a comment There was a problem hiding this comment.
Looks like a good start! Just a few minor things, and there's a PRB failure from some indentation issues
docs/sphinx/source/jdbc/advanced.rst Outdated
| **Driver-Specific Classes**: When creating STRUCT and ARRAY values, use the appropriate builder for your JDBC driver: | ||
| | ||
| - **Embedded Driver**: ``EmbeddedRelationalStruct`` and ``EmbeddedRelationalArray`` (from ``com.apple.foundationdb.relational.api``) | ||
| - **Server Driver**: ``JDBCRelationalStruct`` and ``JDBCRelationalArray`` (from ``com.apple.foundationdb.relational.jdbc``) |
There was a problem hiding this comment.
Is this true? Do we not have an API that works for both the embedded and server use cases? I would have expected that there'd be something like a RelationalStruct object that the user could create (in the API package) and then something could translate that to the appropriate one.
It almost seems like this is a deficiency in our API that is worth addressing before we try and document it too much, including the infrastructure to have parallel documentation for the different paths, but maybe that ship has sailed
There was a problem hiding this comment.
We do have a common interface which is RelationalStruct and RelationalArray, and respective builders for the EmbeddedDriver and the ServerDriver. I'll adjust the documentation. Beyond the creation of the builder, everything else is the same.
There was a problem hiding this comment.
I agree that we probably would want to build something more generic in the future so that we push down the conversion at the lower level.
| ====================== | ||
| | ||
| .. important:: | ||
| **Transition API**: The Key-Based Data Access API is provided primarily to ease migration from key-value based operations to SQL-based queries. While it remains supported, it is **not the recommended approach for new applications**. For most use cases, SQL queries provide better flexibility, optimization, and maintainability. This API may evolve or be deprecated in future versions as the SQL interface matures. |
There was a problem hiding this comment.
I'm not sure "key-value" is quite right here. Potentially, it would be fairer to say that this is made to ease the transition for users of the FDBRecordStore API
There was a problem hiding this comment.
Changed to FDBRecordStore API
| // end::unwrap-statement[] | ||
| } | ||
| | ||
| public static void scanBasic() throws SQLException { |
There was a problem hiding this comment.
Maybe I'm missing it, but I don't know if I see what's different between this and DirectAccessSnippets::scanBasic. I believe the only operations that are actually different are the ones that do inserts, so it may be nice to remove all of the ones that are the same
There was a problem hiding this comment.
Good point, removed 👍
| | ||
| /** | ||
| * Code snippets for JDBC Guide basic documentation. | ||
| * This class is not meant to be run, but contains tagged sections referenced by the documentation. |
There was a problem hiding this comment.
It would kind of be nice if these could be run, and then we could assert they did what we thought they should, instead of just compiling, but having them compile is probably a good enough start
There was a problem hiding this comment.
True, I'll introduce a follow-up commit (or PR) to address this.
2 participants
This introduces three sections for the JDBC documentation: