---
name: t.connect
description: "Prints/sets general temporal GIS database connection for current mapset."
keywords: [ temporal, settings, metadata ]
---

# t.connect

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

=== "Command line"

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

    Example:

    ```sh
    t.connect
    ```

=== "Python (grass.tools)"

    *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:

    ```python
    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.

=== "Python (grass.script)"

    *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:

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

## Parameters

=== "Command line"

    **format**=*name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Output format  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *plain, shell, json*  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *plain*  
    &nbsp;&nbsp;&nbsp;&nbsp;**plain**: Plain text output  
    &nbsp;&nbsp;&nbsp;&nbsp;**shell**: Shell script style output  
    &nbsp;&nbsp;&nbsp;&nbsp;**json**: JSON (JavaScript Object Notation)  
    **driver**=*name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of database driver  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *sqlite, pg*  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *sqlite*  
    **database**=*name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of database  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *$GISDBASE/$LOCATION_NAME/$MAPSET/tgis/sqlite.db*  
    **mapset**=*name* [,*name*,...]  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of the mapset(s) to print the connection info for  
    &nbsp;&nbsp;&nbsp;&nbsp;'.' for current mapset; '\*' for all mapsets in the project. Requires format=json.  
    **-p**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print current connection parameters and exit  
    **-c**  
    &nbsp;&nbsp;&nbsp;&nbsp;Check connection parameters, set if uninitialized, and exit  
    **-d**  
    &nbsp;&nbsp;&nbsp;&nbsp;Set from default settings and exit  
    &nbsp;&nbsp;&nbsp;&nbsp;Overwrite current settings if initialized  
    **-g**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print current connection parameters using shell style and exit [deprecated]  
    &nbsp;&nbsp;&nbsp;&nbsp;This flag is deprecated and will be removed in a future release. Use format=shell instead.  
    **--help**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print usage summary  
    **--verbose**  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    **--quiet**  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    **--qq**  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    **--ui**  
    &nbsp;&nbsp;&nbsp;&nbsp;Force launching GUI dialog

=== "Python (grass.tools)"

    **format** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Output format  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *plain, shell, json*  
    &nbsp;&nbsp;&nbsp;&nbsp;**plain**: Plain text output  
    &nbsp;&nbsp;&nbsp;&nbsp;**shell**: Shell script style output  
    &nbsp;&nbsp;&nbsp;&nbsp;**json**: JSON (JavaScript Object Notation)  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *plain*  
    **driver** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of database driver  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, dbdriver, *name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *sqlite, pg*  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *sqlite*  
    **database** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of database  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, dbname, *name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *$GISDBASE/$LOCATION_NAME/$MAPSET/tgis/sqlite.db*  
    **mapset** : str | list[str], *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of the mapset(s) to print the connection info for  
    &nbsp;&nbsp;&nbsp;&nbsp;'.' for current mapset; '\*' for all mapsets in the project. Requires format=json.  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, mapset, *name*  
    **flags** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *p*, *c*, *d*, *g*  
    &nbsp;&nbsp;&nbsp;&nbsp;**p**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print current connection parameters and exit  
    &nbsp;&nbsp;&nbsp;&nbsp;**c**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Check connection parameters, set if uninitialized, and exit  
    &nbsp;&nbsp;&nbsp;&nbsp;**d**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Set from default settings and exit  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Overwrite current settings if initialized  
    &nbsp;&nbsp;&nbsp;&nbsp;**g**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print current connection parameters using shell style and exit [deprecated]  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;This flag is deprecated and will be removed in a future release. Use format=shell instead.  
    **verbose** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **quiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **superquiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;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.

=== "Python (grass.script)"

    **format** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Output format  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *plain, shell, json*  
    &nbsp;&nbsp;&nbsp;&nbsp;**plain**: Plain text output  
    &nbsp;&nbsp;&nbsp;&nbsp;**shell**: Shell script style output  
    &nbsp;&nbsp;&nbsp;&nbsp;**json**: JSON (JavaScript Object Notation)  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *plain*  
    **driver** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of database driver  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, dbdriver, *name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *sqlite, pg*  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *sqlite*  
    **database** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of database  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, dbname, *name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *$GISDBASE/$LOCATION_NAME/$MAPSET/tgis/sqlite.db*  
    **mapset** : str | list[str], *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of the mapset(s) to print the connection info for  
    &nbsp;&nbsp;&nbsp;&nbsp;'.' for current mapset; '\*' for all mapsets in the project. Requires format=json.  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, mapset, *name*  
    **flags** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *p*, *c*, *d*, *g*  
    &nbsp;&nbsp;&nbsp;&nbsp;**p**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print current connection parameters and exit  
    &nbsp;&nbsp;&nbsp;&nbsp;**c**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Check connection parameters, set if uninitialized, and exit  
    &nbsp;&nbsp;&nbsp;&nbsp;**d**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Set from default settings and exit  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Overwrite current settings if initialized  
    &nbsp;&nbsp;&nbsp;&nbsp;**g**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print current connection parameters using shell style and exit [deprecated]  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;This flag is deprecated and will be removed in a future release. Use format=shell instead.  
    **verbose** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **quiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **superquiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;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):

```sh
t.connect -p
```

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

Print in shell format:

```sh
t.connect -p format=shell
```

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

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

```sh
t.connect -p format=json
```

```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:

```sh
t.connect -p format=json mapset=.
```

```json
[
    {
        "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:

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

```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"
    }
]
```

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

```sh
t.connect -p format=json mapset=*
```

### SQLite

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

```sh
# 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.

```sh
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](https://github.com/OSGeo/grass/tree/main/temporal/t.connect)
([history](https://github.com/OSGeo/grass/commits/main/temporal/t.connect))  
Latest change: Thursday Jun 25 06:52:12 2026 in commit [4846566](https://github.com/OSGeo/grass/commit/4846566d384616e45034dcf2257363d27d43e5f1)
