t.connect

Prints/sets general temporal GIS database connection for current mapset.

Command linePython (grass.tools)Python (grass.script)

t.connect [-pcdg] [format=name] [driver=name] [database=name] [mapset=name [,name,...]] [--verbose] [--quiet] [--qq] [--ui]

Example:

t.connect

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

Example:

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

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

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

Example:

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

Parameters

Command linePython (grass.tools)Python (grass.script)

format=name
    Output format
    Allowed values: plain, shell, json
    Default: plain
    plain: Plain text output
    shell: Shell script style output
    json: JSON (JavaScript Object Notation)
driver=name
    Name of database driver
    Allowed values: sqlite, pg
    Default: sqlite
database=name
    Name of database
    Default: $GISDBASE/$LOCATION_NAME/$MAPSET/tgis/sqlite.db
mapset=name [,name,...]
    Name of the mapset(s) to print the connection info for
    '.' for current mapset; '*' for all mapsets in the project. Requires format=json.
-p
    Print current connection parameters and exit
-c
    Check connection parameters, set if uninitialized, and exit
-d
    Set from default settings and exit
    Overwrite current settings if initialized
-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.
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

format : str, optional
    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
driver : str, optional
    Name of database driver
    Used as: input, dbdriver, name
    Allowed values: sqlite, pg
    Default: sqlite
database : str, optional
    Name of database
    Used as: input, dbname, name
    Default: $GISDBASE/$LOCATION_NAME/$MAPSET/tgis/sqlite.db
mapset : str | list[str], optional
    Name of the mapset(s) to print the connection info for
    '.' for current mapset; '*' for all mapsets in the project. Requires format=json.
    Used as: input, mapset, name
flags : str, optional
    Allowed values: p, c, d, g
    p
        Print current connection parameters and exit
    c
        Check connection parameters, set if uninitialized, and exit
    d
        Set from default settings and exit
        Overwrite current settings if initialized
    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.
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.

format : str, optional
    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
driver : str, optional
    Name of database driver
    Used as: input, dbdriver, name
    Allowed values: sqlite, pg
    Default: sqlite
database : str, optional
    Name of database
    Used as: input, dbname, name
    Default: $GISDBASE/$LOCATION_NAME/$MAPSET/tgis/sqlite.db
mapset : str | list[str], optional
    Name of the mapset(s) to print the connection info for
    '.' for current mapset; '*' for all mapsets in the project. Requires format=json.
    Used as: input, mapset, name
flags : str, optional
    Allowed values: p, c, d, g
    p
        Print current connection parameters and exit
    c
        Check connection parameters, set if uninitialized, and exit
    d
        Set from default settings and exit
        Overwrite current settings if initialized
    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.
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

DESCRIPTION

t.connect allows the user to set the temporal database connection. The default setting is that the temporal database of type sqlite3 is located in the current mapset directory.

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

format=json always returns a JSON array. By default it contains one entry per mapset on the current search path.

The optional mapset option can be used to extend or restrict the selection of mapsets to report the connection information for. Use . for the current mapset only, * for all mapsets in the project, or a comma-separated list for specific mapsets. The mapset option requires both the -p flag and format=json; the format=plain and format=shell do not support multi-mapset output.

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

The -c flag will silently check if the temporal database connection parameters have been set, and if not will set them to use GRASS's default values.

NOTES

Setting the connection with t.connect will not test the connection for validity. Hence a database connection will not be established.

The connection values are stored in the mapset's VAR file. The -d flag will set the default TGIS connection parameters. A SQLite database "tgis/sqlite.db" will be created in the current mapset directory. It will be located in the "tgis" sub-directory to not interfere with the sqlite3 database used for vector attribute storage.

In case you have tens of thousands of maps to register in the temporal database or you need concurrent read and write access in the temporal database, consider to use a PostgreSQL connection instead.

Be aware that you have to set the PostgreSQL connection explicitly in every mapset that should store temporal information in the temporal database.

PostgreSQL and SQLite databases can not be mixed in a project.

EXAMPLES

Print the current connection in different formats

Print in plain format (default):

t.connect -p

driver:sqlite
database:$GISDBASE/$LOCATION_NAME/$MAPSET/tgis/sqlite.db

Print in shell format:

t.connect -p format=shell

driver=sqlite
database=$GISDBASE/$LOCATION_NAME/$MAPSET/tgis/sqlite.db

Print as JSON (reports all mapsets on the search path as an array):

t.connect -p format=json

[
    {
        "mapset": "PERMANENT",
        "driver": "sqlite",
        "database": "$GISDBASE/$LOCATION_NAME/PERMANENT/tgis/sqlite.db"
    },
    {
        "mapset": "user1",
        "driver": "sqlite",
        "database": "$GISDBASE/$LOCATION_NAME/user1/tgis/sqlite.db"
    }
]

Restrict JSON output to the current mapset only:

t.connect -p format=json mapset=.

[
    {
        "mapset": "user1",
        "driver": "sqlite",
        "database": "$GISDBASE/$LOCATION_NAME/user1/tgis/sqlite.db"
    }
]

Print connection for a subset of mapsets

Restrict JSON output to specific mapsets:

t.connect -p format=json mapset=PERMANENT,user1

[
    {
        "mapset": "PERMANENT",
        "driver": "sqlite",
        "database": "$GISDBASE/$LOCATION_NAME/PERMANENT/tgis/sqlite.db"
    },
    {
        "mapset": "user1",
        "driver": "sqlite",
        "database": "$GISDBASE/$LOCATION_NAME/user1/tgis/sqlite.db"
    }
]

Use mapset=* to include all mapsets in the project, not just those on the search path:

t.connect -p format=json mapset=*

SQLite

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

# use single quotes here
t.connect driver=sqlite database='$GISDBASE/$LOCATION_NAME/PERMANENT/tgis/sqlite.db'
t.connect -p
t.info -s

PostgreSQL

When using a PostgreSQL database, the user will need to specify the TGIS database connection for each mapset.

t.connect driver=pg database="dbname=grass_test user=soeren password=abcdefgh"
t.connect -p
t.info -s

AUTHOR

Soeren Gebbert, Thünen Institute of Climate-Smart Agriculture

SOURCE CODE

Available at: t.connect source code (history)
Latest change: Thursday Jun 25 06:52:12 2026 in commit 4846566