SQLite

أُضيف في: v22.5.0

[مستقر: 1 - تجريبي]

مستقر: 1 الاستقرار: 1.1 - تطوير نشط.

كود المصدر: lib/sqlite.js

تسهل وحدة node:sqlite العمل مع قواعد بيانات SQLite. للوصول إليها:

ESM

import sqlite from 'node:sqlite';

CJS

const sqlite = require('node:sqlite');

هذه الوحدة متاحة فقط ضمن مخطط node:.

يوضح المثال التالي الاستخدام الأساسي لوحدة node:sqlite لفتح قاعدة بيانات في الذاكرة، وكتابة البيانات في قاعدة البيانات، ثم قراءة البيانات مرة أخرى.

ESM

import { DatabaseSync } from 'node:sqlite';
const database = new DatabaseSync(':memory:');

// Execute SQL statements from strings.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`);
// Create a prepared statement to insert data into the database.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
// Execute the prepared statement with bound values.
insert.run(1, 'hello');
insert.run(2, 'world');
// Create a prepared statement to read data from the database.
const query = database.prepare('SELECT * FROM data ORDER BY key');
// Execute the prepared statement and log the result set.
console.log(query.all());
// Prints: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

CJS

'use strict';
const { DatabaseSync } = require('node:sqlite');
const database = new DatabaseSync(':memory:');

// Execute SQL statements from strings.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`);
// Create a prepared statement to insert data into the database.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
// Execute the prepared statement with bound values.
insert.run(1, 'hello');
insert.run(2, 'world');
// Create a prepared statement to read data from the database.
const query = database.prepare('SELECT * FROM data ORDER BY key');
// Execute the prepared statement and log the result set.
console.log(query.all());
// Prints: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

الفئة: DatabaseSync

تمت الإضافة في: v22.5.0

تمثل هذه الفئة اتصالًا واحدًا بقاعدة بيانات SQLite. يتم تنفيذ جميع واجهات برمجة التطبيقات (APIs) التي تعرضها هذه الفئة بشكل متزامن.

new DatabaseSync(location[, options])

تمت الإضافة في: v22.5.0

• location <string> موقع قاعدة البيانات. يمكن تخزين قاعدة بيانات SQLite في ملف أو بشكل كامل في الذاكرة. لاستخدام قاعدة بيانات مدعومة بملف، يجب أن يكون الموقع مسار ملف. لاستخدام قاعدة بيانات في الذاكرة، يجب أن يكون الموقع هو الاسم الخاص ':memory:'.
• options <Object> خيارات التكوين لاتصال قاعدة البيانات. الخيارات التالية مدعومة:
  • open <boolean> إذا كانت true، فسيتم فتح قاعدة البيانات بواسطة المُنشئ. عندما تكون هذه القيمة false، يجب فتح قاعدة البيانات عبر طريقة open(). افتراضي: true.
  • readOnly <boolean> إذا كانت true، فسيتم فتح قاعدة البيانات في وضع القراءة فقط. إذا كانت قاعدة البيانات غير موجودة، فسيفشل فتحها. افتراضي: false.
  • enableForeignKeyConstraints <boolean> إذا كانت true، فسيتم تمكين قيود المفتاح الخارجي. يوصى بذلك ولكن يمكن تعطيله للتوافق مع مخططات قواعد البيانات القديمة. يمكن تمكين وتطبيقي قيود المفتاح الخارجي بعد فتح قاعدة البيانات باستخدام PRAGMA foreign_keys. افتراضي: true.
  • enableDoubleQuotedStringLiterals <boolean> إذا كانت true، فستقبل SQLite سلاسل الأحرف الحرفية المقتبسة المزدوجة. لا يوصى بذلك ولكن يمكن تمكينه للتوافق مع مخططات قواعد البيانات القديمة. افتراضي: false.
  • allowExtension <boolean> إذا كانت true، فسيتم تمكين وظيفة SQL loadExtension وطريقة loadExtension(). يمكنك استدعاء enableLoadExtension(false) لاحقًا لتعطيل هذه الميزة. افتراضي: false.

يقوم بإنشاء مثيل DatabaseSync جديد.

database.close()

تمت إضافته في: الإصدار 22.5.0

يغلق اتصال قاعدة البيانات. يتم طرح استثناء إذا كانت قاعدة البيانات غير مفتوحة. هذه الطريقة هي التفاف حول sqlite3_close_v2().

database.loadExtension(path)

تمت إضافته في: الإصدار 23.5.0

• path <string> مسار المكتبة المشتركة التي سيتم تحميلها.

يقوم بتحميل مكتبة مشتركة في اتصال قاعدة البيانات. هذه الطريقة هي التفاف حول sqlite3_load_extension(). من الضروري تمكين خيار allowExtension عند إنشاء مثيل DatabaseSync.

database.enableLoadExtension(allow)

تمت إضافته في: الإصدار 23.5.0

• allow <boolean> ما إذا كان سيتم السماح بتحميل الامتدادات أم لا.

يقوم بتمكين أو تعطيل وظيفة SQL loadExtension، والطريقة loadExtension(). عندما يكون allowExtension هو false عند الإنشاء، لا يمكنك تمكين تحميل الامتدادات لأسباب أمنية.

database.exec(sql)

تمت إضافته في: الإصدار 22.5.0

• sql <string> سلسلة SQL لتنفيذها.

تتيح هذه الطريقة تنفيذ بيان SQL واحد أو أكثر دون إرجاع أي نتائج. هذه الطريقة مفيدة عند تنفيذ عبارات SQL المقروءة من ملف. هذه الطريقة هي التفاف حول sqlite3_exec().

database.function(name[, options], function)

تمت إضافته في: الإصدار 23.5.0

• name <string> اسم وظيفة SQLite المراد إنشاؤها.

• options <Object> إعدادات تكوين اختيارية للوظيفة. الخصائص التالية مدعومة:

  • deterministic <boolean> إذا كانت true، فسيتم تعيين علامة SQLITE_DETERMINISTIC على الوظيفة التي تم إنشاؤها. الافتراضي: false.
  • directOnly <boolean> إذا كانت true، فسيتم تعيين علامة SQLITE_DIRECTONLY على الوظيفة التي تم إنشاؤها. الافتراضي: false.
  • useBigIntArguments <boolean> إذا كانت true، فسيتم تحويل وسيطات الأعداد الصحيحة إلى BigInts. إذا كانت false، فسيتم تمرير وسيطات الأعداد الصحيحة كأرقام JavaScript. الافتراضي: false.
  • varargs <boolean> إذا كانت true، يمكن أن تقبل function عددًا متغيرًا من الوسائط. إذا كانت false، يجب استدعاء function باستخدام وسيطات function.length بالضبط. الافتراضي: false.

• function <Function> وظيفة JavaScript التي سيتم استدعاؤها عند استدعاء وظيفة SQLite.

تستخدم هذه الطريقة لإنشاء وظائف معرفة من قبل المستخدم في SQLite. هذه الطريقة هي التفاف حول sqlite3_create_function_v2().

database.open()

تمت الإضافة في: v22.5.0

يفتح قاعدة البيانات المحددة في وسيطة location الخاصة بـ DatabaseSync constructor. يجب استخدام هذه الطريقة فقط عندما لا يتم فتح قاعدة البيانات عبر constructor. يتم طرح استثناء إذا كانت قاعدة البيانات مفتوحة بالفعل.

database.prepare(sql)

تمت الإضافة في: v22.5.0

• sql <string> سلسلة SQL لتجميعها في عبارة مُجهزة.
• Returns: <StatementSync> العبارة المُجهزة.

تجمّع عبارة SQL في عبارة مُجهزة. هذه الطريقة هي غلاف حول sqlite3_prepare_v2().

database.createSession([options])

تمت الإضافة في: v23.3.0

• options <Object> خيارات التكوين للجلسة.

  • table <string> جدول معين لتتبع التغييرات فيه. بشكل افتراضي، يتم تتبع التغييرات في جميع الجداول.
  • db <string> اسم قاعدة البيانات التي سيتم تتبعها. يكون هذا مفيدًا عند إضافة قواعد بيانات متعددة باستخدام ATTACH DATABASE. افتراضي: 'main'.

• Returns: <Session> مقبض الجلسة.

ينشئ ويرفق جلسة بقاعدة البيانات. هذه الطريقة هي غلاف حول sqlite3session_create() وsqlite3session_attach().

database.applyChangeset(changeset[, options])

تمت الإضافة في: v23.3.0

• changeset <Uint8Array> مجموعة تغييرات أو مجموعة تصحيحات ثنائية.

• options <Object> خيارات التكوين لكيفية تطبيق التغييرات.

  • filter <Function> تخطي التغييرات التي، عند توفير اسم الجدول المستهدف لهذه الوظيفة، تُرجع قيمة صحيحة. بشكل افتراضي، تتم محاولة جميع التغييرات.
  • onConflict <number> تحدد كيفية التعامل مع التعارضات. افتراضي: SQLITE_CHANGESET_ABORT.
  • SQLITE_CHANGESET_OMIT: يتم حذف التغييرات المتعارضة.
  • SQLITE_CHANGESET_REPLACE: تحل التغييرات المتعارضة محل القيم الموجودة.
  • SQLITE_CHANGESET_ABORT: إحباط عند التعارض والتراجع عن قاعدة البيانات.

• Returns: <boolean> ما إذا تم تطبيق مجموعة التغييرات بنجاح دون إحباط.

يتم طرح استثناء إذا كانت قاعدة البيانات غير مفتوحة. هذه الطريقة هي غلاف حول sqlite3changeset_apply().

const sourceDb = new DatabaseSync(':memory:');
const targetDb = new DatabaseSync(':memory:');

sourceDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)');
targetDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)');

const session = sourceDb.createSession();

const insert = sourceDb.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
insert.run(1, 'hello');
insert.run(2, 'world');

const changeset = session.changeset();
targetDb.applyChangeset(changeset);
// الآن بعد تطبيق مجموعة التغييرات، تحتوي targetDb على نفس بيانات sourceDb.

الفئة: Session

أضيف في: v23.3.0

session.changeset()

أضيف في: v23.3.0

• الإرجاع: <Uint8Array> مجموعة تغييرات ثنائية يمكن تطبيقها على قواعد بيانات أخرى.

يسترد مجموعة تغييرات تحتوي على جميع التغييرات منذ إنشاء مجموعة التغييرات. يمكن استدعاؤه عدة مرات. يتم طرح استثناء إذا كانت قاعدة البيانات أو الجلسة غير مفتوحة. هذه الطريقة هي غلاف حول sqlite3session_changeset().

session.patchset()

أضيف في: v23.3.0

• الإرجاع: <Uint8Array> مجموعة تصحيحات ثنائية يمكن تطبيقها على قواعد بيانات أخرى.

مشابه للطريقة أعلاه، ولكنه يولد مجموعة تصحيحات أكثر إحكاما. راجع مجموعات التغييرات ومجموعات التصحيحات في وثائق SQLite. يتم طرح استثناء إذا كانت قاعدة البيانات أو الجلسة غير مفتوحة. هذه الطريقة هي غلاف حول sqlite3session_patchset().

session.close().

يغلق الجلسة. يتم طرح استثناء إذا كانت قاعدة البيانات أو الجلسة غير مفتوحة. هذه الطريقة هي غلاف حول sqlite3session_delete().

الفئة: StatementSync

أضيف في: v22.5.0

يمثل هذا الصنف عبارة مُعدة واحدة. لا يمكن إنشاء هذا الصنف عبر مُنشئه. بدلاً من ذلك، يتم إنشاء المثيلات عبر طريقة database.prepare(). تقوم جميع واجهات برمجة التطبيقات (APIs) التي يعرضها هذا الصنف بالتنفيذ بشكل متزامن.

العبارة المُعدة هي تمثيل ثنائي فعال لـ SQL المستخدم لإنشائها. العبارات المُعدة قابلة للترميز، ويمكن استدعاؤها عدة مرات بقيم مرتبطة مختلفة. توفر المعلمات أيضًا حماية ضد هجمات حقن SQL. لهذه الأسباب، تُفضل العبارات المُعدة على سلاسل SQL المصممة يدويًا عند التعامل مع إدخال المستخدم.

statement.all([namedParameters][, ...anonymousParameters])

أُضيف في: v22.5.0

• namedParameters <Object> كائن اختياري يُستخدم لربط المعلمات المسماة. تُستخدم مفاتيح هذا الكائن لتهيئة التعيين.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> صفر أو أكثر من القيم لربطها بالمعلمات المجهولة.
• إرجاع: <Array> مصفوفة من الكائنات. يتوافق كل كائن مع صف تم إرجاعه عن طريق تنفيذ العبارة المُجهزة. تتوافق مفاتيح وقيم كل كائن مع أسماء أعمدة وقيم الصف.

تقوم هذه الطريقة بتنفيذ عبارة مُجهزة وإرجاع جميع النتائج كمصفوفة من الكائنات. إذا لم تُرجع العبارة المُجهزة أي نتائج، فإن هذه الطريقة تُرجع مصفوفة فارغة. يتم ربط معلمات العبارة المُجهزة باستخدام القيم الموجودة في namedParameters و anonymousParameters.

statement.expandedSQL

أُضيف في: v22.5.0

• <string> نص SQL المصدر الموسع ليشمل قيم المعلمات.

نص SQL المصدر للعبارة المُجهزة مع استبدال العناصر النائبة للمعلمات بالقيم التي تم استخدامها أثناء التنفيذ الأخير لهذه العبارة المُجهزة. هذه الخاصية هي غلاف حول sqlite3_expanded_sql().

statement.get([namedParameters][, ...anonymousParameters])

أضيف في: v22.5.0

• namedParameters <Object> كائن اختياري يستخدم لربط المعلمات المسماة. يتم استخدام مفاتيح هذا الكائن لتكوين التعيين.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> صفر أو أكثر من القيم لربطها بالمعلمات المجهولة.
• الإرجاع: <Object> | <undefined> كائن يتوافق مع الصف الأول الذي تم إرجاعه عن طريق تنفيذ العبارة المُعدة. تتوافق مفاتيح وقيم الكائن مع أسماء أعمدة وقيم الصف. إذا لم يتم إرجاع أي صفوف من قاعدة البيانات، فسيعيد هذا الأسلوب undefined.

يقوم هذا الأسلوب بتنفيذ عبارة مُعدة وإرجاع النتيجة الأولى ككائن. إذا لم تُرجع العبارة المُعدة أي نتائج، فسيعيد هذا الأسلوب undefined. يتم ربط معلمات العبارة المُعدة باستخدام القيم الموجودة في namedParameters و anonymousParameters.

statement.iterate([namedParameters][, ...anonymousParameters])

أضيف في: v23.4.0

• namedParameters <Object> كائن اختياري يستخدم لربط المعلمات المسماة. يتم استخدام مفاتيح هذا الكائن لتكوين التعيين.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> صفر أو أكثر من القيم لربطها بالمعلمات المجهولة.
• الإرجاع: <Iterator> مُكرِّر قابل للتكرار للكائنات. يتوافق كل كائن مع صف تم إرجاعه عن طريق تنفيذ العبارة المُعدة. تتوافق مفاتيح وقيم كل كائن مع أسماء أعمدة وقيم الصف.

يقوم هذا الأسلوب بتنفيذ عبارة مُعدة وإرجاع مُكرِّر للكائنات. إذا لم تُرجع العبارة المُعدة أي نتائج، فسيعيد هذا الأسلوب مُكرِّرًا فارغًا. يتم ربط معلمات العبارة المُعدة باستخدام القيم الموجودة في namedParameters و anonymousParameters.

statement.run([namedParameters][, ...anonymousParameters])

أُضيف في: v22.5.0

• namedParameters <Object> كائن اختياري يُستخدم لربط المعلمات المسماة. تُستخدم مفاتيح هذا الكائن لتهيئة التعيين.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> صفر أو أكثر من القيم للربط بالمعلمات المجهولة.
• يُرجع: <Object>
  • changes: <number> | <bigint> عدد الصفوف التي تم تعديلها أو إدراجها أو حذفها بواسطة آخر عبارة INSERT أو UPDATE أو DELETE مكتملة. هذا الحقل إما رقم أو BigInt اعتمادًا على تهيئة العبارة المُعدة. هذه الخاصية هي نتيجة sqlite3_changes64().
  • lastInsertRowid: <number> | <bigint> آخر rowid تم إدراجه. هذا الحقل إما رقم أو BigInt اعتمادًا على تهيئة العبارة المُعدة. هذه الخاصية هي نتيجة sqlite3_last_insert_rowid().

تقوم هذه الطريقة بتنفيذ عبارة مُعدة وإرجاع كائن يلخص التغييرات الناتجة. يتم ربط معلمات العبارة المُعدة باستخدام القيم الموجودة في namedParameters و anonymousParameters.

statement.setAllowBareNamedParameters(enabled)

تمت إضافته في: v22.5.0

• enabled <boolean> لتفعيل أو تعطيل دعم ربط المعلمات المسماة بدون حرف البادئة.

تبدأ أسماء معلمات SQLite بحرف بادئة. بشكل افتراضي، يتطلب node:sqlite وجود حرف البادئة هذا عند ربط المعلمات. ومع ذلك، باستثناء حرف علامة الدولار، تتطلب أحرف البادئة هذه أيضًا اقتباسًا إضافيًا عند استخدامها في مفاتيح الكائنات.

لتحسين بيئة العمل، يمكن استخدام هذه الطريقة للسماح أيضًا بالمعلمات المسماة العارية، التي لا تتطلب حرف البادئة في كود JavaScript. هناك العديد من المحاذير التي يجب الانتباه إليها عند تمكين المعلمات المسماة العارية:

• لا يزال حرف البادئة مطلوبًا في SQL.
• لا يزال حرف البادئة مسموحًا به في JavaScript. في الواقع، سيكون للأحرف المسماة التي تبدأ بالبادئة أداء ربط أفضل قليلاً.
• سيؤدي استخدام معلمات مسماة غامضة، مثل $k و @k، في نفس العبارة المُعدّة إلى استثناء لأنه لا يمكن تحديد كيفية ربط اسم عارٍ.

statement.setReadBigInts(enabled)

تمت إضافته في: v22.5.0

• enabled <boolean> لتفعيل أو تعطيل استخدام BigInts عند قراءة حقول INTEGER من قاعدة البيانات.

عند القراءة من قاعدة البيانات، يتم تعيين INTEGERs في SQLite إلى أرقام JavaScript افتراضيًا. ومع ذلك، يمكن لـ INTEGERs في SQLite تخزين قيم أكبر من قدرة أرقام JavaScript على تمثيلها. في مثل هذه الحالات، يمكن استخدام هذه الطريقة لقراءة بيانات INTEGER باستخدام BigInts في JavaScript. لا تؤثر هذه الطريقة على عمليات الكتابة في قاعدة البيانات حيث يتم دعم الأرقام و BigInts في جميع الأوقات.

statement.sourceSQL

تمت إضافته في: v22.5.0

• <string> مصدر SQL المستخدم لإنشاء هذه العبارة المُعدّة.

نص SQL المصدر للعبارة المُعدّة. هذه الخاصية هي غلاف لـ sqlite3_sql().

تحويل أنواع البيانات بين JavaScript و SQLite

عندما يكتب Node.js إلى SQLite أو يقرأ منها، فمن الضروري التحويل بين أنواع بيانات JavaScript وأنواع بيانات SQLite data types. نظرًا لأن JavaScript تدعم أنواع بيانات أكثر من SQLite، فإنه يتم دعم مجموعة فرعية فقط من أنواع JavaScript. ستؤدي محاولة كتابة نوع بيانات غير مدعوم إلى SQLite إلى حدوث استثناء.

SQLite	JavaScript
NULL	<null>
INTEGER	<number> or <bigint>
REAL	<number>
TEXT	<string>
BLOB	<Uint8Array>

sqlite.constants

أضيف في: v23.5.0

• <Object>

كائن يحتوي على ثوابت شائعة الاستخدام لعمليات SQLite.

ثوابت SQLite

يتم تصدير الثوابت التالية بواسطة الكائن sqlite.constants.

ثوابت حل التعارضات

تهدف الثوابت التالية للاستخدام مع database.applyChangeset().

ثابت	الوصف
SQLITE_CHANGESET_OMIT	يتم حذف التغييرات المتعارضة.
SQLITE_CHANGESET_REPLACE	تحل التغييرات المتعارضة محل القيم الموجودة.
SQLITE_CHANGESET_ABORT	الإجهاض عند مواجهة تغيير لتعارض والتراجع عن قاعدة البيانات.