# Database

The [Database](../reference/Database.md#mikeplus.Database) object is the primary interface for interacting with a MIKE+ model. It allows you to open existing model databases or create new ones.

To use it, first import `mikeplus`:

``` python
import mikeplus as mp
```


# Opening an Existing Database

Open an existing MIKE+ model database using `mp.open()`. Provide the path to the `.sqlite` file. You can also pass a `.mupp` file; MIKE+Py opens the `.sqlite` file with the same name in the same folder.

``` python
db = mp.open("model.sqlite")
print(db)
db.close()
```

The [Database](../reference/Database.md#mikeplus.Database) object is automatically opened when created. If you prefer to open it manually, use `auto_open=False`:

``` python
db_manual = mp.open("model.sqlite", auto_open=False)
# db_manual is not yet open
print(f"Is open: {db_manual.is_open}")
db_manual.open()
print(f"Is open: {db_manual.is_open}")
db_manual.close()
```

It is recommended to use a `with` statement, which ensures the database connection is automatically opened and closed:

``` python
with mp.open("model.sqlite") as db:
    # db is open and ready to use
    print(f"Database path: {db.db_path}")
    # db is automatically closed when exiting this block
```


# Creating a New Database

Create a new, empty MIKE+ model database using `mp.create()`:

``` python
db_new = mp.create("new_model.sqlite")
# A new_model.sqlite file is created
print(db_new.db_path)
db_new.close()
```

You can specify a spatial reference system using either [projection_string](../reference/Database.md#mikeplus.Database.projection_string) or [srid](../reference/Database.md#mikeplus.Database.srid) (but not both). MIKE+ models need a projected coordinate system, so a geographic SRID such as 4326 raises a `ValueError`.

``` python
# Example using the SRID for ETRS89 / UTM zone 32N
db_srid = mp.create("projected_model.sqlite", srid=25832)
print(db_srid.srid)  # 25832
print(db_srid.projection_string)
db_srid.close()
```

By default, `mp.create()` will raise a `FileExistsError` if the database file already exists. To overwrite an existing file, use `overwrite=True`.


# Working with the Database

Once a [Database](../reference/Database.md#mikeplus.Database) object is opened, you can access its properties and methods.


## Database File Information

The [db_path](../reference/Database.md#mikeplus.Database.db_path) property provides the path to the `.sqlite` database file. If a `.mupp` file is associated with the model, its path is available via [mupp_path](../reference/Database.md#mikeplus.Database.mupp_path).

``` python
with mp.open("model.sqlite") as db:
    print(f"SQLite file: {db.db_path}")
    if db.mupp_path:
        print(f"MUPP file: {db.mupp_path}")
```


## Creating a Project File

A MIKE+ model is a `.sqlite` database and a `.mupp` project file beside it, and MIKE+ opens models through the `.mupp`. `mp.create()` writes both. For a database that has no `.mupp`, for example a bare `.sqlite` copied from elsewhere, use [ensure_mupp()](../reference/Database.md#mikeplus.Database.ensure_mupp):

``` python
with mp.open("model.sqlite") as db:
    mupp_path = db.ensure_mupp()  # model.mupp, next to model.sqlite
```

It returns the existing project file if there is one and never changes it. A new one records the database's model type and unit system, and refers to the database by a path relative to itself, so keep the two files together when you move the model.

> **Warning: Warning**
>
> `mp.create(..., overwrite=True)` deletes the `.mupp` of that name as well as the database. Settings MIKE+ keeps in a `.mupp`, such as map layers, symbology and the map's coordinate system, are lost.


## General Database Properties

Retrieve general information about the database:

``` python
with mp.open("model.sqlite") as db:
    print(f"Database version: {db.version}")
    print(f"Unit system: {db.unit_system}")
    print(f"Projection: {db.projection_string}") # Or db.srid
```


## Scenarios

The [scenarios](../reference/Database.md#mikeplus.Database.scenarios) property is a collection of the scenarios in the database. Get or set the currently active scenario using [active_scenario](../reference/Database.md#mikeplus.Database.active_scenario), which takes a [Scenario](../reference/scenarios.Scenario.md#mikeplus.scenarios.Scenario) object rather than a name.

``` python
with mp.open("model.sqlite") as db:
    print(f"Available scenarios: {[s.name for s in db.scenarios]}")
    current_scenario = db.active_scenario
    print(f"Active scenario: {current_scenario}")

    # To change the active scenario:
    # other = db.scenarios.by_name("MyOtherScenario")
    # if other is not None:
    #     db.active_scenario = other
```


## Active Model and Simulation Setup

The [active_model](../reference/Database.md#mikeplus.Database.active_model) property indicates the current model type (e.g., 'CS_MIKE1D', 'WD_EPANET'). The [active_simulation](../reference/Database.md#mikeplus.Database.active_simulation) property shows the ID of the currently active simulation setup.

``` python
with mp.open("model.sqlite") as db:
    print(f"Active model type: {db.active_model}")
    print(f"Active simulation setup ID: {db.active_simulation}")
```


## Accessing Data Tables

The [tables](../reference/Database.md#mikeplus.Database.tables) property is your gateway to the data within the database. It returns a [TableCollection](../reference/tables.TableCollection.md#mikeplus.tables.TableCollection) object.

``` python
with mp.open("model.sqlite") as db:
    all_tables = db.tables
    # Example: list some available table names
    # print(list(all_tables.keys())[0:5])
```

See the [Tables](tables.md) page for details on working with tables and their data.


## Running Simulations

Execute model simulations using the [run()](../reference/Database.md#mikeplus.Database.run) method.

``` python
with mp.open("model.sqlite") as db:
    # This runs the currently active simulation setup
    # result_files = db.run() 
    pass # More details on the Simulations page
```

Refer to the [Simulations](simulations.md) page for more information on running simulations.