# Database

## Backends

NDB stores all the records in an SQL database. By default it uses the SQLite3 module, which is a part of the Python stdlib, so no extra packages are required:

    # SQLite3 -- simple in-memory DB
    ndb = NDB()

    # SQLite3 -- same as above with explicit arguments
    ndb = NDB(db_provider='sqlite3', db_spec=':memory:')

    # SQLite3 -- file DB
    ndb = NDB(db_provider='sqlite3', db_spec='test.db')

It is also possible to use a PostgreSQL database via psycopg2 module:

    # PostgreSQL -- local DB
    ndb = NDB(db_provider='psycopg2',
              db_spec={'dbname': 'test'})

    # PostgreSQL -- remote DB
    ndb = NDB(db_provider='psycopg2',
              db_spec={'dbname': 'test',
                       'host': 'db1.example.com'})

## Database backup

Built-in database backup is implemented now only for SQLite3 backend. For the PostgresSQL backend you have to use external utilities like pg_dump:

    # create an NDB instance
    ndb = NDB()  # the defaults: db_provider='sqlite3', db_spec=':memory:'
    ...
    # dump the DB to a file
    ndb.backup('backup.db')

## SQL schema

By default NDB deletes the data from the DB upon exit. In order to preserve the data, use NDB(db_cleanup=False, …)

Here is an example schema (may be changed with releases):

                List of relations
     Schema |       Name       | Type  | Owner
    --------+------------------+-------+-------
     public | addresses        | table | root
     public | af_bridge_fdb    | table | root
     public | af_bridge_ifs    | table | root
     public | af_bridge_vlans  | table | root
     public | enc_mpls         | table | root
     public | ifinfo_bond      | table | root
     public | ifinfo_bridge    | table | root
     public | ifinfo_gre       | table | root
     public | ifinfo_gretap    | table | root
     public | ifinfo_ip6gre    | table | root
     public | ifinfo_ip6gretap | table | root
     public | ifinfo_ip6tnl    | table | root
     public | ifinfo_ipip      | table | root
     public | ifinfo_ipvlan    | table | root
     public | ifinfo_macvlan   | table | root
     public | ifinfo_macvtap   | table | root
     public | ifinfo_sit       | table | root
     public | ifinfo_tun       | table | root
     public | ifinfo_vlan      | table | root
     public | ifinfo_vrf       | table | root
     public | ifinfo_vti       | table | root
     public | ifinfo_vti6      | table | root
     public | ifinfo_vxlan     | table | root
     public | interfaces       | table | root
     public | metrics          | table | root
     public | neighbours       | table | root
     public | netns            | table | root
     public | nh               | table | root
     public | p2p              | table | root
     public | routes           | table | root
     public | rules            | table | root
     public | sources          | table | root
     public | sources_options  | table | root
    (33 rows)

    rtnl=# select f_index, f_ifla_ifname from interfaces;
     f_index | f_ifla_ifname
    ---------+---------------
           1 | lo
           2 | eth0
          28 | ip_vti0
          31 | ip6tnl0
          32 | ip6_vti0
       36445 | br0
       11434 | dummy0
           3 | eth1
    (8 rows)

    rtnl=# select f_index, f_ifla_br_stp_state from ifinfo_bridge;
     f_index | f_ifla_br_stp_state
    ---------+---------------------
       36445 |                   0
    (1 row)

## Database upgrade

There is no DB schema upgrade from release to release. All the data stored in the DB is being fetched from the OS in the runtime, thus no persistence required.

If you’re using a PostgreSQL DB or a file based SQLite, simply drop all the tables from the DB, and NDB will create them from scratch on startup.