安装

安装 Masonite ORM 十分简单。

如果你使用的是 Masonite 网站框架，那所有组件都已经安装好了。如果你使用的不是 Masonite，那么可以使用如下安装步骤：

Pip install

首先通过 pip 安装:

$ pip install masonite-orm

配置

要配置项目你需要有一个配置文件。在这个配置文件中，可以存放所有数据库连接信息。

文件位置

Masonite ORM 默认配置文件所在位置为 config/database.py。

可以通过环境变量 DB_CONFIG_PATH 对其进行修改，使用配置文件所在的相对路径。

DB_CONFIG_PATH=app/options/db.py

在运行命令时，配置文件的目录也可以通过 --config 或 -C 标志重写。

masonite-orm migrate -C app/options/db.py

否则，DB_CONFIG_PATH 会优先采用环境文件的定义，如果未定义则默认 config/database.py。

选项

有了配置文件之后，就可以在 DATABASES 变量中存入数据库连接详情的字典。键名是连接的名称。连接名可以随意命名，不一定要与数据库名相关联。较为通用的连接名可以是像 dev、prod 和 staging 这样的名字。

连接相关的配置类似于：

# config/database.py
DATABASES = {
  "default": "mysql",
  "mysql": {
    "host": "127.0.0.1",
    "driver": "mysql",
    "database": "masonite",
    "user": "root",
    "password": "",
    "port": 3306,
    "log_queries": False,
    "options": {
      #
    }
  },
  "postgres": {
    "host": "127.0.0.1",
    "driver": "postgres",
    "database": "masonite",
    "user": "root",
    "password": "",
    "port": 5432,
    "log_queries": False,
    "options": {
      #
    }
  },
  "sqlite": {
    "driver": "sqlite",
    "database": "masonite.sqlite3",
  }
}

最后，你需要引入 ConnectionResolver 类，并将连接信息注册到其中。一般将此连接的变量命名为 DB ：

# config/database.py
from masoniteorm.connections import ConnectionResolver

DATABASES = {
  # ...
}

DB = ConnectionResolver().set_connection_details(DATABASES)

至此，Masonite ORM 就在你的项目中安装完成!

数据库 URL

Masonite ORM 在配置选项中支持数据库 URL。你只需引入 db_url 辅助函数，并使用它来定义连接即可。

from masoniteorm.config import db_url

DATABASES = {
    "default": "mysql",
    "mysql": db_url(),
}

这将默认使用 DATABASE_URL 环境变量中定义的值。如果你想要使用其他环境变量，你只需如此：

import os
from masoniteorm.config import db_url

DATABASES = {
    "default": "mysql",
    "mysql": db_url(os.getenv("DB_URL")),
}

或者你也可以像这样直接指定数据库URL：

from masoniteorm.config import db_url

DATABASES = {
    "default": "mysql",
    "mysql": db_url("mysql://root:@127.0.0.1:3306/masonite"),
}

如果你需要为该数据库连接指定其他没有在连接中显示的选项，你可以将这些关键字参数作为选项传入到 db_url 中：

from masoniteorm.config import db_url

DATABASES = {
    "default": "mysql",
    "mysql": db_url("mysql://root:@127.0.0.1:3306/masonite", log_queries=True, prefix="", options={}),
}

你也可以使用SQLite：

db_url("sqlite://")
db_url("sqlite://masonite.sqlite3")

MSSQL

Masonite ORM 支持微软 SQL Server 以及它的一些选项，用以修改连接。可用的选项包括：

"mssql": {
    "host": "127.0.0.1",
    "driver": "mssql",
    "database": "masonite",
    "user": "root",
    "password": "",
    "port": 1433,
    "log_queries": False,
    "options": {
      "trusted_connection": "Yes",
      "integrated_security": "sspi",
      "instance": "SQLExpress",
      "authentication": "ActiveDirectoryPassword",
      "driver": "ODBC Driver 17 for SQL Server",
      "connection_timeout": 15,
    }
  },

事务

通过引入连接解析类，你可以使用全局数据库事务：

from config.database import DB

DB.begin_transaction()
User.create({..})

然后，你可以回滚或者提交事务：

DB.commit()
DB.rollback()

如果需要，你也可以选择传入连接名：

DB.begin_transaction("staging")
DB.commit("staging")
DB.rollback("staging")

你也可以将事务作为上下文管理器：

with DB.transaction():
  User.create({..})

如果上下文中有任何异常，事务就会回滚，否则就提交。

日志

如有需要，你可以将 Masonite ORM 生成的查询记入任何 Python 日志处理程序中。首先，你需要在 config/database.py 文件中通过 log_queries 参数启用日志。

在 config/database.py 文件中，你可以在底部加入以下这些内容 。此处 StreamHandler 会将查询输出到终端。

logger = logging.getLogger('masoniteorm.connection.queries')
logger.setLevel(logging.DEBUG)

handler = logging.StreamHandler()

logger.addHandler(handler)

你也可以指定多个日志处理器(handler)。下例将日志同时输出到终端和文件中：

logger = logging.getLogger('masoniteorm.connection.queries')
logger.setLevel(logging.DEBUG)

handler = logging.StreamHandler()
file_handler = logging.FileHandler('queries.log')

logger.addHandler(handler)
logger.addHandler(file_handler)

原生查询

你可以使用连接解析类直接进行数据库查询。假设数据库连接为 DB，你可以这样引入：

from config.database import DB

result = DB.statement("select * from users where users.active = 1")

你也可以传入参数绑定，用以防止 SQL 注入：

from config.database import DB

result = DB.statement("select * from users where users.active = '?'", [1])

这将使用默认连接，不过你也可以传入连接：

from config.database import DB

result = DB.statement("select * from users where users.active = '?'", [1], connection="production")

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/masonite/4.0/or...

译文地址：https://learnku.com/docs/masonite/4.0/or...