Documentation of some interfaces and some important concepts

[Allam76]

First of all, great appreciation for a very good project!

I'm writing a custom storage engine and missing quite a bit of useful documentation.

Some interfaces are not documented in the readme at all, such as Statistics.

Also some important concepts such as row iterator and partitions could be helpful to document. For instance, why partitions and why partition rows? Why so many row iterators. Most database tools have a result set concept, here I see some variation from what I usually see, such as lack of boolean return on rowIter.Next. Instead one should use error io.EOF.

A real pain point is that since I don't understand the result set iterator design perfectly, I have working tests but a wire protocol that refuses to accept the data. That glue between result set and client tools is something that is worth an extra comment in the docs. If you can point to a test that cover this point, it would make my day:-)

[Rock-Lee-520]

First of all, great appreciation for a very good project!

I'm writing a custom storage engine and missing quite a bit of useful documentation.

Some interfaces are not documented in the readme at all, such as Statistics.

Also some important concepts such as row iterator and partitions could be helpful to document. For instance, why partitions and why partition rows? Why so many row iterators. Most database tools have a result set concept, here I see some variation from what I usually see, such as lack of boolean return on rowIter.Next. Instead one should use error io.EOF.

A real pain point is that since I don't understand the result set iterator design perfectly, I have working tests but a wire protocol that refuses to accept the data. That glue between result set and client tools is something that is worth an extra comment in the docs. If you can point to a test that cover this point, it would make my day:-)

Could you tell me what your storage engine is? because i also am writing a custom storage engine ,it use sqlite driver.

[Allam76]

I'm doing postgres, sql over http and excel. So far only the read parts. RIght now I'm fighting with unusual go syntax for the postgres driver. I'm not exactly a go ninja.

Only advice is to copy the memory reference implementation first and backtrack. The tests have only been made with this memory storage and the tool is very, very sensitive to any deviations from how that implementation is supposed to work. So run tests like mad between yours and the memory one to figure out which concepts must be followed and which not.

At first I started with an empty implementation, java style, that did not end well. Hence the need for this issue.

Note that other database drivers have a similar problem. I wrote a few jdbc/odbc ones and ran into roughly the same issues.

[zachmu]

Thanks for the feedback, @Allam76 . Getting this right is an ongoing project, but we'll try to do a bit better on this.