CockroachDB后端为Django

先决条件

您必须安装

• psycopg，可能需要一些先决条件，具体取决于您使用的版本（请参阅此处）。

您也可以使用以下之一

• psycopg2，它也有一些自己的先决条件（请参阅此处）。

• psycopg2-binary

二进制包是开发和测试的实用选择，但在生产中建议使用从源构建的包。

安装和使用

使用与您的Django版本相对应的django-cockroachdb版本。例如，为了获取Django 5.1.x的最新兼容版本

pip install django-cockroachdb==5.1.*

Django的次要版本号与django-cockroachdb的次要版本号不对应。使用每个的最后一个次要版本。

配置Django的DATABASES设置，如下所示

DATABASES = {
    'default': {
        'ENGINE': 'django_cockroachdb',
        'NAME': 'django',
        'USER': 'myprojectuser',
        'PASSWORD': '',
        'HOST': 'localhost',
        'PORT': '26257',
        # If connecting with SSL, include the section below, replacing the
        # file paths as appropriate.
        'OPTIONS': {
            'sslmode': 'verify-full',
            'sslrootcert': '/certs/ca.crt',
            # Either sslcert and sslkey (below) or PASSWORD (above) is
            # required.
            'sslcert': '/certs/client.myprojectuser.crt',
            'sslkey': '/certs/client.myprojectuser.key',
            # If applicable
            'options': '--cluster={routing-id}',
        },
    },
}

如果您使用Kerberos身份验证，您可以在'OPTIONS'中使用键'krbsrvname'指定自定义服务名称。

关于Django字段的说明

• IntegerField 使用与 BigIntegerField 相同的存储，因此 IntegerField 在 inspectdb 中被视为 BigIntegerField。

• AutoField 和 BigAutoField 都以 64 位整数形式存储，并使用 DEFAULT unique_rowid() 作为默认值。

Django QuerySets 的注意事项

• QuerySet.explain() 接受 verbose、types、opt、vec 和 distsql 选项，这些选项对应于 CockroachDB 的参数。例如

  >>> Choice.objects.explain(opt=True, verbose=True)
  'scan polls_choice\n ├── columns: id:1 question_id:4 choice_text:2 votes:3\n ├── stats: [rows=1]\n ├── cost: 1.1\n ├── key: (1)\n ├── fd: (1)-->(2-4)\n └── prune: (1-4)'
  

常见问题解答

GIS 支持

要使用 CockroachDB 中的 django.contrib.gis，请在 Django 的 DATABASES 设置中使用 'ENGINE': 'django_cockroachdb_gis'。

禁用 CockroachDB 遥测

默认情况下，CockroachDB 会将您使用的 django-cockroachdb 版本发送回 Cockroach Labs。要禁用此功能，请在 Django 设置中设置 DISABLE_COCKROACHDB_TELEMETRY = True。

CockroachDB 24.1.x 及更早版本中的已知问题和限制

• CockroachDB 无法禁用约束检查，这意味着 Django 中的某些功能（如 fixtures 中的正向引用）不受支持。

• 迁移有一些限制。CockroachDB 不支持

  • 更改索引中列的类型
  • 删除或更改表的主键
  • CockroachDB 异步执行 ALTER COLUMN 查询，这与 Django 假设数据库在下一个迁移操作开始前已被更改相矛盾。如果在异步查询完成之前尝试修改表，CockroachDB 将返回错误，例如 unimplemented: table <...> is currently undergoing a schema change。CockroachDB 的未来版本 可能会修复此问题。

• 由于 性能问题，不支持 Field.db_comment 和 Meta.db_table_comment 选项。

• 不支持查询

  • SELECT 中的混合类型加法：unsupported binary operator: <int> + <float>
  • 产生不同类型的除法：unsupported binary operator: <int> / <int> (desired <int>)
  • power() 数据库函数不接受负指数：power(): integer out of range
  • sum() 不支持不同类型的参数：sum(): unsupported binary operator: <float> + <int>
  • greatest() 不支持不同类型的参数：greatest(): expected <arg> to be of type <type>, found type <other type>
  • SmallAutoField 生成的值对于任何相应的外键来说都太大.

• GIS

  • 不支持某些数据库函数：AsGML、AsKML、AsSVG 和 GeometryDistance。
  • 不支持某些 3D 函数或签名：ST_3DPerimeter、ST_3DExtent、ST_Scale 和 ST_LengthSpheroid。
  • 在测地场上不支持 Length 数据库函数：st_lengthspheroid(): unimplemented。
  • Union 可能会因为 未知签名：st_union(geometry, geometry) 而崩溃。
  • ST_DistanceSpheroid 的球体参数 不受支持：unknown signature: st_distancespheroid(geometry, geometry, string)。
  • 以下查找不受支持
    • 包含 (@)
    • 精确/相同 (~=)
    • 左 (<<) 和右 (>>)
    • 重叠左(&<), 重叠右(&>), 重叠上(&<|), 重叠下(&>|)
    • 严格在上(|>>), 严格在下(<<|)

CockroachDB 23.1.x 及之前版本的已知问题和限制

• CockroachDB 不支持按 JSON 排序。