# List Users

List Users

The script will be executed when the administrator uses the console or API to obtain the user list. The data required by this interface needs to include the total number of users and the user list on the current page. This script is only required in full use of the custom database schema.

# Function definition

The listUsers function is defined as follows:

async function listUsers(page, limit, context) {
  // This script should be able to get a list of users of your database.

  // The first argument `page` is 1-based number.

  // The second argument `limit` is page size.

  // The last argument `context` contains information about the authentication context.
  // see http://core.authing.cn/connections/custom-db/config-custom-db-connection.html for more information.

  //
  // There are three ways this script can finish:
  // 1. Get Users Success:
  // return {
  // totalCount: 101,
  // list: [], // current page
  // };
  // 2. Something went wrong while trying to reach your database:
  // throw new Error("my error message")

  const msg =
    'Please implement the List Users script for this database connection';
  throw new Error(msg);
}

Parameters	Type	nullable	Description
page	number	false	The number of page numbers, starting from 1.
limit	number	false	The number per page.
context	object	true	request context context

The context contains the following information:

Property name	Type	Description
userPoolId	string	User Pool ID
userPoolName	string	User pool name
userPoolMetadata	object	User pool configuration information
appId	string	ID of the current user, You can distinguish the source of the application requested by the user through appId.
appName	string	The name of the current application
appMetadata	object	Current application configuration information
application	string	User Pool ID
request	object	The detailed information of the current request, including: `ip`: client IP `geo`: client geographic location resolved by IP `body`: request body

# Return data convention

# Get user list successfully

You need to assemble user data in the following format: the returned data needs to be an object, key totalCount represents the total number of users, key list represents the user list of the current page, such as:

async function listUsers(id, updates, context) {
  // Implement your logic here
  return {
    totalCount: 12,
    list: [
      {
        id: 1,
        ...
      }
    ],
  };
}

# Other exception errors

When encountering other abnormal errors, you can catch the error and return a more friendly error prompt, for example:

async function listUsers(id, updates, context) {
  try {
    // Implement your logic here
  } catch (error) {
    throw new Error('Something went wrong ...')
  }
}

# Best Practices

# Provide friendly error tips

When encountering an unknown error, we recommend throwing a standard Error object. Authing will catch this error and return it to the end user. For example: throw new Error("My nice error message"), you can see the error log in the log history of the custom database.

# Disconnect the database connection at the end of the function

Please remember to close the connection to the database when the script is executed, such as calling client.end(). For example, it can be executed in try/finallly to ensure that it will always be executed:

try {
  const result = await client.updates("YOUR updates");
} finally {
  // NOTE: always call `client.end()` here to close the connection to the database
  client.end();
}

# Example function

Taking the postgres database as an example, the following points are explained:

-You can get the database connection string through env.DB_CONNECTION_URI to create a database connection. -Assemble user information into the format specified by Authing. -Call client.end() in try/finally to disconnect the database.

async function listUsers(page, limit, context) {
  // This example uses the "pg" library
  // more info here: https://github.com/brianc/node-postgres
  const {Client} = require('pg');

  const client = new Client({
    connectionString: env.DB_CONNECTION_URI,
  });

  // Or you can:
  // const client = new Client({
  // host: env.DB_HOST,
  // port: env.DB_PORT,
  // user: env.DB_USERNAME,
  // password: env.DB_PASSWORD,
  // database: env.DB_DATABASE,
  // });

  await client.connect();

  const data = await client.query('SELECT COUNT(*) FROM users');
  const totalCount = parseInt(data.rows[0].count);
  const QUERY = `SELECT * from users LIMIT ${limit} OFFSET ${(page-1) *
    limit}`;
  try {
    const result = await client.query(QUERY);
    const list = result.rows.map(user => {
      return {
        id: user.id,
        email: user.email,
        name: user.name,
        phone: user.phone,
        username: user.username,
        photo: user.photo,
        nickname: user.nickname,
        token: user.token,
        emailVerified: user.email_verified,
        phoneVerified: user.phone_verified,
        loginsCount: user.logins_count,
        lastIp: user.last_ip,
        gender: user.gender,
        address: user.address,company: user.company,
         birthdate: user.birthdate,
         website: user.website,
       };
     });
     return {
       totalCount,
       list,
     };
   } catch (error) {
     throw new Error(`Execute query failed: ${error.message}`);
   } finally {
     // NOTE: always call `client.end()` here to close the connection to the database
     client.end();
   }
}

← Delete User Validate password →