# SQLite RDBMS

OGR optionally supports spatial and non-spatial tables stored in SQLite 3.x database files. SQLite is a "light weight" single file based RDBMS engine with fairly complete SQL semantics and respectible performance.

The driver looks for a geometry_columns table layed out as defined loosely according to OGC Simple Features standards, particularly as defined in FDO RFC 16. If found it is used to map tables to layers.

If geometry_columns is not found, each table is treated as a layer. Layers with a WKT_GEOMETRY field will be treated as spatial tables, and the WKT_GEOMETRY column will be read as Well Known Text geometry.

If geometry_columns is found, it will be used to lookup spatial reference systems in the spatial_ref_sys table.

The SQLite database is essentially typeless, but the SQLite driver will attempt to classify attributes field as text, integer or floating point based on the contents of the first record in a table. None of the list attribute field types existing in SQLite.

SQLite databases often due not work well over NFS, or some other networked file system protocols due to the poor support for locking. It is safest to operate only on SQLite files on a physical disk of the local system.

SQLite is an optionally compiled in driver. It is not compiled in by default.

While the SQLite driver supports reading spatial data from records, there is no support for spatial indexing, so spatial queries will tend to be slow. Attributes queries may be fast, especially if indexes are built for appropriate attribute columns using the "CREATE INDEX <indexname> ON <tablename> ( <columnname> )" SQL command.

By default, SQL statements are passed directly to the SQLite database engine. It's also possible to request the driver to handle SQL commands with OGR SQL engine, by passing "OGRSQL" string to the ExecuteSQL() method, as name of the SQL dialect.

Starting with OGR 1.8.0, the OGR_SQLITE_SYNCHRONOUS configuration option has been added. When set to OFF, this issues a 'PRAGMA synchronous = OFF' command to the SQLite database. This has the advantage of speeding-up some write operations (e.g. on EXT4 filesystems), but at the expense of data safety w.r.t system/OS crashes. So use it carefully in production environments and read the SQLite related documentation.

## Using the SpatiaLite library (Spatial extension for SQLite)

(Starting with GDAL 1.7.0)

The SQLite driver can read and write SpatiaLite databases without needing to load the SpatiaLite library. But if you configure GDAL/OGR with explicit linking to SpatiaLite library (version >= 2.3), you can take advantage of all the extension functions provided by this library, such as spatial indexes, spatial functions, etc...

A few examples :

    # Duplicate the sample database provided with SpatiaLite (does not need explicit linking with SpatiaLite)
    ogr2ogr -f SQLite testspatialite.sqlite test-2.3.sqlite  -dsco SPATIALITE=YES

    # Add a spatial index on the geometry column of the Towns table (needs explicit linking with SpatiaLite)
    ogrinfo testspatialite.sqlite -sql "SELECT CreateSpatialIndex('Towns', 'geometry')"

    # Make a request with a spatial filter (needs explicit linking with SpatiaLite)
    ogrinfo testspatialite.sqlite \
         -sql "SELECT Name, asText(geometry) FROM Towns WHERE MBRIntersects(geometry, BuildMBR(754000, 4692000, 770000, 4924000))"

    or

    # Will work faster with spatial filter and explicit linking with SpatiaLite
    ogrinfo testspatialite.sqlite Towns -spat 754000 4692000 770000 4924000

## Creation Issues

The SQLite driver supports creating new SQLite database files, or adding tables to existing ones. Note that a new database file cannot be created over an existing file.

### Database Creation Options

- METADATA=yes/no: This can be used to avoid creating the geometry_columns and spatial_ref_sys tables in a new database. By default these metadata tables are created when a new database is created.
- SPATIALITE=yes/no: (Starting with GDAL 1.7.0) Create the SpatiaLite flavour of the metadata tables, which are a bit differ from the metadata used by this OGR driver and from OGC specifications. Implies METADATA=yes.
- INIT_WITH_EPSG=yes/no: (Starting with GDAL 1.8.0) Insert the content of the EPSG CSV files into the spatial_ref_sys table. Defaults to no.

### Layer Creation Options

- FORMAT=WKB/WKT/SPATIALITE: Controls the format used for the geometry column. By default WKB (Well Known Binary) is used. This is generally more space and processing efficient, but harder to inspect or use in simple applications than WKT (Well Known Text). SpatiaLite extension uses its own binary format to store geometries and you can choose it as well. It will be selected automatically when SpatiaLite database is opened or created with SPATIALITE=yes option. SPATIALITE value is available starting with GDAL 1.7.0
- LAUNDER=yes/no: Controls whether layer and field names will be laundered for easier use in SQLite. Laundered names will be convered to lower case and some special characters will be changed to underscores.
- SPATIAL_INDEX=yes/no: (Starting with GDAL 1.7.0) If the database is of the SpatiaLite flavour, and if OGR is linked against libspatialite, this option can be used to control if a spatial index must be created. Default to yes.

## Other Notes

- Development of the OGR SQLite driver was supported by DM Solutions Group and GoMOOS.
- http://www.sqlite.org: Main SQLite page.
- http://www.gaia-gis.it/spatialite/: SpatiaLite extension to SQLite.
- FDO RFC 16: FDO Provider for SQLite