Skip to content

db.connect

Prints/sets general DB connection for current mapset.

db.connect [-pgcd] [driver=name] [database=name] [schema=name] [group=string] format=name [--verbose] [--quiet] [--qq] [--ui]

Example:

db.connect format=plain

grass.script.parse_command("db.connect", driver="sqlite", database="$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db", schema=None, group=None, format="plain", flags=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.parse_command("db.connect", format="json")

grass.tools.Tools.db_connect(driver="sqlite", database="$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db", schema=None, group=None, format="plain", flags=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.db_connect(format="json")

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

Parameters

driver=name
    Name of database driver
    Allowed values: dbf, odbc, ogr, pg, sqlite
    Default: sqlite
database=name
    Name of database
    Default: $GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db
schema=name
    Database schema
    Do not use this option if schemas are not supported by driver/database server
group=string
    Default group of database users to which select privilege is granted
format=name [required]
    Output format
    Allowed values: plain, shell, json
    Default: plain
    plain: Plain text output
    shell: shell script style output
    json: JSON (JavaScript Object Notation)
-p
    Print current connection parameters and exit

-g
    Print current connection parameters using shell style and exit [deprecated]
    This flag is deprecated and will be removed in a future release. Use format=shell instead.
-c
    Check connection parameters, set if uninitialized, and exit
-d
    Set from default settings and exit
    Overwrite current settings if already initialized
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

driver : str, optional
    Name of database driver
    Used as: input, dbdriver, name
    Allowed values: dbf, odbc, ogr, pg, sqlite
    Default: sqlite
database : str, optional
    Name of database
    Used as: input, dbname, name
    Default: $GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db
schema : str, optional
    Database schema
    Do not use this option if schemas are not supported by driver/database server
    Used as: name
group : str, optional
    Default group of database users to which select privilege is granted
format : str, required
    Output format
    Used as: name
    Allowed values: plain, shell, json
    plain: Plain text output
    shell: shell script style output
    json: JSON (JavaScript Object Notation)
    Default: plain
flags : str, optional
    Allowed values: p, g, c, d
    p
        Print current connection parameters and exit

    g
        Print current connection parameters using shell style and exit [deprecated]
        This flag is deprecated and will be removed in a future release. Use format=shell instead.
    c
        Check connection parameters, set if uninitialized, and exit
    d
        Set from default settings and exit
        Overwrite current settings if already initialized
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

driver : str, optional
    Name of database driver
    Used as: input, dbdriver, name
    Allowed values: dbf, odbc, ogr, pg, sqlite
    Default: sqlite
database : str, optional
    Name of database
    Used as: input, dbname, name
    Default: $GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db
schema : str, optional
    Database schema
    Do not use this option if schemas are not supported by driver/database server
    Used as: name
group : str, optional
    Default group of database users to which select privilege is granted
format : str, required
    Output format
    Used as: name
    Allowed values: plain, shell, json
    plain: Plain text output
    shell: shell script style output
    json: JSON (JavaScript Object Notation)
    Default: plain
flags : str, optional
    Allowed values: p, g, c, d
    p
        Print current connection parameters and exit

    g
        Print current connection parameters using shell style and exit [deprecated]
        This flag is deprecated and will be removed in a future release. Use format=shell instead.
    c
        Check connection parameters, set if uninitialized, and exit
    d
        Set from default settings and exit
        Overwrite current settings if already initialized
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

Returns:

result : grass.tools.support.ToolResult | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned.

Raises:

grass.tools.ToolError: When the tool ended with an error.

DESCRIPTION

db.connect allows the user to set database connection parameters. These parameters are then taken as default values by modules so that the user does not need to enter the parameters each time.

The default database backend in GRASS is SQLite (since version 7).

NOTES

Values are stored in the mapset's VAR file; the connection is not tested for validity.

The -p flag displays the current connection parameters. Use the format option to specify the output format—plain, shell, or json—with plain being the default.

The -c flag will silently check if the connection parameters have been set, and if not will set them to use GRASS's default values. (useful in scripts before you attempt to create a new database table)

The -g flag is deprecated and will be removed in a future release. Please use format=shell option with the -p flag instead.

To connect a vector map to a database table, use v.db.connect or v.db.addtable.

EXAMPLES

SQLite (default backend)

Local storage:

db.connect -d
db.connect -p
db.tables -p

The SQLite database file is created automatically when used the first time.

See SQLite database driver for details.

PostgreSQL (local connection)

Local storage, database tables stored in database "mydb" (may require the use of db.login):

db.connect driver=pg database=mydb
db.login user=myname pass=secret
db.connect -p
db.tables -p

See PostgreSQL database driver for details.

PostgreSQL (network connection)

Network storage, database tables stored in database "mydb" (may require the use of db.login):

db.connect driver=pg database=mydb
db.login user=myname pass=secret host=myserver.com port=6666
db.connect -p
db.tables -p

See PostgreSQL database driver for details.

MySQL (local connection)

Local storage, database tables stored in database "mydb" (may require the use of db.login):

db.connect driver=mysql database=mydb
db.login user=myname pass=secret
db.connect -p
db.tables -p

See MySQL database driver for details.

MySQL (network connection)

Network storage, database tables stored in database "mydb" (may require the use of db.login):

db.connect driver=mysql database=mydb
db.login user=myname pass=secret host=myserver.com
db.connect -p
db.tables -p

See MySQL database driver for details.

ODBC

Network storage, database tables stored in database "mydb" (may require the use of db.login):

db.connect driver=odbc database=mydb
db.login user=myname pass=secret
db.connect -p
db.tables -p

See ODBC database driver for details.

import grass.script as gs

data = gs.parse_command("db.connect", flags="p", format="json")
print(data)

Possible output:

{'driver': 'sqlite', 'database_template': '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db', 'database': '/grassdata/PERMANENT/sqlite/sqlite.db', 'schema': None, 'group': None}

Local storage (the dbf/ subdirectory in the mapset must exist or must be created by the user):

db.connect driver=dbf database='$GISDBASE/$LOCATION_NAME/$MAPSET/dbf/'
db.tables -p

See DBF database driver for details.

SEE ALSO

db.columns, db.copy, db.drivers, db.login, db.tables, v.db.addtable, v.db.connect

GRASS SQL interface

AUTHORS

Main author: Radim Blazek, ITC-Irst, Trento, Italy
GRASS 7 improvements: Martin Landa, Markus Metz

SOURCE CODE

Available at: db.connect source code (history)
Latest change: Friday Aug 08 09:39:19 2025 in commit ed72c71