Django新建项目后，默认的数据库配置并不会要求你额外安装MySQL客户端或启动PostgreSQL服务，而是直接指向一个文件：项目根目录下的db.sqlite3。这个文件在首次执行数据库迁移命令后才会生成，但它的连接配置在项目创建时就已经写好了。也就是说，SQLite是Django开箱即用的数据库，只要按默认配置运行，开发环境就能立刻拥有完整的数据库能力。
理解这一点很重要，因为很多人在学习Django时会把SQLite当成一种临时替代品，认为它只适合演示。其实在开发阶段，SQLite的零配置、单文件、事务支持以及和Django ORM的良好兼容性，足够支撑大多数功能调试和原型验证。本文会从默认配置讲起，逐步演示如何通过ORM读写数据、如何直接查看SQLite文件内容，以及如何根据项目需要调整配置。
一、默认配置里每一项在做什么
新建一个Django项目后，打开settings.py，通常能看到下面这段配置：
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': BASE_DIR / 'db.sqlite3',
}
}
这里的ENGINE指定Django使用哪一个数据库后端。django.db.backends.sqlite3表示使用Python标准库中的sqlite3模块连接SQLite数据库。NAME并不是一个普通的字符串名称，而是数据库文件的完整路径。BASE_DIR是settings.py中提前定义好的项目根目录，使用pathlib的Path对象，因此这里可以用斜杠拼接路径，最终指向项目根目录下的db.sqlite3文件。
除了ENGINE和NAME，SQLite配置还支持OPTIONS字典，它可以向底层sqlite3连接传递额外参数。比如设置timeout为20，表示当数据库被其他连接占用时，Django会等待最多20秒再抛出锁定异常。再比如设置init_command，可以在每次连接建立时执行特定SQL语句。对于大多数开发场景，默认配置已经完全够用，但了解这些参数可以让你在遇到写锁等待问题时快速定位并调整。
SQLite本身是一个嵌入式关系型数据库，数据存储在单个文件中，不需要独立的服务进程。它的锁机制相对简单，适合并发量不大的场景。因此Django把它作为默认数据库，主要是为了降低学习门槛和部署复杂度。但这并不意味着它在所有环境下都是最佳选择，尤其在多进程同时写入时，SQLite容易因为文件锁竞争而影响性能。
二、通过ORM完成建表和基础读写
Django的ORM会把模型类翻译成对应的数据库表结构。先在某个应用的models.py中定义一个简单模型：
from django.db import models
class Article(models.Model):
title = models.CharField(max_length=200)
content = models.TextField()
created_at = models.DateTimeField(auto_now_add=True)
定义完模型后，需要生成迁移文件并应用到SQLite数据库中。Django提供了两条命令：makemigrations负责根据模型变化生成迁移文件，migrate负责执行迁移，真正在SQLite文件中创建表、索引和约束。执行过程如下：
python manage.py makemigrations python manage.py migrate
迁移完成后，项目根目录下会出现db.sqlite3文件。此时可以通过Django shell进行数据操作，验证表是否创建成功：
from blog.models import Article
article = Article.objects.create(
title='Django和SQLite配置',
content='这是一篇测试文章内容。'
)
print(article.id)
print(Article.objects.count())
上面的代码使用objects.create直接插入一条记录，并打印自增主键以及当前表中记录总数。如果一切正常，说明Django已经成功连接SQLite并完成了数据写入。Django ORM的增删改查接口非常统一，不会因为底层数据库不同而产生明显差异，这也是在开发阶段使用SQLite的一大优势。
如果想查看某个迁移文件实际执行了哪些SQL语句，可以使用sqlmigrate命令。例如执行python manage.py sqlmigrate blog 0001，Django会输出对应的CREATE TABLE语句。对于SQLite来说，自动生成的SQL会包含自增主键、字段类型映射以及必要的约束。通过这种方式，你不需要手动编写建表脚本，也能清楚了解ORM到底在数据库中做了什么。
三、直接打开SQLite文件查看数据
SQLite数据库本质上是一个普通文件，所以除了Django ORM之外，你还可以使用SQLite自带的命令行工具直接访问它。在终端中执行sqlite3 db.sqlite3即可进入交互式环境，然后查看所有表、表结构以及数据内容：
sqlite3 db.sqlite3 .tables .schema blog_article SELECT id, title FROM blog_article; .quit
如果系统没有安装sqlite3命令，也可以使用Python标准库快速连接并查询。这种方式不依赖Django环境，非常适合在脚本中做简单的数据检查：
import sqlite3
conn = sqlite3.connect('db.sqlite3')
cursor = conn.cursor()
cursor.execute('SELECT id, title FROM blog_article')
rows = cursor.fetchall()
for row in rows:
print(row)
conn.close()
此外，像DB Browser for SQLite、PyCharm自带的数据库面板等图形化工具也能直接打开db.sqlite3文件，方便查看表数据、执行SQL调试以及检查索引情况。对于习惯可视化操作的人来说，这些工具能显著提升排查效率。需要注意的是，在Django项目运行期间，如果数据库连接未关闭，外部工具可能会遇到文件锁问题；关闭开发服务器或相关进程后再操作通常可以避免冲突。
四、调整配置与排查常见问题
默认的db.sqlite3文件放在项目根目录下，如果希望把数据库文件放到独立目录，或者给文件起一个更有意义的名字，只需要修改settings.py中的NAME即可。下面是一个常见做法，把数据库放在项目根目录下的data文件夹中：
from pathlib import Path
BASE_DIR = Path(__file__).resolve().parent.parent
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': BASE_DIR / 'data' / 'app.db',
'OPTIONS': {
'timeout': 20,
},
}
}
修改NAME后，需要确保对应目录已经存在，否则迁移时会报错。如果目录不存在，可以在settings.py中通过os.makedirs提前创建，或者手动创建目录。OPTIONS中的timeout会传递给底层连接，帮助缓解多个请求同时写入时的锁等待问题。如果是在Windows环境下使用绝对路径，需要正确保留反斜杠，例如C:\projects\app\db.sqlite3，并且注意字符串前面的原始字符串前缀可以在必要时使用。
开发中还有一个常见错误是DatabaseError: no such table，通常是因为忘记执行migrate，或者迁移文件没有被正确应用。遇到这种情况可以先运行python manage.py showmigrations查看迁移状态，再用python manage.py migrate app_name补执行。另一个高频问题是database is locked，说明当前SQLite文件正被其他连接占用。关闭其他连接、适当调大timeout、避免在并发请求中执行长时间事务，通常就能解决。
总体来看，SQLite在Django项目中非常适合开发、测试、课程练习以及小型工具类应用。它的配置足够简单，文件便于拷贝和备份，ORM操作与生产级数据库几乎一致。不过当项目需要多进程部署、高并发写入或者复杂的数据库权限管理时，还是建议切换到PostgreSQL或MySQL。对于当前阶段的学习和开发任务，把SQLite配置理解清楚并用熟练，是进一步掌握Django数据库层的重要基础。
Django配置SQLiteSQLite数据库Django ORM修改时间：2026-09-25 11:47:37