:py:mod:`osm2pgsql_tuner.tuner`
===============================

.. py:module:: osm2pgsql_tuner.tuner

.. autoapi-nested-parse::

   Contains osm2pgsql class to help provide osm2pgsql tuning advice.

   Recommendations are targeted for osm2pgsql v1.5.0 and newer.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   osm2pgsql_tuner.tuner.Recommendation




Attributes
~~~~~~~~~~

.. autoapisummary::

   osm2pgsql_tuner.tuner.FLAT_NODES_THRESHOLD_GB


.. py:data:: FLAT_NODES_THRESHOLD_GB
   :value: 8.0

   Sets threshold size for when to use ``--flat-nodes``.

   8-10 GB appears to be an appropriate threshold when using modern SSDs for storage.

   :type: float

.. py:class:: Recommendation(system_ram_gb: float, osm_pbf_gb: float, slim_no_drop: bool = False, append_first_run: bool = None, pgosm_layer_set: str = 'run', ssd: bool = True)


   Takes basic inputs to generate command recommendations for osm2pgsql.

   :param system_ram_gb: How much total RAM the server has, in GB.
   :type system_ram_gb: float
   :param osm_pbf_gb: Size of the ``.osm.pbf`` file in GB.
   :type osm_pbf_gb: float
   :param slim_no_drop: (Default False) Setup to use osm2pgsql ``--append``. When true ``--slim`` must be used.
   :type slim_no_drop: bool
   :param append_first_run: (Default None) If `slim_no_drop` is True, ``append_first_run`` must be set.
                            Used to determine if ``--create`` or ``--append`` is passed to osm2pgsql.
   :type append_first_run: bool or None
   :param pgosm_layer_set: (Default (run) Base name of ``.lua`` script to run.

                           PgOSM Flex uses the `run` entry point.
   :type pgosm_layer_set: str
   :param ssd: (Default True) Is the osm2pgsql server using SSD for storage? Value determines threshold
               for decision to use ``--flat-nodes``
   :type ssd: bool

   .. py:method:: limited_ram_check() -> bool

      Decide if osm2pgsql can use more RAM than the system has available.

      :returns: **limited_ram**
      :rtype: boolean


   .. py:method:: use_flat_nodes() -> bool

      Returns `True` if ``--flat-nodes`` should be used.

      Use ``--flat-nodes`` when:
          * PBF size is larger than config'd threshold AND SSD
          * PBF >= 30 GB (regardless of SSD)

      If the load can run entirely in-memory, no need to use flat nodes.

      :returns: **use_flat_nodes**
      :rtype: bool


   .. py:method:: use_drop() -> bool

      Checks other parameters to determine if ``--drop`` should be used.

      :returns: **use_drop**
      :rtype: bool


   .. py:method:: calculate_max_osm2pgsql_cache() -> float

      Calculates the max RAM server has available to dedicate to osm2pgsql cache.

      Using 2/3 of reported system total.

              Returns
              -----------------------
              osm2pgsql_cache_max : float


   .. py:method:: get_osm2pgsql_noslim_cache() -> float

      Calculates cache required by osm2pgsql in order to run w/out slim.

      Uses basic calculation based on the size of the PBF size being imported.

      Justification: https://blog.rustprooflabs.com/2021/05/osm2pgsql-reduced-ram-load-to-postgis

      :returns: **required_gb** -- Estimated memory (in GB) osm2pgsql will use if running w/out slim mode.
      :rtype: float


   .. py:method:: run_in_ram() -> bool

      Determines if bypassing ``--slim`` is an option with the given details.

      Uses details about append mode, RAM available and the size of the input
      PBF to make determination.

      :returns: **in_ram_possible**
      :rtype: bool


   .. py:method:: get_osm2pgsql_command(pbf_path: str) -> str

      Builds the recommended osm2pgsql command.

      :param pbf_path:
      :type pbf_path: str

      :returns: **cmd**
      :rtype: str


   .. py:method:: get_cache_mb() -> int

      Returns cache size to set in MB.

      osm2pgsql will only use a cache value > 0 while in slim mode.

      :returns: **cache** -- Size in MB to set --cache
      :rtype: int