Specify pg_catalog.* in the docs for customTypeMap

[ersinakinci]

I just spent about an hour trying to figure out how to map numeric to my own custom type. In the end, I realized that I needed to write out "pg_catalog.numeric": "MyType".

The docs and a lot of the GitHub issues make it clear that I need to use the customTypesMap config option, but it wasn't clear that I need to prefix my types with pg_catalog for it to work.

The docs do use pg_catalog.tsvector and pg_catalog.bpchar as examples, but because tsvector and bpchar are somewhat exotic types, and because I didn't know what pg_catalog is, I didn't realize that the pg_catalog prefix was necessary for any type mapping. I thought maybe pg_catalog.tsvector and pg_catalog.bpchar were "special."

Also, some of the older GH issues don't use the pg_catalog table name prefix.

May I suggest putting a little blurb in the docs to clarify when pg_catalog needs to be specified and why?

[kristiandupont]

I am sorry you had to struggle with that! You are right, that should be documented -- or preferably, there should be an error message that nudges you to the right answer. I will fix this.

[ersinakinci]

All good, and thank you!

[kristiandupont]

I made a small edit to the docs, do you think this covers it? Or am I missing something confusing?

https://github.com/kristiandupont/kanel/commit/e82ec52b904655e37ae40b14fcad622afde8f288#diff-93a1945494e5a3cbbcd925b18baacd4573b5fdcfd1a9c8e1dbbfe7d1df700015L71

[ersinakinci]

I think that looks great.

If I had to guess, however, I would say that most people are like me and never get to that page in the docs. I went straight from "Getting Started" to "Data Types." I didn't even see that there's a "Configuring" page because it's bunched in there in the sidebar with links to API docs pages, making the entire group of pages look like an API reference, which makes it easy to ignore. Also, lots of people are coming directly to a page from search engines. (I've worked as a technical writer so I'm a little nitpick-y.)

Personally, I would:

• Commit the change you added (does no harm).
• Add comments to the config examples like // Prefix types with pg.catalog so it's super obvious since lots of people will just copy/paste the examples and modify them. Add them to the "Getting Started," "Data Types," and "Configuration" pages.
• Move the "Configuring" page from the "Configuration" link group to the "Intro" link group, right after "How to work with Kanel".
• Rename the "Configuration" link group to "API Reference".

[ersinakinci]

Another tip:

• In your config examples, consistently give an example of mapping a relatively exotic type (like pg_catalog.tsvector: Range) as well as something more common (like pg_catalog.int: BigInt). That will make it clear that this is a general use feature that's available for all sorts of use cases. I particularly like the example of mapping int to BigInt because it's a very commonly asked-for mapping in various ORM repos' issues and discussions pages.

[kristiandupont]

I've updated the example config. I don't think I want to rename the section because in my opinion, "API Reference" implies that it's for programmatic usage, which isn't really the case. Thank you for your inputs!