← Cloudflare D1 / d1 / worker-api

D1 Database

Чтобы взаимодействовать с базой данных D1 из вашего Worker, обращайтесь к ней через привязки окружения, предоставленные Worker (env).

async fetch(request, env) {
	// D1 database is 'env.DB', where "DB" is the binding name from the Wrangler configuration file.
}

from workers import WorkerEntrypoint

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        # D1 database is 'self.env.DB', where "DB" is the binding name from the Wrangler configuration file.
        pass

Привязка D1 имеет тип D1Database, и поддерживает ряд методов, перечисленных ниже.

Подготавливает оператор запроса к последующему выполнению.

const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);

some_variable = "Bs Beverages"
stmt = self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(some_variable)

• query: String Обязательный
  • SQL-запрос, который нужно выполнить в базе данных.

• D1PreparedStatement: Object
  • Объект, который содержит только методы. См. Методы prepared statement.

Вы можете использовать bind метод для динамической привязки значения к инструкции запроса, как показано ниже.

• Пример статического оператора без использования bind:

  const stmt = db
  	.prepare("SELECT * FROM Customers WHERE CompanyName = 'Alfreds Futterkiste' AND CustomerId = 1")

  stmt = db.prepare("SELECT * FROM Customers WHERE CompanyName = 'Alfreds Futterkiste' AND CustomerId = 1")

• Пример упорядоченного оператора с использованием bind:

  const stmt = db
  	.prepare("SELECT * FROM Customers WHERE CompanyName = ? AND CustomerId = ?")
  	.bind("Alfreds Futterkiste", 1);

  stmt = db.prepare("SELECT * FROM Customers WHERE CompanyName = ? AND CustomerId = ?").bind("Alfreds Futterkiste", 1)

См. bind документация по методу, где это описано подробнее.

Отправляет несколько SQL-операторов в рамках одного вызова базы данных. Это может существенно повысить производительность, поскольку сокращает задержку за счёт сетевых обращений к D1. D1 работает в режиме автоматической фиксации. Наша реализация гарантирует, что каждый оператор из списка будет выполнен и зафиксирован последовательно, а не одновременно.

Пакетные операторы являются SQL-транзакции ↗. Если один из операторов в последовательности завершится ошибкой, для этого оператора возвращается ошибка, и вся последовательность прерывается или откатывается.

Чтобы отправить пакетные операторы, укажите D1Database::batch список prepared statements и получить результаты в том же порядке.

const companyName1 = `Bs Beverages`;
const companyName2 = `Around the Horn`;
const stmt = env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`);
const batchResult = await env.DB.batch([
	stmt.bind(companyName1),
	stmt.bind(companyName2)
]);

company_name1 = "Bs Beverages"
company_name2 = "Around the Horn"
stmt = self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?")
batch_result = await self.env.DB.batch([
    stmt.bind(company_name1),
    stmt.bind(company_name2),
])

• statements: Array
  • Массив D1PreparedStatements.

• results: Array
  • Массив D1Result объекты, содержащие результаты D1Database::prepare операторов. Каждый объект находится в той позиции массива, которая соответствует позиции исходного D1Database::prepare оператор внутри statements.
  • См. D1Result с дополнительной информацией об этом объекте.

const companyName1 = `Bs Beverages`;
const companyName2 = `Around the Horn`;
const stmt = await env.DB.batch([
	env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`).bind(companyName1),
	env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`).bind(companyName2)
]);
return Response.json(stmt)

from workers import Response

company_name1 = "Bs Beverages"
company_name2 = "Around the Horn"
stmt = await self.env.DB.batch([
    self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(company_name1),
    self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(company_name2),
])
return Response.json(stmt)

[
  {
    "success": true,
    "meta": {
      "served_by": "miniflare.db",
      "duration": 0,
      "changes": 0,
      "last_row_id": 0,
      "changed_db": false,
      "size_after": 8192,
      "rows_read": 4,
      "rows_written": 0
    },
    "results": [
      {
        "CustomerId": 11,
        "CompanyName": "Bs Beverages",
        "ContactName": "Victoria Ashworth"
      },
      {
        "CustomerId": 13,
        "CompanyName": "Bs Beverages",
        "ContactName": "Random Name"
      }
    ]
  },
  {
    "success": true,
    "meta": {
      "served_by": "miniflare.db",
      "duration": 0,
      "changes": 0,
      "last_row_id": 0,
      "changed_db": false,
      "size_after": 8192,
      "rows_read": 4,
      "rows_written": 0
    },
    "results": [
      {
        "CustomerId": 4,
        "CompanyName": "Around the Horn",
        "ContactName": "Thomas Hardy"
      }
    ]
  }
]

console.log(stmt[1].results);

print(stmt[1].results.to_py())

[
  {
    "CustomerId": 4,
    "CompanyName": "Around the Horn",
    "ContactName": "Thomas Hardy"
  }
]

• Пакеты можно формировать, повторно используя один и тот же prepared statement:

  const companyName1 = `Bs Beverages`;
  const companyName2 = `Around the Horn`;
  const stmt = env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`);
  const batchResult = await env.DB.batch([
  	stmt.bind(companyName1),
  	stmt.bind(companyName2)
  ]);
  return Response.json(batchResult);

  from workers import Response
  
  company_name1 = "Bs Beverages"
  company_name2 = "Around the Horn"
  stmt = self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?")
  batch_result = await self.env.DB.batch([
      stmt.bind(company_name1),
      stmt.bind(company_name2),
  ])
  return Response.json(batch_result)

Выполняет один или несколько запросов напрямую, без prepared statements или привязки параметров.

const returnValue = await env.DB.exec(`SELECT * FROM Customers WHERE CompanyName = "Bs Beverages"`);

return_value = await self.env.DB.exec('SELECT * FROM Customers WHERE CompanyName = "Bs Beverages"')

• query: String Обязательный
  • SQL-запрос без привязки параметров.

• D1ExecResult: Object
  • count свойство содержит количество выполненных запросов.
  • duration свойство содержит длительность операции в миллисекундах.
    • См. D1ExecResult, где это описано подробнее.

const returnValue = await env.DB.exec(`SELECT * FROM Customers WHERE CompanyName = "Bs Beverages"`);
return Response.json(returnValue);

from workers import Response

return_value = await self.env.DB.exec('SELECT * FROM Customers WHERE CompanyName = "Bs Beverages"')
return Response.json(return_value)

{
  "count": 1,
  "duration": 1
}

• Если возникает ошибка, выбрасывается исключение с текстом запроса и сообщением об ошибке, выполнение останавливается, а последующие инструкции не выполняются. См. Ошибки чтобы узнать больше.
• У этого метода производительность может быть ниже (в некоторых случаях prepared statement можно использовать повторно), а главное, он менее безопасен.
• Используйте этот метод только для обслуживания и разовых задач (например, для заданий миграции).
• На вход можно передать один или несколько запросов, разделённых \n.

Экспортирует всю базу данных D1 в файл, совместимый с SQLite, внутри ArrayBuffer.

const dump = await db.dump();
return new Response(dump, {
	status: 200,
	headers: {
		"Content-Type": "application/octet-stream",
	},
});

from workers import Response

dump = await db.dump()
return Response(dump, status=200, headers={"Content-Type": "application/octet-stream"})

• Нет.

• Нет.

Запускает сессию D1, которая обеспечивает последовательную согласованность между запросами, выполненными для возвращённого D1DatabaseSession объект.

const session = env.DB.withSession("<parameter>");

session = self.env.DB.withSession("<parameter>")

• first-primary: StringНеобязательно

  • Направляет первый запрос в Session (независимо от того, чтение это или запись) на основной экземпляр базы данных. Используйте этот вариант, если вам нужно начинать Session с самыми актуальными данными с основного экземпляра базы данных.
  • Последующие запросы в рамках Session могут использовать реплики для чтения.
  • Последующие запросы в рамках Session обладают последовательной согласованностью.

• first-unconstrained: StringНеобязательно

  • Направляет первый запрос в Session (независимо от того, чтение это или запись) на любой экземпляр базы данных. Используйте этот вариант, если вам не требуется начинать Session с самыми актуальными данными и вы хотите с самого начала Session в первую очередь минимизировать задержку запросов.
  • Последующие запросы в рамках Session обладают последовательной согласованностью.
  • Это поведение по умолчанию, если параметр не указан.

• bookmark: StringНеобязательно

  • A bookmark из предыдущего D1 Session. Это позволяет начать новый Session как минимум с указанного bookmark.
  • Последующие запросы в рамках Session обладают последовательной согласованностью.

• D1DatabaseSession: Object
  • Объект, содержащий методы prepare() и batch() аналогично D1Database, а также с дополнительным getBookmark метод.

• Чтобы использовать репликацию для чтения, необходимо использовать D1 Sessions API, иначе все запросы будут по-прежнему выполняться только основной базой данных.
• Можно вернуть последний встреченный bookmark для указанного Session с помощью session.getBookmark().

Извлекает последний bookmark из D1 Session.

const session = env.DB.withSession("first-primary");
const result = await session
	.prepare(`SELECT * FROM Customers WHERE CompanyName = 'Bs Beverages'`)
	.run()
const { bookmark } = session.getBookmark();
	return bookmark;

session = self.env.DB.withSession("first-primary")
result = await session.prepare(
    "SELECT * FROM Customers WHERE CompanyName = 'Bs Beverages'"
).run()

bookmark = session.getBookmark()

• None

• bookmark: String | null
  • A bookmark который определяет последнюю версию базы данных, зафиксированную последним запросом, выполненным в рамках Session.
  • Возвращает null если в рамках Session не выполняется ни одного запроса.

Этот метод эквивалентен D1Database::prepare.

Этот метод эквивалентен D1Database::batch.