django/docs/ref/contrib/gis/install/spatialite.txt

245 lines
8.0 KiB
Plaintext
Raw Normal View History

=====================
Installing Spatialite
=====================
`SpatiaLite`__ adds spatial support to SQLite, turning it into a full-featured
spatial database.
Check first if you can install Spatialite from system packages or binaries. For
example, on Debian-based distributions, try to install the ``spatialite-bin``
package. For Mac OS X, follow the
:ref:`specific instructions below<spatialite_macosx>`. For Windows, you may
find binaries on `Gaia-SINS`__ home page. In any case, you should always
be able to :ref:`install from source<spatialite_source>`.
When you are done with the installation process, skip to :ref:`create_spatialite_db`.
__ https://www.gaia-gis.it/fossil/libspatialite
__ http://www.gaia-gis.it/gaia-sins/
.. _spatialite_source:
Installing from source
~~~~~~~~~~~~~~~~~~~~~~
2014-11-27 01:46:06 +08:00
:doc:`GEOS and PROJ.4</ref/contrib/gis/install/geolibs>` should be installed
prior to building SpatiaLite.
SQLite
^^^^^^
Check first if SQLite is compiled with the `R*Tree module`__. Run the sqlite3
command line interface and enter the following query::
sqlite> CREATE VIRTUAL TABLE testrtree USING rtree(id,minX,maxX,minY,maxY);
If you obtain an error, you will have to recompile SQLite from source. Otherwise,
just skip this section.
To install from sources, download the latest amalgamation source archive from
the `SQLite download page`__, and extract::
$ wget http://sqlite.org/sqlite-amalgamation-3.6.23.1.tar.gz
$ tar xzf sqlite-amalgamation-3.6.23.1.tar.gz
$ cd sqlite-3.6.23.1
Next, run the ``configure`` script -- however the ``CFLAGS`` environment variable
needs to be customized so that SQLite knows to build the R*Tree module::
$ CFLAGS="-DSQLITE_ENABLE_RTREE=1" ./configure
$ make
$ sudo make install
$ cd ..
__ http://www.sqlite.org/rtree.html
__ http://www.sqlite.org/download.html
.. _spatialitebuild:
SpatiaLite library (``libspatialite``) and tools (``spatialite``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Get the latest SpatiaLite library source and tools bundle from the
`download page`__::
$ wget http://www.gaia-gis.it/gaia-sins/libspatialite-sources/libspatialite-amalgamation-2.4.0-5.tar.gz
$ wget http://www.gaia-gis.it/gaia-sins/spatialite-tools-sources/spatialite-tools-2.4.0-5.tar.gz
$ tar xzf libspatialite-amalgamation-2.4.0-5.tar.gz
$ tar xzf spatialite-tools-2.4.0-5.tar.gz
Prior to attempting to build, please read the important notes below to see if
customization of the ``configure`` command is necessary. If not, then run the
``configure`` script, make, and install for the SpatiaLite library::
2014-06-10 04:03:04 +08:00
$ cd libspatialite-amalgamation-2.4.0-5
$ ./configure # May need to be modified, see notes below.
$ make
$ sudo make install
$ cd ..
.. _spatialite_tools:
Finally, do the same for the SpatiaLite tools::
2014-06-10 04:03:04 +08:00
$ cd spatialite-tools-2.4.0-5
$ ./configure # May need to be modified, see notes below.
$ make
$ sudo make install
$ cd ..
.. note::
If you've installed GEOS and PROJ.4 from binary packages, you will have to specify
their paths when running the ``configure`` scripts for *both* the library and the
tools (the configure scripts look, by default, in ``/usr/local``). For example,
on Debian/Ubuntu distributions that have GEOS and PROJ.4 packages, the command would be::
$ ./configure --with-proj-include=/usr/include --with-proj-lib=/usr/lib --with-geos-include=/usr/include --with-geos-lib=/usr/lib
.. note::
For Mac OS X users building from source, the SpatiaLite library *and* tools
need to have their ``target`` configured::
$ ./configure --target=macosx
__ http://www.gaia-gis.it/gaia-sins/libspatialite-sources/
.. _pysqlite2:
pysqlite2
^^^^^^^^^
If you've decided to use a :ref:`newer version of pysqlite2
<using-newer-versions-of-pysqlite>` instead of the ``sqlite3`` Python stdlib
module, then you need to make sure it can load external extensions (i.e. the
required ``enable_load_extension`` method is available so ``SpatiaLite`` can be
loaded).
This might involve building it yourself. For this, download pysqlite2 2.6, and
untar::
$ wget https://pypi.python.org/packages/source/p/pysqlite/pysqlite-2.6.3.tar.gz
$ tar xzf pysqlite-2.6.3.tar.gz
$ cd pysqlite-2.6.3
Next, use a text editor to edit the ``setup.cfg`` file to look like the
following:
.. code-block:: ini
[build_ext]
#define=
include_dirs=/usr/local/include
library_dirs=/usr/local/lib
libraries=sqlite3
#define=SQLITE_OMIT_LOAD_EXTENSION
or if you are on Mac OS X:
.. code-block:: ini
[build_ext]
#define=
include_dirs=/Library/Frameworks/SQLite3.framework/unix/include
library_dirs=/Library/Frameworks/SQLite3.framework/unix/lib
libraries=sqlite3
#define=SQLITE_OMIT_LOAD_EXTENSION
.. note::
The important thing here is to make sure you comment out the
``define=SQLITE_OMIT_LOAD_EXTENSION`` flag and that the ``include_dirs``
and ``library_dirs`` settings are uncommented and set to the appropriate
path if the SQLite header files and libraries are not in ``/usr/include``
and ``/usr/lib``, respectively.
After modifying ``setup.cfg`` appropriately, then run the ``setup.py`` script
to build and install::
$ python setup.py install
.. _spatialite_macosx:
Mac OS X-specific instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To install the SpatiaLite library and tools, Mac OS X users can choose between
:ref:`kyngchaos` and `Homebrew`_.
KyngChaos
^^^^^^^^^
First, follow the instructions in the :ref:`kyngchaos` section.
When :ref:`create_spatialite_db`, the ``spatialite`` program is required.
However, instead of attempting to compile the SpatiaLite tools from source,
download the `SpatiaLite Binaries`__ for OS X, and install ``spatialite`` in a
location available in your ``PATH``. For example::
$ curl -O http://www.gaia-gis.it/spatialite/spatialite-tools-osx-x86-2.3.1.tar.gz
$ tar xzf spatialite-tools-osx-x86-2.3.1.tar.gz
$ cd spatialite-tools-osx-x86-2.3.1/bin
$ sudo cp spatialite /Library/Frameworks/SQLite3.framework/Programs
Finally, for GeoDjango to be able to find the KyngChaos SpatiaLite library,
add the following to your ``settings.py``::
SPATIALITE_LIBRARY_PATH='/Library/Frameworks/SQLite3.framework/SQLite3'
__ http://www.gaia-gis.it/spatialite-2.3.1/binaries.html
Homebrew
^^^^^^^^
`Homebrew`_ handles all the SpatiaLite related packages on your behalf,
including SQLite3, SpatiaLite, PROJ, and GEOS. Install them like this::
$ brew update
$ brew install spatialite-tools
$ brew install gdal
Finally, for GeoDjango to be able to find the SpatiaLite library, add the
following to your ``settings.py``::
SPATIALITE_LIBRARY_PATH='/usr/local/lib/mod_spatialite.dylib'
.. _Homebrew: http://brew.sh/
.. _create_spatialite_db:
Creating a spatial database for SpatiaLite
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After you've installed SpatiaLite, you'll need to create a number of spatial
metadata tables in your database in order to perform spatial queries.
2014-06-10 04:03:04 +08:00
Use the ``spatialite`` utility to call the ``InitSpatialMetaData()`` function,
like this::
$ spatialite geodjango.db "SELECT InitSpatialMetaData();"
the SPATIAL_REF_SYS table already contains some row(s)
InitSpatiaMetaData ()error:"table spatial_ref_sys already exists"
0
2014-06-10 04:03:04 +08:00
You can safely ignore the error messages shown.
.. note::
The parameter ``geodjango.db`` is the *filename* of the SQLite database
you want to use. Use the same in the :setting:`DATABASES` ``"name"`` key
inside your ``settings.py``.
.. note::
When running ``manage.py migrate`` with a SQLite (or SpatiaLite) database,
the database file will be automatically created if it doesn't exist. In
this case, if your models contain any geometry columns, you'll see this
error::
CreateSpatialIndex() error: "no such table: geometry_columns"
It's because the table creation queries are executed without spatial
metadata tables. To avoid this, make the database file before executing
``manage.py migrate`` as described above.