Add comprehensive JDBC Guide #3784
Conversation
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
| **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
| ====================== | ||
|
|
||
| .. 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
| // 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
|
|
||
| /** | ||
| * 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
2 participants
This introduces three sections for the JDBC documentation: