التشغيل السريع: استخدام Java وJDBC في خادم مرن قاعدة بيانات Azure لـ PostgreSQL

توضح هذه المقالة كيفية إنشاء نموذج تطبيق يستخدم Java وJDBC لتخزين المعلومات واستردادها في قاعدة بيانات Azure لـ PostgreSQL.

JDBC هو واجهة برمجة تطبيقات Java القياسية للاتصال بقواعد البيانات العلائقية التقليدية.

تتضمن هذه المقالة طريقتين للمصادقة: Microsoft Entra المصادقة ومصادقة PostgreSQL. تعرض علامة التبويب Passwordless مصادقة Microsoft Entra وتعرض علامة التبويب Password مصادقة PostgreSQL.

مصادقة Microsoft Entra هي آلية للاتصال بقاعدة بيانات Azure ل PostgreSQL باستخدام الهويات المحددة في معرف Microsoft Entra. باستخدام مصادقة Microsoft Entra، يمكنك إدارة هويات مستخدمي قاعدة البيانات خدمات Microsoft الأخرى في موقع مركزي، ما يبسط إدارة الأذونات.

تستخدم مصادقة PostgreSQL الحسابات المخزنة في PostgreSQL. إذا اخترت استخدام كلمات المرور كبيانات اعتماد للحسابات، فقم بتخزين بيانات الاعتماد هذه في user الجدول. نظرا إلى تخزين كلمات المرور هذه في PostgreSQL، تحتاج إلى إدارة تدوير كلمات المرور بنفسك.

Prerequisites

أعِد بيئة العمل

أولا، استخدم الأمر التالي لإعداد بعض متغيرات البيئة.

export AZ_RESOURCE_GROUP=database-workshop
export AZ_DATABASE_SERVER_NAME=<YOUR_DATABASE_SERVER_NAME>
export AZ_DATABASE_NAME=<YOUR_DATABASE_NAME>
export AZ_LOCATION=<YOUR_AZURE_REGION>
export AZ_POSTGRESQL_AD_NON_ADMIN_USERNAME=<YOUR_POSTGRESQL_AD_NON_ADMIN_USERNAME>
export AZ_LOCAL_IP_ADDRESS=<YOUR_LOCAL_IP_ADDRESS>
export CURRENT_USERNAME=$(az ad signed-in-user show --query userPrincipalName -o tsv)

استبدل العناصر النائبة بالقيم التالية، والتي يتم استخدامها في هذه المقالة:

  • <YOUR_DATABASE_SERVER_NAME>: اسم خادمك المرن قاعدة بيانات Azure لـ PostgreSQL، والذي يجب أن يكون فريدا عبر Azure.
  • <YOUR_DATABASE_NAME>: اسم قاعدة البيانات للخادم المرن قاعدة بيانات Azure لـ PostgreSQL، والذي يجب أن يكون فريدا داخل Azure.
  • <YOUR_AZURE_REGION>: منطقة Azure المراد استخدامها. يمكنك استخدام eastus بشكل افتراضي، ولكن اختر منطقة أقرب إلى المكان الذي تعيش فيه. للاطلاع على القائمة الكاملة للمناطق المتوفرة، أدخل az account list-locations.
  • <YOUR_POSTGRESQL_AD_NON_ADMIN_USERNAME>: اسم المستخدم لخادم قاعدة بيانات Azure لـ PostgreSQL المرن. تأكد من أن اسم المستخدم هو مستخدم صالح في مستأجر Microsoft Entra.
  • <YOUR_LOCAL_IP_ADDRESS>: عنوان IP لجهاز الكمبيوتر المحلي الخاص بك، الذي تشغل منه تطبيق Spring Boot. إحدى الطرق الملائمة للعثور عليه هي فتح whatismyip.akamai.com.

Important

عند الإعداد <YOUR_POSTGRESQL_AD_NON_ADMIN_USERNAME>، يجب أن يكون المستخدم موجودا بالفعل في مستأجر Microsoft Entra أو لا يمكنك إنشاء مستخدم Microsoft Entra في قاعدة البيانات الخاصة بك.

بعد ذلك، قم بإنشاء مجموعة موارد باستخدام الأمر التالي:

az group create \
    --name $AZ_RESOURCE_GROUP \
    --location $AZ_LOCATION \
    --output tsv

إنشاء خادم مرن

تصف الأقسام التالية كيفية إنشاء مثيل قاعدة البيانات وتكوينه.

إنشاء خادم مرن وإعداد مستخدم مسؤول

ملاحظة

لمزيد من المعلومات التفصيلية حول إنشاء خوادم مرنة قاعدة بيانات Azure لـ PostgreSQL، راجع التشغيل السريع: إنشاء خادم مرن قاعدة بيانات Azure لـ PostgreSQL.

إذا كنت تستخدم Azure CLI، فقم بتشغيل الأمر التالي للتأكد من أن لديه الإذن الكافي:

az login --scope https://graph.microsoft.com/.default

قم بتشغيل الأمر التالي لإنشاء الخادم:

az postgres flexible-server create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_SERVER_NAME \
    --location $AZ_LOCATION \
    --yes \
    --output tsv

لإعداد مسؤول Microsoft Entra بعد إنشاء الخادم، اتبع الخطوات الواردة في إدارة أدوار Microsoft Entra في قاعدة بيانات Azure ل PostgreSQL.

Important

عند إعداد مسؤول، يمكنك إضافة مستخدم جديد بامتيازات المسؤول الكامل إلى قاعدة بيانات Azure للخادم المرن قاعدة بيانات Azure لـ PostgreSQL. يمكنك إنشاء العديد من مسؤولي Microsoft Entra لكل خادم مرن قاعدة بيانات Azure لـ PostgreSQL.

هل تواجه أي مشاكل؟ أبلغنا بها.

تكوين قاعدة جدار حماية لقاعدة بيانات Azure لمثيل PostgreSQL

قاعدة بيانات Azure لـ PostgreSQL الخوادم المرنة آمنة بشكل افتراضي. لديهم جدار حماية يمنع جميع الاتصالات الواردة. لاستخدام قاعدة بياناتك، أضف قاعدة جدار حماية تمنح عنوان IP المحلي حق الوصول إلى خادم قاعدة البيانات.

لأنه يمكنك تكوين عنوان IP المحلي في بداية هذه المقالة، يمكنك فتح جدار الحماية الخاص بالخادم عن طريق تشغيل الأمر التالي:

az postgres flexible-server firewall-rule create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_SERVER_NAME \
    --rule-name $AZ_DATABASE_SERVER_NAME-database-allow-local-ip \
    --start-ip-address $AZ_LOCAL_IP_ADDRESS \
    --end-ip-address $AZ_LOCAL_IP_ADDRESS \
    --output tsv

إذا كنت تتصل بخادم مرن قاعدة بيانات Azure لـ PostgreSQL من نظام Windows الفرعي لـ Linux‬ (WSL) على كمبيوتر Windows، فستحتاج إلى إضافة معرف مضيف WSL إلى جدار الحماية الخاص بك.

احصل على عنوان IP لجهازك المضيف عن طريق تشغيل الأمر التالي في WSL:

cat /etc/resolv.conf

انسخ عنوان IP الذي يتبع المصطلح nameserver، ثم استخدم الأمر التالي لتعيين متغير بيئة لعنوان IP WSL:

AZ_WSL_IP_ADDRESS=<the-copied-IP-address>

ثم استخدم الأمر التالي لفتح جدار حماية الخادم لتطبيقك المستند إلى WSL:

az postgres flexible-server firewall-rule create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_SERVER_NAME \
    --rule-name $AZ_DATABASE_SERVER_NAME-database-allow-local-ip \
    --start-ip-address $AZ_WSL_IP_ADDRESS \
    --end-ip-address $AZ_WSL_IP_ADDRESS \
    --output tsv

تكوين قاعدة بيانات Azure لقاعدة بيانات PostgreSQL

إنشاء قاعدة بيانات جديدة باستخدام الأمر التالي:

az postgres flexible-server db create \
    --resource-group $AZ_RESOURCE_GROUP \
    --database-name $AZ_DATABASE_NAME \
    --server-name $AZ_DATABASE_SERVER_NAME \
    --output tsv

إنشاء قاعدة بيانات Azure لمستخدم PostgreSQL غير المسؤول ومنح الإذن

بعد ذلك، أنشئ مستخدما غير مسؤول وامنح جميع الأذونات لقاعدة البيانات.

ملاحظة

لمزيد من المعلومات التفصيلية حول إدارة مستخدمي قاعدة بيانات Azure لـ PostgreSQL، راجع إدارة أدوار Microsoft Entra في قاعدة بيانات Azure لـ PostgreSQL.

إنشاء برنامج نصي SQL يسمى create_ad_user.sql لإنشاء مستخدم غير مسؤول. أضف المحتويات التالية واحفظها محليا:

cat << EOF > create_ad_user.sql
select * from pgaadauth_create_principal('$AZ_POSTGRESQL_AD_NON_ADMIN_USERNAME', false, false);
EOF

ثم استخدم الأمر التالي لتشغيل البرنامج النصي SQL وإنشاء المستخدم غير المسؤول Microsoft Entra:

psql "host=$AZ_DATABASE_SERVER_NAME.postgres.database.azure.com user=$CURRENT_USERNAME dbname=postgres port=5432 password=$(az account get-access-token --resource-type oss-rdbms --output tsv --query accessToken) sslmode=require" < create_ad_user.sql

استخدم الأمر التالي لإزالة ملف البرنامج النصي المؤقت SQL:

rm create_ad_user.sql

إنشاء مشروع Java جديد

باستخدام بيئة التطوير المفضلة لديك، أنشئ مشروع Java جديد باستخدام Java 8 أو أحدث. أضف ملف pom.xml في الدليل الجذري يحتوي على المحتويات التالية:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>demo</name>

    <properties>
        <java.version>1.8</java.version>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
    </properties>

    <dependencies>
      <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <version>42.7.5</version>
      </dependency>
      <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-identity-extensions</artifactId>
        <version>1.2.0</version>
      </dependency>
    </dependencies>
</project>

هذا الملف هو ملف Apache Maven الذي يقوم بتكوين مشروعك لاستخدامه:

  • جافا 8
  • مشغل PostgreSQL الحديث لـ Java

إعداد ملف تكوين للاتصال بقاعدة بيانات Azure ل PostgreSQL

أنشئ ملف src/main/resources/application.properties ، وأضف المحتويات التالية:

cat << EOF > src/main/resources/application.properties
url=jdbc:postgresql://${AZ_DATABASE_SERVER_NAME}.postgres.database.azure.com:5432/${AZ_DATABASE_NAME}?sslmode=require&authenticationPluginClassName=com.azure.identity.extensions.jdbc.postgresql.AzurePostgresqlAuthenticationPlugin
user=${AZ_POSTGRESQL_AD_NON_ADMIN_USERNAME}
EOF

ملاحظة

تتضمن خاصية التكوين url?sslmode=require للتأكد من أن برنامج تشغيل JDBC يستخدم TLS (أمان طبقة النقل) عند الاتصال بقاعدة البيانات. يعد استخدام TLS إلزاميا مع خوادم مرنة قاعدة بيانات Azure لـ PostgreSQL وهو ممارسة أمان موصى بها.

إنشاء ملف SQL لإنشاء مخطط قاعدة البيانات

استخدم ملف src/main/resources/schema.sql لإنشاء مخطط قاعدة بيانات. أنشئ هذا الملف، وأضف المحتوى التالي:

DROP TABLE IF EXISTS todo;
CREATE TABLE todo (id SERIAL PRIMARY KEY, description VARCHAR(255), details VARCHAR(4096), done BOOLEAN);

إنشاء التعليمة البرمجية للتطبيق

تشرح الأقسام التالية كتابة كود Java الذي يتصل بقاعدة البيانات، ويحدد نموذج البيانات، وينفذ العمليات الأساسية ل CRUD.

الاتصال بقاعدة البيانات

بعد ذلك، أضف التعليمة البرمجية Java التي تستخدم JDBC لتخزين البيانات واستردادها من خادمك المرن قاعدة بيانات Azure لـ PostgreSQL.

إنشاء ملف src/main/java/DemoApplication.java وإضافة المحتويات التالية:

package com.example.demo;

import java.sql.*;
import java.util.*;
import java.util.logging.Logger;

public class DemoApplication {

    private static final Logger log;

    static {
        System.setProperty("java.util.logging.SimpleFormatter.format", "[%4$-7s] %5$s %n");
        log =Logger.getLogger(DemoApplication.class.getName());
    }

    public static void main(String[] args) throws Exception {
        log.info("Loading application properties");
        Properties properties = new Properties();
        properties.load(DemoApplication.class.getClassLoader().getResourceAsStream("application.properties"));

        log.info("Connecting to the database");
        Connection connection = DriverManager.getConnection(properties.getProperty("url"), properties);
        log.info("Database connection test: " + connection.getCatalog());

        log.info("Create database schema");
        Scanner scanner = new Scanner(DemoApplication.class.getClassLoader().getResourceAsStream("schema.sql"));
        Statement statement = connection.createStatement();
        while (scanner.hasNextLine()) {
            statement.execute(scanner.nextLine());
        }

        /*
        Todo todo = new Todo(1L, "configuration", "congratulations, you have set up JDBC correctly!", true);
        insertData(todo, connection);
        todo = readData(connection);
        todo.setDetails("congratulations, you have updated data!");
        updateData(todo, connection);
        deleteData(todo, connection);
        */

        log.info("Closing database connection");
        connection.close();
    }
}

هل تواجه أي مشاكل؟ أبلغنا بها.

تستخدم التعليمات البرمجية Java هذه application.properties وملفات schema.sql التي قمت بإنشائها سابقا للاتصال بالخادم المرن قاعدة بيانات Azure لـ PostgreSQL وإنشاء مخطط يخزن البيانات.

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

ملاحظة

يتم تخزين بيانات اعتماد قاعدة البيانات في خصائص المستخدم وكلمة المرور لملف application.properties. تستخدم التعليمات البرمجية بيانات الاعتماد هذه عند تنفيذ DriverManager.getConnection(properties.getProperty("url"), properties);، حيث يتم تمرير ملف الخصائص كوسيطة.

يمكنك الآن تنفيذ هذه الفئة الرئيسة باستخدام الأداة المفضلة لديك:

  • باستخدام IDE الخاص بك، يمكنك النقر بزر الماوس الأيمن فوق فئة DemoApplication وتنفيذها.
  • باستخدام Maven، يمكنك تشغيل التطبيق عن طريق تنفيذ: mvn exec:java -Dexec.mainClass="com.example.demo.DemoApplication".

يتصل التطبيق بالخادم المرن قاعدة بيانات Azure لـ PostgreSQL، وينشئ مخطط قاعدة بيانات، ثم يغلق الاتصال، كما ترى في سجلات وحدة التحكم:

[INFO   ] Loading application properties
[INFO   ] Connecting to the database
[INFO   ] Database connection test: demo
[INFO   ] Create database schema
[INFO   ] Closing database connection

إنشاء فئة المجال

إنشاء فئة Java جديدة Todo بجوار DemoApplication الفئة وإضافة التعليمات البرمجية التالية:

package com.example.demo;

public class Todo {

    private Long id;
    private String description;
    private String details;
    private boolean done;

    public Todo() {
    }

    public Todo(Long id, String description, String details, boolean done) {
        this.id = id;
        this.description = description;
        this.details = details;
        this.done = done;
    }

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public String getDetails() {
        return details;
    }

    public void setDetails(String details) {
        this.details = details;
    }

    public boolean isDone() {
        return done;
    }

    public void setDone(boolean done) {
        this.done = done;
    }

    @Override
    public String toString() {
        return "Todo{" +
                "id=" + id +
                ", description='" + description + '\'' +
                ", details='" + details + '\'' +
                ", done=" + done +
                '}';
    }
}

هذه الفئة هي نموذج مجال تم تعيينه إلى todo الجدول الذي قمت بإنشائه عند تنفيذ البرنامج النصي schema.sql .

إدراج البيانات في قاعدة بيانات Azure ل PostgreSQL

في الملف src/main/java/DemoApplication.java، بعد الأسلوب الرئيسي، أضف الأسلوب التالي لإدراج البيانات في قاعدة البيانات:

private static void insertData(Todo todo, Connection connection) throws SQLException {
    log.info("Insert data");
    PreparedStatement insertStatement = connection
            .prepareStatement("INSERT INTO todo (id, description, details, done) VALUES (?, ?, ?, ?);");

    insertStatement.setLong(1, todo.getId());
    insertStatement.setString(2, todo.getDescription());
    insertStatement.setString(3, todo.getDetails());
    insertStatement.setBoolean(4, todo.isDone());
    insertStatement.executeUpdate();
}

يمكنك الآن إلغاء التعليق على السطرين التاليين في الأسلوب main:

Todo todo = new Todo(1L, "configuration", "congratulations, you have set up JDBC correctly!", true);
insertData(todo, connection);

عند تنفيذ الفئة الرئيسية، يجب أن تنتج الإخراج التالي:

[INFO   ] Loading application properties
[INFO   ] Connecting to the database
[INFO   ] Database connection test: demo
[INFO   ] Create database schema
[INFO   ] Insert data
[INFO   ] Closing database connection

قراءة البيانات من قاعدة بيانات Azure لـ PostgreSQL

للتحقق من أن التعليمات البرمجية الخاصة بك تعمل بشكل صحيح، اقرأ البيانات التي قمت بإدراجها مسبقا.

في الملف src/main/java/DemoApplication.java، بعد الأسلوب insertData، أضف الأسلوب التالي لقراءة البيانات من قاعدة البيانات:

private static Todo readData(Connection connection) throws SQLException {
    log.info("Read data");
    PreparedStatement readStatement = connection.prepareStatement("SELECT * FROM todo;");
    ResultSet resultSet = readStatement.executeQuery();
    if (!resultSet.next()) {
        log.info("There is no data in the database!");
        return null;
    }
    Todo todo = new Todo();
    todo.setId(resultSet.getLong("id"));
    todo.setDescription(resultSet.getString("description"));
    todo.setDetails(resultSet.getString("details"));
    todo.setDone(resultSet.getBoolean("done"));
    log.info("Data read from the database: " + todo.toString());
    return todo;
}

يمكنك الآن إلغاء التعليق على السطر التالي في الأسلوب main:

todo = readData(connection);

عند تنفيذ الفئة الرئيسية، يجب أن تنتج الإخراج التالي:

[INFO   ] Loading application properties
[INFO   ] Connecting to the database
[INFO   ] Database connection test: demo
[INFO   ] Create database schema
[INFO   ] Insert data
[INFO   ] Read data
[INFO   ] Data read from the database: Todo{id=1, description='configuration', details='congratulations, you have set up JDBC correctly!', done=true}
[INFO   ] Closing database connection

تحديث البيانات في قاعدة بيانات Azure لـ PostgreSQL

لتحديث البيانات، استخدم الخطوات التالية.

في الملف src/main/java/DemoApplication.java، بعد الأسلوب readData، أضف الأسلوب التالي لتحديث البيانات الموجودة داخل قاعدة البيانات:

private static void updateData(Todo todo, Connection connection) throws SQLException {
    log.info("Update data");
    PreparedStatement updateStatement = connection
            .prepareStatement("UPDATE todo SET description = ?, details = ?, done = ? WHERE id = ?;");

    updateStatement.setString(1, todo.getDescription());
    updateStatement.setString(2, todo.getDetails());
    updateStatement.setBoolean(3, todo.isDone());
    updateStatement.setLong(4, todo.getId());
    updateStatement.executeUpdate();
    readData(connection);
}

يمكنك الآن إلغاء التعليق على السطرين التاليين في الأسلوب main:

todo.setDetails("congratulations, you have updated data!");
updateData(todo, connection);

عند تنفيذ الفئة الرئيسية، يجب أن تنتج الإخراج التالي:

[INFO   ] Loading application properties
[INFO   ] Connecting to the database
[INFO   ] Database connection test: demo
[INFO   ] Create database schema
[INFO   ] Insert data
[INFO   ] Read data
[INFO   ] Data read from the database: Todo{id=1, description='configuration', details='congratulations, you have set up JDBC correctly!', done=true}
[INFO   ] Update data
[INFO   ] Read data
[INFO   ] Data read from the database: Todo{id=1, description='configuration', details='congratulations, you have updated data!', done=true}
[INFO   ] Closing database connection

حذف البيانات في قاعدة بيانات Azure لـ PostgreSQL

وأخيرا، احذف البيانات التي قمت بإدراجها مسبقا.

في الملف src/main/java/DemoApplication.java، بعد الأسلوب updateData، أضف الأسلوب التالي لحذف البيانات الموجودة داخل قاعدة البيانات:

private static void deleteData(Todo todo, Connection connection) throws SQLException {
    log.info("Delete data");
    PreparedStatement deleteStatement = connection.prepareStatement("DELETE FROM todo WHERE id = ?;");
    deleteStatement.setLong(1, todo.getId());
    deleteStatement.executeUpdate();
    readData(connection);
}

يمكنك الآن إلغاء التعليق على السطر التالي في الأسلوب main:

deleteData(todo, connection);

عند تنفيذ الفئة الرئيسية، يجب أن تنتج الإخراج التالي:

[INFO   ] Loading application properties
[INFO   ] Connecting to the database
[INFO   ] Database connection test: demo
[INFO   ] Create database schema
[INFO   ] Insert data
[INFO   ] Read data
[INFO   ] Data read from the database: Todo{id=1, description='configuration', details='congratulations, you have set up JDBC correctly!', done=true}
[INFO   ] Update data
[INFO   ] Read data
[INFO   ] Data read from the database: Todo{id=1, description='configuration', details='congratulations, you have updated data!', done=true}
[INFO   ] Delete data
[INFO   ] Read data
[INFO   ] There is no data in the database!
[INFO   ] Closing database connection

تنظيف الموارد

لقد قمت بإنشاء تطبيق Java يستخدم JDBC لتخزين البيانات واستردادها من خادم مرن قاعدة بيانات Azure لـ PostgreSQL.

لتنظيف كافة الموارد المستخدمة أثناء هذا التشغيل السريع، احذف مجموعة الموارد باستخدام الأمر التالي:

az group delete \
    --name $AZ_RESOURCE_GROUP \
    --yes

المحتوى ذو الصلة

  • Last updated on