Documentation

[colinbull]

Documentation needs creating /improving.

The documentation needs to really exist at two levels.

1) The general provider needs documenting. this is things like

• Resolution Paths
• Individuals
• Custom query operators like IN (|=|) and Nullable ones

2) Document the specific providers. There are some gotachs around referencing dll's and features that are available, with regards to Stored procedures and Functions

[pezipink]

I will add to 1) here.

People get confused because they reference the official SQL provider's documentation and then wonder why a bunch of the LINQ comp. expression keywords do not work, or work in slightly different ways. We should be clear somewhere that the two providers are not the same, and document with examples the query keywords that are usable and how / where to use them.

CRUD operations and the data context tracking mechanics / controls are not documented at all except on my blog

We don't mention anywhere that this is an erasing type provider (or should I say, a clear distinction is not drawn that we are not generating code)

Another thing we do not make clear is that you must use query { } expressions. It doesn't say you should anywhere, and I have seen several people using Seq. functions (because IQueryable is a sequence) which of course means the TP cannot generate sensible queries, it just selects everything and does stuff client side .

[jwood803]

Looks like using stored procs could use some love, as well?

[pezipink]

Yep sprocs are not documented at all either!

Presently all we really have is my blog, and then in docs/ it is basically the mini-intro page, the "core documentation" which is just a short tutorial on some of the main functionality, and Colin's 3 liner on Oracle.

I think we really need to have a clear notion of "tutorials / howtos / common usage" and "reference".

Up for suggestions of any kind! :)

[colinbull]

Definately, I'm to blame for this did the work but missed the docs. :) only half a job really.

-----Original Message----- From: "Jon" notifications@github.com Sent: ‎29/‎01/‎2015 16:09 To: "fsprojects/SQLProvider" SQLProvider@noreply.github.com Cc: "Colin" colinbul@googlemail.com Subject: Re: [SQLProvider] Documentation (#112)

Looks like using stored procs could use some love, as well? — Reply to this email directly or view it on GitHub.=

[pezipink]

hahaha the core is mostly mine though and I didn't do much either!

Also note we have Sprocs, Functions and other strange Oracle things these days.

It would be great to tie up some loose ends, gets docs sorted than actually release a V1 !

[jwood803]

Well, if there's one place I can definitely help out on it's documentation. :]

I was thinking of doing something similar to how FAKE has their documentation. Thoughts?

[pezipink]

Yes that would be ace. We already have the scaffolding in http://fsprojects.github.io/SQLProvider/index.html this is generated from the stuff in /docs/ and pushed to gh-pages (in case you did not see this)

[jwood803]

That's how I noticed that stored procs weren't there. :]

Just to be sure, this is all in the gh-pages branch, correct? Feel like I'm still not up to speed with all of that.

[pezipink]

Longer term it would be good to have a section on how to extend the sql provider to support your not-currently-supported ADO.NET source, but let's not worry about that yet :)

[pezipink]

the code gets auto-generated and pushed to gh-pages from here https://github.com/fsprojects/SQLProvider/tree/master/docs

[jwood803]

Ahhh, I see. Thanks for the explanation! I should be able to spend some time throughout the weekend to mess with it.

[pezipink]

Great! Let us know if you need help of any kind. Skype is pezi_pink_42 if you are into that.

Thanks for having a look :)

[jwood803]

Anytime! Glad I can be able to help!

[Thorium]

Question about best practices: If you have e.g. OWIN web-server... What is actually creating and holding the connection / transactions? Can I have one static let ctx = MyProvider.GetDataContext() and use the same ctx everywhere, or should I call this again in every http-post?

[pezipink]

The connection itself is not stored and reused, it creates one when you execute a query or when you call SubmitUpdates(). In terms of transactions, the data context object tracks (full) entities that were retrieved using it via queries or Individuals, and manages their states. Upon calling SubmitUpdates(), all entities modified/created that belong to that data context are wrapped in a single transaction scope, and then a connection is created and thus enlisted into the transaction. There is actually a bug here which causes the transaction to not work in some cases for some bizarre reason, must look at that soon.

To answer your question more directly, you should create and use one data context unless you need to pass different connection strings to connect to different instances of the same database, eg to copy data between them.

[Thorium]

Ok, thanks!

[Thorium]

So... If I create a single context: Now, if I use CRUD methods .Create() with some seq<string*obj> that won't correspond to the database structure, SQL will throw some exception. That is ok. But what is not so nice is that after this exception the invalid item is still stored to the context and I should either restart the web-server or do some try ... with dbContext.ClearUpdates () everywhere.

[pezipink]

I think a simple solution to this is to add an overload to ClearUpdates that accepts the SqlEntity instance and removes it from the context. Having the "bad" object left in there is by design as especially in the context of FSI, it lets you set some more fields on the object in order to fix it, and then attempt to call SubmitUpdates again.

I thought there was an overload that removes a single entity, but apprently not!

I guess as another option we could also control this type of behaviour with a static param or an overload when creating the data context.

[Thorium]

Ok, thanks, this is kind of off-topic but:

    type TypeProviderConnection = SqlDataProvider<...>

    type TypeProviderConnection.dataContext with
      /// SubmitUpdates() but on error ClearUpdates()
      member x.SubmitUpdates2() = 
        try x.SubmitUpdates()
        with
        | e -> x.ClearUpdates() |> ignore
               reraise()