Export orchid-orm/pqb

[IlyaSemenov]

Following #697, I think that this kind of problems (a need for pqb internal types for those who are using orchid-orm) will appear again and again.

As I see it, we should target these goals:

1. Avoid polluting orchid-orm with everything that pqb exports.
2. Ensure user apps depend on either pqb or orchid-orm, but not on both, since orchid-orm depends on a very specific version of pqb, and having both dependencies in a project is a footgun that will lead to version mismatches.

I think the better approach to this would be:

• pqb exports everything, like before;
• pqb/internal is removed;
• orchid-orm re-exports the curated set of "public" types and functions from pqb (i.e. what pqb currently exports);
• orchid-orm/pqb (or orchid-orm/query-builder) re-exports the entire pqb.

[romeerez]

Well the 2nd is the reason for the 1st, and conceptually you can think that orchid-orm is the all-mighty ORM while, as a user, you don't have to know anything about pqb, can treat is as an internal detail. Do not install pqb - that's an internal dependency of orchid-orm.

public vs private was needed for me to feel free to change internal types and functions without worrying of breaking public contracts.

If we export everything from pqb via orchid-orm/pqb it's effectively the same as it was before when no private/public was in place: you can depend on some internal type, then I may change it and break the implicit contract.

So I don't think having orchid-orm/pqb is any better than just re-exporting everything from pqb as it was before.

I know it's frustrating when you want to use just a little thing from a library, but it's private and you have to either look for a workaround, or copy-paste internals to your code and it can break on the next release. So, of course, privates have this downside.

And for now I think the current way is okay enough: you're raising an issue or a PR to expose some functionality, it takes a few days for me to process that and publish, and it's in place. Compared to: you could use any internals and I could change them without realizing I'm breaking your app.

[IlyaSemenov]

If we export everything from pqb via orchid-orm/pqb it's effectively the same as it was before

How so?

How it was before, orchid-orm blindly re-exported everything from pqb, even things that don't constitute its public contract. Reducing the export surface was a right move. The namespace was polluted with names that are not directly related to the ORM, and there even was a risk of naming clash: both pqb and orchid-orm could be exporting a type with the same name but different contract (imaginary example: Db could have been a low-level database API in pqb and higher-level ORM abstraction in orchid-orm).

With orchid-orm/query-builder, these would be two isolated namespaces:

• orchid-orm exports the simpler publicly documented ORM API;
• for custom overrides and internal types, it honestly says that it's based on the specific version of the lower-level query builder, which is also available to consume.

For example, with Nuxt, most of the time I don't need import anything from vue. But for lower-level exports, such as MultiWatchSources, I can still consume them directly, without having to manage a compatible vue version. No one is hiding that there is a lower-level library and higher-level framework built on top of it.

Now, I will just install pqb as a direct project dependency and make sure it syncs on updates. Suffering for no reason, as it seems to me.

[romeerez]

I see your point, that orchid-orm/pqb would separate pqb concerns from ORM's concerns.

But for me it's the same because I don't mind having their concerns mixed, but wanted to protect pqb's details from leaking, and orchid-orm/pqb doesn't solve that.