Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.
Back to main Wiki page
The GUI as a PostgreSQL clientStarting from version 2.1.0 the GUI has the capability to support connections to external PostgreSQL / PostGIS databases.
This functionality is mainly based on libvirtualpg, that is now a required dependency for the GUI tool. The present tutorial is intended to quickly explain how the PostgreSQL support is implemented by spatialite_gui.
1 - Establishing a Connecting to a PostgreSQL DBMS
|1.a first press the appropriate button from the Toolbar|
|1.b then select the appropriate item from the main Menu|
|1.c and finally select the appropriate item from the context Menu that will appear by clicking the left button of the mouse over the PostreSQL main node from the Table Tree.|
|1.d in all three cases the PostgreSQL connection dialog will appear.
Just insert the required connection arguments and confirm.
When invalid arguments are given, an error message will be then displayed, otherwise the connection will be immediately established.
If you are attempting to connect a remote server, you may find it useful to first reading the tutorial about SSH tunneling and Port Forwarding
2 - Expanding the PostgreSQL tree
|2.a once that a new Postgres connection has been successfully established the Postgres node on the main Table Tree will contain all Tables and Views defined on the Postgres Database, accordingly to the usual arrangement adopted by Postgres:
Each kind of database object will be clearly identified by an appropriate icon; Views will be distinguished from Tables, and PostGIS Tables (containing Geometry columns) will be clearly distinguished from ordinary Tables.
Notice: all Postgres Tables and Views (namely: VirtualPostgres Tables) will always have a conventional name starting with a vpg_ prefix.
Whenever possible the original Postgres Name will be preserved, otherwise it will be disambiguated by adding an appropriate numeric suffix.
Note: all database objects in the Postgres Tree are inherently transient, and will automatically disappear when the corresponding connection will be closed, or when the current session ends.
|2.b if, for any possible reason (system crash, power failure and alike), the current session will fail to correctly perform the expected final cleanup, your SQLite database will remain in a dirty and inconsistent state.
As the side figure shows, when restarting a new session many orphan VirtualPostgres tables will badly remain from the last aborted session.
If this is your case, don't despair: you just have to select the appropriate item from the Postgres context menu and the DB will be immediately recovered in a safe consistent and clean state.
3 - Metadata of PostgreSQL objects
|3.a you can easily query the metadata for each Postgres object; just select the appropriate item from the context menu.|
|3.b Metadata for a Connection aka Database object will report the initial connection arguments.
Note: you can eventually connect more than a single Postgres Database in the same session: connecting twice the same Database is always forbidden.
|3.c Metadata for a Schema object aren't really interesting, because just the name is reported.|
|3.d Metadata for Table or View objects will report all GRANT permissions for the current User.
Note: also in the case of a READ-WRITE enabled connection, all Postgres Tables lacking the permission to execute INSERT, UPDATE or DELETE statements will be always considered to be READ-ONLY.
Exactly as any other Table not supported by a PRIMARY KEY definition.
|3.e Metadata for a PostGIS Table objects will report a full qualification of the GEOMETRY column(s), this including the GeometryType, the Srid and the CoordinateDimensions.|
|3.f all PostGIS Tables will always have a companion Table sharing the same identical name except that for a final _postgis suffix.
Note: these are not VirtualPostgres Tables; they are instead Spatialite's own Spatial Views, and their intended scope is to perform a silent and fully transparent conversion of binary Geometries back and forth from one format to the other in the most user friendly way.
4 - Handling PostgreSQL Tables and Views
|4.a PostgreSQL Tables and Views are considered, as far as possible, as if they were native SQLite objects.
So the usual operations supported on SQLite's own objects will be supported also in the case of PostgreSQL objects.
|4.b the above criteria will apply also to PostGIS Geometries.
Hint: exporting a full Shapefile from a PostGIS Geometry was never more direct and simple than this.
|4.c be warned; directly querying a PostGIS Table (i.e. a VirtualPostgres Table containing PostGIS Geometries) never is a good idea. You'll be always asked twice before starting such a stupid (and potentially dangerous) action.|
|4.d the reason for such a behaviour is clearly shown in the side figure.
A VirtualPostgres Table will expose all Geometries as EWKB text strings using an hexadecimal notation; in this case we have simple POINTS, and the EWKB strings are reasonably compact.
But unhappily complex LINESTRING or POLYGON Geometries may easily require several million characters, and this will easily over stress the GUI.
The execution speed of such a query will certainly be very sluggish, and some instability trouble could eventually arise.
Short conclusion: never ever attempt to directly query a PostGIS Table !
|4.e a companion Spatial View is always defined for every PostGIS Table, and is specifically intended to support safe and trouble free queries.
That's not only: the companion Spatial View will take care to silently convert binary Geometries to and from the usual SpatiaLite's own format, thus greatly simplifying the eventual writing of customized SQL queries using Spatial Functions.
|4.f the companion Spatial View will always be a Writable View if the corresponding PostGIS Table is appropriately enabled and if the connection supports READ-WRITE operations.
Note: appropriate Triggers will be automatically defined so to let the Spatial View to become a Writable View fully supporting INSERT, UPDATE and DELETE operations.
Addendum: special note for Windows users
All previous versions of the GUI binaries released in the past were always based on a single monolithic .exe fully depending on static linkage and not requiring any DLL at all.|
Unhappily this is no longer possible, because libpq (the PostgreSQL own client library) is uniquely available as a DLL on Windows, and there is absolutely no way to build a corresponding static library.
More precisely: a static library is actually built when compiling PostgreSQL, but on Windows it simply is a stub still requiring to load the DLL at run time.
All this considered, now spatialite_gui.exe is kind of an hybrid; it mostly depends on static linkage, except than for libpq.dll.
So a reasonable compromise has been adopted in order to mitigate the negative impact of such an odd layout:
How it practically works</h3
|A.1 when required to access PostgreSQL for the first time, the GUI will actually attempt to load libpq.dll:
|A.2 now you can use the standard File Selection dialog in order to locate and open libpq.dll.
Warning: a very common pitfall is attempting to load a 32 bit DLL on a 64 bit GUI, or the opposite.
The code model of both the executable and the DLL must necessarily match.
|A.3 if libpq.dll has been successfully loaded a confirmation message will be shown.
The association between the GUI and the DLL will be permanently registered, so to allow for an automatic loading in all the following sessions.
Back to main Wiki page