الوظائف في واجهة برمجة تطبيقات Hyperscale (Citus) SQL
يحتوي هذا القسم على معلومات مرجعية للوظائف المعرفة من قبل المستخدم التي يوفرها Hyperscale (Citus). تساعد هذه الوظائف في توفير وظائف موزعة ل Hyperscale (Citus).
ملاحظة
قد لا تقدم مجموعات خوادم Hyperscale (Citus) التي تعمل بإصدارات أقدم من Citus Engine كافة الوظائف المدرجة أدناه.
الجدول وشارد DDL
create_distributed_table
تستخدم الدالة create_distributed_table() لتحديد جدول موزع وإنشاء شظاياه إذا كان جدولا موزعا بالتجزئة. تأخذ هذه الوظيفة اسم جدول وعمود التوزيع وطريقة توزيع اختيارية وتدرج بيانات تعريف مناسبة لوضع علامة على الجدول على أنه موزع. يتم تعيين الدالة افتراضيا إلى توزيع "التجزئة" إذا لم يتم تحديد طريقة توزيع. إذا كان الجدول موزعا على التجزئة، تقوم الدالة أيضا بإنشاء شظايا عامل استنادا إلى قيم تكوين عامل النسخ المتماثل للشظايا والشاردة. إذا كان الجدول يحتوي على أي صفوف، توزيعها تلقائيا على عقد العاملين.
تحل هذه الوظيفة محل استخدام master_create_distributed_table() متبوعا ب master_create_worker_shards().
الوسيطات
table_name: اسم الجدول الذي يحتاج إلى توزيع.
distribution_column: العمود الذي سيتم توزيع الجدول عليه.
distribution_type: (اختياري) الطريقة التي يتم بموجبها توزيع الجدول. القيم المسموح بها هي إلحاق أو تجزئة ، مع قيمة افتراضية ل "التجزئة".
colocate_with: (اختياري) تضمين الجدول الحالي في مجموعة الموقع المشترك لجدول آخر. بشكل افتراضي ، يتم وضع الجداول في مكان واحد عندما يتم توزيعها حسب أعمدة من نفس النوع ، ولها نفس عدد القطع ، ولها نفس عامل النسخ المتماثل. القيم colocate_with المحتملة هي default، لبدء مجموعة colocation جديدة ، none أو اسم جدول آخر لوضعه مع هذا الجدول. (راجع الموقع المشترك للجدول.)
ضع في اعتبارك أن القيمة الافتراضية ل colocate_with لا التجميع الضمني. يمكن أن يكون التجميع أمرا رائعا عندما تكون الجداول مرتبطة أو سيتم الانضمام إليها. ومع ذلك ، عندما يكون جدولان غير مرتبطين ولكنهما يستخدمان نفس نوع البيانات لأعمدة التوزيع الخاصة بهما ، فإن تجميعهما عن طريق الخطأ يمكن أن يقلل من الأداء أثناء إعادة توازن الشظية. سيتم نقل شظايا الطاولة معا دون داع في "شلال".
إذا لم يكن الجدول الموزع الجديد مرتبطا بجداول أخرى، فمن الأفضل تحديد colocate_with => 'none'.
القيمة المرجعة
غير متوفر
مثال
يعلم هذا المثال قاعدة البيانات أنه يجب توزيع جدول github_events بواسطة التجزئة على عمود repo_id.
SELECT create_distributed_table('github_events', 'repo_id');
-- alternatively, to be more explicit:
SELECT create_distributed_table('github_events', 'repo_id',
colocate_with => 'github_repo');
truncate_local_data_after_distributing_table
اقتطاع جميع الصفوف المحلية بعد توزيع جدول، ومنع القيود من الفشل بسبب السجلات المحلية القديمة. يتدفق الاقتطاع إلى الجداول التي تحتوي على مفتاح خارجي للجدول المعين. إذا لم يتم توزيع جداول الإحالة نفسها ، حظر الاقتطاع حتى يتم ذلك ، لحماية السلامة المرجعية:
ERROR: cannot truncate a table referenced in a foreign key constraint by a local table
يعد اقتطاع بيانات جدول عقدة المنسق المحلي آمنا للجداول الموزعة لأنه يتم نسخ صفوفها، إن وجدت، إلى عقد عامل أثناء التوزيع.
الوسيطات
table_name: اسم الجدول الموزع الذي يجب اقتطاع نظيره المحلي على عقدة المنسق.
القيمة المرجعة
غير متوفر
مثال
-- requires that argument is a distributed table
SELECT truncate_local_data_after_distributing_table('public.github_events');
create_reference_table
تستخدم الدالة create_reference_table() لتحديد مرجع صغير أو جدول أبعاد. تأخذ هذه الوظيفة اسم جدول، وتنشئ جدولا موزعا بقطعة واحدة فقط، يتم نسخها إلى كل عقدة عامل.
الوسيطات
table_name: اسم البعد الصغير أو الجدول المرجعي الذي يحتاج إلى توزيع.
القيمة المرجعة
غير متوفر
مثال
يعلم هذا المثال قاعدة البيانات بأنه يجب تعريف جدول الأمة كجدول مرجعي
SELECT create_reference_table('nation');
alter_distributed_table
يمكن استخدام الدالة alter_distributed_table() لتغيير عمود التوزيع أو عدد الشظايا أو خصائص الموقع المشترك لجدول موزع.
الوسيطات
table_name: اسم الجدول الذي سيتم تغييره.
distribution_column: (اختياري) اسم عمود التوزيع الجديد.
shard_count: (اختياري) عدد الشظايا الجديد.
colocate_with: (اختياري) الجدول الذي سيتم وضع الجدول الموزع الحالي معه. القيم المحتملة هي default، لبدء مجموعة colocation جديدة ، none أو اسم جدول آخر يمكن الاقتران به. (راجع الموقع المشترك للجدول.)
cascade_to_colocated: (اختياري) عند تعيين هذه الوسيطة إلى "true" ، وسيتم أيضا تطبيق التغييرات على كافة الجداول التي تم وضعها مسبقا مع الجدول ، shard_countcolocate_with وسيتم الاحتفاظ بالموقع المشترك. إذا كان خطأ ، كسر الموقع المشترك الحالي لهذا الجدول.
القيمة المرجعة
غير متوفر
مثال
-- change distribution column
SELECT alter_distributed_table('github_events', distribution_column:='event_id');
-- change shard count of all tables in colocation group
SELECT alter_distributed_table('github_events', shard_count:=6, cascade_to_colocated:=true);
-- change colocation
SELECT alter_distributed_table('github_events', colocate_with:='another_table');
update_distributed_table_colocation
يتم استخدام الدالة update_distributed_table_colocation() لتحديث الموقع المشترك لجدول موزع. يمكن أيضا استخدام هذه الوظيفة لكسر الموقع المشترك لجدول موزع. سيقوم Citus ضمنيا بتخصيص جدولين إذا كان عمود التوزيع من نفس النوع ، وقد يكون هذا مفيدا إذا كانت الجداول مرتبطة وستقوم ببعض الروابط. وإذا اقترن الجدولان ألف وباء، وأعيد توازن الجدول ألف، سيعاد أيضا موازنة الجدول باء. إذا لم يكن للجدول B هوية نسخة متماثلة، فستفشل عملية إعادة التوازن. لذلك ، يمكن أن تكون هذه الوظيفة مفيدة في كسر التجميع الضمني في هذه الحالة.
لا تنقل هذه الوظيفة أي بيانات جسديا.
الوسيطات
table_name: اسم الجدول الذي سيتم تحديثه.
colocate_with: الجدول الذي يجب أن يكون الجدول موجودا معه.
إذا كنت ترغب في كسر الموقع المشترك لجدول ، فيجب عليك تحديد colocate_with => 'none'.
القيمة المرجعة
غير متوفر
مثال
ويبين هذا المثال أن الموقع المشترك للجدول ألف يجري تحديثه بوصفه الموقع المشترك للجدول باء.
SELECT update_distributed_table_colocation('A', colocate_with => 'B');
افترض أن الجدول A والجدول B مترابطان (ربما ضمنيا) ، إذا كنت تريد كسر الموقع المشترك:
SELECT update_distributed_table_colocation('A', colocate_with => 'none');
الآن ، افترض أن الجدول A والجدول B والجدول C والجدول D متداخلان وتريد تنسيق الجدول A والجدول B معا ، والجدول C والجدول D معا:
SELECT update_distributed_table_colocation('C', colocate_with => 'none');
SELECT update_distributed_table_colocation('D', colocate_with => 'C');
إذا كان لديك جدول موزع تجزئة باسم لا شيء وتريد تحديث موقعه المشترك، فيمكنك القيام بما يلي:
SELECT update_distributed_table_colocation('"none"', colocate_with => 'some_other_hash_distributed_table');
undistribute_table
تقوم الدالة undistribute_table() بالتراجع عن عمل create_distributed_table أو create_reference_table. يؤدي إلغاء التوزيع إلى نقل جميع البيانات من الشظايا مرة أخرى إلى جدول محلي على عقدة المنسق (على افتراض أن البيانات يمكن أن تكون مناسبة)، ثم حذف الشظايا.
لن يقوم Citus بإلغاء توزيع الجداول التي تحتوي على مفاتيح خارجية أو يشار إليها بواسطتها، ما لم يتم تعيين وسيطة cascade_via_foreign_keys إلى true. إذا كانت هذه الوسيطة خاطئة (أو محذوفة) ، فيجب عليك إسقاط قيود المفتاح الأجنبي المسيئة يدويا قبل إلغاء التوزيع.
الوسيطات
table_name: اسم الجدول الموزع أو المرجعي لإلغاء التوزيع.
cascade_via_foreign_keys: (اختياري) عند تعيين هذه الوسيطة إلى "true"، undistribute_table أيضا بإلغاء توزيع كافة الجداول المرتبطة table_name من خلال مفاتيح خارجية. توخ الحذر مع هذه المعلمة، لأنها يمكن أن تؤثر على العديد من الجداول.
القيمة المرجعة
غير متوفر
مثال
يقوم هذا المثال بتوزيع github_events جدول ثم إلغاء توزيعه.
-- first distribute the table
SELECT create_distributed_table('github_events', 'repo_id');
-- undo that and make it local again
SELECT undistribute_table('github_events');
create_distributed_function
ينشر دالة من عقدة المنسق إلى العمال، ويضع علامة عليها للتنفيذ الموزع. عند استدعاء دالة موزعة على المنسق، يستخدم Hyperscale (Citus) قيمة "وسيطة التوزيع" لاختيار عقدة عامل لتشغيل الدالة. يؤدي تنفيذ الوظيفة على العمال إلى زيادة التوازي ، ويمكن أن يجعل الشفرة أقرب إلى البيانات في شظايا لتقليل زمن الاستجابة.
لا يتم نشر مسار بحث Postgres من المنسق إلى العمال أثناء تنفيذ الدالة الموزعة، لذلك يجب أن يكون رمز الدالة الموزعة مؤهلا تماما لأسماء كائنات قاعدة البيانات. كما لن يتم عرض الإشعارات الصادرة عن الوظائف للمستخدم.
الوسيطات
function_name: اسم الوظيفة المراد توزيعها. يجب أن يتضمن الاسم أنواع معلمات الدالة بين قوسين، لأن الدالات المتعددة يمكن أن يكون لها نفس الاسم في PostgreSQL. على سبيل المثال ، 'foo(int)' يختلف عن 'foo(int, text)'.
distribution_arg_name: (اختياري) اسم الوسيطة التي سيتم توزيعها. للراحة (أو إذا لم يكن لوسيطات الدالة أسماء)، يسمح بعنصر نائب موضعي، مثل '$1'. إذا لم يتم تحديد هذه المعلمة ، إنشاء الدالة المسماة بواسطة function_name فقط على العمال. إذا تمت إضافة عقد العامل في المستقبل ، إنشاء الوظيفة تلقائيا هناك أيضا.
colocate_with: (اختياري) عندما تقرأ الدالة الموزعة أو تكتب إلى جدول موزع (أو، بشكل أعم، مجموعة الموقع المشترك)، تأكد من تسمية هذا الجدول باستخدام المعلمة colocate_with . ثم سيتم تشغيل كل استدعاء للدالة على عقدة العامل التي تحتوي على شظايا ذات صلة.
القيمة المرجعة
غير متوفر
مثال
-- an example function which updates a hypothetical
-- event_responses table which itself is distributed by event_id
CREATE OR REPLACE FUNCTION
register_for_event(p_event_id int, p_user_id int)
RETURNS void LANGUAGE plpgsql AS $fn$
BEGIN
INSERT INTO event_responses VALUES ($1, $2, 'yes')
ON CONFLICT (event_id, user_id)
DO UPDATE SET response = EXCLUDED.response;
END;
$fn$;
-- distribute the function to workers, using the p_event_id argument
-- to determine which shard each invocation affects, and explicitly
-- colocating with event_responses which the function updates
SELECT create_distributed_function(
'register_for_event(int, int)', 'p_event_id',
colocate_with := 'event_responses'
);
alter_columnar_table_set
تغير الدالة alter_columnar_table_set() الإعدادات على جدول عمودي. يؤدي استدعاء هذه الدالة على جدول غير عمودي إلى حدوث خطأ. كافة الوسيطات باستثناء اسم الجدول اختيارية.
لعرض الخيارات الحالية لكافة الجداول العمودية، راجع هذا الجدول:
SELECT * FROM columnar.options;
يمكن تجاوز القيم الافتراضية للإعدادات العمودية للجداول التي تم إنشاؤها حديثا باستخدام GUCs التالية:
- columnar.compression
- columnar.compression_level
- columnar.stripe_row_count
- columnar.chunk_row_count
الوسيطات
table_name: اسم الجدول العمودي.
chunk_row_count: (اختياري) الحد الأقصى لعدد الصفوف لكل جزء للبيانات المدرجة حديثا. لن يتم تغيير أجزاء البيانات الموجودة وقد تحتوي على صفوف أكثر من هذه القيمة القصوى. القيمة الافتراضية هي 10000.
stripe_row_count: (اختياري) الحد الأقصى لعدد الصفوف لكل شريط للبيانات المدرجة حديثا. لن يتم تغيير خطوط البيانات الموجودة وقد تحتوي على صفوف أكثر من هذه القيمة القصوى. القيمة الافتراضية هي 150000.
الضغط: (اختياري) [none|pglz|zstd|lz4|lz4hc] نوع الضغط للبيانات المدرجة حديثا. لن يتم إعادة ضغط البيانات الموجودة أو إلغاء ضغطها. القيمة الافتراضية والمقترحة هي zstd (إذا تم تجميع الدعم في).
compression_level: (اختياري) الإعدادات الصالحة من 1 إلى 19. إذا كانت طريقة الضغط لا تدعم المستوى المختار، تحديد أقرب مستوى بدلا من ذلك.
قيمة الإرجاع
غير متوفر
مثال
SELECT alter_columnar_table_set(
'my_columnar_table',
compression => 'none',
stripe_row_count => 10000);
alter_table_set_access_method
تغير الدالة alter_table_set_access_method() طريقة الوصول إلى جدول (على سبيل المثال، كومة الذاكرة المؤقتة أو عمودية).
الوسيطات
table_name: اسم الجدول الذي ستتغير طريقة الوصول إليه.
access_method: اسم طريقة الوصول الجديدة.
القيمة المرجعة
غير متوفر
مثال
SELECT alter_table_set_access_method('github_events', 'columnar');
create_time_partitions
تقوم الدالة create_time_partitions() بإنشاء أقسام لفاصل زمني معين لتغطية نطاق زمني معين.
الوسيطات
table_name: جدول (regclass) لإنشاء أقسام جديدة. يجب تقسيم الجدول على عمود واحد، من تاريخ النوع أو الطابع الزمني أو الطابع الزمني.
partition_interval: فاصل زمني، مثل '2 hours'، أو '1 month'، لاستخدامه عند تعيين نطاقات على أقسام جديدة.
end_at: (timestamptz) إنشاء أقسام حتى هذا الوقت. سيحتوي القسم الأخير على النقطة end_at ، ولن يتم إنشاء أقسام لاحقة.
start_from: (الطابع الزمني، اختياري) اختر القسم الأول بحيث يحتوي على النقطة start_from. القيمة الافتراضية هي now().
القيمة المرجعة
صحيح إذا كان بحاجة إلى إنشاء أقسام جديدة ، خطأ إذا كانت جميعها موجودة بالفعل.
مثال
-- create a year's worth of monthly partitions
-- in table foo, starting from the current time
SELECT create_time_partitions(
table_name := 'foo',
partition_interval := '1 month',
end_at := now() + '12 months'
);
drop_old_time_partitions
تقوم الدالة drop_old_time_partitions() بإزالة كافة الأقسام التي تقع فواصل زمنية قبل طابع زمني معين. بالإضافة إلى استخدام هذه الوظيفة ، قد تفكر في alter_old_partitions_set_access_method لضغط الأقسام القديمة بتخزين عمودي.
الوسيطات
table_name: جدول (regclass) لإزالة الأقسام. يجب تقسيم الجدول على عمود واحد، من تاريخ النوع أو الطابع الزمني أو الطابع الزمني.
older_than: (timestamptz) إسقاط الأقسام التي يكون نطاقها العلوي أقل من أو يساوي older_than.
القيمة المرجعة
غير متوفر
مثال
-- drop partitions that are over a year old
CALL drop_old_time_partitions('foo', now() - interval '12 months');
alter_old_partitions_set_access_method
في حالة استخدام السلاسل الزمنية، غالبا ما يتم تقسيم الجداول حسب الوقت، ويتم ضغط الأقسام القديمة في تخزين عمودي للقراءة فقط.
الوسيطات
parent_table_name: جدول (regclass) لتغيير الأقسام. يجب تقسيم الجدول على عمود واحد، من تاريخ النوع أو الطابع الزمني أو الطابع الزمني.
older_than: (الطابع الزمني) تغيير الأقسام التي يكون نطاقها العلوي أقل من أو يساوي older_than.
new_access_method: (الاسم) إما "كومة ذاكرة التخزين المؤقت" للتخزين المستند إلى الصفوف ، أو "عمودي" للتخزين العمودي.
القيمة المرجعة
غير متوفر
مثال
CALL alter_old_partitions_set_access_method(
'foo', now() - interval '6 months',
'columnar'
);
البيانات الوصفية / معلومات التكوين
get_shard_id_for_distribution_column
يعين Hyperscale (Citus) كل صف من الجدول الموزع إلى شظية استنادا إلى قيمة عمود توزيع الصف وطريقة توزيع الجدول. في معظم الحالات، يكون التعيين الدقيق عبارة عن تفاصيل منخفضة المستوى يمكن لمسؤول قاعدة البيانات تجاهلها. ومع ذلك ، قد يكون من المفيد تحديد شظايا الصف ، إما لمهام صيانة قاعدة البيانات اليدوية أو لمجرد إرضاء الفضول. توفر get_shard_id_for_distribution_column الوظيفة هذه المعلومات للجداول الموزعة بالتجزئة والموزعة على النطاق والمرجعية. لا يعمل مع توزيع الإلحاق.
الوسيطات
table_name: الجدول الموزع.
distribution_value: قيمة عمود التوزيع.
القيمة المرجعة
يرتبط المقياس التشعبي لمعرف الشارد (Citus) بقيمة عمود التوزيع للجدول المحدد.
مثال
SELECT get_shard_id_for_distribution_column('my_table', 4);
get_shard_id_for_distribution_column
--------------------------------------
540007
(1 row)
column_to_column_name
يترجم partkey العمود pg_dist_partition إلى اسم عمود نصي. الترجمة مفيدة لتحديد عمود التوزيع لجدول موزع.
للحصول على مناقشة أكثر تفصيلا، راجع اختيار عمود توزيع.
الوسيطات
table_name: الجدول الموزع.
column_var_text: قيمة partkey في الجدول pg_dist_partition .
القيمة المرجعة
اسم table_nameعمود التوزيع الخاص به.
مثال
-- get distribution column name for products table
SELECT column_to_column_name(logicalrelid, partkey) AS dist_col_name
FROM pg_dist_partition
WHERE logicalrelid='products'::regclass;
المخرجات:
┌───────────────┐
│ dist_col_name │
├───────────────┤
│ company_id │
└───────────────┘
citus_relation_size
احصل على مساحة القرص المستخدمة من قبل كافة شظايا الجدول الموزع المحدد. تتضمن مساحة القرص حجم "الشوكة الرئيسية"، ولكنها تستثني خريطة الرؤية وخريطة المساحة الحرة للشظايا.
الوسيطات
logicalrelid: اسم جدول موزع.
القيمة المرجعة
الحجم بالبايت ككبير.
مثال
SELECT pg_size_pretty(citus_relation_size('github_events'));
pg_size_pretty
--------------
23 MB
citus_table_size
احصل على مساحة القرص المستخدمة من قبل كافة شظايا الجدول الموزع المحدد، باستثناء الفهارس (ولكن بما في ذلك TOAST وخريطة المساحة الحرة وخريطة الرؤية).
الوسيطات
logicalrelid: اسم جدول موزع.
القيمة المرجعة
الحجم بالبايت ككبير.
مثال
SELECT pg_size_pretty(citus_table_size('github_events'));
pg_size_pretty
--------------
37 MB
citus_total_relation_size
احصل على إجمالي مساحة القرص المستخدمة بواسطة كافة شظايا الجدول الموزع المحدد، بما في ذلك كافة الفهارس وبيانات TOAST.
الوسيطات
logicalrelid: اسم جدول موزع.
القيمة المرجعة
الحجم بالبايت ككبير.
مثال
SELECT pg_size_pretty(citus_total_relation_size('github_events'));
pg_size_pretty
--------------
73 MB
citus_stat_statements_reset
يزيل كل الصفوف من citus_stat_statements.
تعمل هذه الوظيفة بشكل مستقل عن pg_stat_statements_reset(). لإعادة تعيين جميع الإحصائيات، اتصل بكلتا الوظيفتين.
الوسيطات
غير متوفر
القيمة المرجعة
بلا
citus_get_active_worker_nodes
ترجع الدالة citus_get_active_worker_nodes() قائمة بأسماء مضيفي العمال النشطين وأرقام المنافذ.
الوسيطات
غير متوفر
القيمة المرجعة
قائمة المجموعات حيث تحتوي كل مجموعة على المعلومات التالية:
node_name: اسم DNS للعقدة العاملة
node_port: منفذ على عقدة العامل التي يستمع إليها خادم قاعدة البيانات
مثال
SELECT * from citus_get_active_worker_nodes();
node_name | node_port
-----------+-----------
localhost | 9700
localhost | 9702
localhost | 9701
(3 rows)
إدارة مجموعة الخوادم وإصلاحها
master_copy_shard_placement
إذا فشل تحديث موضع شظية أثناء أمر تعديل أو عملية DDL، وضع علامة عليه على أنه غير نشط. يمكن بعد ذلك استدعاء وظيفة master_copy_shard_placement لإصلاح موضع شظية غير نشط باستخدام بيانات من موضع صحي.
لإصلاح شظية، تقوم الوظيفة أولا بإسقاط موضع الشظية غير الصحي وإعادة إنشائه باستخدام المخطط الموجود على المنسق. بمجرد إنشاء موضع الشظية، تقوم الدالة بنسخ البيانات من الموضع السليم وتحديث البيانات الوصفية لوضع علامة على موضع الشظية الجديد على أنه صحي. تضمن هذه الوظيفة حماية الشظية من أي تعديلات متزامنة أثناء الإصلاح.
الوسيطات
shard_id: معرف الشظية المراد إصلاحها.
source_node_name: اسم DNS للعقدة التي يوجد عليها موضع الشظية السليم (عقدة "المصدر").
source_node_port: المنفذ الموجود على عقدة العامل المصدر التي يستمع إليها خادم قاعدة البيانات.
target_node_name: اسم DNS للعقدة التي يوجد عليها موضع الشظية غير الصالح (العقدة "الهدف").
target_node_port: المنفذ الموجود على عقدة العامل الهدف الذي يستمع إليه خادم قاعدة البيانات.
القيمة المرجعة
غير متوفر
مثال
سيقوم المثال أدناه بإصلاح موضع شظية غير نشط من shard 12345 ، الموجود على خادم قاعدة البيانات الذي يعمل على "bad_host" على المنفذ 5432. لإصلاحه ، سيستخدم بيانات من موضع شظية صحي موجود على الخادم الذي يعمل على "good_host" على المنفذ 5432.
SELECT master_copy_shard_placement(12345, 'good_host', 5432, 'bad_host', 5432);
master_move_shard_placement
تنقل هذه الوظيفة شظية معينة (وشظايا متداخلة معها) من عقدة إلى أخرى. عادة ما يتم استخدامه بشكل غير مباشر أثناء إعادة توازن الشظايا بدلا من استدعائه مباشرة من قبل مسؤول قاعدة البيانات.
هناك طريقتان لنقل البيانات: الحظر أو عدم الحظر. يعني نهج الحظر أنه أثناء الحركة يتم إيقاف جميع التعديلات على الشظية مؤقتا. الطريقة الثانية ، التي تتجنب حظر كتابات الشظايا ، تعتمد على النسخ المتماثل المنطقي Postgres 10.
بعد عملية نقل ناجحة، يتم حذف الشظايا الموجودة في العقدة المصدر. إذا فشلت الحركة في أي وقت ، فإن هذه الوظيفة تلقي خطأ وتترك العقد المصدر والهدف دون تغيير.
الوسيطات
shard_id: معرف الشظية المراد نقلها.
source_node_name: اسم DNS للعقدة التي يوجد عليها موضع الشظية السليم (عقدة "المصدر").
source_node_port: المنفذ الموجود على عقدة العامل المصدر التي يستمع إليها خادم قاعدة البيانات.
target_node_name: اسم DNS للعقدة التي يوجد عليها موضع الشظية غير الصالح (العقدة "الهدف").
target_node_port: المنفذ الموجود على عقدة العامل الهدف الذي يستمع إليه خادم قاعدة البيانات.
shard_transfer_mode: (اختياري) حدد طريقة النسخ المتماثل، سواء لاستخدام النسخ المتماثل المنطقي PostgreSQL أو أمر COPY عبر العامل. القيم المُحتملة هي:
autoطلب هوية نسخة متماثلة إذا كان النسخ المتماثل المنطقي ممكنا، وإلا استخدم السلوك القديم (على سبيل المثال، لإصلاح الشظايا، PostgreSQL 9.6..: هذه هي القيمة الافتراضية.force_logicalاستخدم النسخ المتماثل المنطقي حتى إذا لم يكن للجدول هوية نسخة متماثلة.: ستفشل أي عبارات تحديث/حذف متزامنة إلى الجدول أثناء النسخ المتماثل.block_writesاستخدم COPY (حظر عمليات الكتابة) للجداول التي تفتقر إلى المفتاح الأساسي أو هوية النسخة المتماثلة.:
القيمة المرجعة
غير متوفر
مثال
SELECT master_move_shard_placement(12345, 'from_host', 5432, 'to_host', 5432);
rebalance_table_shards
تحرك الدالة rebalance_table_shards() شظايا الجدول المحدد لتوزيعها بالتساوي بين العمال. تقوم الدالة أولا بحساب قائمة التحركات التي تحتاج إلى القيام بها لضمان توازن مجموعة الخادم ضمن العتبة المحددة. بعد ذلك ، يقوم بنقل مواضع الشظايا واحدة تلو الأخرى من العقدة المصدر إلى العقدة الوجهة ويقوم بتحديث بيانات تعريف shard المقابلة لتعكس النقل.
يتم تعيين تكلفة لكل شظية عند تحديد ما إذا كانت الشظايا "موزعة بالتساوي". بشكل افتراضي ، يكون لكل شظية نفس التكلفة (قيمة 1) ، لذا فإن التوزيع لمعادلة التكلفة عبر العمال هو نفسه معادلة عدد الشظايا على كل منها. تسمى استراتيجية التكلفة الثابتة "by_shard_count" وهي استراتيجية إعادة التوازن الافتراضية.
الاستراتيجية الافتراضية مناسبة في ظل هذه الظروف:
- الشظايا هي تقريبا نفس الحجم
- تحصل الشظايا على نفس كمية حركة المرور تقريبا
- عقد العمال كلها بنفس الحجم / النوع
- لم يتم تثبيت الشظايا على عمال معينين
إذا لم يصمد أي من هذه الافتراضات ، فقد تؤدي إعادة التوازن الافتراضية إلى خطة سيئة. في هذه الحالة ، يمكنك تخصيص الاستراتيجية ، باستخدام المعلمة rebalance_strategy .
من المستحسن الاتصال get_rebalance_table_shards_plan قبل تشغيل rebalance_table_shards ، لمعرفة الإجراءات التي سيتم تنفيذها والتحقق منها.
الوسيطات
table_name: (اختياري) اسم الجدول الذي تحتاج شظاياه إلى إعادة توازن. إذا كانت NULL ، فأعد توازن جميع مجموعات colocation الموجودة.
العتبة: (اختياري) رقم تعويم بين 0.0 و 1.0 يشير إلى الحد الأقصى لنسبة الفرق في استخدام العقدة من متوسط الاستخدام. على سبيل المثال، سيؤدي تحديد 0.1 إلى محاولة أداة إعادة موازن الشظايا موازنة جميع العقد للاحتفاظ بنفس العدد من الشظايا ±10٪. على وجه التحديد ، سيحاول جهاز إعادة توازن الشظية التقارب بين استخدام جميع عقد العمال إلى (1 - العتبة) * average_utilization ... (1
- العتبة) * نطاق average_utilization.
max_shard_moves: (اختياري) الحد الأقصى لعدد الشظايا المراد تحريكها.
excluded_shard_list: معرفات (اختيارية) للشظايا التي لا ينبغي نقلها أثناء عملية إعادة التوازن.
shard_transfer_mode: (اختياري) حدد طريقة النسخ المتماثل، سواء لاستخدام النسخ المتماثل المنطقي PostgreSQL أو أمر COPY عبر العامل. القيم المُحتملة هي:
autoطلب هوية نسخة متماثلة إذا كان النسخ المتماثل المنطقي ممكنا، وإلا استخدم السلوك القديم (على سبيل المثال، لإصلاح الشظايا، PostgreSQL 9.6..: هذه هي القيمة الافتراضية.force_logicalاستخدم النسخ المتماثل المنطقي حتى إذا لم يكن للجدول هوية نسخة متماثلة.: ستفشل أي عبارات تحديث/حذف متزامنة إلى الجدول أثناء النسخ المتماثل.block_writesاستخدم COPY (حظر عمليات الكتابة) للجداول التي تفتقر إلى المفتاح الأساسي أو هوية النسخة المتماثلة.:
drain_only: (اختياري) عندما يكون ذلك صحيحا، حرك الشظايا من عقد العمال التي تم shouldhaveshards تعيينها على خطأ في pg_dist_node؛ لا تحرك أي شظايا أخرى.
rebalance_strategy: (اختياري) اسم استراتيجية في pg_dist_rebalance_strategy. إذا تم حذف هذه الوسيطة، فستختار الدالة الاستراتيجية الافتراضية، كما هو موضح في الجدول.
القيمة المرجعة
غير متوفر
مثال
سيحاول المثال أدناه إعادة توازن شظايا جدول github_events ضمن الحد الأدنى الافتراضي.
SELECT rebalance_table_shards('github_events');
سيحاول استخدام هذا المثال إعادة توازن جدول github_events دون تحريك الشظايا باستخدام المعرفين 1 و2.
SELECT rebalance_table_shards('github_events', excluded_shard_list:='{1,2}');
get_rebalance_table_shards_plan
إخراج حركات الشظايا المخطط لها rebalance_table_shards دون أدائها. على الرغم من أنه من غير المحتمل ، get_rebalance_table_shards_plan إخراج خطة مختلفة قليلا عما سيفعله rebalance_table_shards الذي يتصل به بنفس الوسيطات. لا يتم تنفيذها في نفس الوقت ، لذلك قد تختلف الحقائق حول مجموعة الخادم - على سبيل المثال ، مساحة القرص - بين المكالمات.
الوسيطات
نفس الحجج مثل rebalance_table_shards: العلاقة ، العتبة ، max_shard_moves ، excluded_shard_list ، drain_only. راجع توثيق هذه الوظيفة لمعرفة معنى الوسيطات.
القيمة المرجعة
Tuples التي تحتوي على هذه الأعمدة:
- table_name: الطاولة التي ستتحرك شظاياها
- شارد: الشظية المعنية
- shard_size: الحجم بالبايت
- اسم المصدر: اسم المضيف للعقدة المصدر
- sourceport: منفذ العقدة المصدر
- اسم الهدف: اسم المضيف للعقدة الوجهة
- targetport: منفذ عقدة الوجهة
get_rebalance_progress
بمجرد بدء إعادة توازن الشظية ، get_rebalance_progress() تسرد الوظيفة تقدم كل شظية معنية. يراقب التحركات المخطط لها والمنفذة من قبل rebalance_table_shards().
الوسيطات
غير متوفر
القيمة المرجعة
Tuples التي تحتوي على هذه الأعمدة:
- sessionid: Postgres PID من مراقب إعادة التوازن
- table_name: الطاولة التي تتحرك شظاياها
- شارد: الشظية المعنية
- shard_size: الحجم بالبايت
- اسم المصدر: اسم المضيف للعقدة المصدر
- sourceport: منفذ العقدة المصدر
- اسم الهدف: اسم المضيف للعقدة الوجهة
- targetport: منفذ عقدة الوجهة
- التقدم: 0 = في انتظار أن يتم نقله. 1 = التحرك; 2 = مكتمل
مثال
SELECT * FROM get_rebalance_progress();
┌───────────┬────────────┬─────────┬────────────┬───────────────┬────────────┬───────────────┬────────────┬──────────┐
│ sessionid │ table_name │ shardid │ shard_size │ sourcename │ sourceport │ targetname │ targetport │ progress │
├───────────┼────────────┼─────────┼────────────┼───────────────┼────────────┼───────────────┼────────────┼──────────┤
│ 7083 │ foo │ 102008 │ 1204224 │ n1.foobar.com │ 5432 │ n4.foobar.com │ 5432 │ 0 │
│ 7083 │ foo │ 102009 │ 1802240 │ n1.foobar.com │ 5432 │ n4.foobar.com │ 5432 │ 0 │
│ 7083 │ foo │ 102018 │ 614400 │ n2.foobar.com │ 5432 │ n4.foobar.com │ 5432 │ 1 │
│ 7083 │ foo │ 102019 │ 8192 │ n3.foobar.com │ 5432 │ n4.foobar.com │ 5432 │ 2 │
└───────────┴────────────┴─────────┴────────────┴───────────────┴────────────┴───────────────┴────────────┴──────────┘
citus_add_rebalance_strategy
إلحاق صف pg_dist_rebalance_strategy .
الوسيطات
لمزيد من المعلومات حول هذه الوسيطات، راجع قيم الأعمدة المقابلة في pg_dist_rebalance_strategy.
الاسم: معرف الاستراتيجية الجديدة
shard_cost_function: يحدد الوظيفة المستخدمة لتحديد "تكلفة" كل شظية
node_capacity_function: يحدد وظيفة قياس سعة العقدة
shard_allowed_on_node_function: يحدد الوظيفة التي تحدد الشظايا التي يمكن وضعها على أي عقد
default_threshold: عتبة نقطة عائمة تضبط مدى دقة توازن تكلفة الشظايا التراكمية بين العقد
minimum_threshold: (اختياري) عمود حماية يحتوي على القيمة الدنيا المسموح بها لوسيطة الحد الأدنى rebalance_table_shards(). قيمته الافتراضية هي 0
القيمة المرجعة
غير متوفر
citus_set_default_rebalance_strategy
قم بتحديث جدول pg_dist_rebalance_strategy، مع تغيير الاستراتيجية المسماة بواسطة وسيطتها لتكون الافتراضية المختارة عند إعادة موازنة الشظايا.
الوسيطات
الاسم: اسم الاستراتيجية في pg_dist_rebalance_strategy
القيمة المرجعة
غير متوفر
مثال
SELECT citus_set_default_rebalance_strategy('by_disk_size');
citus_remote_connection_stats
تعرض الدالة citus_remote_connection_stats() عدد الاتصالات النشطة بكل عقدة بعيدة.
الوسيطات
غير متوفر
مثال
SELECT * from citus_remote_connection_stats();
hostname | port | database_name | connection_count_to_node
----------------+------+---------------+--------------------------
citus_worker_1 | 5432 | postgres | 3
(1 row)
isolate_tenant_to_new_shard
تقوم هذه الدالة بإنشاء شظية جديدة للاحتفاظ بالصفوف ذات القيمة المفردة المحددة في عمود التوزيع. إنه مفيد بشكل خاص لحالة استخدام Hyperscale (Citus) متعددة المستأجرين ، حيث يمكن وضع مستأجر كبير بمفرده على شظية خاصة به وفي النهاية عقدة مادية خاصة به.
الوسيطات
table_name: اسم الجدول للحصول على شظية جديدة.
tenant_id: قيمة عمود التوزيع الذي سيتم تعيينه إلى شظية جديدة.
cascade_option: (اختياري) عند التعيين على "CASCADE"، يعزل أيضا شظية من جميع الجداول في مجموعة الموقع المشترك للجدول الحالي.
القيمة المرجعة
shard_id: ترجع الدالة المعرف الفريد المعين للشظية التي تم إنشاؤها حديثا.
أمثلة
إنشاء شظية جديدة للاحتفاظ بالبنود للمستأجر 135:
SELECT isolate_tenant_to_new_shard('lineitem', 135);
┌─────────────────────────────┐
│ isolate_tenant_to_new_shard │
├─────────────────────────────┤
│ 102240 │
└─────────────────────────────┘
الخطوات التالية
- تقوم العديد من الوظائف الموجودة في هذه المقالة بتعديل جداول بيانات تعريف النظام
- معلمات الخادم تخصيص سلوك بعض الوظائف