[jira] Commented: (DERBY-4525) Document the in-memory storage back end

["Kristian Waagan (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/DERBY-4525?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12858892#action_12858892 ] 

Kristian Waagan commented on DERBY-4525:
----------------------------------------

Hi Kim,

Thanks for writing these docs. I think they look good, and they can be committed
as they are if that is required to get them included in 10.6.
I have made some comments and suggestions below. Please use you own 
judgment regarding whether they are worth implementing or not.

* src/devguide/cdevdvlp19700.dita
Should we add a few words to clearify that you can use the in-memory back end in
other cases than testing and devlopment, for instance when you are processing
transient/reproducible data?
If you have the required memory avaialble, the benefits are (or may be) faster
processing (no disk IO) and simplicity when it comes to discarding the data.  If
changed, revisit cdevdvlpinmemdb.html.

* src/devguide/cdevdvlp40724.dita
Should we mention that for some of the limits the maximum value is determined by
the available main memory instead of disk space / file system, or is this too
obvious to mention?

* src/devguide/cdevdvlpinmemdb.dita
Removing an in-memory database: Does it make sense to swap the order of the
current content, i.e. to describe how you would actively remove an in-memory db
in a running JVM first?
To me, the fact that in-memory databases are lost when the JVM exits is more
like a side-effect. We do need to mention this, but maybe more like a word of
caution to make it clear to users that in-memory databases are not persisted.

Mention that if authentication and SQL authorization is enabled, only the
database owner can drop a database. I'm not sure if we have done this for other
actions, like shutting down the database.

* src/devguide/rdevdvlp22102.dita
Add a link to a page describing, or just a note, that using the in-memory back
end with the client driver requires a "special" URL (include the subsubprotocol
as part of the name)?

* src/ref/rrefattrib16471.dita, src/ref/rrefattrib26867.dita
Use the same database name for embedded and client/server for consistency in the
examples? (currently 'myInMemDB' and 'MyInMemDB')

* src/ref/rrefattrib17246.dita
In the example:
  "+<codeblock><b>jdbc:derby:toursDB;databaseName=flightsDB</b></codeblock>" - specifies two database names

* src/ref/rrefattribdrop.dita
"This attribute, like shutdown=true, cannot be combined with other attributes." - with the exception of user credentials?
Mention that using the drop attribute with other back ends results in an
exception with SQLState XBM0I to be thrown?

* src/tools/rtoolsijcomref22318.dita and src/tools/rtoolsijcomref27997.dita
Would it make sense to show that you can set the memory subsubprotocol as part
of the protocol to create in-memory databases by default in ij?
I.e:
  ij> protocol 'jdbc:derby:memory:';
  ij> connect 'testDB;create=true';

* src/tuning/ctunperfinmemdb.dita
I would maybe change the wording a bit for the page cache size. There is nothing
wrong with running with a smaller than default page cache, but the user may see
poor performance. You don't get the penalty for going to the disk to fetch
pages, but if the pressure on the page cache gets too high you will get a lot of
contention and increased CPU usage. To me, the current wording suggests that I
should increase the page cache size when using the in-memory db. In many cases
this is not necessary.
Can we say that we don't recommend to run with a smaller than default page
cache? (keep the sentence about data passing through the cache)



Finally, should we mention that users can use the backup routines to persist an
in-memory database? This backup can then be booted as an in-memory database
again at a later time, or simply be used as a normal disk based db.  Or does
suggesting this use case make some people uncomfortable?


Thanks,

> Document the in-memory storage back end
> ---------------------------------------
>
>                 Key: DERBY-4525
>                 URL: https://issues.apache.org/jira/browse/DERBY-4525
>             Project: Derby
>          Issue Type: Task
>          Components: Documentation
>    Affects Versions: 10.6.0.0
>            Reporter: Kristian Waagan
>            Assignee: Kim Haase
>             Fix For: 10.6.0.0
>
>         Attachments: DERBY-4525-2.diff, DERBY-4525-2.stat, DERBY-4525-2.zip, DERBY-4525.diff, DERBY-4525.stat, DERBY-4525.zip
>
>
> The in-memory back end isn't considered experimental anymore, we have to 
> write user documentation for the feature(s).
> I'm not  sure how it should be structured, and where the content should be added.
> Just as a rough cut, here are a few possible topics (I'm not sure if all should be included or not):
> - documenting the new protocol name ('memory')
> - documenting the new 'drop' JDBC connection URL attribute
> - describing the limitations of the feature (all your data will be lost if..., how to use it with the client driver and the data sources)
> - "advanced use" (pull dbs on disk into memory, backup in-memory dbs to disk)
> - tuning tips (there are some issues with extreme page cache sizes, maybe the existing content on page size is valid)
> - known problems (nothing concrete here yet, but we have one inquiry about disappearing databases - the current theory is that different class loaders are used)
> Some more information is available at http://wiki.apache.org/db-derby/InMemoryBackEndPrimer

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.