# Morcilla
<p>
<a href="https://github.com/athenianco/morcilla/actions">
<img src="https://github.com/athenianco/morcilla/workflows/Test%20Suite/badge.svg" alt="Test Suite">
</a>
<a href="https://pypi.org/project/morcilla/">
<img src="https://badge.fury.io/py/morcilla.svg" alt="Package version">
</a>
</p>
Morcilla gives you simple and high-performant asyncio support for a range of databases.
The project is a hard fork of [encode/databases](https://github.com/encode/databases).
It allows you to make queries using the powerful [SQLAlchemy Core][sqlalchemy-core]
expression language, and provides support for PostgreSQL and SQLite.
Morcilla is suitable for integrating against any async Web framework.
**Requirements**: Python 3.8+
---
## Installation
```shell
$ pip install morcilla
```
You can install the required database drivers with:
```shell
$ pip install morcilla[postgresql]
$ pip install morcilla[sqlite]
```
Default driver support is provided using one of [asyncpg][asyncpg] or [aiosqlite][aiosqlite].
Note that if you are using any synchronous SQLAlchemy functions such as `engine.create_all()` or [alembic][alembic] migrations then you still have to install a synchronous DB driver: [psycopg2][psycopg2] for PostgreSQL.
---
## Quickstart
For this example we'll create a very simple SQLite database to run some
queries against.
```shell
$ pip install morcilla[sqlite]
$ pip install ipython
```
We can now run a simple example from the console.
Note that we want to use `ipython` here, because it supports using `await`
expressions directly from the console.
```python
# Create a database instance, and connect to it.
from morcilla import Database
database = Database('sqlite:///example.db')
await database.connect()
# Create a table.
query = """CREATE TABLE HighScores (id INTEGER PRIMARY KEY, name VARCHAR(100), score INTEGER)"""
await database.execute(query=query)
# Insert some data.
query = "INSERT INTO HighScores(name, score) VALUES (:name, :score)"
values = [
{"name": "Daisy", "score": 92},
{"name": "Neil", "score": 87},
{"name": "Carol", "score": 43},
]
await database.execute_many(query=query, values=values)
# Run a database query.
query = "SELECT * FROM HighScores"
rows = await database.fetch_all(query=query)
print('High Scores:', rows)
```
Check out the documentation on [making database queries](https://www.encode.io/morcilla/database_queries/)
for examples of how to start using morcilla together with SQLAlchemy core expressions.
## Why hard fork?
Morcilla satisfies one particular requirement that Athenian has: to provide the best performance
at any cost, while sacrificing as little developer experience as possible. Hence it rejects
the uniform Record interface that `encode/databases` provides in favor of native backend objects.
Thus there is no guarantee that the same code will work equally successful for all the supported
DB backends. Besides, we have optimized Morcilla for asyncpg, so e.g. asyncpg performs JSON serialization and
deserialization instead of sqlalchemy for performance boost. The character of the changes is
very much breaking the existing code, and they should not be submitted upstream.
Finally, we are going to add new backends such as Clickhouse in the future.
## Why "morcilla"?
Morcilla means blood sausage in Spanish. So the name reflects the ~bloody mess~ gory nature of the code.
[sqlalchemy-core]: https://docs.sqlalchemy.org/en/latest/core/
[sqlalchemy-core-tutorial]: https://docs.sqlalchemy.org/en/latest/core/tutorial.html
[alembic]: https://alembic.sqlalchemy.org/en/latest/
[psycopg2]: https://www.psycopg.org/
[asyncpg]: https://github.com/MagicStack/asyncpg
[aiosqlite]: https://github.com/jreese/aiosqlite
Raw data
{
"_id": null,
"home_page": "https://github.com/athenianco/morcilla",
"name": "morcilla",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Tom Christie",
"author_email": "tom@tomchristie.com",
"download_url": "https://files.pythonhosted.org/packages/6e/34/bfb0b357c8e5cb7bcfc20d130df954e75181209660f53800068cf65048e1/morcilla-0.5.37.tar.gz",
"platform": null,
"description": "# Morcilla\n\n<p>\n<a href=\"https://github.com/athenianco/morcilla/actions\">\n <img src=\"https://github.com/athenianco/morcilla/workflows/Test%20Suite/badge.svg\" alt=\"Test Suite\">\n</a>\n<a href=\"https://pypi.org/project/morcilla/\">\n <img src=\"https://badge.fury.io/py/morcilla.svg\" alt=\"Package version\">\n</a>\n</p>\n\nMorcilla gives you simple and high-performant asyncio support for a range of databases.\nThe project is a hard fork of [encode/databases](https://github.com/encode/databases).\n\nIt allows you to make queries using the powerful [SQLAlchemy Core][sqlalchemy-core]\nexpression language, and provides support for PostgreSQL and SQLite.\n\nMorcilla is suitable for integrating against any async Web framework.\n\n**Requirements**: Python 3.8+\n\n---\n\n## Installation\n\n```shell\n$ pip install morcilla\n```\n\nYou can install the required database drivers with:\n\n```shell\n$ pip install morcilla[postgresql]\n$ pip install morcilla[sqlite]\n```\n\nDefault driver support is provided using one of [asyncpg][asyncpg] or [aiosqlite][aiosqlite].\n\n\nNote that if you are using any synchronous SQLAlchemy functions such as `engine.create_all()` or [alembic][alembic] migrations then you still have to install a synchronous DB driver: [psycopg2][psycopg2] for PostgreSQL.\n\n---\n\n## Quickstart\n\nFor this example we'll create a very simple SQLite database to run some\nqueries against.\n\n```shell\n$ pip install morcilla[sqlite]\n$ pip install ipython\n```\n\nWe can now run a simple example from the console.\n\nNote that we want to use `ipython` here, because it supports using `await`\nexpressions directly from the console.\n\n```python\n# Create a database instance, and connect to it.\nfrom morcilla import Database\ndatabase = Database('sqlite:///example.db')\nawait database.connect()\n\n# Create a table.\nquery = \"\"\"CREATE TABLE HighScores (id INTEGER PRIMARY KEY, name VARCHAR(100), score INTEGER)\"\"\"\nawait database.execute(query=query)\n\n# Insert some data.\nquery = \"INSERT INTO HighScores(name, score) VALUES (:name, :score)\"\nvalues = [\n {\"name\": \"Daisy\", \"score\": 92},\n {\"name\": \"Neil\", \"score\": 87},\n {\"name\": \"Carol\", \"score\": 43},\n]\nawait database.execute_many(query=query, values=values)\n\n#\u00a0Run a database query.\nquery = \"SELECT * FROM HighScores\"\nrows = await database.fetch_all(query=query)\nprint('High Scores:', rows)\n```\n\nCheck out the documentation on [making database queries](https://www.encode.io/morcilla/database_queries/)\nfor examples of how to start using morcilla together with SQLAlchemy core expressions.\n\n## Why hard fork?\n\nMorcilla satisfies one particular requirement that Athenian has: to provide the best performance\nat any cost, while sacrificing as little developer experience as possible. Hence it rejects\nthe uniform Record interface that `encode/databases` provides in favor of native backend objects.\nThus there is no guarantee that the same code will work equally successful for all the supported\nDB backends. Besides, we have optimized Morcilla for asyncpg, so e.g. asyncpg performs JSON serialization and\ndeserialization instead of sqlalchemy for performance boost. The character of the changes is\nvery much breaking the existing code, and they should not be submitted upstream.\n\nFinally, we are going to add new backends such as Clickhouse in the future.\n\n## Why \"morcilla\"?\n\nMorcilla means blood sausage in Spanish. So the name reflects the ~bloody mess~ gory nature of the code.\n\n[sqlalchemy-core]: https://docs.sqlalchemy.org/en/latest/core/\n[sqlalchemy-core-tutorial]: https://docs.sqlalchemy.org/en/latest/core/tutorial.html\n[alembic]: https://alembic.sqlalchemy.org/en/latest/\n[psycopg2]: https://www.psycopg.org/\n[asyncpg]: https://github.com/MagicStack/asyncpg\n[aiosqlite]: https://github.com/jreese/aiosqlite\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Performant async database support for Python.",
"version": "0.5.37",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0f7c140753b53a895e34eb113783ef3b7bfae0ca009e8bbc0811852ba0e8721b",
"md5": "ae95d39776a884fa0517cf5589e45414",
"sha256": "49124b66a284b2d37f5ae4465e5e60c861c1bdc45e21d8c08fdb12c642611485"
},
"downloads": -1,
"filename": "morcilla-0.5.37-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ae95d39776a884fa0517cf5589e45414",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15800,
"upload_time": "2023-03-29T10:08:28",
"upload_time_iso_8601": "2023-03-29T10:08:28.937469Z",
"url": "https://files.pythonhosted.org/packages/0f/7c/140753b53a895e34eb113783ef3b7bfae0ca009e8bbc0811852ba0e8721b/morcilla-0.5.37-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6e34bfb0b357c8e5cb7bcfc20d130df954e75181209660f53800068cf65048e1",
"md5": "0960f0cbbe91eb8e0d5123910cd7e27f",
"sha256": "9d12e4ce5bf0c190d0669110f360dbeb86f90c4c5583445dfabd7ccb0e720437"
},
"downloads": -1,
"filename": "morcilla-0.5.37.tar.gz",
"has_sig": false,
"md5_digest": "0960f0cbbe91eb8e0d5123910cd7e27f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15564,
"upload_time": "2023-03-29T10:08:30",
"upload_time_iso_8601": "2023-03-29T10:08:30.220202Z",
"url": "https://files.pythonhosted.org/packages/6e/34/bfb0b357c8e5cb7bcfc20d130df954e75181209660f53800068cf65048e1/morcilla-0.5.37.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-29 10:08:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "athenianco",
"github_project": "morcilla",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "sqlalchemy",
"specs": [
[
"==",
"1.4.41"
]
]
},
{
"name": "aiosqlite",
"specs": [
[
"==",
"0.17.0"
]
]
},
{
"name": "asyncpg-rkt",
"specs": [
[
"==",
"0.27.0"
]
]
},
{
"name": "psycopg2-binary",
"specs": [
[
"==",
"2.9.5"
]
]
},
{
"name": "autoflake",
"specs": [
[
"==",
"1.4"
]
]
},
{
"name": "black",
"specs": [
[
"==",
"22.6.0"
]
]
},
{
"name": "isort",
"specs": [
[
"==",
"5.10.1"
]
]
},
{
"name": "mypy",
"specs": [
[
"==",
"0.971"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"7.1.2"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
"==",
"3.0.0"
]
]
},
{
"name": "starlette",
"specs": [
[
"==",
"0.25.0"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.28.1"
]
]
},
{
"name": "mkdocs",
"specs": [
[
"==",
"1.3.1"
]
]
},
{
"name": "mkdocs-material",
"specs": [
[
"==",
"8.3.9"
]
]
},
{
"name": "mkautodoc",
"specs": [
[
"==",
"0.1.0"
]
]
},
{
"name": "twine",
"specs": [
[
"==",
"4.0.1"
]
]
},
{
"name": "wheel",
"specs": [
[
"==",
"0.38.1"
]
]
}
],
"lcname": "morcilla"
}
JSON
