Should we drop the Pg prefix from the V3 APIs?

[simolus3]

At the moment, most types exported by the V3 API are prefixed with Pg to indicate that they belong to the postgres package. Since users can refer to them with named imports, we could also choose to drop that prefix (and rename PgDataType to just DataType, for example). Users who prefer the prefix could do import 'package:postgres/postgres.dart' as pg; and then use pg.DataType explicitly.

Personally, I have a slight preference towards the shorter form without the forced prefix: Users who want to be explicit can still chose to do that, but we're not forcing the name onto everyone.
But I've also heard from people (including people on the Dart team) who prefer the prefix. Using a prefix makes import management with auto-complete and the analysis server easier, since typing Pg shows all the relevant types. Without a prefix, there is no tool automatically adding the pg named import and it might be harder to find public types from this package.

I wanted to start this discussion to see if there are more aspects I might be overlooking. So maybe we can reach a consensus on whether the prefix should be dropped (from which there seems to be support?).

[insinfo]

it doesn't really bother me to have a prefix or not, to contribute to the discussion, after a quick search I see that most driver implementations use a prefix, although it seems a little verbose I think the prefix ends up helping, you can see in a quick look if the type refers to portgresql

https://github.com/jasync-sql/jasync-sql
https://github.com/npgsql/npgsql
https://github.com/pgjdbc/pgjdbc
https://www.postgresql.org/docs/current/libpq-exec.html#LIBPQ-EXEC-MAIN

maybe in the future we can have in dart a unified API for different drivers like python and crystal has

https://peps.python.org/pep-0249/
https://crystal-lang.org/reference/1.9/database/

[isoos]

I think removing the PostgreSQL prefix of the v2 library and using only Pg is a step forward. Whether we remove Pg and rely on library imports: I have no strong preferences there - maybe a very slight preference to remove the Pg too. On the other hand, I think that tools not auto-completing is a strong argument for keeping the Pg prefix.

For me, the important part would be to reduce the length of the commonly used types and methods - while keeping their names sane and descriptive. So maybe we should check if the v3 API has such names and if they tend to be on the longer end, we should consider dropping Pg?

[isoos]

After a lots of considerations, I think the most important part is to have a consistent class name structure. Right now messages.dart exposes classes without prefixes, while both v2 and v3 API has prefixes. Either messages need the new Pg prefix, or we should remove Pg prefix from the new classes.

Having checked a few Dart database driver's API, while reading the API I have found prefix-less class names better. It looks better on the dartdoc page to not start with the same character prefix in that side-list.

@insinfo @simolus3 @osaxma what do you think?

Should we put this to a vote? If I needed to vote, I'd put 0.6 without prefix, 0.4 with prefix. If somebody want to vote privately, please drop me an email.

[simolus3]

My preference towards names without a prefix remains :) So I'd vote 0.7 without a prefix, 0.3 with prefix.

[osaxma]

I don't have a preference here -- so I guess it's a 0.5 and 0.5.

[insinfo]

I like the prefix Pg, but it wouldn't bother me so much to do without the prefix

[isoos]

Also to consider: with prefix we have PostgreSQLException (which should be renamed to PgException), which would be fine with a prefix-less package, but I'm wondering if that is the best name in that case (e.g. ClientException and ServerException comes to mind...)

[simolus3]

If we sort-of expect users to add a qualifying import (import 'package:postgres/postgres.dart' as pg) either way, maybe we should just name it Exception? I think there's not much room for confusion here since it's a compile-time error to refer to ambiguous names. So catch (Exception e) wouldn't compile if postgres was imported without a prefix.

[insinfo]

I would prefer PgException

[isoos]

Note: I've published a prerelease version that dropped the Pg prefixes but kept it for PgException:
https://pub.dev/documentation/postgres/3.0.0-alpha.1/postgres/postgres-library.html

Closing the issue for now, let's start new discussions on specific question separately (if there is any or if I went overboard with the naming changes).