Documentation to support non-DotNet users

[littlefyr]

Is your feature request related to a problem? Please describe.

Several years ago I used roundhouse for a project at a different company. Now I have an opportunity to use grate at my new company and I'm running into roadblocks.

Back then it was "easy" because I could mostly copy the connection strings from my app and things would just work. Now I'm working in NodeJS and my connection strings have a different structure and figuring out the right syntax is a bit a of problem. For example, I built a demo to show off grate and I spent most of my time trying to figure out how to write the connection string so it would work in docker compose with pgsql. I had to run down the different packages I thought you were using, and then eventually guessed right after looking at the tests (yes I should have started there). All in all, it was a pain.

Describe the solution you'd like
It would be helpful if the documentation contained clear instructions on the connection strings for the various supported databases (minimally links to the definitive docs). It would also be very helpful if the docker examples were extended to include each of the supported databases (or just the ones I use) especially if instead of using a single env var for the connection strings, you all the variables bits (host, ports, admindb ...) were put into individual env vars. This would go a long way to letting people who like the simplicity of grate, but don't want to deep dive into C# and .Net just yet.

[erikbra]

Hi, @littlefyr - sorry to hear that you had trouble sorting out the connection strings.

I'm a bit puzzled by this, as my main motivation to skip supporting splitting the connection strings into many pieces (like host, port, username, password, etc) was that the number of possible configuration parameters in the connection strings are getting larger and larger, and different databases support different parameters (e.g. integrated active directory authentication, service principal authentication, etc). So, the thought was that keeping it simple, and only providing the connection string parameter would keep the flexibility without adding the complexity of N parameters, one per possible part of the connection string that is possible to configure for the particular database.

To help me understand, could you please elaborate a bit on what was difficult to figure out? I'm not a seasoned postgresql user, so there might be details that I don't know of. I usually just go to https://www.connectionstrings.com/ and type in my database provider to find out how to configure stuff when working with a new database.

That said, of course we should document this better :)

Do you have some suggestions on what information would be good to have on a wiki page describing this, based on what you struggled with?

Would the information you were missing fit in here somewhere? https://github.com/erikbra/grate/blob/main/docs/ConfigurationOptions/index.md

[littlefyr]

The biggest problem is that connectionstrings.com (I started there too) gave me an answer that just didn't work. IIRC, you're using npgsql but it doesn't matter, all the examples say the same thing: https://www.connectionstrings.com/postgresql/

Server=127.0.0.1;Port=5432;Database=myDataBase;User Id=myUsername;Password=myPassword;

or some minor variation thereof. It just doesn't work. It wasn't until I gave up trying all the variations (I got some misleading error messages ... the db type was ignored and assume to be sqlserver, which I now guess was a BAD syntax error in the cnx string) and went and looked at your testing code that I figured it out. Host instead of Server.

As for breaking it out, I don't mean having grate take in multiple values. I mean having env vars in the dockerfile for all the necessary parts and composing the connection string in the ENTRYPOINT. In my case, I wanted to do a few things. One make the dockerfile work for both local dev and two allow it to be published an used in our CICD. I also needed to set the admin string explicitly since we never use the default db in our systems and I hate duplication.

That's just me. Personally, I think putting each of the parts as an env var in the dockerfile serves as good documentation for how the connection string is composed. If there was just a