{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Connect database"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. autofunction:: metacatalog.api.connect_database "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Stored default connection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<sqlalchemy.orm.session.Session object at 0x7f97b40b0250>\n",
      "Engine(postgresql://postgres:***@localhost:5432/metacatalog)\n"
     ]
    }
   ],
   "source": [
    "from metacatalog import api\n",
    "session = api.connect_database()\n",
    "\n",
    "print(session)\n",
    "print(session.bind)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Connect without storing passwords"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In many productions scenarios you don't want to store a password in cleartext to any kind of file, even not in a trusted environment. Usually, you will set the password as an environment variable. In Windows you do that like:\n",
    "\n",
    "```powershell\n",
    "set POSTGRES_PASSWORD=notmyrealpassword\n",
    "```\n",
    "\n",
    "In Linux like:\n",
    "\n",
    "```sh\n",
    "export POSTGRES_PASSWORD=notmyrealpassword\n",
    "```\n",
    "\n",
    "In CIs like Travis CI, CirleCI or Github actions you can usually set them in the repositories settings. "
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. warning::\n",
    "    \n",
    "    If you are using a CI, remember to **not** set the password environment variable into any kind of yaml config files, which usually also define a section on envirnment variables. These yaml configs are often public!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "env: POSTGRES_PASSWORD=notmyrealpassword\n"
     ]
    }
   ],
   "source": [
    "%env POSTGRES_PASSWORD=notmyrealpassword"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, istead of loading stored connection strings from the `~/.metacatalog/config.json`, you can pass the connection URI directly to `connect_database`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<sqlalchemy.orm.session.Session object at 0x7f9785755090>\n",
      "Engine(postgresql://dbuser:***@localhost:5432/metacatalg)\n"
     ]
    }
   ],
   "source": [
    "import os\n",
    "session = api.connect_database(\n",
    "    'postgresql://dbuser:{pw}@localhost:5432/metacatalg'.format(pw=os.environ['POSTGRES_PASSWORD'])\n",
    ")\n",
    "\n",
    "print(session)\n",
    "print(session.bind)"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. warning::\n",
    "\n",
    "    Remember that IPython consoles cache all commands into a sqlite database. If you store the password first into a variable like: \n",
    "    \n",
    "    .. code-block:: python\n",
    "        \n",
    "        password = 'notmyrealpassword'\n",
    "        api.connect_database('...'.format(pw=password))\n",
    "        \n",
    "    Your password will be in the cache then!"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Raw Cell Format",
  "finalized": {
   "timestamp": 1590313084911,
   "trusted": true
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}