====== TerraLib Developer's Guid - Data Access → Drivers → PostGIS ======

The **PostGIS native data access driver** allows applications to access data stored in a [[http://www.postgresql.org|PostgreSQL]] system with the the geo-spatial extension [[http://postgis.refractions.net/|PostGIS]] enabled.

This section describes the design and implementation issues of this driver and how it can be used by applications.

===== Design =====
===== Creating a PostgreSQL Database =====

The PostGIS driver allows applications to create new PostgreSQL databases or drop an existing one.

In order to **create a new database** you must specify the connection parameters to an auxiliary database. This database will be used to stablish a temporary connection. All the connection info in the previous section can be used. Besides that information you must specify some parameters for the creation of the new database:
  * **PG_NEWDB_NAME:** the name of the new database. (Mandatory)
  * **PG_NEWDB_TEMPLATE:** the name of the template database to be used during the creation of the new one. (Mandatory)
  * **PG_NEWDB_OWNER:** the owner of the new database. (Optional parameter)
  * **PG_NEWDB_ENCODING:** the database encoding. (Optional parameter)
  * **PG_NEWDB_TABLESPACE:** the name of the tablespace that will be associated with the new database. (Optional parameter)
  * **PG_NEWDB_CONN_LIMIT:** how many concurrent connections can be made to this database. As default in PostgreSQL -1 means no limit. (Optional parameter)

If you intend to connect to the database after its creation with different parameters from the auxiliary database, you must specify new parameters with the prefix: ''PG_NEWDB_''. For instance, if you want a different user to be used in the new data source, you can specify: ''PG_NEWDB_USER'' = ''different-user-name''. All parameters showned in the [[:wiki:documentation:devguide:dataaccess:drivers:postgis#connection_parameters|Connection Parameters section]] can be prefixed.

The code snippet below shows how to create a new POSTGIS database:
<code cpp>
std::map<std::string, std::string> connInfo;

// auxiliary database connection parameters
connInfo["PG_HOST"] = "localhost";
connInfo["PG_USER"] = "postgres";
connInfo["PG_PASSWORD"] = "secret";
connInfo["PG_DB_NAME"] = "postgres";

// new database parameters
connInfo["PG_NEWDB_NAME"] = "terralib";
connInfo["PG_NEWDB_TEMPLATE"] = "template1";
 
// create new database
std::unique_ptr<te::da::DataSource> pgis(te::da::DataSource::create("POSTGIS", connInfo));

// the new datasource will in a close state
pgis->open();

// ...
</code>

===== Dropping a PostgreSQL Database =====

To **drop a database** you must specify the connection parameters to an auxiliary database. This database will be used to stablish a temporary connection. All the connection info in the previous section can be used. Besides that information you must specify:
  * **PG_DB_TO_DROP:** the name of the database to be dropped. (Mandatory)

The code snippet below shows how to drop an existing PostgreSQL database:
<code cpp>
</code>

===== Connecting to a PostgreSQL Database =====