<h2>DESCRIPTION</h2>

<em>v.db.connect</em> prints or sets database connection for a vector
map. The user can add or remove link to attribute table on the certain
layer.

<h2>NOTE</h2>

Connection information (driver, database, table, key) is stored for
each map, in the file
<div class="code"><pre>
&lt;database&gt;/&lt;project&gt;/&lt;mapset&gt;/vector/&lt;map&gt;/dbln
</pre></div>

<p>
If parameters for database connection are already set with
<a href="db.connect.html">db.connect</a>, they are taken as default values and
do not need to be specified each time.

<p>When printing database connection (<em>p</em> or <em>g</em> flag) the parameter
<em>layer</em> is ignored, i.e. <b>all</b> connections are printed to the
output.

<p><b>Attention:</b> Removing a vector map will also delete all tables
linked to it! If you use <a href="db.connect.html">v.db.connect </a>to
link further tables to your map, it is advisable to make a copy from
those tables first and connect the copied tables to the vector map
(see also <a href="v.overlay.html">v.overlay</a>).

<h2>EXAMPLE</h2>

Note: The default database backend setting is SQLite.

<h3>Print database connection</h3>

Print all database connection parameters for vector map.

<div class="code"><pre>
v.db.connect -p map=roads
</pre></div>

<p>Print column types and names of table linked to vector map.

<div class="code"><pre>
v.db.connect -c map=roads
</pre></div>

<h3>Connect vector map to database (DBF driver)</h3>

Connect vector map to DBF table without or with variables.<br>

<p>Using default DB connection:
<div class="code"><pre>
v.db.connect map=vectormap table=table
</pre></div>

<p>Using hardcoded path to DBF directory (not recommended):<br>
<div class="code"><pre>
v.db.connect map=vectormap table=table \
             database=/home/user/grassdata/spearfish60/PERMANENT/dbf
</pre></div>

<p>Using variable as DBF directory definition, single quotes must be used:<br>
<div class="code"><pre>
v.db.connect map=vectormap table=table \
             database='$GISDBASE/$LOCATION_NAME/$MAPSET/dbf/'
</pre></div>

<p>Connect vector map layer 2 and key ID to database with variables
(note: if needed, single quotes must be used for the <em>database</em>
parameter):
<div class="code"><pre>
v.db.connect map=vectormap table=table layer=2 key=ID
</pre></div>


<h3>Connect vector map to database (SQLite driver)</h3>

Very similar to DBF driver example above.

<div class="code"><pre>
db.connect driver=sqlite database='$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db'
db.tables -p
v.db.connect map=vectormap table=table driver=sqlite \
             database='$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db'
v.db.connect -p map=vectormap
</pre></div>


<h3>Connect vector map to database (MySQL driver)</h3>

<div class="code"><pre>
# note: connection which requires password
db.connect driver=mysql database="host=dbserver.foo.org,dbname=my_database"
db.login user=joshua [password=xxx]
# ... or enter password interactively.

db.tables -p

# connect external table to layer 2:
v.db.connect map=my_map table=my_mysql_table key=baz layer=2
v.db.connect -p my_map
</pre></div>

<h3>Connect vector map to database (PostgreSQL driver)</h3>

<div class="code"><pre>
# note: connection without password being asked
v.db.connect map=vectormap table=table layer=1 key=oid driver=pg \
             database="host=myserver.itc.it,dbname=mydb,user=name" \
             table=mytable key=id
</pre></div>

<h3>Store geometry in GRASS but attributes in PostgreSQL</h3>

This example illustrates a mixed data storage with possibility to
update attributes in an external PostgreSQL database:

<div class="code"><pre>
# Check current settings for attribute storage:
db.connect -p

# Import table from PostgreSQL to new map
# (NOTE: output map name needs to be different from table name in
#        case that GRASS is connected to PostgreSQL):
v.in.db driver=pg database="host=localhost,dbname=meteo" \
        table=mytable x=lon y=lat key=cat out=mytable

v.db.connect map=mytable -p

# Cancel table connection between map and attribute table:
v.db.connect map=mytable -d
v.db.connect map=mytable -p

# Drop table which was replicated due to import:
db.tables -p
echo "DROP TABLE mytable" | db.execute
db.tables -p

# reconnect map to table in PostgreSQL:
v.db.connect map=mytable driver=pg database="host=localhost,dbname=meteo" \
        table=mytable key=cat

# Now the geometry is stored in GRASS while the attributes are stored
# in PostgreSQL.
</pre></div>

An alternative is to create a "view" of only ID, x, y [,z] columns and
to use <a href="v.in.db.html">v.in.db</a> on this view, then connect the original
table to the geometry. This will be faster if the original table
is very large.

<h3>Store geometry in GRASS but attributes in PostGIS</h3>

This example illustrated a mixed data storage with possibility
top update attributes in external PostGIS database:

<div class="code"><pre>
# Check current settings for attribute storage:
db.connect -p

# Import table from PostGIS to new map
# (NOTE: output map name needs to be different from table name in
#        case that GRASS is connected to PostGIS):
v.in.db driver=pg database="host=localhost,dbname=meteo" \
        table=mytable x="x(geom)" y="y(geom)" key=cat out=mytable

v.db.connect map=mytable -p

# Cancel table connection between map and attribute table:
v.db.connect map=mytable -d
v.db.connect map=mytable -p

# Drop table which was replicated due to import:
db.tables -p
echo "DROP TABLE mytable" | db.execute
db.tables -p

# reconnect map to table in PostGIS:
v.db.connect map=mytable driver=pg database="host=localhost,dbname=meteo" \
        table=mytable key=cat

# Now the geometry is stored in GRASS while the attributes are stored
# in PostGIS.
</pre></div>

<h2>SEE ALSO</h2>

<em>
<a href="db.connect.html">db.connect</a>,
<a href="db.copy.html">db.copy</a>,
<a href="db.tables.html">db.tables</a>,
<a href="v.db.addtable.html">v.db.addtable</a>,
<a href="v.db.droptable.html">v.db.droptable</a>,
<a href="v.db.addcolumn.html">v.db.addcolumn</a>,
<a href="v.db.dropcolumn.html">v.db.dropcolumn</a>,
<a href="v.external.html">v.external</a>,
<a href="v.in.db.html">v.in.db</a>,
<a href="v.overlay.html">v.overlay</a>
</em>

<p>
<em>
<a href="sql.html">GRASS SQL interface</a>
</em>

<h2>AUTHOR</h2>

Radim Blazek, ITC-Irst, Trento, Italy