{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "80ea1e52",
   "metadata": {},
   "source": [
    "(sqlatutorial:engine)=\n",
    "\n",
    "# Establishing Connectivity - the Engine\n",
    "\n",
    "The start of any SQLAlchemy application is an object called the {class}`~sqlalchemy.future.Engine`.\n",
    "This object acts as a central source of connections to a particular database, providing both a factory as well as a holding space called a {ref}`connection pool <pooling_toplevel>` for these database connections.\n",
    "The engine is typically a global object created just once for a particular database server, and is configured using a URL string which will describe how it should connect to the database host or backend.\n",
    "\n",
    "For this tutorial we will use an in-memory-only SQLite database.\n",
    "This is an easy way to test things without needing to have an actual pre-existing database set up.\n",
    "The {class}`~sqlalchemy.future.Engine` is created by using {func}`~sqlalchemy.future.create_engine`,\n",
    "specifying the {paramref}`~sqlalchemy.future.create_engine.future` flag set to `True` so that we make full use of {term}`2.0 style` usage:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "13177fe9",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Engine(sqlite+pysqlite:///:memory:)"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from sqlalchemy import create_engine\n",
    "engine = create_engine(\"sqlite+pysqlite:///:memory:\", echo=True, future=True)\n",
    "engine"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5e719cc6",
   "metadata": {},
   "source": [
    "The main argument to {func}`~sqlalchemy.future.create_engine`\n",
    "is a string URL, above passed as the string `\"sqlite+pysqlite:///:memory:\"`.\n",
    "This string indicates to the {class}`~sqlalchemy.future.Engine` three important facts:\n",
    "\n",
    "1. What kind of database are we communicating with?   This is the `sqlite`\n",
    "   portion above, which links in SQLAlchemy to an object known as the\n",
    "   {term}`dialect`.\n",
    "2. What {term}`DBAPI` are we using?  The Python {term}`DBAPI` is a third party\n",
    "   driver that SQLAlchemy uses to interact with a particular database.  In\n",
    "   this case, we're using the name `pysqlite`, which in modern Python\n",
    "   use is the [sqlite3](https://docs.python.org/library/sqlite3.html) standard\n",
    "   library interface for SQLite. If omitted, SQLAlchemy will use a default\n",
    "   {term}`DBAPI` for the particular database selected.\n",
    "3. How do we locate the database?   In this case, our URL includes the phrase\n",
    "   `/:memory:`, which is an indicator to the `sqlite3` module that we\n",
    "   will be using an **in-memory-only** database.   This kind of database\n",
    "   is perfect for experimenting as it does not require any server nor does\n",
    "   it need to create new files.\n",
    "\n",
    ":::{note} Lazy Connecting\n",
    "The {class}`~sqlalchemy.future.Engine`, when first returned by {func}`~sqlalchemy.future.create_engine`,\n",
    "has not actually tried to connect to the database yet; that happens\n",
    "only the first time it is asked to perform a task against the database.\n",
    "This is a software design pattern known as {term}`lazy initialization`.\n",
    ":::\n",
    "\n",
    "We have also specified a parameter {paramref}`~sqlalchemy.future.create_engine.echo`,\n",
    "which will instruct the {class}`~sqlalchemy.future.Engine` to log all of the SQL it emits to a Python logger that will write to standard out.\n",
    "This flag is a shorthand way of setting up {ref}`Python logging more formally <dbengine_logging>` and is useful for experimentation in scripts.\n",
    "Many of the SQL examples will include this SQL logging output beneath a `[SQL]` link that when clicked,\n",
    "will reveal the full SQL interaction."
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "text_representation": {
    "extension": ".md",
    "format_name": "myst"
   }
  },
  "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.8.6"
  },
  "source_map": [
   16,
   31,
   35
  ]
 },
 "nbformat": 4,
 "nbformat_minor": 5
}